Toggle Group

A toggle group is used to toggle either one option or multiple options.

Properties

disabled

multiple

Features

Fully managed keyboard navigation
Supports horizontal and vertical orientation
Support for multiple selection

Installation

To use the toggle group machine in your project, run the following command in your command line:

npm install @zag-js/toggle-group @zag-js/react
# or
yarn add @zag-js/toggle-group @zag-js/react

npm install @zag-js/toggle-group @zag-js/solid
# or
yarn add @zag-js/toggle-group @zag-js/solid

npm install @zag-js/toggle-group @zag-js/vue
# or
yarn add @zag-js/toggle-group @zag-js/vue

npm install @zag-js/toggle-group @zag-js/svelte
# or
yarn add @zag-js/toggle-group @zag-js/svelte

Anatomy

To set up the toggle group 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

First, import the toggle group package into your project

import * as toggle from "@zag-js/toggle-group"

The toggle group package exports two key functions:

machine — The state machine logic for the toggle group widget as described in the WAI-ARIA spec.
connect — The function that translates the machine's state to JSX attributes and event handlers.

You'll need to provide a unique id to the useMachine hook. This is used to ensure that every part has a unique identifier.

Next, import the required hooks and functions for your framework and use the toggle group machine in your project 🔥

import { normalizeProps, useMachine } from "@zag-js/react"
import * as toggle from "@zag-js/toggle-group"
import { useId } from "react"

export function ToggleGroup() {
  const service = useMachine(toggle.machine, { id: useId() })
  const api = toggle.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <button {...api.getItemProps({ value: "bold" })}>B</button>
      <button {...api.getItemProps({ value: "italic" })}>I</button>
      <button {...api.getItemProps({ value: "underline" })}>U</button>
    </div>
  )
}

import { normalizeProps, useMachine } from "@zag-js/solid"
import * as toggle from "@zag-js/toggle-group"
import { createMemo, createUniqueId } from "solid-js"

export function ToggleGroup() {
  const service = useMachine(toggle.machine, { id: createUniqueId() })
  const api = createMemo(() => toggle.connect(service, normalizeProps))

  return (
    <div {...api().getRootProps()}>
      <button {...api().getItemProps({ value: "bold" })}>B</button>
      <button {...api().getItemProps({ value: "italic" })}>I</button>
      <button {...api().getItemProps({ value: "underline" })}>U</button>
    </div>
  )
}

<script setup>
  import * as toggle from "@zag-js/toggle-group"
  import { normalizeProps, useMachine } from "@zag-js/vue"
  import { computed } from "vue"

  const service = useMachine(toggle.machine, { id: "1" })
  const api = computed(() => toggle.connect(service, normalizeProps))
</script>

<template>
  <div v-bind="api.getRootProps()">
    <button v-bind="api.getItemProps({ value: 'bold' })">B</button>
    <button v-bind="api.getItemProps({ value: 'italic' })">I</button>
    <button v-bind="api.getItemProps({ value: 'underline' })">U</button>
  </div>
</template>

<script lang="ts">
  import { normalizeProps, useMachine } from "@zag-js/svelte"
  import * as toggle from "@zag-js/toggle-group"

  const id = $props.id()
  const service = useMachine(toggle.machine, { id })
  const api = $derived(toggle.connect(service, normalizeProps))
</script>

<div {...api.getRootProps()}>
  <button {...api.getItemProps({ value: "bold" })}>B</button>
  <button {...api.getItemProps({ value: "italic" })}>I</button>
  <button {...api.getItemProps({ value: "underline" })}>U</button>
</div>

Changing the orientation

By default, the toggle group is assumed to be horizontal. To change the orientation to vertical, set the orientation property in the machine's context to vertical.

const service = useMachine(toggle.machine, {
  orientation: "vertical",
})

Listening for value changes

When the pressed toggle in the group changes, onValueChange callback is invoked.

const service = useMachine(toggle.machine, {
  onValueChange(details) {
    // details => { value: string[] }
    console.log(details.value)
  },
})

Allowing multiple selection

Set the multiple property in the machine's context to true to allow multiple options to be toggled.

const service = useMachine(toggle.machine, {
  multiple: true,
})

Disabling the toggle group

Set the disabled property in the machine's context to true to disable the toggle group.

const service = useMachine(toggle.machine, {
  disabled: true,
})

Disabling a toggle

Set the disabled property in the getToggleProps function to true to disable a toggle.

//...
<div {...api.getRootProps()}>
  <button {...api.getToggleProps({ value: "bold", disabled: true })}>B</button>
</div>
//...

Disabling focus loop

The toggle group loops keyboard navigation by default. To disable this, set the loop property in the machine's context to false.

const service = useMachine(toggle.machine, {
  loop: false,
})

Disabling roving focus management

The toggle group uses roving focus management by default. To disable this, set the rovingFocus property in the machine's context to false.

const service = useMachine(toggle.machine, {
  rovingFocus: false,
})

Styling Guide

Earlier, we mentioned that each toggle group part has a data-part attribute added to them to select and style them in the DOM.

Pressed State

The toggle is pressed, the data-state attribute is applied to the toggle button with on or off values.

[data-part="toggle"][data-state="on|off"] {
  /* styles for toggle button */
}

Focused State

When a toggle button is focused, the data-focus is applied to the root and matching toggle button.

[data-part="root"][data-focus] {
  /* styles for the root */
}

[data-part="toggle"][data-focus] {
  /* styles for the toggle */
}

Disabled State

When a toggle button is disabled, the data-disabled is applied to the root and matching toggle button.

[data-part="root"][data-disabled] {
  /* styles for the root */
}

[data-part="toggle"][data-disabled] {
  /* styles for the toggle */
}

Methods and Properties

Machine Context

The toggle group machine exposes the following context properties:

idsPartial<{ root: string; item: (value: string) => string; }>The ids of the elements in the toggle. Useful for composition.

disabledbooleanWhether the toggle is disabled.

valuestring[]The controlled selected value of the toggle group.

defaultValuestring[]The initial selected value of the toggle group when rendered. Use when you don't need to control the selected value of the toggle group.

onValueChange(details: ValueChangeDetails) => voidFunction to call when the toggle is clicked.

loopFocusbooleanWhether to loop focus inside the toggle group.

rovingFocusbooleanWhether to use roving tab index to manage focus.

orientationOrientationThe orientation of the toggle group.

multiplebooleanWhether to allow multiple toggles to be selected.

deselectablebooleanWhether the toggle group allows empty selection. **Note:** This is ignored if `multiple` is `true`.

dir"ltr" | "rtl"The document's text/writing direction.

idstringThe unique identifier of the machine.

getRootNode() => ShadowRoot | Node | DocumentA root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.

Machine API

The toggle group api exposes the following methods:

valuestring[]The value of the toggle group.

setValue(value: string[]) => voidSets the value of the toggle group.

getItemState(props: ItemProps) => ItemStateReturns the state of the toggle item.

Data Attributes

Root

data-scope

toggle-group

data-part

root

data-disabled

Present when disabled

data-orientation

The orientation of the toggle-group

data-focus

Present when focused

Item