Toggle group

Installation#

pnpm dlx shadcn@latest add @zui/toggle-group

The CLI writes components/ui/toggle-group.tsx, installs Toggle, Text, Icon and Utils, and adds @rn-primitives/toggle-group and class-variance-authority.

Usage#

import { useState } from 'react';

import { Text } from '@/components/ui/text';
import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group';

const [align, setAlign] = useState<string | undefined>('left');

<ToggleGroup type="single" value={align} onValueChange={setAlign} variant="outline" spacing={0}>
  <ToggleGroupItem value="left">
    <Text>Left</Text>
  </ToggleGroupItem>
  <ToggleGroupItem value="center">
    <Text>Center</Text>
  </ToggleGroupItem>
  <ToggleGroupItem value="right">
    <Text>Right</Text>
  </ToggleGroupItem>
</ToggleGroup>;

The items must be the group's direct children. A group with spacing={0} rounds only its first and last item, and it finds them among its children, so an item wrapped in another component loses its place.

API reference#

ToggleGroup#

Takes every prop of the @rn-primitives/toggle-group root, plus:

The group is controlled. Pressing an item calls onValueChange with a string or undefined in single mode and an array in multiple mode, and the item draws as pressed once value follows. It is announced as a radio group in single mode and as a group in multiple mode. disabled disables every item. spacing is a step of the spacing scale, so 2 is an 8px gap and 0 joins the items into one bar. The group's variant and size go over the item's own.

ToggleGroupItem#

Takes every prop of the @rn-primitives/toggle-group item, plus variant and size, which apply when the group sets none. It is announced as a radio in single mode and as a checkbox in multiple mode, with its checked and disabled state. Its label is a Text child, and an Icon child takes a 16px size. An icon-only item is named with aria-label.