` element.
### ToggleOption
| Prop | Type | Description | Default |
| ----------- | ----------- | ----------------------------------------------------------- | ------- |
| `value` | `string` | A unique value identifying this toggle option. | — |
| `text` | `string` | The text label displayed in the toggle option. | — |
| `icon` | `ReactNode` | An icon element displayed instead of text. | — |
| `ariaLabel` | `string` | An accessible `aria-label`. Required for icon-only options. | — |
## Examples
### Controlled vs uncontrolled
Render a `Toggle` in an uncontrolled fashion to let it keep track of its own state. Pass `defaultValue` if it should start out with a value pre-selected:
```tsx demo
import { Grid, List } from "@tenstorrent/vesper/icons";
import { Toggle } from "@tenstorrent/vesper/toggle";
export default function UncontrolledToggle() {
return (
, ariaLabel: "Grid view" },
{ value: "list", icon:
, ariaLabel: "List view" },
]}
/>
);
}
```
If you need to control the toggle's state, you can do so via the `value` and `onValueChange` props:
```tsx demo
import { useState } from "react";
import { Grid, List } from "@tenstorrent/vesper/icons";
import { Toggle } from "@tenstorrent/vesper/toggle";
import { Typography } from "@tenstorrent/vesper/typography";
export default function ControlledToggle() {
const [value, setValue] = useState("");
return (
Value: {value || "nothing selected"}
);
}
```
### Text and icon options
You can render both text and icon options in a `Toggle`. To render text options, you would pass an array of `options` objects that each have `value` and `text` properties:
```tsx demo
import { Toggle } from "@tenstorrent/vesper/toggle";
export default function TextOptionsToggle() {
return (
);
}
```
To render icon options, pass an array of `options` objects that each have `value`, `icon`, and `ariaLabel` properties:
```tsx demo
import { Globe, Lock } from "@tenstorrent/vesper/icons";
import { Toggle } from "@tenstorrent/vesper/toggle";
export default function IconOptionsToggle() {
return (
, ariaLabel: "Public" },
{ value: "private", icon:
, ariaLabel: "Private" },
]}
defaultValue="public"
/>
);
}
```
### Different sizes
`Toggle` can be rendered in one of three sizes; `"sm"`, `"md"`, or `"lg"`. The default size is `"md"`.
```tsx demo
import { Toggle } from "@tenstorrent/vesper/toggle";
export default function AllToggleSizes() {
return (
);
}
```
### Required fields
Passing `required` marks the toggle as required for native form validation:
```tsx
import { Toggle } from "@tenstorrent/vesper/toggle";
export default function RequiredToggleDemo() {
return (
);
}
```
### Disabling the toggle
You can disable a `Toggle` by passing `disabled={true}` or just `disabled` as a prop. A disabled toggle still displays its current state, but it cannot be toggled by pointer or keyboard, is skipped in the tab order, and is excluded from form data:
```tsx demo
import { Toggle } from "@tenstorrent/vesper/toggle";
export default function DisabledToggle() {
return (
);
}
```
### Usage in forms
`Toggle` renders a native `
`, so it works with regular form submission and native validation via props like `name`, `value`, `form`, and `required`.
Pass `required` when the toggle must have an option selected before the form can be submitted, such as a terms and conditions agreement:
```tsx demo
import { useState } from "react";
import { Button } from "@tenstorrent/vesper/button";
import { Toggle } from "@tenstorrent/vesper/toggle";
import { Typography } from "@tenstorrent/vesper/typography";
export default function FormToggleDemo() {
const [submitted, setSubmitted] = useState("");
return (
);
}
```
The form above submits `billing_period=monthly` when the "Monthly" toggle option is selected, and refuses to submit at all while the toggle is empty.
Use the `form` prop to associate the field with a `