{"slug":"toggle-group","title":"Toggle Group","description":"Using the toggle-group machine in your project.","contentType":"component","framework":"react","content":"A toggle group lets users toggle one or more related options.\n\n## Resources\n\n\n[Latest version: v1.35.3](https://www.npmjs.com/package/@zag-js/toggle-group)\n[Logic Visualizer](https://zag-visualizer.vercel.app/toggle-group)\n[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/toggle-group)\n\n\n\n**Features**\n\n- Fully managed keyboard navigation\n- Supports horizontal and vertical orientation\n- Supports multiple selection\n\n## Installation\n\nInstall the toggle group package:\n\n```bash\nnpm install @zag-js/toggle-group @zag-js/react\n# or\nyarn add @zag-js/toggle-group @zag-js/react\n```\n\n## Anatomy\n\nTo set up the toggle group correctly, you'll need to understand its anatomy and\nhow 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 group package:\n\n```jsx\nimport * as toggle from \"@zag-js/toggle-group\"\n```\n\nThe toggle group 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```jsx\nimport { normalizeProps, useMachine } from \"@zag-js/react\"\nimport * as toggle from \"@zag-js/toggle-group\"\nimport { useId } from \"react\"\n\nexport function ToggleGroup() {\n  const service = useMachine(toggle.machine, { id: useId() })\n  const api = toggle.connect(service, normalizeProps)\n\n  return (\n    <div {...api.getRootProps()}>\n      <button {...api.getItemProps({ value: \"bold\" })}>B</button>\n      <button {...api.getItemProps({ value: \"italic\" })}>I</button>\n      <button {...api.getItemProps({ value: \"underline\" })}>U</button>\n    </div>\n  )\n}\n```\n\n### Changing the orientation\n\nBy default, the toggle group is assumed to be horizontal. To change the\norientation to vertical, set the `orientation` property in the machine's context\nto `vertical`.\n\n```jsx {2}\nconst service = useMachine(toggle.machine, {\n  orientation: \"vertical\",\n})\n```\n\n### Listening for value changes\n\nWhen the pressed toggle in the group changes, `onValueChange` callback is\ninvoked.\n\n```jsx {2-4}\nconst service = useMachine(toggle.machine, {\n  onValueChange(details) {\n    // details => { value: string[] }\n    console.log(details.value)\n  },\n})\n```\n\n### Controlled toggle group\n\nUse `value` and `onValueChange` for controlled usage.\n\n```jsx\nconst service = useMachine(toggle.machine, {\n  value,\n  onValueChange(details) {\n    setValue(details.value)\n  },\n})\n```\n\n### Allowing multiple selection\n\nSet the `multiple` property in the machine's context to `true` to allow multiple\noptions to be toggled.\n\n```jsx {2}\nconst service = useMachine(toggle.machine, {\n  multiple: true,\n})\n```\n\n### Disabling the toggle group\n\nSet the `disabled` property in the machine's context to `true` to disable the\ntoggle group.\n\n```jsx {2}\nconst service = useMachine(toggle.machine, {\n  disabled: true,\n})\n```\n\n### Disabling a toggle\n\nSet the `disabled` property in `getItemProps` to `true` to disable a toggle.\n\n```jsx\n//...\n<div {...api.getRootProps()}>\n  <button {...api.getItemProps({ value: \"bold\", disabled: true })}>B</button>\n</div>\n//...\n```\n\n### Disabling focus loop\n\nThe toggle group loops keyboard navigation by default. To disable this, set the\n`loopFocus` property in the machine's context to `false`.\n\n```jsx {2}\nconst service = useMachine(toggle.machine, {\n  loopFocus: false,\n})\n```\n\n### Disabling roving focus management\n\nThe toggle group uses roving focus management by default. To disable this, set\nthe `rovingFocus` property in the machine's context to `false`.\n\n```jsx {2}\nconst service = useMachine(toggle.machine, {\n  rovingFocus: false,\n})\n```\n\n### Allowing or preventing deselection\n\nUse `deselectable` to control whether the active item can be toggled off in\nsingle-select mode.\n\n```jsx\nconst service = useMachine(toggle.machine, {\n  deselectable: false,\n})\n```\n\n### Programmatic value control\n\nUse the API for imperative updates.\n\n```jsx\napi.setValue([\"bold\", \"italic\"])\n```\n\n## Styling Guide\n\nEach part includes a `data-part` attribute you can target in CSS.\n\n### Pressed State\n\nThe toggle is pressed, the `data-state` attribute is applied to the toggle\nbutton with `on` or `off` values.\n\n```css\n[data-part=\"item\"][data-state=\"on|off\"] {\n  /* styles for toggle button */\n}\n```\n\n### Focused State\n\nWhen a toggle button is focused, the `data-focus` is applied to the root and\nmatching toggle button.\n\n```css\n[data-part=\"root\"][data-focus] {\n  /* styles for the root */\n}\n\n[data-part=\"item\"][data-focus] {\n  /* styles for the toggle */\n}\n```\n\n### Disabled State\n\nWhen a toggle button is disabled, the `data-disabled` is applied to the root and\nmatching toggle button.\n\n```css\n[data-part=\"root\"][data-disabled] {\n  /* styles for the root */\n}\n\n[data-part=\"item\"][data-disabled] {\n  /* styles for the toggle */\n}\n```\n\n## Methods and Properties\n\n### Machine Context\n\nThe toggle group machine exposes the following context properties:\n\n**`ids`**\nType: `Partial<{ root: string; item: (value: string) => string; }>`\nDescription: The ids of the elements in the toggle. Useful for composition.\n\n**`disabled`**\nType: `boolean`\nDescription: Whether the toggle is disabled.\n\n**`value`**\nType: `string[]`\nDescription: The controlled selected value of the toggle group.\n\n**`defaultValue`**\nType: `string[]`\nDescription: The initial selected value of the toggle group when rendered.\nUse when you don't need to control the selected value of the toggle group.\n\n**`onValueChange`**\nType: `(details: ValueChangeDetails) => void`\nDescription: Function to call when the toggle is clicked.\n\n**`loopFocus`**\nType: `boolean`\nDescription: Whether to loop focus inside the toggle group.\n\n**`rovingFocus`**\nType: `boolean`\nDescription: Whether to use roving tab index to manage focus.\n\n**`orientation`**\nType: `Orientation`\nDescription: The orientation of the toggle group.\n\n**`multiple`**\nType: `boolean`\nDescription: Whether to allow multiple toggles to be selected.\n\n**`deselectable`**\nType: `boolean`\nDescription: Whether the toggle group allows empty selection.\n**Note:** This is ignored if `multiple` is `true`.\n\n**`dir`**\nType: `\"ltr\" | \"rtl\"`\nDescription: The document's text/writing direction.\n\n**`id`**\nType: `string`\nDescription: The unique identifier of the machine.\n\n**`getRootNode`**\nType: `() => ShadowRoot | Node | Document`\nDescription: A root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.\n\n### Machine API\n\nThe toggle group `api` exposes the following methods:\n\n**`value`**\nType: `string[]`\nDescription: The value of the toggle group.\n\n**`setValue`**\nType: `(value: string[]) => void`\nDescription: Sets the value of the toggle group.\n\n**`getItemState`**\nType: `(props: ItemProps) => ItemState`\nDescription: Returns the state of the toggle item.\n\n### Data Attributes\n\n**`Root`**\n\n**`data-scope`**: toggle-group\n**`data-part`**: root\n**`data-disabled`**: Present when disabled\n**`data-orientation`**: The orientation of the toggle-group\n**`data-focus`**: Present when focused\n\n**`Item`**\n\n**`data-scope`**: toggle-group\n**`data-part`**: item\n**`data-focus`**: Present when focused\n**`data-disabled`**: Present when disabled\n**`data-orientation`**: The orientation of the item\n**`data-state`**: \"on\" | \"off\"\n\n## Accessibility\n\nUses\n[roving tabindex](https://www.w3.org/TR/wai-aria-practices-1.2/examples/radio/radio.html)\nto manage focus movement among items.\n\n### Keyboard Interactions\n\n**`Tab`**\nDescription: Moves focus to either the pressed item or the first item in the group.\n\n**`Space`**\nDescription: Activates/deactivates the item.\n\n**`Enter`**\nDescription: Activates/deactivates the item.\n\n**`ArrowDown`**\nDescription: Moves focus to the next item in the group.\n\n**`ArrowRight`**\nDescription: Moves focus to the next item in the group.\n\n**`ArrowUp`**\nDescription: Moves focus to the previous item in the group.\n\n**`ArrowLeft`**\nDescription: Moves focus to the previous item in the group.\n\n**`Home`**\nDescription: Moves focus to the first item.\n\n**`End`**\nDescription: Moves focus to the last item.","package":"@zag-js/toggle-group","editUrl":"https://github.com/chakra-ui/zag/edit/main/website/data/components/toggle-group.mdx"}