Checkbox group
Select multiple options bound to a collection
<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: AddStellarAdminUI() 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")])" />Media
Put a <sa-checkbox-group-item-media> inside an item to show an icon, avatar, image or other media with the option. The media sits before the option's text, or leads the card in the choice card variant. Size the media with classes on its content. Use one media tag per item; options supplied with asp-items have no media. This example adds icons to plain options.
<sa-checkbox-group name="media-checkbox" values="@(["flight"])" label="Transport">
<sa-checkbox-group-item value="flight">
<sa-checkbox-group-item-media><sa-icon name="plane" /></sa-checkbox-group-item-media>
Flight
</sa-checkbox-group-item>
<sa-checkbox-group-item value="train">
<sa-checkbox-group-item-media><sa-icon name="train-front" /></sa-checkbox-group-item-media>
Train
</sa-checkbox-group-item>
<sa-checkbox-group-item value="ferry">
<sa-checkbox-group-item-media><sa-icon name="ship" /></sa-checkbox-group-item-media>
Ferry
</sa-checkbox-group-item>
</sa-checkbox-group>Columns
Set columns to show the options in columns at every width, or columns-sm, columns-md and columns-lg to set the number of columns once the field is at least 30rem, 40rem and 56rem wide; a width without a value uses the value of the next smaller width, and columns defaults to one column. The widths are measured against the field, so a group in a narrow column of an <sa-grid> stays in one column. The options fill each row in turn; set flow="CheckboxGroupFlow.Down" to fill each column from top to bottom before the next.
<sa-checkbox-group name="columns-checkbox" label="Trip extras" columns-sm="2" columns-lg="3"
flow="CheckboxGroupFlow.Down" values="@(["lounge", "transfer"])">
<sa-checkbox-group-item value="wifi">Wi-Fi on board</sa-checkbox-group-item>
<sa-checkbox-group-item value="lounge">Lounge access</sa-checkbox-group-item>
<sa-checkbox-group-item value="priority">Priority boarding</sa-checkbox-group-item>
<sa-checkbox-group-item value="baggage">Extra baggage</sa-checkbox-group-item>
<sa-checkbox-group-item value="seat">Seat selection</sa-checkbox-group-item>
<sa-checkbox-group-item value="insurance">Travel insurance</sa-checkbox-group-item>
<sa-checkbox-group-item value="transfer">Airport transfer</sa-checkbox-group-item>
</sa-checkbox-group>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 an element with role="group", named by the field label, around native checkbox inputs with associated labels. The group's description and validation message are associated with the group, and each option's description with its input. Set disabled="true" on the group or an item to disable it. Avoid interactive elements inside item labels. Media sits inside the label, so keep it decorative: an avatar without a name and an image with an empty alt leave the option text as its name.
API Reference
<sa-checkbox-group>
| Attribute | Type | Description |
|---|---|---|
asp-for | ModelExpression | Model property bound to the group. |
asp-items | IEnumerable<SelectListItem> | Options supplied instead of child tags. |
name | string | Submitted field name for an unbound group. |
values | IEnumerable<string> | Selected values for an unbound group. |
variant | CheckboxGroupVariant | Default or ChoiceCard. Defaults to Default. |
columns | int | Number of columns at the smallest width, from 1 to 12. Wider widths use this count unless they set their own. Defaults to 1. |
columns-sm | int | Number of columns once the field is at least 30rem wide. Defaults to the smaller width's value. |
columns-md | int | Number of columns once the field is at least 40rem wide. Defaults to the smaller width's value. |
columns-lg | int | Number of columns once the field is at least 56rem wide. Defaults to the smaller width's value. |
flow | CheckboxGroupFlow | Across or Down: the order in which the options fill the columns, when there is more than one. Defaults to Across. |
label | string | Group label; overrides model metadata. |
description | string | Supporting text; overrides model metadata. |
error | string | Explicit group error message. |
disabled | bool | Disables every option. Defaults to false. |
wrap-in-field | bool | Whether to wrap the group in a field with its label, description and error. By default it is wrapped when it has a label, description, error or bound property and isn't already inside a field. |
column-span | string | Number of columns the group spans in an <sa-grid>, from 1 to 12, or full. Defaults to 1. |
column-span-sm | string | Column span once the grid is at least 30rem wide. Defaults to the smaller width's value. |
column-span-md | string | Column span once the grid is at least 40rem wide. Defaults to the smaller width's value. |
column-span-lg | string | Column span once the grid is at least 56rem wide. Defaults to the smaller width's value. |
column-start | string | Column the group starts at in an <sa-grid>, from 1 to 12, or auto to follow the previous item. Defaults to auto. |
column-start-sm | string | Start column once the grid is at least 30rem wide. Defaults to the smaller width's value. |
column-start-md | string | Start column once the grid is at least 40rem wide. Defaults to the smaller width's value. |
column-start-lg | string | Start column once the grid is at least 56rem wide. Defaults to the smaller width's value. |
class-names | ChoiceGroupClassNames | Additional CSS classes for the parts of the group: Root, Label, Description, Error, Content, Control (the element that holds the options) and Item (each option). |
class | string | Additional classes for the element that holds the options. |
<sa-checkbox-group-item>
| Attribute | Type | Description |
|---|---|---|
value | string | Required submitted option value. Each option in a group needs a different value. |
description | string | Supporting text below the option label. |
disabled | bool | Disables this option. Defaults to false. |
class | string | Additional classes for the field, or the outer label in ChoiceCard. |
<sa-checkbox-group-item-media>
Media shown with an option, placed inside <sa-checkbox-group-item>. It renders no element of its own and takes no attributes; its content is placed in the option.