Toggle Group

A set of toggle buttons where one or several can be pressed.

Usage

import { ToggleGroup } from '@appica/ui-react/toggle-group'
import { Toggle } from '@appica/ui-react/toggle'
import { Button } from '@appica/ui-react/button'

<ToggleGroup aria-label="Text alignment" defaultValue={['center']}>
  <Toggle
    value="left"
    aria-label="Align left"
    render={
      <Button variant="ghost" size="icon-md">
        <AlignLeft />
      </Button>
    }
  />
  <Toggle
    value="center"
    aria-label="Align center"
    render={
      <Button variant="ghost" size="icon-md">
        <AlignCenter />
      </Button>
    }
  />
  <Toggle
    value="right"
    aria-label="Align right"
    render={
      <Button variant="ghost" size="icon-md">
        <AlignRight />
      </Button>
    }
  />
</ToggleGroup>

ToggleGroup lays out a row of Toggles and tracks which ones are pressed as a string array of their values. It's single-select by default — pressing one toggle releases the previous — and becomes multi-select with the multiple prop, where any number of toggles can stay pressed at once. Drive it uncontrolled with defaultValue, or controlled with value + onValueChange.

Toggle ships no styling of its own, so give each one a look by composing it with Button through render={<Button … />} — Button already reacts to data-pressed, so the pressed state comes for free. Because a toggle group is a role="group" rather than a labelable form control, name it with aria-label or aria-labelledby — never with a <Field>/FieldLabel.

Examples

Single selection

By default the group is single-select: pressing a toggle releases whichever one was pressed before, so exactly one stays active.

import { Button } from '@appica/ui-react/button'
import { Toggle } from '@appica/ui-react/toggle'
import { ToggleGroup } from '@appica/ui-react/toggle-group'
import { AlignLeft, AlignCenter, AlignRight } from '@appica/icons-react'

export default function ToggleGroupSingle() {
  return (
    <ToggleGroup aria-label="Text alignment" defaultValue={['center']}>
      <Toggle
        value="left"
        aria-label="Align left"
        render={
          <Button variant="ghost" size="icon-md">
            <AlignLeft />
          </Button>
        }
      />
      <Toggle
        value="center"
        aria-label="Align center"
        render={
          <Button variant="ghost" size="icon-md">
            <AlignCenter />
          </Button>
        }
      />
      <Toggle
        value="right"
        aria-label="Align right"
        render={
          <Button variant="ghost" size="icon-md">
            <AlignRight />
          </Button>
        }
      />
    </ToggleGroup>
  )
}

Multiple selection

Add multiple to let several toggles stay pressed at once — handy for independent formatting options like bold, italic, and underline.

import { Button } from '@appica/ui-react/button'
import { Toggle } from '@appica/ui-react/toggle'
import { ToggleGroup } from '@appica/ui-react/toggle-group'
import { Bold, Italic, Underline } from '@appica/icons-react'

export default function ToggleGroupMultiple() {
  return (
    <ToggleGroup aria-label="Text formatting" multiple defaultValue={['bold']}>
      <Toggle
        value="bold"
        aria-label="Bold"
        render={
          <Button variant="ghost" size="icon-md">
            <Bold />
          </Button>
        }
      />
      <Toggle
        value="italic"
        aria-label="Italic"
        render={
          <Button variant="ghost" size="icon-md">
            <Italic />
          </Button>
        }
      />
      <Toggle
        value="underline"
        aria-label="Underline"
        render={
          <Button variant="ghost" size="icon-md">
            <Underline />
          </Button>
        }
      />
    </ToggleGroup>
  )
}

Vertical orientation

Set orientation="vertical" to stack the toggles in a column. Arrow-key focus follows the same axis.

import { Button } from '@appica/ui-react/button'
import { Toggle } from '@appica/ui-react/toggle'
import { ToggleGroup } from '@appica/ui-react/toggle-group'
import { AlignLeft, AlignCenter, AlignRight } from '@appica/icons-react'

export default function ToggleGroupVertical() {
  return (
    <ToggleGroup aria-label="Text alignment" orientation="vertical" defaultValue={['left']}>
      <Toggle
        value="left"
        aria-label="Align left"
        render={
          <Button variant="ghost" size="icon-md">
            <AlignLeft />
          </Button>
        }
      />
      <Toggle
        value="center"
        aria-label="Align center"
        render={
          <Button variant="ghost" size="icon-md">
            <AlignCenter />
          </Button>
        }
      />
      <Toggle
        value="right"
        aria-label="Align right"
        render={
          <Button variant="ghost" size="icon-md">
            <AlignRight />
          </Button>
        }
      />
    </ToggleGroup>
  )
}

Disabled

Set disabled on the group to disable every toggle inside it at once.

import { Button } from '@appica/ui-react/button'
import { Toggle } from '@appica/ui-react/toggle'
import { ToggleGroup } from '@appica/ui-react/toggle-group'
import { AlignLeft, AlignCenter, AlignRight } from '@appica/icons-react'

