# Toggle Group

URL: https://ark-ui.com/docs/components/toggle-group
Source: https://raw.githubusercontent.com/chakra-ui/ark/refs/heads/main/website/src/content/pages/components/toggle-group.mdx

A set of two-state buttons that can be toggled on or off.

---

<ComponentPreview id="ToggleGroup" />

## Anatomy

To set up the toggle group correctly, you'll need to understand its anatomy and how we name its parts.

> Each part includes a `data-part` attribute to help identify them in the DOM.

<Anatomy id="toggle-group" />

## Examples

Learn how to use the `ToggleGroup` component in your project. Let's take a look at the most basic example:

<Example id="basic" />

### Multiple Selection

Demonstrates how to enable `multiple` selection within the group.

<Example id="multiple" />

### Initial Value

Shows how to set an initial value in the toggle group.

<Example id="initial-value" />

### Using the Root Provider

The `RootProvider` component provides a context for the toggle-group. It accepts the value of the `useToggle-group`
hook. You can leverage it to access the component state and methods from outside the toggle-group.

<Example id="root-provider" />

> If you're using the `RootProvider` component, you don't need to use the `Root` component.

## API Reference

### Props

**Component API Reference**

#### React

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `defaultValue` | `string[]` | No | The initial selected value of the toggle group when rendered.
Use when you don't need to control the selected value of the toggle group. |
| `deselectable` | `boolean` | No | Whether the toggle group allows empty selection.
**Note:** This is ignored if `multiple` is `true`. |
| `disabled` | `boolean` | No | Whether the toggle is disabled. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{ root: string; item: (value: string) => string }>` | No | The ids of the elements in the toggle. Useful for composition. |
| `loopFocus` | `boolean` | No | Whether to loop focus inside the toggle group. |
| `multiple` | `boolean` | No | Whether to allow multiple toggles to be selected. |
| `onValueChange` | `(details: ValueChangeDetails) => void` | No | Function to call when the toggle is clicked. |
| `orientation` | `Orientation` | No | The orientation of the toggle group. |
| `rovingFocus` | `boolean` | No | Whether to use roving tab index to manage focus. |
| `value` | `string[]` | No | The controlled selected value of the toggle group. |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | toggle-group |
| `[data-part]` | root |
| `[data-disabled]` | Present when disabled |
| `[data-orientation]` | The orientation of the toggle-group |
| `[data-focus]` | Present when focused |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `string` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `disabled` | `boolean` | No |  |


**Item Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | toggle-group |
| `[data-part]` | item |
| `[data-focus]` | Present when focused |
| `[data-disabled]` | Present when disabled |
| `[data-orientation]` | The orientation of the item |
| `[data-state]` | "on" | "off" |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseToggleGroupReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


#### Solid

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `defaultValue` | `string[]` | No | The initial selected value of the toggle group when rendered.
Use when you don't need to control the selected value of the toggle group. |
| `deselectable` | `boolean` | No | Whether the toggle group allows empty selection.
**Note:** This is ignored if `multiple` is `true`. |
| `disabled` | `boolean` | No | Whether the toggle is disabled. |
| `ids` | `Partial<{ root: string; item: (value: string) => string }>` | No | The ids of the elements in the toggle. Useful for composition. |
| `loopFocus` | `boolean` | No | Whether to loop focus inside the toggle group. |
| `multiple` | `boolean` | No | Whether to allow multiple toggles to be selected. |
| `onValueChange` | `(details: ValueChangeDetails) => void` | No | Function to call when the toggle is clicked. |
| `orientation` | `Orientation` | No | The orientation of the toggle group. |
| `rovingFocus` | `boolean` | No | Whether to use roving tab index to manage focus. |
| `value` | `string[]` | No | The controlled selected value of the toggle group. |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | toggle-group |
| `[data-part]` | root |
| `[data-disabled]` | Present when disabled |
| `[data-orientation]` | The orientation of the toggle-group |
| `[data-focus]` | Present when focused |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `string` | Yes |  |
| `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `disabled` | `boolean` | No |  |


