CheckboxListInput

The CheckboxListInput component is used to capture multiple selections with Bulma's checkbox list styling, typed data items, and Blazor-friendly binding.

API Documentation

How it works #

The CheckboxListInput component renders a typed collection of Bulma-styled checkboxes and binds the selected values to your Blazor state as a list.

How to use:
  1. Create a list of CheckboxListInputItem<TValue> items for the available choices.
  2. Add the CheckboxListInput component and set the matching TValue type.
  3. Bind the selected values with @bind-Values.
This demo shows the default multi-select behavior of the CheckboxListInput component.

Selected days: saturday, sunday

<CheckboxListInput TValue="string"
                   Items="@weekDayItems"
                   @bind-Values="@selectedDays" />

<p class="mt-3">
    Selected days: @(selectedDays.Count == 0 ? "None" : string.Join(", ", selectedDays))
</p>

@code {
    private readonly List<CheckboxListInputItem<string>> weekDayItems =
    [
        new("monday", "Monday"),
        new("tuesday", "Tuesday"),
        new("wednesday", "Wednesday"),
        new("thursday", "Thursday"),
        new("friday", "Friday"),
        new("saturday", "Saturday"),
        new("sunday", "Sunday")
    ];

    private List<string> selectedDays = ["saturday", "sunday"];
}

Data parameter #

The CheckboxListInput component uses the Items parameter to render typed checkbox data from your page or view model.

How to use:
  1. Create a typed list of CheckboxListInputItem<TValue> values in your code.
  2. Pass that list to the Items parameter.
  3. Bind the Values parameter to track which items are selected.
This demo shows how to populate the checkbox list from a strongly typed data collection.

Selected feature ids: 101, 103

<CheckboxListInput TValue="int"
                   Items="@featureItems"
                   @bind-Values="@selectedFeatureIds" />

<p class="mt-3">
    Selected feature ids: @(selectedFeatureIds.Count == 0 ? "None" : string.Join(", ", selectedFeatureIds))
</p>

@code {
    private readonly List<CheckboxListInputItem<int>> featureItems =
    [
        new(101, "Audit logs"),
        new(102, "API access"),
        new(103, "Dark theme"),
        new(104, "Offline mode")
    ];

    private List<int> selectedFeatureIds = [101, 103];
}

Sizes #

The CheckboxListInput component supports multiple sizes so you can match the list to the density and emphasis of the surrounding form layout.

How to use:
  1. Add the CheckboxListInput component with your typed items and selected values.
  2. Set Size to one of the available CheckboxListInputSize values: Small, Normal, Medium, or Large.
  3. Use the size that best fits the visual weight of the rest of your form.
This demo shows the available size variants for CheckboxListInput. 
<CheckboxListInput TValue="string"
                   Class="mb-4"
                   Items="@notificationItems"
                   Size="CheckboxListInputSize.Small"
                   @bind-Values="@smallValues" />

<CheckboxListInput TValue="string"
                   Class="mb-4"
                   Items="@notificationItems"
                   Size="CheckboxListInputSize.Normal"
                   @bind-Values="@normalValues" />

<CheckboxListInput TValue="string"
                   Class="mb-4"
                   Items="@notificationItems"
                   Size="CheckboxListInputSize.Medium"
                   @bind-Values="@mediumValues" />

<CheckboxListInput TValue="string"
                   Items="@notificationItems"
                   Size="CheckboxListInputSize.Large"
                   @bind-Values="@largeValues" />

@code {
    private readonly List<CheckboxListInputItem<string>> notificationItems =
    [
        new("builds", "Build notifications"),
        new("releases", "Release notifications"),
        new("alerts", "Alert notifications")
    ];

    private List<string> largeValues = ["releases"];
    private List<string> mediumValues = ["releases"];
    private List<string> normalValues = ["releases"];
    private List<string> smallValues = ["releases"];
}

Orientation #

The CheckboxListInput component can render checkboxes horizontally or vertically, depending on how much horizontal space you want each option to take.

How to use:
  1. Add the CheckboxListInput component with your typed items and selected values.
  2. Set Orientation to CheckboxListInputOrientation.Horizontal or CheckboxListInputOrientation.Vertical.
  3. Use the default horizontal layout for compact forms, or vertical for stacked lists.
This demo shows both supported orientation modes for CheckboxListInput. 
<CheckboxListInput TValue="string"
                   Class="mb-4"
                   Items="@taskItems"
                   Orientation="CheckboxListInputOrientation.Horizontal"
                   @bind-Values="@horizontalValues" />

<CheckboxListInput TValue="string"
                   Items="@taskItems"
                   Orientation="CheckboxListInputOrientation.Vertical"
                   @bind-Values="@verticalValues" />

