# React Native ButtonGroup

> A React Native ButtonGroup for iOS, Android and the web: related buttons joined into one bar, across or down, with shared edges, or Material 3's connected button group with a gap and soft inner corners.

# ButtonGroup

Related [buttons](./button) joined into one bar: only the outer corners round, and touching borders overlap into one line. Use it for actions that belong together, like paging or a split of Save and its options.

```tsx
import { ButtonGroup } from 'patine-ui';
```

```tsx live
import { Button, ButtonGroup, HStack } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

export default function Example() {
  const [page, setPage] = React.useState(3);
  return (
    <HStack gap="md" wrap>
      <ButtonGroup variant="outline" aria-label="Pages">
        <Button startIcon={<Icon name="chevronLeft" size="sm" />} onPress={() => setPage((p) => Math.max(1, p - 1))}>Prev</Button>
        <Button disabled>{`Page ${page}`}</Button>
        <Button endIcon={<Icon name="chevronRight" size="sm" />} onPress={() => setPage((p) => p + 1)}>Next</Button>
      </ButtonGroup>
      <ButtonGroup aria-label="Merge">
        <Button>Merge pull request</Button>
        <Button size="icon" accessibilityLabel="More merge options">
          <Icon name="chevronDown" color="onPrimary" />
        </Button>
      </ButtonGroup>
    </HStack>
  );
}
```

## Example: zoom controls

An image preview: zoom out, the current zoom (press it to go back to 100%) and zoom in sit in one group, each end disabled at its limit.

```tsx live
import { useState } from 'react';
import { Image, View } from 'react-native';
import { Button, ButtonGroup, HStack, VStack } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

const STEPS = [50, 75, 100, 150, 200];

export default function Example() {
  const [step, setStep] = useState(2);
  const zoom = STEPS[step];
  return (
    <VStack gap="md" style={{ width: '100%', maxWidth: 420 }}>
      <View style={{ height: 200, borderRadius: 12, overflow: 'hidden', alignItems: 'center', justifyContent: 'center', backgroundColor: '#0F172A' }}>
        <Image
          source={{ uri: 'https://picsum.photos/id/1043/600/400' }}
          style={{ width: 300, height: 200, transform: [{ scale: zoom / 100 }] }}
          accessibilityLabel="A mountain lake"
        />
      </View>
      <HStack justify="center">
        <ButtonGroup variant="outline" size="sm" aria-label="Zoom">
          <Button size="icon" accessibilityLabel="Zoom out" disabled={step === 0} onPress={() => setStep(step - 1)}>
            <Icon name="zoomOut" />
          </Button>
          <Button accessibilityLabel={`Zoom ${zoom}%, reset`} onPress={() => setStep(2)}>{`${zoom}%`}</Button>
          <Button size="icon" accessibilityLabel="Zoom in" disabled={step === STEPS.length - 1} onPress={() => setStep(step + 1)}>
            <Icon name="zoomIn" />
          </Button>
        </ButtonGroup>
      </HStack>
    </VStack>
  );
}
```

## Variant and size

`variant` and `size` on the group pass to each button that doesn't set its own, so one button can still stand out.

## Down

`orientation="vertical"` stacks the buttons, and they stretch to the widest.

```tsx live
import { Button, ButtonGroup } from 'patine-ui';

export default function Example() {
  return (
    <ButtonGroup orientation="vertical" variant="outline" style={{ width: 220 }} aria-label="Export">
      <Button>Export as PDF</Button>
      <Button>Export as CSV</Button>
      <Button>Export as JSON</Button>
    </ButtonGroup>
  );
}
```

## Designs

brand, iOS and web join the buttons edge to edge. Material 3 leaves a 2pt gap and softens the inner corners to 8pt, as its connected button groups do.

## Accessibility

The bar is a `group`; name it with `aria-label`. Each button keeps its own role, label, focus ring and 44pt touch target.

## Props

Also takes `View` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `Button` elements | — | The buttons, joined. |
| `variant` | `ButtonVariant` | — | Passed to each Button that doesn't set its own. |
| `size` | `ButtonSize` | — | Passed to each Button that doesn't set its own. |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Across or down. |
| `theme` | `DeepPartial<Theme>` | — | Theme override. |
| `design` | `Design` | from `PatineProvider` | The look to follow. |