export default function ToggleGroupDisabled() {
  return (
    <ToggleGroup aria-label="Text alignment" disabled defaultValue={['center']}>
      <Toggle
        value="left"
        aria-label="Align left"
        render={
          <Button variant="ghost" size="icon-md">
            <AlignLeft />
          </Button>
        }
      />
      <Toggle
        value="center"
        aria-label="Align center"
        render={
          <Button variant="ghost" size="icon-md">
            <AlignCenter />
          </Button>
        }
      />
      <Toggle
        value="right"
        aria-label="Align right"
        render={
          <Button variant="ghost" size="icon-md">
            <AlignRight />
          </Button>
        }
      />
    </ToggleGroup>
  )
}

Color swatches (controlled)

A controlled single-select group, used as a color picker. Here the toggles aren't button-shaped, so they're styled directly rather than composed with Button — each bare Toggle is a 16px circular swatch carrying its color, and the pressed one gets an offset border-inverse ring. Driving it with value + onValueChange keeps the selection in state, which the label above reads to name the current color.

Color - Sage

'use client'

import * as React from 'react'
import { Toggle } from '@appica/ui-react/toggle'
import { ToggleGroup } from '@appica/ui-react/toggle-group'

const SWATCHES = [
  { value: 'sage', name: 'Sage', color: '#8fb478' },
  { value: 'terracotta', name: 'Terracotta', color: '#cc8259' },
  { value: 'sand', name: 'Sand', color: '#d9ba6e' },
  { value: 'blush', name: 'Blush', color: '#db9385' },
  { value: 'denim', name: 'Denim', color: '#7e9cc9' },
]

export default function ToggleGroupSwatches() {
  const [value, setValue] = React.useState(['sage'])
  const selected = SWATCHES.find((swatch) => swatch.value === value[0])

  return (
    <div className="flex flex-col items-start gap-3">
      <span className="text-foreground-muted text-sm">
        Color - <span className="text-foreground-intense font-medium">{selected?.name}</span>
      </span>
      <ToggleGroup
        aria-label="Swatch color"
        className="gap-3"
        value={value}
        onValueChange={(next) => next.length > 0 && setValue(next)}
      >
        {SWATCHES.map((swatch) => (
          <Toggle
            key={swatch.value}
            value={swatch.value}
            aria-label={swatch.name}
            style={{ backgroundColor: swatch.color }}
            className="after:ring-border-inverse outline-ring relative size-4 rounded-full outline-offset-2 transition-transform after:pointer-events-none after:absolute after:-inset-0.5 after:scale-50 after:rounded-full after:opacity-0 after:ring-1 after:transition after:duration-200 after:ease-[cubic-bezier(0.175,0.885,0.32,1.5)] active:scale-90 data-pressed:after:scale-100 data-pressed:after:opacity-100 motion-reduce:transition-none motion-reduce:after:transition-none"
          />
        ))}
      </ToggleGroup>
    </div>
  )
}

RTL

Every Appica UI component supports right-to-left layouts out of the box. Set the dir attribute on a container (commonly your <html> element) so CSS logical properties resolve correctly, and wrap your tree in DirectionProvider so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.

import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}

The toggles align to the start edge and arrow-key focus follows the resolved direction, so the first toggle sits on the right under RTL. For setup details and caveats, see the RTL guide.

API reference

ToggleGroup wraps Base UI's Toggle Group, renders with role="group", and forwards ref and every remaining <div> attribute. Its children are Toggles — each needs a value and an accessible name. To present a standalone toolbar, pass role="toolbar" yourself (don't nest one inside Toolbar, which is already a toolbar).

Prop	Type	Default	Description
`value`	`string[]`	—	The pressed toggles' `value`s, for controlled use. Pair with `onValueChange`.
`defaultValue`	`string[]`	—	The initially pressed toggles, for uncontrolled use.
`onValueChange`	`(value: string[], eventDetails) => void`	—	Called when the pressed set changes, with the new array of `value`s.
`multiple`	`boolean`	`false`	Allow several toggles to be pressed at once. When `false`, pressing one releases the previous (single-select).
`orientation`	`'horizontal' \| 'vertical'`	`'horizontal'`	Layout axis and the direction arrow keys move focus. Exposed as `data-orientation`.
`loopFocus`	`boolean`	`true`	Whether arrow-key focus wraps around from the last toggle to the first and back.
`disabled`	`boolean`	`false`	Disable every toggle in the group.
`render`	`ReactElement \| ((props, state) => ReactElement)`	—	Replace the rendered element, or compose it with another component.
`className`	`string \| ((state) => string)`	—	Extra classes, merged via `tailwind-merge`. May be a function of state.

Accessibility

The group renders as a role="group", so name it with aria-label or aria-labelledby — not a <Field>/FieldLabel, whose <label for> doesn't associate with a group.
Arrow keys move focus between toggles via roving tabindex (the row has a single tab stop), following the group's orientation; loopFocus controls whether focus wraps at the ends.
Space or Enter toggles the focused button, which exposes its pressed state through aria-pressed.
Setting disabled on the group disables all of its toggles, removing them from the tab order.

Actions & Inputs

Data Display

Decoration & Effects

Layout

Menus

Navigation

Overlays

Status & Feedback