@code {
    private readonly List<CheckboxListInputItem<string>> taskItems =
    [
        new("planning", "Planning"),
        new("design", "Design"),
        new("testing", "Testing")
    ];

    private List<string> horizontalValues = ["planning"];
    private List<string> verticalValues = ["planning"];
}

Disabled #

The CheckboxListInput component can be disabled to prevent user interaction while still displaying the current selections.

How to use:
  1. Add the CheckboxListInput component to your page.
  2. Set Disabled="true" to make the entire checkbox list non-interactive.
  3. Pass the same typed items and selected values as usual.
This demo shows how to render the entire checkbox list in a disabled state. 
<CheckboxListInput TValue="string"
                   Disabled="true"
                   Items="@environmentItems"
                   Values="@selectedEnvironments" />

@code {
    private readonly List<CheckboxListInputItem<string>> environmentItems =
    [
        new("dev", "Development"),
        new("test", "Testing"),
        new("prod", "Production")
    ];

    private readonly List<string> selectedEnvironments = ["dev", "test"];
}

Conditional disable individual checkboxes #

Individual checkbox items can be disabled by setting the Disabled property on specific CheckboxListInputItem<TValue> entries.

How to use:
  1. Create your item collection in code.
  2. Set Disabled = true only for the entries that should not be selectable.
  3. Pass the updated collection to the Items parameter.
This demo illustrates how to disable only selected checkbox items based on your application rules.

Selected permissions: read, export

<CheckboxListInput TValue="string"
                   Items="@permissionItems"
                   @bind-Values="@selectedPermissions" />

<p class="mt-3">
    Selected permissions: @(selectedPermissions.Count == 0 ? "None" : string.Join(", ", selectedPermissions))
</p>

@code {
    private readonly List<CheckboxListInputItem<string>> permissionItems =
    [
        new("read", "Read"),
        new("write", "Write"),
        new("delete", "Delete") { Disabled = true },
        new("export", "Export")
    ];

    private List<string> selectedPermissions = ["read", "export"];
}

Events: ValuesChanged #

The CheckboxListInput component exposes a ValuesChanged event, allowing you to react whenever the selected values list changes.

How to use:
  1. Set the Values parameter to the current selection list.
  2. Handle the ValuesChanged callback to update your page state when the selection changes.
  3. Use the updated values elsewhere in your UI as needed.
This demo shows how to handle selection changes through the ValuesChanged event.

Selected frameworks: Blazor, MAUI

<CheckboxListInput TValue="string"
                   Items="@frameworkItems"
                   Values="@selectedFrameworks"
                   ValuesChanged="OnValuesChanged" />

<p class="mt-3">@message</p>

@code {
    private readonly List<CheckboxListInputItem<string>> frameworkItems =
    [
        new("blazor", "Blazor"),
        new("minimal-api", "Minimal API"),
        new("maui", "MAUI"),
        new("worker", "Worker Service")
    ];

    private string message = "Selected frameworks: Blazor, MAUI";
    private List<string> selectedFrameworks = ["blazor", "maui"];

    private Task OnValuesChanged(List<string> values)
    {
        selectedFrameworks = values;
        message = values.Count == 0
            ? "Selected frameworks: None"
            : $"Selected frameworks: {string.Join(", ", values)}";

        return Task.CompletedTask;
    }
}

Custom item template #

The CheckboxListInput component supports an ItemTemplate parameter so you can render richer checkbox labels without replacing the component.

How to use:
  1. Pass your typed items to the Items parameter.
  2. Add an ItemTemplate block and use the current item context to render custom content.
  3. Keep the checkbox selection binding with Values or @bind-Values.
This demo shows how to customize each checkbox label with richer markup while keeping the built-in behavior.

Selected notifications: deployments, mentions

<CheckboxListInput TValue="string"
                   Items="@notificationItems"
                   @bind-Values="@selectedNotifications">
    <ItemTemplate Context="item">
        <span>
            <strong>@item.Text</strong>
            <span class="is-size-7 has-text-grey ml-2">@GetDescription(item.Value)</span>
        </span>
    </ItemTemplate>
</CheckboxListInput>

<p class="mt-3">
    Selected notifications: @(selectedNotifications.Count == 0 ? "None" : string.Join(", ", selectedNotifications))
</p>

@code {
    private readonly List<CheckboxListInputItem<string>> notificationItems =
    [
        new("deployments", "Deployments"),
        new("security", "Security alerts"),
        new("mentions", "Mentions")
    ];

    private List<string> selectedNotifications = ["deployments", "mentions"];

    private static string GetDescription(string value) =>
        value switch
        {
            "deployments" => "Production and staging release updates",
            "security" => "Critical dependency and access warnings",
            "mentions" => "Direct mentions from your teammates",
            _ => string.Empty
        };
}

Validations #

