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

## 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

```jsx
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 ð¥

```jsx
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>
  )
}
```

### 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`.

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

### Listening for value changes

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

```jsx {2-4}
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.

```jsx {2}
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.

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

### Disabling a toggle

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

```jsx
//...
<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`.

```jsx {2}
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`.

```jsx {2}
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.

```css
[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.

```css
[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.

```css
[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:

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

**`disabled`**
Type: `boolean`
Description: Whether the toggle is disabled.

**`value`**
Type: `string[]`
Description: The controlled selected value of the toggle group.

**`defaultValue`**
Type: `string[]`
Description: 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`**
Type: `(details: ValueChangeDetails) => void`
Description: Function to call when the toggle is clicked.

**`loopFocus`**
Type: `boolean`
Description: Whether to loop focus inside the toggle group.

**`rovingFocus`**
Type: `boolean`
Description: Whether to use roving tab index to manage focus.

**`orientation`**
Type: `Orientation`
Description: The orientation of the toggle group.

**`multiple`**
Type: `boolean`
Description: Whether to allow multiple toggles to be selected.

**`deselectable`**
Type: `boolean`
Description: Whether the toggle group allows empty selection.
**Note:** This is ignored if `multiple` is `true`.

**`dir`**
Type: `"ltr" | "rtl"`
Description: The document's text/writing direction.

**`id`**
Type: `string`
Description: The unique identifier of the machine.

**`getRootNode`**
Type: `() => ShadowRoot | Node | Document`
Description: A root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.

### Machine API

The toggle group `api` exposes the following methods:

**`value`**
Type: `string[]`
Description: The value of the toggle group.

**`setValue`**
Type: `(value: string[]) => void`
Description: Sets the value of the toggle group.

**`getItemState`**
Type: `(props: ItemProps) => ItemState`
Description: Returns 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`**

**`data-scope`**: toggle-group
**`data-part`**: item
**`data-focus`**: Present when focused
**`data-disabled`**: Present when disabled
**`data-orientation`**: The orientation of the item
**`data-state`**: "on" | "off"

## Accessibility

Uses
[roving tabindex](https://www.w3.org/TR/wai-aria-practices-1.2/examples/radio/radio.html)
to manage focus movement among items.

### Keyboard Interactions

**`Tab`**
Description: Moves focus to either the pressed item or the first item in the group.

**`Space`**
Description: Activates/deactivates the item.

**`Enter`**
Description: Activates/deactivates the item.

**`ArrowDown`**
Description: Moves focus to the next item in the group.

**`ArrowRight`**
Description: Moves focus to the next item in the group.

**`ArrowUp`**
Description: Moves focus to the previous item in the group.

**`ArrowLeft`**
Description: Moves focus to the previous item in the group.

**`Home`**
Description: Moves focus to the first item.

**`End`**
Description: Moves focus to the last item.
A tooltip is a brief, informative message that appears when a user interacts
with an element. Tooltips are usually initiated when a button is focused or
hovered.

## Resources


[Latest version: v1.33.1](https://www.npmjs.com/package/@zag-js/tooltip)
[Logic Visualizer](https://zag-visualizer.vercel.app/tooltip)
[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/tooltip)



**Features**

- Show tooltip on hover and focus
- Hide tooltip on esc or pointer down
- Only one tooltip shows at a time
- Labeling support for screen readers via `aria-describedby`
- Custom show and hide delay support
- Matches native tooltip behavior with delay on hover of first tooltip and no
  delay on subsequent tooltips

## Installation

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

```bash
npm install @zag-js/tooltip @zag-js/react