# Toggle Group

URL: https://ark-ui.com/docs/components/toggle-group
LLM: https://ark-ui.com/llms.txt/components/toggle-group

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

---



## Anatomy



```tsx
<ToggleGroup.Root>
  <ToggleGroup.Item />
</ToggleGroup.Root>
```

## Examples

```tsx
import { ToggleGroup } from '@ark-ui/react/toggle-group'
import { AlignCenterIcon, AlignJustifyIcon, AlignLeftIcon, AlignRightIcon } from 'lucide-react'
import styles from 'styles/toggle-group.module.css'

export const Basic = () => {
  return (
    <ToggleGroup.Root defaultValue={['left']} className={styles.Root}>
      <ToggleGroup.Item value="left" className={styles.Item}>
        <AlignLeftIcon />
      </ToggleGroup.Item>
      <ToggleGroup.Item value="center" className={styles.Item}>
        <AlignCenterIcon />
      </ToggleGroup.Item>
      <ToggleGroup.Item value="right" className={styles.Item}>
        <AlignRightIcon />
      </ToggleGroup.Item>
      <ToggleGroup.Item value="justify" className={styles.Item}>
        <AlignJustifyIcon />
      </ToggleGroup.Item>
    </ToggleGroup.Root>
  )
}
```

### Controlled

Use the `value` and `onValueChange` props to control the toggle group state.

```tsx
import { ToggleGroup } from '@ark-ui/react/toggle-group'
import { AlignCenterIcon, AlignJustifyIcon, AlignLeftIcon, AlignRightIcon } from 'lucide-react'
import { useState } from 'react'
import styles from 'styles/toggle-group.module.css'

export const Controlled = () => {
  const [value, setValue] = useState(['left'])
  return (
    <ToggleGroup.Root value={value} onValueChange={(e) => setValue(e.value)} className={styles.Root}>
      <ToggleGroup.Item value="left" className={styles.Item}>
        <AlignLeftIcon />
      </ToggleGroup.Item>
      <ToggleGroup.Item value="center" className={styles.Item}>
        <AlignCenterIcon />
      </ToggleGroup.Item>
      <ToggleGroup.Item value="right" className={styles.Item}>
        <AlignRightIcon />
      </ToggleGroup.Item>
      <ToggleGroup.Item value="justify" className={styles.Item}>
        <AlignJustifyIcon />
      </ToggleGroup.Item>
    </ToggleGroup.Root>
  )
}
```

### Root Provider

An alternative way to control the toggle group is to use the `RootProvider` component and the `useToggleGroup` hook.
This way you can access the state and methods from outside the component.

```tsx
import { ToggleGroup, useToggleGroup } from '@ark-ui/react/toggle-group'
import { AlignCenterIcon, AlignJustifyIcon, AlignLeftIcon, AlignRightIcon } from 'lucide-react'
import styles from 'styles/toggle-group.module.css'

export const RootProvider = () => {
  const toggleGroup = useToggleGroup({ defaultValue: ['left'] })

  return (
    <>
      <output>Set to Center: {String(toggleGroup.value)}</output>
      <ToggleGroup.RootProvider value={toggleGroup} className={styles.Root}>
        <ToggleGroup.Item value="left" className={styles.Item}>
          <AlignLeftIcon />
        </ToggleGroup.Item>
        <ToggleGroup.Item value="center" className={styles.Item}>
          <AlignCenterIcon />
        </ToggleGroup.Item>
        <ToggleGroup.Item value="right" className={styles.Item}>
          <AlignRightIcon />
        </ToggleGroup.Item>
        <ToggleGroup.Item value="justify" className={styles.Item}>
          <AlignJustifyIcon />
        </ToggleGroup.Item>
      </ToggleGroup.RootProvider>
    </>
  )
}
```

### Multiple

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

```tsx
import { ToggleGroup } from '@ark-ui/react/toggle-group'
import { BoldIcon, ItalicIcon, UnderlineIcon } from 'lucide-react'
import styles from 'styles/toggle-group.module.css'

export const Multiple = () => {
  return (
    <ToggleGroup.Root defaultValue={['bold']} multiple className={styles.Root}>
      <ToggleGroup.Item value="bold" className={styles.Item}>
        <BoldIcon />
      </ToggleGroup.Item>
      <ToggleGroup.Item value="italic" className={styles.Item}>
        <ItalicIcon />
      </ToggleGroup.Item>
      <ToggleGroup.Item value="underline" className={styles.Item}>
        <UnderlineIcon />
      </ToggleGroup.Item>
    </ToggleGroup.Root>
  )
}
```

