Checkbox group

<sa-checkbox-group name="intro-checkbox" values="@(["insurance"])" label="Extras">
    <sa-checkbox-group-item value="insurance" description="Protection for your parcel">Insurance</sa-checkbox-group-item>
    <sa-checkbox-group-item value="gift" description="A reusable gift box">Gift packaging</sa-checkbox-group-item>
</sa-checkbox-group>

Usage

Prefer a checkbox group when selected options should bind to one array or collection. Use a normal checkbox for an individual boolean property.

Use <sa-checkbox-group> with <sa-checkbox-group-item> children to render a labeled group. Each item uses its content as the label and accepts an optional description. Both display variants use the existing Field and Input markup.

Use asp-for for model binding, or name and values for a group without model binding. Option value attributes are strings, including values such as value="1" that bind to numeric properties. MVC converts submitted values to the model type. Values must be unique within the group.

Examples

Model binding

Bind to an array or a collection of strings, enums, GUIDs, booleans, or numeric primitives. Supported collection types include List<T>, IList<T>, ICollection<T>, IEnumerable<T>, IReadOnlyList<T>, and IReadOnlyCollection<T>. Nullable value-type elements, byte[], sets, and immutable collections are not supported. Clearing every checkbox binds an empty collection: AddTagHelpers() registers the binder that handles the hidden group-presence marker.

Labels and descriptions are derived from [Display] metadata. Submitted ModelState values take precedence when redisplaying the form. Do not combine asp-for with name or values. Date/time and complex model types are not supported.

<sa-checkbox-group asp-for="Extras">
    <sa-checkbox-group-item value="1" description="Protection for your parcel">Insurance</sa-checkbox-group-item>
    <sa-checkbox-group-item value="2" description="A reusable gift box">Gift packaging</sa-checkbox-group-item>
    <sa-checkbox-group-item value="3" disabled="true">Same-day delivery (unavailable)</sa-checkbox-group-item>
</sa-checkbox-group>

The example binds to this model property:

[Display(Name = "Extras", Description = "Choose extras, or clear every checkbox and save.")]
[MaxLength(2, ErrorMessage = "Choose at most two extras.")]
public int[] Extras { get; set; } = [1, 2];

In a Razor Page, expose the containing model with [BindProperty] to receive form submissions. These exported previews demonstrate the rendered state; the DocsSamples application contains the working POST form.

Choice cards

Set variant="CheckboxGroupVariant.ChoiceCard" to make each option a clickable card. The default is CheckboxGroupVariant.Default.

<sa-checkbox-group name="choicecards-checkbox" values="@(["insurance"])" label="Extras" variant="CheckboxGroupVariant.ChoiceCard">
    <sa-checkbox-group-item value="insurance" description="Protection for your parcel">Insurance</sa-checkbox-group-item>
    <sa-checkbox-group-item value="gift" description="A reusable gift box">Gift packaging</sa-checkbox-group-item>
</sa-checkbox-group>

Items

Use asp-items with SelectListItem objects as an alternative to child tags. Selected sets the initial selection for an unbound group when values is not supplied. Disabled disables an individual option. Do not combine asp-items with child items; SelectListGroup is not supported.

<sa-checkbox-group name="items-checkbox" label="Options"
    asp-items="@([new SelectListItem("First option", "first", true), new SelectListItem("Second option", "second")])" />

Validation

The group displays one ModelState error and marks its inputs invalid. StellarAdmin does not provide client-side validation; use server-side validation or add your own client validation.

<sa-checkbox-group asp-for="Extras">
    <sa-checkbox-group-item value="1" description="Protection for your parcel">Insurance</sa-checkbox-group-item>
    <sa-checkbox-group-item value="2" description="A reusable gift box">Gift packaging</sa-checkbox-group-item>
</sa-checkbox-group>

Use validation attributes on the bound property:

[MinLength(1, ErrorMessage = "Choose at least one extra.")]
public int[] Extras { get; set; } = [];

This preview is rendered with an empty selection and a seeded ModelState error. Its partial is rendered with the PartialModel prefix, so the error uses the full field name:

ModelState.AddModelError("PartialModel.Extras", "Choose at least one extra.");

For an unbound group, use error to display a group error.

Accessibility

The group renders a fieldset and legend with native checkbox inputs and associated labels. Descriptions and validation messages are associated with the inputs. Set disabled="true" on the group or an item to disable it. Avoid interactive elements inside item labels.

API Reference

<sa-checkbox-group>

<sa-checkbox-group-item>