Toggle group

A toggle group is a row of choices that reads as a single control. Build it from items, and say which one is on with value.

Basic group

toggleGroup({
  label: 'Text alignment',
  value: 'center',
  items: [
    { value: 'left', label: 'Left' },
    { value: 'center', label: 'Center' },
    { value: 'right', label: 'Right' },
  ],
})

Plain strings

toggleGroup({ label: 'Density', value: 'comfortable', items: ['compact', 'comfortable', 'spacious'] })

Links

This is the form a static site usually wants: each segment is a page. Items with an href render as anchors and the active one is marked aria-current="page" — not aria-pressed, because a link is not a button you have pushed in.

Docs UI Examples

toggleGroup({
  label: 'Section',
  value: 'ui',
  items: [
    { value: 'docs', label: 'Docs', href: '/docs' },
    { value: 'ui', label: 'UI', href: '/ui' },
    { value: 'examples', label: 'Examples', href: '/examples' },
  ],
})

More than one on

Pass an array as value. The container is a plain group either way — a radiogroup would be wrong, since these are pressed buttons rather than radios.

toggleGroup({
  label: 'Formatting',
  value: ['bold', 'underline'],
  items: [
    { value: 'bold', label: 'Bold' },
    { value: 'italic', label: 'Italic' },
    { value: 'underline', label: 'Underline' },
  ],
})

Sizes and variants

stack({ gap: 'md' },
  toggleGroup({ size: 'sm', label: 'Small', value: 'a', items: ['a', 'b', 'c'] }),
  toggleGroup({ size: 'md', label: 'Medium', value: 'a', items: ['a', 'b', 'c'] }),
  toggleGroup({ size: 'lg', label: 'Large', value: 'a', items: ['a', 'b', 'c'] }),
  toggleGroup({ variant: 'ghost', label: 'Ghost', value: 'b', items: ['a', 'b', 'c'] }),
)

Disabled items

toggleGroup({
  label: 'Renderer',
  value: 'static',
  items: [
    { value: 'static', label: 'Static' },
    { value: 'islands', label: 'Islands' },
    { value: 'ssr', label: 'SSR', disabled: true },
  ],
})

stack({ direction: 'row', gap: 'md', wrap: true, align: 'center' },
  toggleGroup({ label: 'Alignment', value: 'Left', size: 'sm', items: ['Left', 'Center', 'Right'] }),
  divider({ orientation: 'vertical' }),
  toggleGroup({ label: 'Style', value: ['Bold'], size: 'sm', items: ['Bold', 'Italic'] }),
)

When to use something else

If the choice is submitted with a form, use choiceGroup() — real radios, no script needed. If each segment is a page, prefer the link form above. A toggle group is for a choice the page itself acts on.

Props

Prop	Type	Default	Description
`items`	`Array`	`[]`	Strings, or { value, label, href, disabled } objects.
`value`	`string \| number \| Array`	—	Which item is on. An array when several can be.
`label`	`string`	—	Accessible name for the group.
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Applied to every item.
`variant`	`'outline' \| 'ghost' \| 'soft'`	`'outline'`	How an item that is off looks.