Toggle Group

A set of two-state buttons that can be toggled on or off. Implements proper keyboard navigation and ARIA attributes to ensure accessibility. Suitable for creating groups of related toggle buttons where users can select one or multiple options.

Full keyboard navigation

Supports horizontal/vertical orientation

Support single and multiple pressed buttons

Can be controlled or uncontrolled

Example

Architecture

sc-toggle-group-root
Slot: default
sc-toggle-group-item
Slot: default

Reference

  • Root

    The root container that manages the state and behavior of the toggle group system. Coordinates the interaction between toggle items and implements proper ARIA attributes for accessibility support.

    • Attributes

      • aria-label
        string
        /
        default: -

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

      • aria-labelled-by
        string
        /
        default: -

        References the ID of the element that labels the toggle group.

      • default-value
        string[]
        /
        default: -

        The initial pressed state of items when the toggle group is rendered. Use when you do not need to control the pressed state.

      • direction
        enum
        /
        default: ltr

        The reading direction of the toggle group. Affects the layout and keyboard navigation behavior.

      • disabled
        boolean
        /
        default: false

        When true, prevents the user from interacting with the toggle group and all its items.

      • id
        string
        /
        default: -

        ID that is forwarded to the underlying container for DOM manipulation.

      • loop
        boolean
        /
        default: true

        When true, keyboard navigation will loop from last item to first and vice versa.

      • orientation
        enum
        /
        default: horizontal

        The orientation of the toggle group. Affects layout and keyboard navigation behavior.

      • roving-focus
        boolean
        /
        default: true

        When true, implements a roving tab index pattern for keyboard navigation between items.

      • type
        enum
        /
        default: single

        Determines whether one or multiple items can be pressed simultaneously.

      • value
        string[]
        /
        default: -

        The controlled pressed state of items. Must be used in conjunction with onValueChange.

    • Events

      • onValueChange

        Event handler called when the pressed state of any toggle item changes.

    • Classes

      • direction-rtl

        Applied when the reading direction is right-to-left.

      • disabled

        Applied when the toggle group is in a disabled state.

      • orientation-vertical

        Applied when the toggle group orientation is vertical.

  • Item

    An individual toggle button within the group. Manages its own pressed state while coordinating with the group's overall state management. Implements proper ARIA attributes for accessibility support.

    • Attributes

      • aria-label
        string
        /
        default: -

        Defines an accessible label for the toggle item when a visible label is not present. Essential for proper screen reader identification.

      • aria-labelled-by
        string
        /
        default: -

        References the ID of the element that labels the toggle group item.

      • disabled
        boolean
        /
        default: false

        When true, prevents the user from interacting with this specific toggle item.

      • id
        string
        /
        default: -

        ID that is forwarded to the underlying element for DOM manipulation.

      • value
        string
        /
        default: -

        A unique identifier for the item. Used to track and control the pressed state within the toggle group.

    • Classes

      • disabled

        Applied when the toggle item is in a disabled state.

      • pressed

        Applied when the toggle item is in a pressed state.

Keyboard

  • Space

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

  • Enter

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

  • When orientation is vertical, moves focus to the next item in the group.

  • When orientation is vertical, moves focus to the previous item in the group.

  • When orientation is horizontal, moves focus to the next item in ltr or to the previous item in rtl.

  • When orientation is horizontal, moves focus to the previous item in ltr or to the next item in rtl.

  • Home

    Moves focus to the first item in the toggle group.

  • End

    Moves focus to the last item in the toggle group.

made for toddle