---
title: Group
description: A component for visually grouping a series of controls.
---

<ComponentPreview name="p-group-1" />

## Installation

<CodeTabs>

<TabsList>
  <TabsTab value="cli">CLI</TabsTab>
  <TabsTab value="manual">Manual</TabsTab>
</TabsList>
<TabsPanel value="cli">

```bash
npx shadcn@latest add @coss/group
```

</TabsPanel>

<TabsPanel value="manual">

<Steps>

<Step>Install the following dependencies:</Step>

```bash
npm install @base-ui/react
```

<Step>Copy and paste the following code into your project.</Step>

<ComponentSource name="group" title="components/ui/group.tsx" />

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

</Steps>

</TabsPanel>

</CodeTabs>

## Usage

```tsx
import { Button } from "@/components/ui/button"
import { Group, GroupSeparator } from "@/components/ui/group"
```

```tsx
<Group>
  <Button>Button</Button>
  <GroupSeparator />
  <Button>Button</Button>
</Group>
```

## Accessibility

- The `Group` component has the `role` attribute set to `group`.
- Use `Tab` to navigate between the controls in the group.
- Use `aria-label` or `aria-labelledby` to label the group.

```tsx showLineNumbers
<Group aria-label="Media controls">
  <Button variant="outline">Play</Button>
  <GroupSeparator />
  <Button variant="outline">Pause</Button>
</Group>
```

### Group vs ToggleGroup

- Use the `Group` component when you want to group controls that perform an action.
- Use the `ToggleGroup` component when you want to group controls that toggle a state.

## API Reference

### Group

The `Group` component is a container that visually groups a series of related controls together with consistent styling.

| Prop          | Type                         | Default        |
| ------------- | ---------------------------- | -------------- |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |

```tsx
<Group>
  <Button>Button 1</Button>
  <GroupSeparator />
  <Button>Button 2</Button>
</Group>
```

Nest multiple groups to create complex layouts with spacing. See the [nested groups](#nested-groups) example for more details.

```tsx
<Group>
  <Group>
    <Button>1</Button>
    <GroupSeparator />
    <Button>2</Button>
  </Group>
  <Group>
    <Button>Previous</Button>
    <GroupSeparator />
    <Button>Next</Button>
  </Group>
</Group>
```

### GroupSeparator

The `GroupSeparator` component visually divides controls within a group.

| Prop          | Type                         | Default      |
| ------------- | ---------------------------- | ------------ |
| `orientation` | `"horizontal" \| "vertical"` | `"vertical"` |

```tsx
<Group>
  <Button>Button 1</Button>
  <GroupSeparator />
  <Button>Button 2</Button>
</Group>
```

**Note:** Unlike shadcn's ButtonGroup, `GroupSeparator` is required between all controls, including outline buttons. This ensures consistent visual hierarchy and focus states.

### GroupText

Use this component to display text within a group, such as labels or prefixes.

| Prop     | Type                       | Default |
| -------- | -------------------------- | ------- |
| `render` | `React.ReactNode \| null` | `null`  |

```tsx
<Group>
  <GroupText>https://</GroupText>
  <GroupSeparator />
  <Input placeholder="example.com" />
</Group>
```

Use the `render` prop to render a custom component as the text, for example a label.

```tsx
<Group>
  <GroupText render={<Label htmlFor="domain" aria-label="Domain" />}>
    https://
  </GroupText>
  <GroupSeparator />
  <Input id="domain" placeholder="example.com" />
</Group>
```

## Examples

### With Input

<ComponentPreview name="p-group-2" />

### Small Size

<ComponentPreview name="p-group-3" />

### Large Size

<ComponentPreview name="p-group-4" />

### With Disabled Button

<ComponentPreview name="p-group-5" />

### With Default Buttons

<ComponentPreview name="p-group-6" />

### With Start Labeled Text

<ComponentPreview name="p-group-7" />

### With End Text

<ComponentPreview name="p-group-8" />

### Vertical

<ComponentPreview name="p-group-9" />

### Nested Groups

<ComponentPreview name="p-group-10" />

### With Popup

<ComponentPreview name="p-group-11" />

### With Input Group

<ComponentPreview name="p-group-12" />

### With Menu

<ComponentPreview name="p-group-13" />

### With Select

<ComponentPreview name="p-group-14" />