Skip to main content
Kaleidoscope

ToggleGroup

A card containing a primary toggle that controls a group of related toggle items.

Default

<ToggleGroup /> renders a with a primary toggle for the group and individual toggles for each item. Toggling the group toggle typically toggles all items on or off.

Editable example
() => {
  const [groupOn, setGroupOn] = React.useState(true)
  const [items, setItems] = React.useState([
    { id: "1", label: "Email notifications", value: true },
    { id: "2", label: "Push notifications", value: true },
  ])

  const handleGroupToggle = () => {
    const newValue = !groupOn
    setGroupOn(newValue)
    setItems(items.map((item) => ({ ...item, value: newValue })))
  }

  const handleItemToggle = (id) => {
    setItems(items.map((item) => (item.id === id ? { ...item, value: !item.value } : item)))
  }

  return (
    <div style={{ maxWidth: 350 }}>
      <ToggleGroup
        name="Notifications"
        on={groupOn}
        items={items}
        onGroupToggle={handleGroupToggle}
        onItemToggle={handleItemToggle}
      />
    </div>
  )
}

Disabled

Use the disabled prop to prevent interaction with the group and all its items.

Editable example
() => {
  return (
    <div style={{ maxWidth: 350 }}>
      <ToggleGroup
        name="Notifications"
        on={true}
        disabled
        items={[
          { id: "1", label: "Email notifications", value: true },
          { id: "2", label: "Push notifications", value: false },
        ]}
        onGroupToggle={() => {}}
        onItemToggle={() => {}}
      />
    </div>
  )
}

Best practices

  1. Use ToggleGroup to manage a set of related on/off settings that share a common category — for example, notification channels or feature flags.
  2. Keep the name prop descriptive of the category the items belong to.
  3. When the group toggle is switched off, consider toggling all child items off too for a consistent user experience.
  4. For "select all" patterns where items use checkboxes rather than toggles, consider using a with the "mixed" (indeterminate) state instead — it better communicates that only some children are selected.

Accessibility

  • Each toggle within the group is a standard with its own label, so each item is individually accessible.