**Item Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | toggle-group |
| `[data-part]` | item |
| `[data-focus]` | Present when focused |
| `[data-disabled]` | Present when disabled |
| `[data-orientation]` | The orientation of the item |
| `[data-state]` | "on" | "off" |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseToggleGroupReturn` | Yes |  |
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


#### Vue

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `defaultValue` | `string[]` | No | The initial selected value of the toggle group when rendered.
Use when you don't need to control the selected value of the toggle group. |
| `deselectable` | `boolean` | No | Whether the toggle group allows empty selection.
**Note:** This is ignored if `multiple` is `true`. |
| `disabled` | `boolean` | No | Whether the toggle is disabled. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{ root: string; item(value: string): string }>` | No | The ids of the elements in the toggle. Useful for composition. |
| `loopFocus` | `boolean` | No | Whether to loop focus inside the toggle group. |
| `modelValue` | `string[]` | No | The v-model value of the toggle group |
| `multiple` | `boolean` | No | Whether to allow multiple toggles to be selected. |
| `orientation` | `Orientation` | No | The orientation of the toggle group. |
| `rovingFocus` | `boolean` | No | Whether to use roving tab index to manage focus. |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | toggle-group |
| `[data-part]` | root |
| `[data-disabled]` | Present when disabled |
| `[data-orientation]` | The orientation of the toggle-group |
| `[data-focus]` | Present when focused |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `string` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `disabled` | `boolean` | No |  |


**Item Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | toggle-group |
| `[data-part]` | item |
| `[data-focus]` | Present when focused |
| `[data-disabled]` | Present when disabled |
| `[data-orientation]` | The orientation of the item |
| `[data-state]` | "on" | "off" |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `ToggleGroupApi<PropTypes>` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


#### Svelte

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `defaultValue` | `string[]` | No | The initial selected value of the toggle group when rendered.
Use when you don't need to control the selected value of the toggle group. |
| `deselectable` | `boolean` | No | Whether the toggle group allows empty selection.
**Note:** This is ignored if `multiple` is `true`. |
| `disabled` | `boolean` | No | Whether the toggle is disabled. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{ root: string; item: (value: string) => string }>` | No | The ids of the elements in the toggle. Useful for composition. |
| `loopFocus` | `boolean` | No | Whether to loop focus inside the toggle group. |
| `multiple` | `boolean` | No | Whether to allow multiple toggles to be selected. |
| `onValueChange` | `(details: ValueChangeDetails) => void` | No | Function to call when the toggle is clicked. |
| `orientation` | `Orientation` | No | The orientation of the toggle group. |
| `ref` | `Element` | No |  |
| `rovingFocus` | `boolean` | No | Whether to use roving tab index to manage focus. |
| `value` | `string[]` | No | The controlled selected value of the toggle group. |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | toggle-group |
| `[data-part]` | root |
| `[data-disabled]` | Present when disabled |
| `[data-orientation]` | The orientation of the toggle-group |
| `[data-focus]` | Present when focused |


**Context Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `render` | `Snippet<[UseToggleGroupContext]>` | Yes |  |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `string` | Yes |  |
| `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `disabled` | `boolean` | No |  |
| `ref` | `Element` | No |  |


**Item Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | toggle-group |
| `[data-part]` | item |
| `[data-focus]` | Present when focused |
| `[data-disabled]` | Present when disabled |
| `[data-orientation]` | The orientation of the item |
| `[data-state]` | "on" | "off" |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseToggleGroupReturn` | Yes |  |
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


### Context

These are the properties available when using `UtoggleUgroup.Context`, `useUtoggleUgroupContext` hook or `useUtoggleUgroup` hook.

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `value` | `string[]` | The value of the toggle group. |
| `setValue` | `(value: string[]) => void` | Sets the value of the toggle group. |
| `getItemState` | `(props: ItemProps) => ItemState` | Returns the state of the toggle item. |


## Accessibility

### Keyboard Support

<KeyBindingsTable id="toggle-group" />