### With Tooltip

Pair an item with a `Tooltip.Trigger` via `asChild`, matching their ids with `ids.item` and `ids.trigger` so they share
one element and tab stop.

```tsx
import { Portal } from '@ark-ui/react/portal'
import { ToggleGroup } from '@ark-ui/react/toggle-group'
import { Tooltip, useTooltip } from '@ark-ui/react/tooltip'
import { BoldIcon, ItalicIcon, UnderlineIcon } from 'lucide-react'
import styles from 'styles/toggle-group.module.css'
import tooltipStyles from 'styles/tooltip.module.css'

const items = [
  { value: 'bold', label: 'Bold', icon: <BoldIcon /> },
  { value: 'italic', label: 'Italic', icon: <ItalicIcon /> },
  { value: 'underline', label: 'Underline', icon: <UnderlineIcon /> },
]

const getTriggerId = (value?: string) => `toggle-item:${value}`

export const WithTooltip = () => {
  const tooltip = useTooltip({ ids: { trigger: getTriggerId } })

  return (
    <Tooltip.RootProvider value={tooltip}>
      <ToggleGroup.Root defaultValue={['bold']} ids={{ item: getTriggerId }} className={styles.Root}>
        {items.map((item) => (
          <ToggleGroup.Item key={item.value} value={item.value} aria-label={item.label} className={styles.Item} asChild>
            <Tooltip.Trigger value={item.value}>{item.icon}</Tooltip.Trigger>
          </ToggleGroup.Item>
        ))}
      </ToggleGroup.Root>
      <Portal>
        <Tooltip.Positioner>
          <Tooltip.Content className={tooltipStyles.Content}>
            {items.find((item) => item.value === tooltip.triggerValue)?.label}
          </Tooltip.Content>
        </Tooltip.Positioner>
      </Portal>
    </Tooltip.RootProvider>
  )
}
```

## API Reference

### Props

### Root

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

**`defaultValue`**
Type: `string[]`
Required: false
Default Value: `undefined`
Description: 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`**
Type: `boolean`
Required: false
Default Value: `true`
Description: Whether the toggle group allows empty selection.
**Note:** This is ignored if `multiple` is `true`.

**`disabled`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Whether the toggle is disabled.

**`id`**
Type: `string`
Required: false
Default Value: `undefined`
Description: The unique identifier of the machine.

**`ids`**
Type: `Partial<{ root: string; item: (value: string) => string }>`
Required: false
Default Value: `undefined`
Description: The ids of the elements in the toggle. Useful for composition.

**`loopFocus`**
Type: `boolean`
Required: false
Default Value: `true`
Description: Whether to loop focus inside the toggle group.

**`multiple`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Whether to allow multiple toggles to be selected.

**`onValueChange`**
Type: `(details: ValueChangeDetails) => void`
Required: false
Default Value: `undefined`
Description: Function to call when the toggle is clicked.

**`orientation`**
Type: `Orientation`
Required: false
Default Value: `"horizontal"`
Description: The orientation of the toggle group.

**`rovingFocus`**
Type: `boolean`
Required: false
Default Value: `true`
Description: Whether to use roving tab index to manage focus.

**`value`**
Type: `string[]`
Required: false
Default Value: `undefined`
Description: The controlled selected value of the toggle group.

#### Data Attributes

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

**`value`**
Type: `string`
Required: true
Default Value: `undefined`
Description: undefined

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

**`disabled`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: undefined

#### Data Attributes

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

**`value`**
Type: `UseToggleGroupReturn`
Required: true
Default Value: `undefined`
Description: undefined

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### Context

**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

**`Tab`**
Description: Moves focus to either the pressed item or the first item in the group.

**`Space`**
Description: Activates/deactivates the item.

**`Enter`**
Description: Activates/deactivates the item.

**`ArrowDown`**
Description: Moves focus to the next item in the group.

**`ArrowRight`**
Description: Moves focus to the next item in the group.

**`ArrowUp`**
Description: Moves focus to the previous item in the group.

**`ArrowLeft`**
Description: Moves focus to the previous item in the group.

**`Home`**
Description: Moves focus to the first item.

**`End`**
Description: Moves focus to the last item.