Integrate CheckboxListInput with Blazor's form validation system by using it inside an EditForm and binding the selected values to a model property with validation attributes.

How to use:
  1. Wrap the component in an EditForm and bind it to a model property with @bind-Values.
  2. Add DataAnnotationsValidator and a ValidationMessage for the same property.
  3. Use a validation attribute such as MinLength to require one or more selections.
This demo shows how to validate a checkbox list selection before form submission.
Choose at least one delivery day and submit the form.
@using System.ComponentModel.DataAnnotations
@using Microsoft.AspNetCore.Components.Forms

<style>
    .valid.modified:not([type=checkbox]) {
        border-color: hsl(var(--bulma-success-h), var(--bulma-success-s), var(--bulma-success-l)) !important;
        outline: 1px solid hsl(var(--bulma-success-h), var(--bulma-success-s), var(--bulma-success-l)) !important;
    }

    .invalid {
        border-color: hsl(var(--bulma-danger-h), var(--bulma-danger-s), var(--bulma-danger-l)) !important;
        outline: 1px solid hsl(var(--bulma-danger-h), var(--bulma-danger-s), var(--bulma-danger-l)) !important;
    }

    .validation-message {
        color: hsl(var(--bulma-danger-h), var(--bulma-danger-s), var(--bulma-danger-l)) !important;
    }
</style>

<EditForm EditContext="@editContext" OnValidSubmit="OnValidSubmit">
    <DataAnnotationsValidator />

    <div style="max-width: 24rem;">
        <CheckboxListInput TValue="string"
                           Items="@deliveryDayItems"
                           @bind-Values="subscription.DeliveryDays" />
        <ValidationMessage For="@(() => subscription.DeliveryDays)" />
    </div>

    <Button Class="mt-3" Color="ButtonColor.Primary" Type="ButtonType.Submit" Size="ButtonSize.Small">
        Submit
    </Button>
</EditForm>

<div class="mt-3">@resultMessage</div>

@code {
    private SubscriptionModel subscription = new();
    private EditContext? editContext;

    private string resultMessage = "Choose at least one delivery day and submit the form.";

    private readonly List<CheckboxListInputItem<string>> deliveryDayItems =
    [
        new("monday", "Monday"),
        new("wednesday", "Wednesday"),
        new("friday", "Friday")
    ];

    protected override void OnInitialized()
    {
        editContext = new EditContext(subscription);
        base.OnInitialized();
    }

    private void OnValidSubmit()
    {
        resultMessage = $"Submitted delivery days: {string.Join(", ", subscription.DeliveryDays)}";
    }

    private sealed class SubscriptionModel
    {
        [MinLength(1, ErrorMessage = "Please select at least one delivery day.")]
        public List<string> DeliveryDays { get; set; } = [];
    }
}

Methods: Select all and clear #

The CheckboxListInput component includes helper methods that are useful when you want to control selection programmatically.

How to use:
  1. Capture a component reference with @ref.
  2. Call SelectAllAsync() to select all enabled items.
  3. Call ClearAsync() to clear the current selection list.
This demo demonstrates programmatic selection helpers for common developer workflows.

Selected modules: billing

<div class="buttons">
    <Button Class="mt-3" Color="ButtonColor.Link" Type="ButtonType.Submit" Size="ButtonSize.Small" @onclick="SelectAllAsync">
        Select all
    </Button>
    <Button Class="mt-3" Color="ButtonColor.Light" Type="ButtonType.Submit" Size="ButtonSize.Small" @onclick="ClearAsync">
        Clear
    </Button>
</div>

<CheckboxListInput @ref="checkboxListInputRef"
                   TValue="string"
                   Items="@moduleItems"
                   Values="@selectedModules"
                   ValuesChanged="OnValuesChanged" />

<p class="mt-3">
    Selected modules: @(selectedModules.Count == 0 ? "None" : string.Join(", ", selectedModules))
</p>

@code {
    private CheckboxListInput<string> checkboxListInputRef = default!;

    private readonly List<CheckboxListInputItem<string>> moduleItems =
    [
        new("billing", "Billing"),
        new("catalog", "Catalog"),
        new("orders", "Orders"),
        new("reports", "Reports") { Disabled = true }
    ];

    private List<string> selectedModules = ["billing"];

    private Task ClearAsync() => checkboxListInputRef.ClearAsync();

    private Task OnValuesChanged(List<string> values)
    {
        selectedModules = values;
        return Task.CompletedTask;
    }

    private Task SelectAllAsync() => checkboxListInputRef.SelectAllAsync();
}
DO YOU KNOW?
This demo website is built using the BlazorExpress.Bulma library and published on the Azure Web App. See our source code on GitHub.
If you like BlazorExpress.Bulma, give it a star on GitHub!