# Toggle Group

A set of two-state buttons that can be toggled on (pressed) or off (not pressed).

## Import

```
Copyts
import { ToggleGroup } from "@kobalte/core/toggle-group";
// or
import { Root, Item, ... } from "@kobalte/core/toggle-group";
// or (deprecated)
import { ToggleGroup } from "@kobalte/core";
```

```
Copyts
import { ToggleGroup } from "@kobalte/core/toggle-group";
// or
import { Root, Item, ... } from "@kobalte/core/toggle-group";
// or (deprecated)
import { ToggleGroup } from "@kobalte/core";
```

## Features

- Supports horizontal/vertical orientation.
- Keyboard event support for `Space` and `Enter` keys.
- Can be controlled or uncontrolled.

## Anatomy

The toggle group consists of:

- **ToggleGroup:** the root container for a toggle group.

The toggle item consists of:

- **ToggleGroup.Item:** the root container for a toggle button.

```
Copytsx
<ToggleGroup>
	<ToggleGroup.Item />
</ToggleGroup>
```

```
Copytsx
<ToggleGroup>
	<ToggleGroup.Item />
</ToggleGroup>
```

## Example

BoldItalicUnderline

index.tsxstyle.css

```
Copytsx
import {ToggleButton} from "@kobalte/core/toggle-group";
import {BoldIcon, ItalicIcon, UnderlineIcon} from "some-icon-library";
import "./style.css";

  <ToggleGroup class="toggle-group">
    <ToggleGroup.Item class="toggle-group__item" value="bold" aria-label="Bold">
      <BoldIcon/>
    </ToggleGroup.Item>
    <ToggleGroup.Item class="toggle-group__item" value="italic" aria-label="Italic">
      <ItalicIcon/>
    </ToggleGroup.Item>
    <ToggleGroup.Item class="toggle-group__item" value="underline" aria-label="Underline">
      <UnderlineIcon/>
    </ToggleGroup.Item>
  </ToggleGroup>
```

```
Copytsx
import {ToggleButton} from "@kobalte/core/toggle-group";
import {BoldIcon, ItalicIcon, UnderlineIcon} from "some-icon-library";
import "./style.css";

  <ToggleGroup class="toggle-group">
    <ToggleGroup.Item class="toggle-group__item" value="bold" aria-label="Bold">
      <BoldIcon/>
    </ToggleGroup.Item>
    <ToggleGroup.Item class="toggle-group__item" value="italic" aria-label="Italic">
      <ItalicIcon/>
    </ToggleGroup.Item>
    <ToggleGroup.Item class="toggle-group__item" value="underline" aria-label="Underline">
      <UnderlineIcon/>
    </ToggleGroup.Item>
  </ToggleGroup>
```

## Usage

### Default pressed

An initial, uncontrolled value can be provided using the `defaultValue` prop.

BoldItalicUnderline

```
Copytsx
<ToggleGroup defaultValue="underline">
	<ToggleGroup.Item value="bold" aria-label="Bold">
		<BoldIcon />
	</ToggleGroup.Item>
	<ToggleGroup.Item value="italic" aria-label="Italic">
		<ItalicIcon />
	</ToggleGroup.Item>
	<ToggleGroup.Item value="underline" aria-label="Underline">
		<UnderlineIcon />
	</ToggleGroup.Item>
</ToggleGroup>
```

```
Copytsx
<ToggleGroup defaultValue="underline">
	<ToggleGroup.Item value="bold" aria-label="Bold">
		<BoldIcon />
	</ToggleGroup.Item>
	<ToggleGroup.Item value="italic" aria-label="Italic">
		<ItalicIcon />
	</ToggleGroup.Item>
	<ToggleGroup.Item value="underline" aria-label="Underline">
		<UnderlineIcon />
	</ToggleGroup.Item>
</ToggleGroup>
```

### Controlled pressed

The `value` prop can be used to make the pressed state controlled. The `onChange` event is fired when the user toggle the button, and receives the new value.

BoldItalicUnderline

Your text style is: **bold**.

```
Copytsx
import { createSignal } from "solid-js";

function ControlledExample() {
	const [value, setValue] = createSignal("underline");

	return (
		<>
			<ToggleGroup value={value()} onChange={setValue}>
				...
			</ToggleGroup>
			<p>Your text style is: {value()}.</p>
		</>
	);
}
```

```
Copytsx
import { createSignal } from "solid-js";

function ControlledExample() {
	const [value, setValue] = createSignal("underline");

	return (
		<>
			<ToggleGroup value={value()} onChange={setValue}>
				...
			</ToggleGroup>
			<p>Your text style is: {value()}.</p>
		</>
	);
}
```

