Alert Avatar AvatarGroup Button ButtonGroup Checkbox CheckboxGroup FilePicker Form FormRow Hamburger Input Modal Option Radio RadioGroup Rating Select Spinner Textarea Toast Tooltip Toggle

CheckboxGroup

Use a CheckboxGroup to group multiple Checkbox components for a predictable layout and the ability to two-way bind a value array value coupled to which radio button is value.

Example

Use bind:value to two-way bind a reactive array of value items.

<script>
  import { CheckboxGroup, Checkbox } from '$lib/ui';
  let toppings = $state(['pepperoni']);
</script>

<CheckboxGroup bind:value={toppings}>
  <Checkbox label="Pepperoni" value="pepperoni" />
  <Checkbox label="Olives" value="olives" />
  <Checkbox label="Tomatoes" value="tomatoes" />
</CheckboxGroup>

<p>Toppings: {toppings}</p>

Pepperoni Olives Tomatoes

Toppings: pepperoni

Label

Use the label prop to set a label for the CheckboxGroup. This will be rendered as a <label> element and will be styled like the label elements on other form components.

<CheckboxGroup label="Beer Options">
  <Checkbox label="Pilsner" />
  <Checkbox label="India Pale Ale" />
  <Checkbox label="Stout" />
</CheckboxGroup>

Beer Options Pilsner India Pale Ale Stout

Name

If a name prop is set, it will be applied to all child Checkbox components for proper form submission.

<CheckboxGroup name="beer">
  <Checkbox label="Pilsner" value="pilsner" />
  <Checkbox label="India Pale Ale" value="ipa" />
  <Checkbox label="Stout" value="stout" />
</CheckboxGroup>

Pilsner India Pale Ale Stout

Error

Display error message below the checkboxes. Also adds error styles.

<CheckboxGroup label="Bands" error="You must select at least two">
  <Checkbox label="Bauhaus" />
  <Checkbox label="The Cure" />
  <Checkbox label="The Smiths" />
</CheckboxGroup>

Bands Bauhaus The Cure The Smiths

You must select at least two

Note

A note prop let’s you define a note displayed below the field.

<CheckboxGroup label="Favorite Band" note="Choose as many as you like">
  <Checkbox label="Bauhaus" />
  <Checkbox label="The Cure" />
  <Checkbox label="The Smiths" />
</CheckboxGroup>

Favorite Band Bauhaus The Cure The Smiths

Choose as many as you like

Legend Named Slot

Instead of using the label prop which can only be a String, a label named slot can be used for a label with more complex content.

<CheckboxGroup>
  <label slot="label"><CocktailIcon /> Cocktails</label>
  <Checkbox label="Martini" />
  <Checkbox label="Gimlet" />
</CheckboxGroup>

Cocktails Martini Gimlet

CheckboxGroup Component Props

Name	Type	Description
`bind:value`	Array	Two-way binded array of value items
`label`	String	Text label appears before CheckboxGroup
`name`	String	The `name` property to be inherited by all child Checkbox components
`error`	String	The error note displayed
`note`	String	The help note displayed
`class`	String	CSS classes declared in global scope can be applied to the outermost element
`...`		Additional props will be passed through to the HTML element enabling support for things like `on:click`, etc

To style a CheckboxGroup, use Checkbox CSS Style Props like --ui-checkbox-border-color. These can be passed to the CheckboxGroup and will be inherited by child Checkboxes.

CheckboxGroup Named Slots

Name	Description
`label`	Content to be used for label before CheckboxGroup (supercedes `label` property)