# Button Group

Groups related buttons into a single visual unit for React Native apps running on Android and iOS via Expo.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).

<DocsBaseSwitcher base="native" component="button-group" />

<ComponentPreview name="native/button-group" src="../../apps/native/registry/button-group.tsx" title="button-group.tsx">
<Component />
</ComponentPreview>

A `View` wrapper that lays out children in a row (`horizontal`, default) or a column (`vertical`). Each direct child is cloned to strip the shared border and radius on the inner edges, so adjacent buttons read as a single unit. Outer corners keep their full radius.

## Installation [#installation]

<CodeTabs>
<TabsList>
<TabsTrigger value="cli">
Command
</TabsTrigger>

<TabsTrigger value="manual">
Manual
</TabsTrigger>
</TabsList>

<TabsContent value="cli">
```bash
npx frakment add button-group --expo
```
</TabsContent>

<TabsContent value="manual">
<Steps>
<Step>
Install the following dependencies:
</Step>

```bash
npm install class-variance-authority clsx tailwind-merge lucide-react-native
```

<Step>
Configure NativeWind in your Expo project.
</Step>

Skip this step if your project already uses NativeWind v5. The project needs a `babel.config.js` with `babel-preset-expo`, a `metro.config.js` wrapped with `withNativewind`, and a `global.css` that imports `tailwindcss/theme.css`, `tailwindcss/utilities.css`, and `nativewind/theme`. Import `global.css` in the root layout.

<Step>
Copy `lib/utils.ts` into your project.
</Step>

<ComponentSource src="../../apps/native/lib/utils.ts" title="lib/utils.ts" />

<Step>
Copy `lib/theme.ts` into your project.
</Step>

<ComponentSource src="../../apps/native/lib/theme.ts" title="lib/theme.ts" />

<Step>
Copy `separator` into your project.
</Step>

Button Group imports Separator. Install it first from the [Separator](/docs/components/native/separator) page.

<Step>
Copy the button group into your project.
</Step>

<ComponentSource src="../../apps/native/registry/button-group.tsx" title="components/ui/button-group.tsx" />

<Step>
Update the import paths to match your project setup.
</Step>
</Steps>
</TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx title="button-group.tsx"
import { Button } from "@/components/ui/button";
import { ButtonGroup } from "@/components/ui/button-group";
```

```tsx title="button-group.tsx"
<ButtonGroup>
  <Button variant="outline">Archive</Button>
  <Button variant="outline">Report</Button>
</ButtonGroup>
```

## Orientation [#orientation]

<ComponentPreview name="native/button-group-orientation" title="button-group-orientation.tsx" src="../../apps/native/examples/button-group-orientation.tsx">
<l />
</ComponentPreview>

Pass `orientation="vertical"`. Children stack in a column. Inner edges lose their border and radius the same way they do in a horizontal group, so the column reads as a single unit.

## Size [#size]

<ComponentPreview name="native/button-group-size" title="button-group-size.tsx" src="../../apps/native/examples/button-group-size.tsx">
<h />
</ComponentPreview>

`ButtonGroup` has no `size` prop. Each child `Button` keeps its own height from the `size` prop documented on the [Button](/docs/components/native/button#size) page.

The preview above renders at the web size scale. On iOS and Android the child button applies the larger dp values.

| Child `size` | Height |
| :--- | :--- |
| `xs` | 40dp |
| `sm` | 44dp |
| `default` | 48dp |
| `lg` | 51dp |

Icon-only children use the icon size system. Width matches height.

| Child icon `size` | Dimensions |
| :--- | :--- |
| `icon-xs` | 40×40 |
| `icon-sm` | 44×44 |
| `icon` | 48×48 |
| `icon-lg` | 51×51 |

The group does not enforce size. Mixing `sm`, `default`, and `lg` inside the same group is allowed. Inner edges lose border and radius regardless of child size.

## Separator [#separator]

<ComponentPreview name="native/button-group-separator" title="button-group-separator.tsx" src="../../apps/native/examples/button-group-separator.tsx">
<d />
</ComponentPreview>

`ButtonGroupSeparator` renders a transparent 1dp gap between adjacent children, letting the page background show through. Use it when two actions should read as distinct units without a visible divider line.

## Split [#split]

<ComponentPreview name="native/button-group-split" title="button-group-split.tsx" src="../../apps/native/examples/button-group-split.tsx">
<o />
</ComponentPreview>

Combine a labeled action with a related icon-only action inside one group. The separator gives each half its own tap target while the group reads as a single unit.

## API Reference [#api-reference]

### ButtonGroup [#buttongroup]

<PropsTable rows={[{"name":"orientation","type":"horizontal | vertical","default":"horizontal","description":"Layout direction of the group."},{"name":"className","type":"string","description":"Additional NativeWind classes merged with the group classes."},{"name":"style","type":"ViewStyle","description":"Inline style override, merged after the computed group style."}]} />

### ButtonGroupText [#buttongrouptext]

<PropsTable rows={[{"name":"children","type":"ReactNode","description":"String or number children are wrapped in Text with the group foreground color. Other children render as-is."},{"name":"className","type":"string","description":"Additional NativeWind classes."},{"name":"style","type":"ViewStyle","description":"Inline style override."}]} />

### ButtonGroupSeparator [#buttongroupseparator]

Renders a transparent gap between adjacent children. Applies `marginVertical: 1` and stretches to the group height. Accepts every `Separator` prop.

## Accessibility [#accessibility]

- Each child button keeps its own `accessibilityRole="button"` and `accessibilityState`. The group does not override them.
- Icon-only children should set `accessibilityLabel`. The group does not synthesize one.
- Visual size equals tap area. Groups of `xs` and `sm` buttons fall below the 44dp iOS minimum. Prefer `default` or `lg` for touch-critical actions.

## Best Practices [#best-practices]

- **Group actions that belong to the same task.** Archive and Report belong together. Archive and Delete do not.
- **Keep group size uniform.** Mixing `sm` and `lg` inside a group reads as a bug, not a feature.
- **Use `ButtonGroupSeparator` sparingly.** The default border merge is enough for most cases.
- **Nested groups need the outer `ButtonGroup`.** The outer wrapper adds the gap between inner groups and keeps the composition readable.

## Platform notes [#platform-notes]

- **Border merge is inline.** Native does not have CSS child selectors. `ButtonGroup` clones its direct children and sets `borderRadius` and `borderWidth` on the inner edges. This works for `Button`, `ButtonGroupText`, and any child that accepts a `style` prop.
- **Dropdown, Input, Input Group, and Select demos are web-only for now.** The web Button Group page shows those compositions. Native ports are pending. The `ButtonGroup` API is identical and works with any child that renders a tappable surface.
- **The hero example uses three nested groups.** The web hero includes a dropdown trigger inside the third group. Native renders a plain button there because DropdownMenu is not ported yet. The nesting and group composition are otherwise identical.
- **Separator is transparent on native.** The web `ButtonGroupSeparator` renders `bg-input` (a subtle divider line). Native drops the line and lets the page background show through, so the gap reads as a darker separation in dark mode and a subtle one in light mode. The layout matches web: 1dp wide, stretched to the group height, with 1dp vertical margin.

## Related Components [#related-components]

- [Button](/docs/components/native/button): the base button used inside groups
- [Separator](/docs/components/native/separator): the divider used between buttons
- [Theming](/docs/guides/theming): customize colors and borders