Skip to main content

ToggleGroup & ToggleButton

A ToggleButton stays pressed until it's pressed again: Bold in an editor, a favorite, mute. A ToggleGroup is a row of them, with one pressed (type="single") or any number (type="multiple"). The names follow shadcn/ui and Radix.

import { ToggleButton, ToggleGroup, ToggleGroupItem } from 'patine-ui';
Loading…
<Box border radius="md" padding="sm" gap="sm">
  <HStack gap="sm" wrap>
    <ToggleGroup
      type="multiple"
      attached
      variant="outline"
      size="sm"
      value={marks}
      onValueChange={setMarks}
      aria-label="Text style"
      items={[
        { value: 'bold', icon: <Icon name="bold" size="sm" />, accessibilityLabel: 'Bold' },
        { value: 'italic', icon: <Icon name="italic" size="sm" />, accessibilityLabel: 'Italic' },
        { value: 'underline', icon: <Icon name="underline" size="sm" />, accessibilityLabel: 'Underline' },
      ]}
    />
    <ToggleGroup
      type="single"
      size="sm"
      value={align}
      onValueChange={(next) => next && setAlign(next)}
      aria-label="Alignment"
      items={[
        { value: 'left', label: 'Left' },
        { value: 'center', label: 'Center' },
        { value: 'right', label: 'Right' },
      ]}
    />
    <ToggleButton size="sm" variant="outline" defaultPressed startIcon={<Icon name="star" size="sm" />}>Starred</ToggleButton>
  </HStack>
  <Separator />
  <Text
    style={{
      textAlign: align,
      fontWeight: marks.includes('bold') ? '700' : '400',
      fontStyle: marks.includes('italic') ? 'italic' : 'normal',
      textDecorationLine: marks.includes('underline') ? 'underline' : 'none',
    }}
  >
    The quick brown fox jumps over the lazy dog.
  </Text>
</Box>

Try the props​

Props
variant
size
orientation
design
<ToggleGroup
type="single"
items={alignments}
value={align}
onValueChange={setAlign}
/>

Example: map layers​

A city guide's map filters: each button turns a kind of place on or off, any number at a time, and the list follows. Turning them all off says so instead of showing nothing.

Loading…
<VStack gap="sm" style={{ width: '100%', maxWidth: 420 }}>
  <ToggleGroup
    type="multiple"
    variant="outline"
    size="sm"
    value={kinds}
    onValueChange={setKinds}
    aria-label="Show on map"
    items={[
      { value: 'coffee', label: 'Coffee', icon: <Icon name="coffee" size="sm" /> },
      { value: 'museum', label: 'Museums', icon: <Icon name="building" size="sm" /> },
      { value: 'food', label: 'Food', icon: <Icon name="store" size="sm" /> },
    ]}
  />
  {shown.length ? (
    <List>
      {shown.map((p) => (
        <ListItem key={p.name} leading={<Icon name={ICON[p.kind]} />} title={p.name} description={p.meta} onPress={() => {}} />
      ))}
    </List>
  ) : (
    <Text color="textSecondary">Pick a kind of place to see it on the map.</Text>
  )}
</VStack>

ToggleButton​

pressed and onPressedChange make it controlled; defaultPressed sets where it starts. It takes Button's size, startIcon, endIcon and disabled.

Props
variant
size
design
<ToggleButton defaultPressed>Starred</ToggleButton>

Single or multiple​

type="single" keeps at most one pressed, like a radio group the user can clear: onValueChange gets the value, or null when the pressed one is pressed again. To always keep one, ignore null (as the alignment above does), or use a SegmentedControl. type="multiple" gets an array.

Items or children​

items is the short way. When an item needs more, pass ToggleGroupItem children; they take ToggleButton's props and a value.

Loading…
<ToggleGroup type="single" defaultValue="grid" variant="outline" attached aria-label="View">
  <ToggleGroupItem value="list" size="icon" accessibilityLabel="List view">
    <Icon name="layoutList" />
  </ToggleGroupItem>
  <ToggleGroupItem value="grid" size="icon" accessibilityLabel="Grid view">
    <Icon name="layoutGrid3" />
  </ToggleGroupItem>
</ToggleGroup>

Designs​

  • brand: clear until pressed, then a soft primary tint.
  • iOS: a gray button that turns tinted, as UIKit's tinted buttons do.
  • Material 3: tonal when off, filled with the primary color when on; attached leaves a 2pt gap and softens the inner corners, as its connected button groups do.
  • web: shadcn's Toggle: ghost when off, a muted fill when on.

Accessibility​

  • A single group is a radiogroup of radio items with a checked state; a multiple group is a group of buttons with a pressed state. A lone ToggleButton is a button with pressed.
  • Give icon-only items an accessibilityLabel, and the group an aria-label.
  • On the web, Tab reaches the group, arrow keys move between items, and Space or Enter presses one. Touch targets stay at least 44pt on phones.

Props​

ToggleGroup​

PropTypeDefaultDescription
type'single' | 'multiple'—One pressed at most, or any number. Required.
items{ value, label?, icon?, accessibilityLabel?, disabled? }[]—The buttons, as data. Or pass ToggleGroupItem children.
valuestring | null (single), string[] (multiple)—Controlled value.
defaultValuesame as value—Initial value when uncontrolled.
onValueChange(value) => void—Called when the user presses an item.
variant'default' | 'outline''default'Outline draws a border either way.
size'sm' | 'default' | 'lg' | 'icon''default'Button size.
attachedbooleanfalseJoins the buttons into one bar.
orientation'horizontal' | 'vertical''horizontal'Row or column.
disabledbooleanfalseDisables every item.
themeDeepPartial<Theme>—Theme override.
designDesignfrom PatineProviderThe look to follow.

ToggleButton​

PropTypeDefaultDescription
pressedboolean—Controlled state.
defaultPressedbooleanfalseInitial state when uncontrolled.
onPressedChange(pressed: boolean) => void—Called when the user presses it.
variant'default' | 'outline''default'Outline draws a border either way.
size'sm' | 'default' | 'lg' | 'icon''default'As Button.
startIcon, endIconReactNode—Beside the label.
disabledbooleanfalseDims it and blocks presses.
style, labelStyleStyleProp—The box and the label.
theme, designAs every component.

ToggleGroupItem takes ToggleButton's props, without the pressed state, and a required value.