# React Native ToggleGroup and ToggleButton

> Accessible React Native toggle buttons for iOS, Android and the web: ToggleButton (shadcn Toggle) and ToggleGroup with single or multiple selection, attached toolbars, icons, keyboard support and a brand, iOS, Material 3 or web design.

# 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.

```tsx
import { ToggleButton, ToggleGroup, ToggleGroupItem } from 'patine-ui';
```

```tsx live
import { Box, Separator, Text, ToggleButton, ToggleGroup, HStack } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

export default function Example() {
  const [marks, setMarks] = React.useState(['bold']);
  const [align, setAlign] = React.useState('left');
  return (
    <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>
  );
}
```

## 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.

```tsx live
import { useState } from 'react';
import { List, ListItem, Text, ToggleGroup, VStack } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

const PLACES = [
  { name: 'Café Kobalt', kind: 'coffee', meta: '4 min walk' },
  { name: 'Rijksmuseum', kind: 'museum', meta: '9 min walk' },
  { name: 'Foodhallen', kind: 'food', meta: '12 min walk' },
  { name: 'Lot Sixty One', kind: 'coffee', meta: '6 min walk' },
  { name: 'Eye Film Museum', kind: 'museum', meta: 'Ferry, 15 min' },
] as const;
const ICON = { coffee: 'coffee', museum: 'building', food: 'store' } as const;

export default function Example() {
  const [kinds, setKinds] = useState<string[]>(['coffee', 'museum']);
  const shown = PLACES.filter((p) => kinds.includes(p.kind));
  return (
    <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`.

## 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](./segmented-control). `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`.

```tsx live
import { ToggleGroup, ToggleGroupItem } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

export default function Example() {
  return (
    <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

| 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`.
