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';
<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
variantsizeorientationdesign<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.
<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.
variantsizedesign<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.
<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;
attachedleaves 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
radiogroupofradioitems with acheckedstate; a multiple group is agroupof buttons with apressedstate. A lone ToggleButton is a button withpressed. - Give icon-only items an
accessibilityLabel, and the group anaria-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
| Prop | Type | Default | Description |
|---|---|---|---|
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. |
value | string | null (single), string[] (multiple) | — | Controlled value. |
defaultValue | same 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. |
attached | boolean | false | Joins the buttons into one bar. |
orientation | 'horizontal' | 'vertical' | 'horizontal' | Row or column. |
disabled | boolean | false | Disables every item. |
theme | DeepPartial<Theme> | — | Theme override. |
design | Design | from PatineProvider | The look to follow. |
ToggleButton
| Prop | Type | Default | Description |
|---|---|---|---|
pressed | boolean | — | Controlled state. |
defaultPressed | boolean | false | Initial 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, endIcon | ReactNode | — | Beside the label. |
disabled | boolean | false | Dims it and blocks presses. |
style, labelStyle | StyleProp | — | The box and the label. |
theme, design | As every component. |
ToggleGroupItem takes ToggleButton's props, without the pressed state, and a required value.