295 lines
8.0 KiB
Markdown
295 lines
8.0 KiB
Markdown
# 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) |