--- title: Toggle description: Using the toggle machine in your project. package: "@zag-js/toggle" --- A toggle is a two-state button that can be on or off. Use it for a single independent option (for multiple related options, see [Toggle Group](/components/toggle-group)). **Features** - Controlled and uncontrolled pressed state - Optional indicator part for icons or labels - `aria-pressed` for assistive technology ## Installation Install the toggle package: ## Anatomy To set up the toggle correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Usage Import the toggle package: ```tsx import * as toggle from "@zag-js/toggle" ``` The toggle package exports two key functions: - `machine` - State machine logic. - `connect` - Maps machine state to JSX props and event handlers. Then use the framework integration helpers: ### Default pressed state Use `defaultPressed` to start in the pressed (on) state when uncontrolled. ```tsx {2} const service = useMachine(toggle.machine, { defaultPressed: true, }) ``` ### Controlled pressed state Use `pressed` and `onPressedChange` for controlled usage. ```tsx const service = useMachine(toggle.machine, { pressed, onPressedChange(nextPressed) { setPressed(nextPressed) }, }) ``` ### Listening for changes When the pressed state changes, `onPressedChange` is called with the next boolean value. ```tsx {2-4} const service = useMachine(toggle.machine, { onPressedChange(pressed) { console.log(pressed ? "on" : "off") }, }) ``` ### Disabling the toggle Set `disabled` to `true` to prevent interaction. ```tsx {2} const service = useMachine(toggle.machine, { disabled: true, }) ``` ### Programmatic control Use the API to set pressed state imperatively. ```tsx api.setPressed(true) ``` ### Indicator part Render an optional element with `getIndicatorProps()` for icons or secondary visuals. The root remains the interactive `button`. ```tsx ``` ## Styling guide Each part includes a `data-part` attribute you can target in CSS. ### Pressed state When pressed, `data-state` is `on` or `off` on the root and indicator. ```css [data-part="root"][data-state="on"] { /* pressed */ } [data-part="indicator"][data-state="on"] { /* pressed indicator */ } ``` ### Disabled state When disabled, `data-disabled` is set on the root and indicator. ```css [data-part="root"][data-disabled] { /* disabled */ } ``` ## Methods and Properties ### Machine Context The toggle machine exposes the following context properties: ### Machine API The toggle `api` exposes the following methods: ### Data Attributes ## Accessibility Implements a [button](https://www.w3.org/WAI/ARIA/apg/patterns/button/) with `aria-pressed` reflecting the pressed state. ### Keyboard Interactions