Toggle
View as MarkdownA button that toggles between pressed and unpressed.
Features
Permalink to heading "Features"- Renders a native
<button>witharia-pressed, toggled with Space and Enter - Can be pressed by default and disabled
- Optional indicator part that follows the pressed state
- For a set of related toggles, see Toggle Group
<primitives:toggle.root>
<primitives:toggle.indicator />
</primitives:toggle.root>
Installation
Permalink to heading "Installation"typo3 ui:add toggle
Please copy the files manually from GitHub into your project.
Read more about installing Components and Primitives.
Examples
Permalink to heading "Examples"Default Pressed
Permalink to heading "Default Pressed"Set the toggle to be pressed by default.
Disabled
Permalink to heading "Disabled"Prevent the toggle from being pressed.
Indicator
Permalink to heading "Indicator"The indicator carries the same data-pressed and data-disabled attributes as the root, so it can show the state of the toggle without any extra markup.
API Reference
Permalink to heading "API Reference"The following tables cover the available props of the Fluid Primitives. For a full list of available client side props and methods, see the Zag.js Machine API.
toggle.root
Permalink to heading "toggle.root"Provides the pressed state and toggles it on click. Renders a <button> element.
| Name | Description | Required | Default |
|---|---|---|---|
defaultPressed | booleanThe initial pressed state of the toggle when rendered. Use when you don't need to control the pressed state of the toggle. | No | false |
disabled | booleanWhether the toggle is disabled. | No | - |
attributes | arrayAdditional attributes that should be rendered on the component where ui:attributes is used. | No | [] |
asChild | booleanIf true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. | No | - |
rootId | stringThe root ID of the component, used for hydration and identification. | No | - |
ids | arrayThe IDs of of the component parts for composition. | No | [] |
autoMount | booleanWhether the client initializes the component on its own. Set it to false to mount it yourself with `mount()` | No | true |
class | stringThe CSS class(es) to be applied to the component. | No | - |
Rendered data attributes
| Attribute | Description |
|---|---|
data-toggle-root | <uid> |
data-pressed | Present when pressed |
data-disabled | Present when disabled |
toggle.indicator
Permalink to heading "toggle.indicator"Visual indicator of the pressed state, e.g. an icon or a dot. Renders a <span> element.
| Name | Description | Required | Default |
|---|---|---|---|
attributes | arrayAdditional attributes that should be rendered on the component where ui:attributes is used. | No | [] |
asChild | booleanIf true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. | No | - |
class | stringThe CSS class(es) to be applied to the component. | No | - |
Rendered data attributes
| Attribute | Description |
|---|---|
data-toggle-indicator | <uid> |
data-disabled | Present when disabled |
data-pressed | Present when pressed |
Machine JavaScript API
Permalink to heading "Machine JavaScript API"| Name | Type | Description |
|---|---|---|
pressed | boolean | Whether the toggle is pressed. |
disabled | boolean | Whether the toggle is disabled. |
setPressed | (pressed: boolean) => void | Sets the pressed state of the toggle. |
getRootState | () => RootState | Returns the state of the toggle |
getRootProps | () => T["element"] | Props for the root `button` element. |
getIndicatorProps | () => T["element"] | Props for the optional visual indicator (e.g. icon) element. |
Accessibility
Permalink to heading "Accessibility"| Key | Description |
|---|---|
SpaceEnter | Toggle the pressed state |