### Multiple selection

The `multiple` prop can be used to create a select that allow multi-selection.

BoldItalicUnderline

```
Copytsx
import { createSignal } from "solid-js";

function MultipleSelectionExample() {
	const [values, setValues] = createSignal(["bold", "underline"]);

	return (
		<ToggleGroup class="toggle-group" value={values()} onChange={setValues}>
			<ToggleGroup.Item class="toggle-group__item" value="bold" aria-label="Bold">
				<BoldIcon />
			</ToggleGroup.Item>
			<ToggleGroup.Item class="toggle-group__item" value="italic" aria-label="Italic">
				<ItalicIcon />
			</ToggleGroup.Item>
			<ToggleGroup.Item class="toggle-group__item" value="underline" aria-label="Underline">
				<UnderlineIcon />
			</ToggleGroup.Item>
		</ToggleGroup>
	);
}
```

```
Copytsx
import { createSignal } from "solid-js";

function MultipleSelectionExample() {
	const [values, setValues] = createSignal(["bold", "underline"]);

	return (
		<ToggleGroup class="toggle-group" value={values()} onChange={setValues}>
			<ToggleGroup.Item class="toggle-group__item" value="bold" aria-label="Bold">
				<BoldIcon />
			</ToggleGroup.Item>
			<ToggleGroup.Item class="toggle-group__item" value="italic" aria-label="Italic">
				<ItalicIcon />
			</ToggleGroup.Item>
			<ToggleGroup.Item class="toggle-group__item" value="underline" aria-label="Underline">
				<UnderlineIcon />
			</ToggleGroup.Item>
		</ToggleGroup>
	);
}
```

## API Reference

### ToggleGroup

`ToggleGroup` is equivalent to the `Root` import from `@kobalte/core/toggle-group` (and deprecated `ToggleGroup.Root`).

| Prop | Description |
| --- | --- |
| value | `string | string[]`<br> The controlled pressed state of the toggle button. |
| defaultValue | `string | string[]`<br> The default pressed state when initially rendered. Useful when you do not need to control the pressed state. |
| onChange | `(value: string | string[]) => void`<br> Event handler called when the pressed state of an item changes. |
| multiple | `boolean`<br> Whether the toggle group allows multi-selection. |
| orientation | `'horizontal' | 'vertical'`<br> The orientation of the toggle group. |
| disabled | `boolean`<br> Whether toggle group should be disabled. |

| Data attribute | Description |
| --- | --- |
| data-orientation='horizontal' | Present when the separator has horizontal orientation. |
| data-orientation='vertical' | Present when the separator has vertical orientation. |

### ToggleGroup.Item

| Prop | Description |
| --- | --- |
| value | `string`<br> A unique value for the item. |
| disabled | `boolean`<br> Whether the item is disabled. |
| children | `JSX.Element | (state: ToggleButtonState) => JSX.Element`<br> The children of the item. Can be a `JSX.Element` or a _render prop_ for having access to the internal state. |

| Render Prop | Description |
| --- | --- |
| pressed | `Accessor<boolean>`<br> Whether the toggle button is on (pressed) or off (not pressed). |

| Data attribute | Description |
| --- | --- |
| data-orientation='horizontal' | Present when the separator has horizontal orientation. |
| data-orientation='vertical' | Present when the separator has vertical orientation. |
| data-disabled | Present when the accordion item is disabled. |
| data-pressed | Present when the toggle button is on (pressed). |

## Rendered elements

| Component | Default rendered element |
| --- | --- |
| `ToggleGroup` | `div` |
| `ToggleGroup.Item` | `button` |

## Accessibility

### Keyboard Interactions

| Key | Description |
| --- | --- |
| `Tab` | Move focus to either the pressed item or the first item in the group. |
| `ArrowDown` | If orientation is vertical, moves focus to the next item. |
| `ArrowRight` | If orientation is horizontal, Moves focus to the next item. |
| `ArrowUp` | If orientation is vertical, moves focus to the previous item. |
| `ArrowLeft` | If orientation is vertical, moves focus to the previous item. |
| `Home` | Moves focus to the first item. |
| `End` | Moves focus to the last item. |
| `Enter` | Activates/deactivates the item. |
| `Space` | Activates/deactivates the item. |

Previous[←Toggle Button](https://kobalte.dev/docs/core/components/toggle-button)Next[Tooltip→](https://kobalte.dev/docs/core/components/tooltip)