Checkbox Group

A component that manages a collection of related checkbox inputs, allowing users to select multiple options from a set of choices. Provides coordinated selection behavior and accessibility features for grouped checkbox interactions.

Supports multiple selections

Full keyboard navigation

Can be controlled or uncontrolled

Architecture

so-checkbox-group
Slot: default
so-checkbox-group-item
Slot: default
so-checkbox-group-description
Slot: default

Reference

  • Checkbox Group

    The root container that manages the state and behavior of the checkbox group system. Coordinates the interaction between individual checkbox items and maintains the overall selection state.

    • Attributes

      • aria-label
        string
        /
        default: -

        Defines an accessible label for the checkbox group when a visible label is not present.

      • default-value
        string[]
        /
        default: -

        The initial selected values when the checkbox group is rendered. Use when you do not need to control the selection state.

      • value
        string[]
        /
        default: -

        The controlled selected values of the checkbox group. Must be used in conjunction with onValueChange.

    • Events

      • onValueChange

        Event handler called when the selection state of any checkbox group changes.

  • Item

    The container for an individual selectable option. Manages the selection state and visual presentation of a single choice within the group.

    • Attributes

      • aria-label
        string
        /
        default: -

        Defines an accessible label for the individual checkbox group item when a visible label is not present or when additional context is needed.

      • disabled
        boolean
        /
        default: false

        When true, prevents the user from interacting with the checkbox group item.

      • value
        string
        /
        default: -

        A unique identifier for the checkbox group item. Used to track and control the selection state.

  • Description

    The container for descriptive text that provides additional context or information about the checkbox group item.

Keyboard

  • Tab

    Moves focus to either the checked item or the first item in the group.

  • Space

    When focus is on an item, toggles its checked state.

  • Enter

    When focus is on an item, toggles its checked state.

  • Moves focus to the next item in the group.

  • Moves focus to the previous item in the group.

  • Home

    Moves focus to the first item in the group.

  • End

    Moves focus to the last item in the group.

made for toddle