{"slug":"toggle","title":"Toggle","description":"Using the toggle machine in your project.","contentType":"component","framework":"react","content":"A toggle is a two-state button that can be on or off. Use it for a single independent option (for multiple related\noptions, see [Toggle Group](/components/toggle-group)).\n\n## Resources\n\n\n[Latest version: v1.40.0](https://www.npmjs.com/package/@zag-js/toggle)\n[Logic Visualizer](https://zag-visualizer.vercel.app/toggle)\n[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/toggle)\n\n\n\n**Features**\n\n- Controlled and uncontrolled pressed state\n- Optional indicator part for icons or labels\n- `aria-pressed` for assistive technology\n\n## Installation\n\nInstall the toggle package:\n\n```bash\nnpm install @zag-js/toggle @zag-js/react\n# or\nyarn add @zag-js/toggle @zag-js/react\n```\n\n## Anatomy\n\nTo set up the toggle correctly, you'll need to understand its anatomy and how we name its parts.\n\n> Each part includes a `data-part` attribute to help identify them in the DOM.\n\n\n\n## Usage\n\nImport the toggle package:\n\n```tsx\nimport * as toggle from \"@zag-js/toggle\"\n```\n\nThe toggle package exports two key functions:\n\n- `machine` - State machine logic.\n- `connect` - Maps machine state to JSX props and event handlers.\n\nThen use the framework integration helpers:\n\n```tsx\nimport * as toggle from \"@zag-js/toggle\"\nimport { useMachine, normalizeProps } from \"@zag-js/react\"\nimport { useId } from \"react\"\n\nfunction Toggle() {\n  const service = useMachine(toggle.machine, { id: useId() })\n  const api = toggle.connect(service, normalizeProps)\n\n  return (\n    <button {...api.getRootProps()}>\n      <span {...api.getIndicatorProps()} />\n      Bold\n    </button>\n  )\n}\n```\n\n### Default pressed state\n\nUse `defaultPressed` to start in the pressed (on) state when uncontrolled.\n\n```tsx {2}\nconst service = useMachine(toggle.machine, {\n  defaultPressed: true,\n})\n```\n\n### Controlled pressed state\n\nUse `pressed` and `onPressedChange` for controlled usage.\n\n```tsx\nconst service = useMachine(toggle.machine, {\n  pressed,\n  onPressedChange(nextPressed) {\n    setPressed(nextPressed)\n  },\n})\n```\n\n### Listening for changes\n\nWhen the pressed state changes, `onPressedChange` is called with the next boolean value.\n\n```tsx {2-4}\nconst service = useMachine(toggle.machine, {\n  onPressedChange(pressed) {\n    console.log(pressed ? \"on\" : \"off\")\n  },\n})\n```\n\n### Disabling the toggle\n\nSet `disabled` to `true` to prevent interaction.\n\n```tsx {2}\nconst service = useMachine(toggle.machine, {\n  disabled: true,\n})\n```\n\n### Programmatic control\n\nUse the API to set pressed state imperatively.\n\n```tsx\napi.setPressed(true)\n```\n\n### Indicator part\n\nRender an optional element with `getIndicatorProps()` for icons or secondary visuals. The root remains the interactive\n`button`.\n\n```tsx\n<button {...api.getRootProps()}>\n  <span {...api.getIndicatorProps()}>\n    <BoldIcon />\n  </span>\n</button>\n```\n\n## Styling guide\n\nEach part includes a `data-part` attribute you can target in CSS.\n\n### Pressed state\n\nWhen pressed, `data-state` is `on` or `off` on the root and indicator.\n\n```css\n[data-part=\"root\"][data-state=\"on\"] {\n  /* pressed */\n}\n\n[data-part=\"indicator\"][data-state=\"on\"] {\n  /* pressed indicator */\n}\n```\n\n### Disabled state\n\nWhen disabled, `data-disabled` is set on the root and indicator.\n\n```css\n[data-part=\"root\"][data-disabled] {\n  /* disabled */\n}\n```\n\n## Methods and Properties\n\n### Machine Context\n\nThe toggle machine exposes the following context properties:\n\n**`disabled`**\nType: `boolean | undefined`\nDescription: Whether the toggle is disabled.\n\n**`defaultPressed`**\nType: `boolean | undefined`\nDescription: The default pressed state of the toggle.\n\n**`pressed`**\nType: `boolean | undefined`\nDescription: The pressed state of the toggle.\n\n**`onPressedChange`**\nType: `((pressed: boolean) => void) | undefined`\nDescription: Event handler called when the pressed state of the toggle changes.\n\n### Machine API\n\nThe toggle `api` exposes the following methods:\n\n**`pressed`**\nType: `boolean`\nDescription: Whether the toggle is pressed.\n\n**`disabled`**\nType: `boolean`\nDescription: Whether the toggle is disabled.\n\n**`setPressed`**\nType: `(pressed: boolean) => void`\nDescription: Sets the pressed state of the toggle.\n\n**`getRootProps`**\nType: `() => T[\"element\"]`\nDescription: Props for the root `button` element.\n\n**`getIndicatorProps`**\nType: `() => T[\"element\"]`\nDescription: Props for the optional visual indicator (e.g. icon) element.\n\n### Data Attributes\n\n**`Root`**\n\n**`data-scope`**: toggle\n**`data-part`**: root\n**`data-state`**: \"on\" | \"off\"\n**`data-pressed`**: Present when pressed\n**`data-disabled`**: Present when disabled\n\n**`Indicator`**\n\n**`data-scope`**: toggle\n**`data-part`**: indicator\n**`data-disabled`**: Present when disabled\n**`data-pressed`**: Present when pressed\n**`data-state`**: \"on\" | \"off\"\n\n## Accessibility\n\nImplements a [button](https://www.w3.org/WAI/ARIA/apg/patterns/button/) with `aria-pressed` reflecting the pressed\nstate.\n\n### Keyboard Interactions\n\n**`Space + Enter`**\nDescription: Toggle the pressed state","package":"@zag-js/toggle","editUrl":"https://github.com/chakra-ui/zag/edit/main/website/data/components/toggle.mdx"}