An accordion is a vertically stacked set of interactive headings containing a
title, content snippet, or thumbnail representing a section of content.

## Resources


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



**Features**

- Full keyboard navigation
- Supports single and multiple expanded items
- Supports collapsible items
- Supports horizontal and vertical orientation

## Installation

Install the accordion package:

```bash
npm install @zag-js/accordion @zag-js/react
# or
yarn add @zag-js/accordion @zag-js/react
```

## Anatomy

Check the accordion anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the accordion package:

```tsx
import * as accordion from "@zag-js/accordion"
```

The accordion package exports two key functions:

- `machine` - State machine logic.
- `connect` - Maps machine state to JSX props and event handlers.

> Pass a unique `id` to `useMachine` so generated element ids stay predictable.

Then use the framework integration helpers:

```tsx
import * as accordion from "@zag-js/accordion"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useId } from "react"

const data = [
  { title: "Watercraft", content: "Sample accordion content" },
  { title: "Automobiles", content: "Sample accordion content" },
  { title: "Aircraft", content: "Sample accordion content" },
]

function Accordion() {
  const service = useMachine(accordion.machine, { id: useId() })

  const api = accordion.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      {data.map((item) => (
        <div key={item.title} {...api.getItemProps({ value: item.title })}>
          <h3>
            <button {...api.getItemTriggerProps({ value: item.title })}>
              {item.title}
            </button>
          </h3>
          <div {...api.getItemContentProps({ value: item.title })}>
            {item.content}
          </div>
        </div>
      ))}
    </div>
  )
}
```

You may have noticed we wrapped each accordion trigger within an `h3`. This is
recommended by the
[WAI-ARIA](https://www.w3.org/TR/wai-aria-practices-1.1/#wai-aria-roles-states-and-properties)
design pattern to ensure the accordion has the appropriate hierarchy on the
page.

### Opening multiple items

Set `multiple` to `true` to allow more than one expanded item at a time.

```tsx {2}
const service = useMachine(accordion.machine, {
  multiple: true,
})
```

### Setting the initial value

Set `defaultValue` to define expanded items on first render.

```tsx
// multiple mode
const service = useMachine(accordion.machine, {
  multiple: true,
  defaultValue: ["home", "about"],
})

// single mode
const service = useMachine(accordion.machine, {
  defaultValue: ["home"],
})
```

### Controlled accordions

Use `value` and `onValueChange` to control expanded items externally.

```tsx
import { useState } from "react"

export function ControlledAccordion() {
  const [value, setValue] = useState(["home"])

  const service = useMachine(accordion.machine, {
    value,
    onValueChange(details) {
      setValue(details.value)
    },
  })

  return (
    // ...
  )
}
```

### Making items collapsible

Set `collapsible` to `true` to allow closing an expanded item by clicking it
again.

> Note: If `multiple` is `true`, we internally set `collapsible` to be `true`.

```tsx {2}
const service = useMachine(accordion.machine, {
  collapsible: true,
})
```

### Listening for value changes

When the accordion value changes, the `onValueChange` callback is invoked.

```tsx {2-5}
const service = useMachine(accordion.machine, {
  onValueChange(details) {
    // details => { value: string[] }
    console.log("selected accordion:", details.value)
  },
})
```

### Listening for focus changes

Use `onFocusChange` to react when keyboard focus moves between item triggers.

```tsx
const service = useMachine(accordion.machine, {
  onFocusChange(details) {
    // details => { value: string | null }
    console.log("focused item:", details.value)
  },
})
```

### Horizontal orientation

Set `orientation` to `horizontal` when rendering items side by side.

```tsx {2}
const service = useMachine(accordion.machine, {
  orientation: "horizontal",
})
```

### Disabling an accordion item

To disable a specific accordion item, pass the `disabled: true` property to the
`getItemProps`, `getItemTriggerProps` and `getItemContentProps`.

When an accordion item is disabled, it is skipped from keyboard navigation and
can't be interacted with.

```tsx
//...
<div {...api.getItemProps({ value: "item", disabled: true })}>
  <h3>
    <button {...api.getItemTriggerProps({ value: "item", disabled: true })}>
      Trigger
    </button>
  </h3>
  <div {...api.getItemContentProps({ value: "item", disabled: true })}>
    Content
  </div>
</div>
//...
```

You can also disable the entire accordion by setting `disabled` on the machine.

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

## Styling guide

Each part includes a `data-part` attribute you can target in CSS.

### Open and closed state

When an accordion item expands or collapses, `data-state` is set to `open` or
`closed` on the item, trigger, and content elements.

```css
[data-part="item"][data-state="open|closed"] {
  /* styles for the item is open or closed state */
}

[data-part="item-trigger"][data-state="open|closed"] {
  /* styles for the item is open or closed state */
}

[data-part="item-content"][data-state="open|closed"] {
  /* styles for the item is open or closed state */
}
```

### Focused state

When an accordion item's trigger is focused, a `data-focus` attribute is set on
the item and content.

```css
[data-part="item"][data-focus] {
  /* styles for the item's focus state */
}

[data-part="item-trigger"]:focus {
  /* styles for the trigger's focus state */
}

[data-part="item-content"][data-focus] {
  /* styles for the content's focus state */
}
```

## Creating a component

Create your accordion component by abstracting the machine into your own
component.

### Usage

```tsx
import { Accordion } from "./your-accordion"

function Demo() {
  return (
    <Accordion
      defaultValue={["1"]}
      items={[
        { value: "1", title: "Title 1", content: "Content 1" },
        { value: "2", title: "Title 2", content: "Content 2" },
      ]}
    />
  )
}
```

### Implementation

Use the `splitProps` utility to separate the machine's props from the
component's props.

```tsx
import * as accordion from "@zag-js/accordion"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useId } from "react"

interface Item {
  value: string
  title: React.ReactNode
  content: React.ReactNode
}

export interface AccordionProps extends Omit<accordion.Props, "id"> {
  items: Item[]
}

export function Accordion(props: AccordionProps) {
  const [machineProps, localProps] = accordion.splitProps(props)

  const service = useMachine(accordion.machine, {
    id: useId(),
    ...machineProps,
  })

  const api = accordion.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      {localProps.items.map((item) => (
        <div {...api.getItemProps({ value: item.value })}>
          <h3>
            <button {...api.getItemTriggerProps({ value: item.value })}>
              {item.title}
            </button>
          </h3>
          <div {...api.getItemContentProps({ value: item.value })}>
            {item.content}
          </div>
        </div>
      ))}
    </div>
  )
}
```

## Methods and Properties

The accordion's `api` exposes the following methods and properties:

### Machine Context

The accordion machine exposes the following context properties:

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the accordion. Useful for composition.

**`multiple`**
Type: `boolean | undefined`
Description: Whether multiple accordion items can be expanded at the same time.

**`collapsible`**
Type: `boolean | undefined`
Description: Whether an accordion item can be closed after it has been expanded.

**`value`**
Type: `string[] | undefined`
Description: The controlled value of the expanded accordion items.

**`defaultValue`**
Type: `string[] | undefined`
Description: The initial value of the expanded accordion items.
Use when you don't need to control the value of the accordion.

**`disabled`**
Type: `boolean | undefined`
Description: Whether the accordion items are disabled

**`onValueChange`**
Type: `((details: ValueChangeDetails) => void) | undefined`
Description: The callback fired when the state of expanded/collapsed accordion items changes.

**`onFocusChange`**
Type: `((details: FocusChangeDetails) => void) | undefined`
Description: The callback fired when the focused accordion item changes.

**`orientation`**
Type: `"horizontal" | "vertical" | undefined`
Description: The orientation of the accordion items.

**`loopFocus`**
Type: `boolean | undefined`
Description: Whether to loop focus back to the first/last trigger when navigating
past the end/start with the arrow keys.

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

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

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

### Machine API

The accordion `api` exposes the following methods:

**`focusedValue`**
Type: `string | null`
Description: The value of the focused accordion item.

**`value`**
Type: `string[]`
Description: The value of the accordion

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

**`getItemState`**
Type: `(props: ItemProps) => ItemState`
Description: Returns the state of an accordion item.

**`getItemHeaderProps`**
Type: `(props: ItemProps) => T["element"]`
Description: Returns props for the item heading wrapper around the trigger.
Render this as a heading element (e.g. `h3`) per the WAI-ARIA accordion pattern.

### Data Attributes

**`Root`**

**`data-accordion-root`**: <uid>
**`data-orientation`**: The orientation of the accordion

**`Item`**

**`data-accordion-item`**: <uid>
**`data-state`**: "open" | "closed"
**`data-focus`**: Present when focused
**`data-disabled`**: Present when disabled
**`data-orientation`**: The orientation of the item

**`ItemContent`**

**`data-accordion-item-content`**: <uid>
**`data-state`**: "open" | "closed"
**`data-disabled`**: Present when disabled
**`data-focus`**: Present when focused
**`data-orientation`**: The orientation of the item

**`ItemIndicator`**

**`data-accordion-item-indicator`**: <uid>
**`data-state`**: "open" | "closed"
**`data-disabled`**: Present when disabled
**`data-focus`**: Present when focused
**`data-orientation`**: The orientation of the item

**`ItemHeader`**

**`data-accordion-item-header`**: <uid>
**`data-state`**: "open" | "closed"
**`data-focus`**: Present when focused
**`data-disabled`**: Present when disabled
**`data-orientation`**: The orientation of the item

**`ItemTrigger`**

**`data-accordion-item-trigger`**: <uid>
**`data-controls`**: 
**`data-orientation`**: The orientation of the item
**`data-state`**: "open" | "closed"
**`data-focus`**: Present when focused

## Accessibility

### Keyboard Interactions

**`Space`**
Description: When focus is on an trigger of a collapsed item, the item is expanded

**`Enter`**
Description: When focus is on an trigger of a collapsed section, expands the section.

**`Tab`**
Description: Moves focus to the next focusable element

**`Shift + Tab`**
Description: Moves focus to the previous focusable element

**`ArrowDown`**
Description: Moves focus to the next trigger

**`ArrowUp`**
Description: Moves focus to the previous trigger.

**`Home`**
Description: When focus is on an trigger, moves focus to the first trigger.

**`End`**
Description: When focus is on an trigger, moves focus to the last trigger.

An angle slider is a circular dial that allows users to select an angle,
typically in degrees, within a 360° range. It provides an intuitive way to
control rotations or orientations, offering accessibility features.

## Resources


[Latest version: v2.0.0-next.1](https://www.npmjs.com/package/@zag-js/angle-slider)
[Logic Visualizer](https://zag-visualizer.vercel.app/angle-slider)
[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/angle-slider)



**Features**

- Fully managed keyboard navigation
- Supports touch or click on the track to update value
- Supports right-to-left direction

## Installation

Install the angle slider package:

```bash
npm install @zag-js/angle-slider @zag-js/react
# or
yarn add @zag-js/angle-slider @zag-js/react
```

## Anatomy

To set up the angle slider 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 angle-slider package:

```tsx
import * as angleSlider from "@zag-js/angle-slider"
```

The angle slider package exports two key functions:

- `machine` - State machine logic.
- `connect` - Maps machine state to JSX props and event handlers.

> Pass a unique `id` to `useMachine` so generated element ids stay predictable.

Then use the framework integration helpers:

```tsx
import * as angleSlider from "@zag-js/angle-slider"
import { normalizeProps, useMachine } from "@zag-js/react"
import { useId } from "react"

export function AngleSlider() {
  const service = useMachine(angleSlider.machine, { id: useId() })

  const api = angleSlider.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <label {...api.getLabelProps()}>Wind direction</label>
      <div {...api.getControlProps()}>
        <div {...api.getThumbProps()}></div>
        <div {...api.getMarkerGroupProps()}>
          {[0, 45, 90, 135, 180, 225, 270, 315].map((value) => (
            <div key={value} {...api.getMarkerProps({ value })}></div>
          ))}
        </div>
      </div>
      <div {...api.getValueTextProps()}>{api.value} degrees</div>
      <input {...api.getHiddenInputProps()} />
    </div>
  )
}
```

### Setting the initial value

Set `defaultValue` to define the initial slider value.

```tsx {2}
const service = useMachine(angleSlider.machine, {
  defaultValue: 45,
})
```

### Controlled angle slider

Use `value` and `onValueChange` to control the value externally.

```tsx
import { useState } from "react"

export function ControlledAngleSlider() {
  const [value, setValue] = useState(45)

  const service = useMachine(angleSlider.machine, {
    value,
    onValueChange(details) {
      setValue(details.value)
    },
  })

  return (
    // ...
  )
}
```

### Setting the value's granularity

By default, `step` is `1`, so values move in whole-number increments. Set `step`
to control granularity.

For example, set `step` to `0.01` for two-decimal precision:

```tsx {2}
const service = useMachine(angleSlider.machine, {
  step: 0.01,
})
```

### Listening for changes

When the angle slider value changes, the `onValueChange` and `onValueChangeEnd`
callbacks are invoked.

```tsx {2-7}
const service = useMachine(angleSlider.machine, {
  onValueChange(details) {
    console.log("value:", details.value)
    console.log("as degree:", details.valueAsDegree)
  },
  onValueChangeEnd(details) {
    console.log("final value:", details.value)
  },
})
```

### Read-only mode

Set `readOnly` to prevent updates while preserving focus and form semantics.

```tsx {2}
const service = useMachine(angleSlider.machine, {
  readOnly: true,
})
```

### Usage in forms

To submit the value with a form:

- Set `name` on the machine.
- Render the hidden input from `api.getHiddenInputProps()`.

```tsx {2}
const service = useMachine(angleSlider.machine, {
  name: "wind-direction",
})
```

### Labeling the thumb for assistive tech

Use `aria-label` or `aria-labelledby` when you need custom labeling.

```tsx {2}
const service = useMachine(angleSlider.machine, {
  "aria-label": "Wind direction",
})
```

### Using angle slider marks

To show marks or ticks along the angle slider track, use the exposed
`api.getMarkerProps()` method to position the angle slider marks at desired
angles.

```tsx {7-11}
//...

<div {...api.getRootProps()}>
  <label {...api.getLabelProps()}>Wind direction</label>
  <div {...api.getControlProps()}>
    <div {...api.getThumbProps()}></div>
    <div {...api.getMarkerGroupProps()}>
      {[0, 45, 90, 135, 180, 225, 270, 315].map((value) => (
        <div key={value} {...api.getMarkerProps({ value })}></div>
      ))}
    </div>
  </div>
  <div {...api.getValueTextProps()}>{api.value} degrees</div>
  <input {...api.getHiddenInputProps()} />
</div>
//...
```

## Styling guide

Each part includes a `data-part` attribute you can target in CSS.

### Disabled State

When the angle slider is disabled, the `data-disabled` attribute is added to the
root, label, control, thumb and marker.

```css
[data-part="root"][data-disabled] {
  /* styles for root disabled state */
}

[data-part="label"][data-disabled] {
  /* styles for label disabled state */
}

[data-part="control"][data-disabled] {
  /* styles for control disabled state */
}

[data-part="thumb"][data-disabled] {
  /* styles for thumb disabled state */
}

[data-part="range"][data-disabled] {
  /* styles for thumb disabled state */
}
```

### Invalid State

When the slider is invalid, the `data-invalid` attribute is added to the root,
track, range, label, and thumb parts.

```css
[data-part="root"][data-invalid] {
  /* styles for root invalid state */
}

[data-part="label"][data-invalid] {
  /* styles for label invalid state */
}

[data-part="control"][data-invalid] {
  /* styles for control invalid state */
}

[data-part="valueText"][data-invalid] {
  /* styles for output invalid state */
}

[data-part="thumb"][data-invalid] {
  /* styles for thumb invalid state */
}

[data-part="marker"][data-invalid] {
  /* styles for marker invalid state */
}
```

### Styling the markers

```css
[data-part="marker"][data-state="(at|under|over)-value"] {
  /* styles for when the value exceeds the marker's value */
}
```

## Methods and Properties

### Machine Context

The angle slider machine exposes the following context properties:

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the machine.
Useful for composition.

**`step`**
Type: `number | undefined`
Description: The step value for the slider.

**`value`**
Type: `number | undefined`
Description: The value of the slider.

**`defaultValue`**
Type: `number | undefined`
Description: The initial value of the slider.
Use when you don't need to control the value of the slider.

**`onValueChange`**
Type: `((details: ValueChangeDetails) => void) | undefined`
Description: The callback function for when the value changes.

**`onValueChangeEnd`**
Type: `((details: ValueChangeDetails) => void) | undefined`
Description: The callback function for when the value changes ends.

**`disabled`**
Type: `boolean | undefined`
Description: Whether the slider is disabled.

**`readOnly`**
Type: `boolean | undefined`
Description: Whether the slider is read-only.

**`invalid`**
Type: `boolean | undefined`
Description: Whether the slider is invalid.

**`name`**
Type: `string | undefined`
Description: The name of the slider. Useful for form submission.

**`aria-label`**
Type: `string | undefined`
Description: The accessible label for the slider thumb.

**`aria-labelledby`**
Type: `string | undefined`
Description: The id of the element that labels the slider thumb.

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

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

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

### Machine API

The angle slider `api` exposes the following methods:

**`value`**
Type: `number`
Description: The current value of the angle slider

**`valueAsDegree`**
Type: `string`
Description: The current value as a degree string

**`setValue`**
Type: `(value: number) => void`
Description: Sets the value of the angle slider

**`dragging`**
Type: `boolean`
Description: Whether the slider is being dragged.

### Data Attributes

**`Root`**

**`data-angle-slider-root`**: <uid>
**`data-disabled`**: Present when disabled
**`data-invalid`**: Present when invalid
**`data-readonly`**: Present when read-only

**`Label`**

**`data-angle-slider-label`**: <uid>
**`data-disabled`**: Present when disabled
**`data-invalid`**: Present when invalid
**`data-readonly`**: Present when read-only

**`Control`**

**`data-angle-slider-control`**: <uid>
**`data-disabled`**: Present when disabled
**`data-invalid`**: Present when invalid
**`data-readonly`**: Present when read-only

**`Thumb`**

**`data-angle-slider-thumb`**: <uid>
**`data-disabled`**: Present when disabled
**`data-invalid`**: Present when invalid
**`data-readonly`**: Present when read-only

**`Marker`**

**`data-angle-slider-marker`**: <uid>
**`data-value`**: The value of the item
**`data-state`**: 
**`data-disabled`**: Present when disabled

### CSS Variables

<CssVarTable name="angle-slider" />

### Keyboard Interactions

**`ArrowRight`**
Description: <span>Increments the angle slider based on defined step</span>

**`ArrowLeft`**
Description: <span>Decrements the angle slider based on defined step</span>

**`ArrowUp`**
Description: <span>Decreases the value by the step amount.</span>

**`ArrowDown`**
Description: <span>Increases the value by the step amount.</span>

**`Shift + ArrowUp`**
Description: <span>Decreases the value by a larger step</span>

**`Shift + ArrowDown`**
Description: <span>Increases the value by a larger step</span>

**`Home`**
Description: Sets the value to 0 degrees.

**`End`**
Description: Sets the value to 360 degrees.

An avatar represents a user profile picture. It displays an image or fallback
content in a container.

Avatar supports fallback text or elements when the image fails to load or when
no image is provided.

## Resources


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



## Installation

Install the avatar package:

```bash
npm install @zag-js/avatar @zag-js/react
# or
yarn add @zag-js/avatar @zag-js/react
```

## Anatomy

Check the avatar anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the avatar package:

```tsx
import * as avatar from "@zag-js/avatar"
```

The avatar package exports two key functions:

- `machine` - State machine logic.
- `connect` - Maps machine state to JSX props and event handlers.

> Pass a unique `id` to `useMachine` so generated element ids stay predictable.

Then use the framework integration helpers:

```tsx
import * as avatar from "@zag-js/avatar"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useId } from "react"

function Avatar() {
  const service = useMachine(avatar.machine, { id: useId() })

  const api = avatar.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <span {...api.getFallbackProps()}>PA</span>
      <img alt="PA" src={src} {...api.getImageProps()} />
    </div>
  )
}
```

### Loading status

The image loading status is `loading`, `loaded`, or `error`. Read the current
value from `api.status`, or react to changes with `onStatusChange`.

```tsx {2}
const service = useMachine(avatar.machine, {
  onStatusChange(details) {
    // details => { status: "loading" | "error" | "loaded" }
  },
})
```

### Updating the image source

In framework adapters, update the image `src` through your own state. The
machine watches the rendered image and reacts automatically, resetting to
`loading` and then to `loaded` or `error`.

For imperative usage like vanilla JS, `api.setSrc` sets the source on the
machine's image element directly.

```tsx
api.setSrc(nextSrc)
```

## Styling guide

Each avatar part includes a `data-part` attribute you can target in CSS.

```css
[data-scope="avatar"][data-part="root"] {
  /* Styles for the root part */
}

[data-scope="avatar"][data-part="image"] {
  /* Styles for the image part */
}

[data-scope="avatar"][data-part="fallback"] {
  /* Styles for the fallback part */
}
```

## Creating a component

Create your avatar component by abstracting the machine into your own component.

### Usage

```tsx
import { Avatar } from "./your-avatar"

function Demo() {
  return (
    <Avatar
      src="https://avatars.githubusercontent.com/u/139426"
      name="John Doe"
    />
  )
}
```

### Implementation

Use the `splitProps` utility to separate the machine's props from the
component's props.

```tsx
import * as avatar from "@zag-js/avatar"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useId } from "react"

export interface AvatarProps extends Omit<avatar.Context, "id"> {
  /**
   * The src of the avatar image
   */
  src?: string
  /**
   * The srcSet of the avatar image
   */
  srcSet?: string
  /**
   * The name of the avatar
   */
  name: string
}

function Avatar(props: AvatarProps) {
  const [machineProps, localProps] = avatar.splitProps(props)

  const service = useMachine(avatar.machine, {
    id: useId(),
    ...machineProps,
  })

  const api = avatar.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <span {...api.getFallbackProps()}>{getInitials(localProps.name)}</span>
      <img
        alt="PA"
        src={localProps.src}
        srcSet={localProps.srcSet}
        {...api.getImageProps()}
      />
    </div>
  )
}

function getInitials(name: string) {
  return name
    .split(" ")
    .map((word) => word[0])
    .join("")
}
```

## Methods and Properties

### Machine Context

The avatar machine exposes the following context properties:

**`onStatusChange`**
Type: `((details: StatusChangeDetails) => void) | undefined`
Description: Functional called when the image loading status changes.

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the avatar. Useful for composition.

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

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

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

### Machine API

The avatar `api` exposes the following methods:

**`status`**
Type: `LoadStatus`
Description: The current image loading status.

**`loaded`**
Type: `boolean`
Description: Whether the image is loaded.

**`setSrc`**
Type: `(src: string) => void`
Description: Function to set new src.

**`setLoaded`**
Type: `VoidFunction`
Description: Function to set loaded state.

**`setError`**
Type: `VoidFunction`
Description: Function to set error state.

### Data Attributes

**`Image`**

**`data-avatar-image`**: <uid>
**`data-state`**: "visible" | "hidden"

**`Fallback`**

**`data-avatar-fallback`**: <uid>
**`data-state`**: "hidden" | "visible"

A carousel component that leverages native CSS Scroll Snap for smooth,
performant scrolling between slides.

## Resources


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



**Features**

- Uses native CSS Scroll Snap
- Supports horizontal and vertical orientations
- Supports slide alignment (`start`, `center`, `end`)
- Supports showing multiple slides at a time
- Supports looping and auto-playing
- Supports custom spacing between slides

## Installation

Install the carousel package:

```bash
npm install @zag-js/carousel @zag-js/react
# or
yarn add @zag-js/carousel @zag-js/react
```

## Anatomy

Check the carousel anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the carousel package:

```tsx
import * as carousel from "@zag-js/carousel"
```

The carousel package exports two key functions:

- `machine` - State machine logic.
- `connect` - Maps machine state to JSX props and event handlers.

> Pass a unique `id` to `useMachine` so generated element ids stay predictable.

Then use the framework integration helpers:

> **Note:** The carousel requires that you provide a `count` property in the
> machine context. This is the total number of slides.

```tsx
import * as carousel from "@zag-js/carousel"
import { normalizeProps, useMachine } from "@zag-js/react"

const items = [
  "https://tinyurl.com/5b6ka8jd",
  "https://tinyurl.com/7rmccdn5",
  "https://tinyurl.com/59jxz9uu",
]

export function Carousel() {
  const service = useMachine(carousel.machine, {
    id: "1",
    count: items.length,
  })

  const api = carousel.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <div {...api.getControlProps()}>
        <button {...api.getPrevTriggerProps()}>Prev</button>
        <button {...api.getNextTriggerProps()}>Next</button>
      </div>
      <div {...api.getItemGroupProps()}>
        {items.map((image, index) => (
          <div {...api.getItemProps({ index })} key={index}>
            <img
              src={image}
              alt=""
              style={{ height: "300px", width: "100%", objectFit: "cover" }}
            />
          </div>
        ))}
      </div>
      <div {...api.getIndicatorGroupProps()}>
        {api.pageSnapPoints.map((_, index) => (
          <button {...api.getIndicatorProps({ index })} key={index} />
        ))}
      </div>
    </div>
  )
}
```

### Vertical orientation

Set `orientation` to `vertical` to render a vertical carousel.

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

### Setting the initial slide

Set `defaultPage` to define the initial page.

> The `defaultPage` corresponds to the scroll snap position index based on the
> layout. It does not necessarily correspond to the index of the slide in the
> carousel.

```tsx {2}
const service = useMachine(carousel.machine, {
  defaultPage: 2,
})
```

### Controlling the current page

Use `page` and `onPageChange` for controlled navigation.

```tsx
const service = useMachine(carousel.machine, {
  count: 8,
  page,
  onPageChange(details) {
    setPage(details.page)
  },
})
```

### Setting slides per page

Set `slidesPerPage` to control how many slides are visible per page.

```tsx {2}
const service = useMachine(carousel.machine, {
  slidesPerPage: 2,
})
```

### Setting slides per move

Set `slidesPerMove` to control how many slides advance on next/previous.

```tsx {2}
const service = useMachine(carousel.machine, {
  slidesPerMove: 2,
})
```

**Considerations**

- If the value is `auto`, the carousel will move the number of slides equal to
  the number of slides per page.
- Ensure the `slidesPerMove` is less than or equal to the `slidesPerPage` to
  avoid skipping slides.
- On touch devices, `slidesPerMove` is not enforced during active swiping. The
  browser's native scrolling and CSS Scroll Snap determine slide movement for
  optimal performance and UX.

### Looping pages

Set `loop` to `true` to wrap around from last to first page.

```tsx {2}
const service = useMachine(carousel.machine, {
  loop: true,
})
```

### Setting the gap between slides

Set `spacing` to control the gap between slides.

```tsx {2}
const service = useMachine(carousel.machine, {
  spacing: "16px",
})
```

### Setting viewport padding

Set `itemSpacing` to keep neighboring slides partially visible.

```tsx {2}
const service = useMachine(carousel.machine, {
  itemSpacing: "16px",
})
```

### Variable-width slides

Set `autoSize` to `true` when slides have different widths.

```tsx {2}
const service = useMachine(carousel.machine, {
  autoSize: true,
})
```

### Listening for page changes

When the carousel page changes, the `onPageChange` callback is invoked.

```tsx {2-5}
const service = useMachine(carousel.machine, {
  onPageChange(details) {
    // details => { page: number }
    console.log("selected page:", details.page)
  },
})
```

### Listening for drag and autoplay status

Use status callbacks to react to dragging and autoplay lifecycle changes.

```tsx
const service = useMachine(carousel.machine, {
  onDragStatusChange(details) {
    console.log(details.type, details.isDragging)
  },
  onAutoplayStatusChange(details) {
    console.log(details.type, details.isPlaying)
  },
})
```

### Dragging the carousel

Set `allowMouseDrag` to `true` to drag the carousel with a mouse.

```tsx {2}
const service = useMachine(carousel.machine, {
  allowMouseDrag: true,
})
```

### Autoplaying the carousel

Set `autoPlay` to `true` to start automatic slide movement.

```tsx {2}
const service = useMachine(carousel.machine, {
  autoPlay: true,
})
```

Alternatively, you can configure the autoplay interval by setting the `delay`
property.

```tsx {2}
const service = useMachine(carousel.machine, {
  autoPlay: { delay: 2000 },
})
```

### Customizing accessibility messages

Use `translations` to customize localized trigger, item, and progress text.

```tsx
const service = useMachine(carousel.machine, {
  count: 5,
  translations: {
    nextTrigger: "Next slide",
    prevTrigger: "Previous slide",
    indicator: (index) => `Go to slide ${index + 1}`,
    item: (index, count) => `Slide ${index + 1} of ${count}`,
    autoplayStart: "Start autoplay",
    autoplayStop: "Stop autoplay",
    progressText: ({ page, totalPages }) => `Page ${page + 1} of ${totalPages}`,
  },
})
```

## Styling guide

Each part includes a `data-part` attribute you can target in CSS.

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

[data-part="item-group"] {
  /* styles for the item-group part */
}

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

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

[data-part="next-trigger"] {
  /* styles for the next-trigger part */
}

[data-part="prev-trigger"] {
  /* styles for the prev-trigger part */
}

[data-part="indicator-group"] {
  /* styles for the indicator-group part */
}

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

[data-part="autoplay-trigger"] {
  /* styles for the autoplay-trigger part */
}
```

### Active state

When a carousel's indicator is active, a `data-current` attribute is set on the
indicator.

```css
[data-part="indicator"][data-current] {
  /* styles for the indicator's active state */
}
```

## Methods and Properties

The carousel's `api` exposes the following methods and properties:

### Machine Context

The carousel machine exposes the following context properties:

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the carousel. Useful for composition.

**`translations`**
Type: `IntlTranslations | undefined`
Description: The localized messages to use.

**`slidesPerPage`**
Type: `number | undefined`
Description: The number of slides to show at a time.

**`autoSize`**
Type: `boolean | undefined`
Description: Whether to enable variable width slides.

**`slidesPerMove`**
Type: `number | "auto" | undefined`
Description: The number of slides to scroll at a time.

When set to `auto`, the number of slides to scroll is determined by the
`slidesPerPage` property.

**`autoPlay`**
Type: `boolean | { delay: number } | undefined`
Description: Whether to scroll automatically. The default delay is 4000ms.

**`allowMouseDrag`**
Type: `boolean | undefined`
Description: Whether to allow scrolling via dragging with mouse

**`loop`**
Type: `boolean | undefined`
Description: Whether the carousel should loop around.

**`page`**
Type: `number | undefined`
Description: The controlled page of the carousel.

**`defaultPage`**
Type: `number | undefined`
Description: The initial page to scroll to when rendered.
Use when you don't need to control the page of the carousel.

**`spacing`**
Type: `string | undefined`
Description: The amount of space between items.

**`itemSpacing`**
Type: `string | undefined`
Description: Defines the extra space added around the scrollable area,
enabling nearby items to remain partially in view.

**`onPageChange`**
Type: `((details: PageChangeDetails) => void) | undefined`
Description: Function called when the page changes.

**`inViewThreshold`**
Type: `number | number[] | undefined`
Description: The threshold for determining if an item is in view.

**`snapType`**
Type: `"proximity" | "mandatory" | undefined`
Description: The snap type of the item.

**`count`**
Type: `number`
Description: The total number of slides.
Useful for SSR to render the initial snap points.

**`onDragStatusChange`**
Type: `((details: DragStatusDetails) => void) | undefined`
Description: Function called when the drag status changes.

**`onAutoplayStatusChange`**
Type: `((details: AutoplayStatusDetails) => void) | undefined`
Description: Function called when the autoplay status changes.

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

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

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

**`orientation`**
Type: `"horizontal" | "vertical" | undefined`
Description: The orientation of the element.

### Machine API

The carousel `api` exposes the following methods:

**`page`**
Type: `number`
Description: The current index of the carousel

**`pageSnapPoints`**
Type: `number[]`
Description: The current snap points of the carousel

**`isPlaying`**
Type: `boolean`
Description: Whether the carousel is auto playing

**`isDragging`**
Type: `boolean`
Description: Whether the carousel is being dragged. This only works when `draggable` is true.

**`canScrollNext`**
Type: `boolean`
Description: Whether the carousel is can scroll to the next view

**`canScrollPrev`**
Type: `boolean`
Description: Whether the carousel is can scroll to the previous view

**`scrollToIndex`**
Type: `(index: number, instant?: boolean) => void`
Description: Function to scroll to a specific item index

**`scrollTo`**
Type: `(page: number, instant?: boolean) => void`
Description: Function to scroll to a specific page

**`scrollNext`**
Type: `(instant?: boolean) => void`
Description: Function to scroll to the next page

**`scrollPrev`**
Type: `(instant?: boolean) => void`
Description: Function to scroll to the previous page

**`getProgress`**
Type: `() => number`
Description: Returns the current scroll progress as a percentage

**`getProgressText`**
Type: `() => string`
Description: Returns the progress text

**`play`**
Type: `VoidFunction`
Description: Function to start/resume autoplay

**`pause`**
Type: `VoidFunction`
Description: Function to pause autoplay

**`isInView`**
Type: `(index: number) => boolean`
Description: Whether the item is in view

**`refresh`**
Type: `VoidFunction`
Description: Function to re-compute the snap points
and clamp the page

### Data Attributes

**`Root`**

**`data-carousel-root`**: <uid>
**`data-orientation`**: The orientation of the carousel

**`ItemGroup`**

**`data-carousel-item-group`**: <uid>
**`data-orientation`**: The orientation of the item
**`data-dragging`**: Present when in the dragging state

**`Item`**

**`data-carousel-item`**: <uid>
**`data-index`**: The index of the item
**`data-inview`**: Present when in viewport
**`data-orientation`**: The orientation of the item

**`Control`**

**`data-carousel-control`**: <uid>
**`data-orientation`**: The orientation of the control

**`PrevTrigger`**

**`data-carousel-prev-trigger`**: <uid>
**`data-orientation`**: The orientation of the prevtrigger

**`NextTrigger`**

**`data-carousel-next-trigger`**: <uid>
**`data-orientation`**: The orientation of the nexttrigger

**`IndicatorGroup`**

**`data-carousel-indicator-group`**: <uid>
**`data-orientation`**: The orientation of the indicatorgroup

**`Indicator`**

**`data-carousel-indicator`**: <uid>
**`data-orientation`**: The orientation of the indicator
**`data-index`**: The index of the item
**`data-readonly`**: Present when read-only
**`data-current`**: Present when current

**`AutoplayTrigger`**

**`data-carousel-autoplay-trigger`**: <uid>
**`data-orientation`**: The orientation of the autoplaytrigger
**`data-pressed`**: Present when pressed

### CSS Variables

<CssVarTable name="carousel" />

A cascade select component allows users to select from hierarchical data through
multiple linked levels of dropdown menus.

## Resources


[Latest version: v2.0.0-next.1](https://www.npmjs.com/package/@zag-js/cascade-select)
[Logic Visualizer](https://zag-visualizer.vercel.app/cascade-select)
[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/cascade-select)



**Features**

- Supports hierarchical data with unlimited depth levels
- Full keyboard navigation across all levels with arrow keys
- Supports single and multiple selections
- Supports both click and hover triggering modes
- Supports looping keyboard navigation
- Built-in accessibility with ARIA roles and keyboard interactions
- Supports disabled items and read-only state
- Form integration with hidden input element
- Supports right-to-left direction

## Installation

Install the cascade select package:

```bash
npm install @zag-js/cascade-select @zag-js/react
# or
yarn add @zag-js/cascade-select @zag-js/react
```

## Anatomy

Check the cascade select anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the cascade select package:

```tsx
import * as cascadeSelect from "@zag-js/cascade-select"
```

These are the key exports:

- `machine` - State machine logic.
- `connect` - Maps machine state to JSX props and event handlers.
- `collection` - Creates a tree collection from your hierarchical data.

### Create the collection

Use the `collection` function to create a tree collection from your hierarchical
data. Pass a `rootNode` along with functions to extract each node's value,
string label, and children.

```ts
import * as cascadeSelect from "@zag-js/cascade-select"

interface Node {
  label: string
  value: string
  children?: Node[]
}

const collection = cascadeSelect.collection<Node>({
  nodeToValue: (node) => node.value,
  nodeToString: (node) => node.label,
  nodeToChildren: (node) => node.children,
  rootNode: {
    label: "ROOT",
    value: "ROOT",
    children: [
      {
        label: "North America",
        value: "north-america",
        children: [
          {
            label: "United States",
            value: "us",
            children: [
              { label: "New York", value: "ny" },
              { label: "California", value: "ca" },
            ],
          },
          { label: "Canada", value: "canada" },
        ],
      },
      {
        label: "Africa",
        value: "africa",
        children: [
          { label: "Nigeria", value: "ng" },
          { label: "Kenya", value: "ke" },
        ],
      },
    ],
  },
})
```

### Create the cascade select

> Pass a unique `id` to `useMachine` so generated element ids stay predictable.

Then use the framework integration helpers:

```tsx
import * as cascadeSelect from "@zag-js/cascade-select"
import { normalizeProps, Portal, useMachine } from "@zag-js/react"
import { JSX, useId } from "react"

// 1. Create the collection (see above)
const collection = cascadeSelect.collection<Node>({
  // ...
})

// 2. Create the recursive tree node

interface TreeNodeProps {
  node: Node
  indexPath?: number[]
  value?: string[]
  api: cascadeSelect.Api
}

const TreeNode = (props: TreeNodeProps): JSX.Element => {
  const { node, indexPath = [], value = [], api } = props

  const nodeProps = { indexPath, value, item: node }
  const nodeState = api.getItemState(nodeProps)
  const children = collection.getNodeChildren(node)

  return (
    <>
      <ul {...api.getListProps(nodeProps)}>
        {children.map((item, index) => {
          const itemProps = {
            indexPath: [...indexPath, index],
            value: [...value, collection.getNodeValue(item)],
            item,
          }
          const itemState = api.getItemState(itemProps)
          return (
            <li key={collection.getNodeValue(item)} {...api.getItemProps(itemProps)}>
              <span {...api.getItemTextProps(itemProps)}>{item.label}</span>
              {itemState.hasChildren && <span>›</span>}
              <span {...api.getItemIndicatorProps(itemProps)}>✓</span>
            </li>
          )
        })}
      </ul>
      {nodeState.highlightedChild &&
        collection.isBranchNode(nodeState.highlightedChild) && (
          <TreeNode
            node={nodeState.highlightedChild}
            api={api}
            indexPath={[...indexPath, nodeState.highlightedIndex]}
            value={[...value, collection.getNodeValue(nodeState.highlightedChild)]}
          />
        )}
    </>
  )
}

// 3. Create the cascade select

export function CascadeSelect() {
  const service = useMachine(cascadeSelect.machine, {
    id: useId(),
    collection,
  })

  const api = cascadeSelect.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <label {...api.getLabelProps()}>Location</label>
      <div {...api.getControlProps()}>
        <button {...api.getTriggerProps()}>
          <span>{api.valueAsString || "Select location"}</span>
          <span {...api.getIndicatorProps()}>▼</span>
        </button>
        <button {...api.getClearTriggerProps()}>✕</button>
      </div>
      <Portal>
        <div {...api.getPositionerProps()}>
          <div {...api.getContentProps()}>
            <TreeNode node={collection.rootNode} api={api} />
          </div>
        </div>
      </Portal>
    </div>
  )
}
```

### Setting the initial value

Use the `defaultValue` property to set the initial value of the cascade select.

> The `value` property must be an array of string paths. Each path is an array
> of values from the root to the selected leaf item.

```tsx {4}
const service = useMachine(cascadeSelect.machine, {
  id: useId(),
  collection,
  defaultValue: [["north-america", "us", "ny"]],
})
```

### Controlled selection

Use `value` and `onValueChange` for controlled selection state.

```tsx
const service = useMachine(cascadeSelect.machine, {
  id: useId(),
  collection,
  value,
  onValueChange(details) {
    setValue(details.value)
  },
})
```

### Selecting multiple values

To allow selecting multiple values, set the `multiple` property to `true`.

```tsx {4}
const service = useMachine(cascadeSelect.machine, {
  id: useId(),
  collection,
  multiple: true,
})
```

### Hover triggering

By default, items are highlighted when clicked. To highlight items on hover
instead (like a traditional cascading menu), set the `highlightTrigger` property
to `"hover"`.

```tsx {4}
const service = useMachine(cascadeSelect.machine, {
  id: useId(),
  collection,
  highlightTrigger: "hover",
})
```

### Allowing parent selection

By default, only leaf nodes (items without children) can be selected. To allow
parent (branch) nodes to also be selectable, set `allowParentSelection` to
`true`.

```tsx {4}
const service = useMachine(cascadeSelect.machine, {
  id: useId(),
  collection,
  allowParentSelection: true,
})
```

### Close on select

By default, the menu closes when you select an item. Set `closeOnSelect` to
`false` to keep it open.

```tsx {4}
const service = useMachine(cascadeSelect.machine, {
  id: useId(),
  collection,
  closeOnSelect: false,
})
```

### Looping the keyboard navigation

By default, arrow-key navigation stops at the first and last items. Set
`loopFocus: true` to loop back around.

```tsx {4}
const service = useMachine(cascadeSelect.machine, {
  id: useId(),
  collection,
  loopFocus: true,
})
```

### Listening for highlight changes

When an item is highlighted with the pointer or keyboard, use the
`onHighlightChange` to listen for the change and do something with it.

```tsx {3-6}
const service = useMachine(cascadeSelect.machine, {
  id: useId(),
  onHighlightChange(details) {
    // details => { highlightedValue: string[], highlightedItems: Item[] }
    console.log(details)
  },
})
```

### Setting the initial highlighted path

Use `defaultHighlightedValue` to set the initially highlighted path.

```tsx
const service = useMachine(cascadeSelect.machine, {
  id: useId(),
  collection,
  defaultHighlightedValue: ["north-america", "us"],
})
```

### Controlled highlighted path

Use `highlightedValue` and `onHighlightChange` to control highlighting
externally.

```tsx
const service = useMachine(cascadeSelect.machine, {
  id: useId(),
  collection,
  highlightedValue,
  onHighlightChange(details) {
    setHighlightedValue(details.highlightedValue)
  },
})
```

### Listening for selection changes

When an item is selected, use the `onValueChange` property to listen for the
change and do something with it.

```tsx {4-7}
const service = useMachine(cascadeSelect.machine, {
  id: useId(),
  collection,
  onValueChange(details) {
    // details => { value: string[][], items: Item[][] }
    console.log(details)
  },
})
```

### Listening for open and close events

Use `onOpenChange` to listen for open and close events.

```tsx {4-7}
const service = useMachine(cascadeSelect.machine, {
  id: useId(),
  collection,
  onOpenChange(details) {
    // details => { open: boolean, value: string[][] }
    console.log(details)
  },
})
```

### Controlling open state

Use `open` and `onOpenChange` for controlled open state, or `defaultOpen` for an
uncontrolled initial state.

```tsx
const service = useMachine(cascadeSelect.machine, {
  id: useId(),
  collection,
  open,
  onOpenChange({ open }) {
    setOpen(open)
  },
})
```

```tsx
const service = useMachine(cascadeSelect.machine, {
  id: useId(),
  collection,
  defaultOpen: true,
})
```

### Positioning submenu panels

Use `positioning` to configure placement and collision behavior.

```tsx
const service = useMachine(cascadeSelect.machine, {
  id: useId(),
  collection,
  positioning: {
    placement: "right-start",
    gutter: 4,
  },
})
```

### Custom scroll behavior

Use `scrollToIndexFn` to customize how each level scrolls highlighted items into
view.

```tsx
const service = useMachine(cascadeSelect.machine, {
  id: useId(),
  collection,
  scrollToIndexFn(details) {
    // details => { index, depth, immediate? }
    customScroll(details)
  },
})
```

### Customizing the trigger label

Use `formatValue` to control how selected paths are rendered in the trigger.

```tsx
const service = useMachine(cascadeSelect.machine, {
  id: useId(),
  collection,
  formatValue(selectedItems) {
    return selectedItems
      .map((path) => path.map((item) => item.label).join(" / "))
      .join(", ")
  },
})
```

### Usage within a form

To use cascade select in a form, pass `name`. A hidden input is rendered with
`getHiddenInputProps()`.

```tsx {4}
const service = useMachine(cascadeSelect.machine, {
  id: useId(),
  collection,
  name: "location",
})

// In your JSX
<input {...api.getHiddenInputProps()} />
```

If the hidden input belongs to a different form element, also set `form`.

```tsx
const service = useMachine(cascadeSelect.machine, {
  id: useId(),
  collection,
  name: "location",
  form: "checkout-form",
})
```

### Validation and read-only state

Use `readOnly`, `required`, and `invalid` to control interaction and form state.

```tsx
const service = useMachine(cascadeSelect.machine, {
  id: useId(),
  collection,
  readOnly: true,
  required: true,
  invalid: false,
})
```

## Styling guide

Each cascade select part includes a `data-part` attribute you can target in CSS.

### Open and closed state

When the cascade select is open, the trigger and content is given a `data-state`
attribute.

```css
[data-part="trigger"][data-state="open|closed"] {
  /* styles for open or closed state */
}

[data-part="content"][data-state="open|closed"] {
  /* styles for open or closed state */
}
```

### Selected state

Items are given a `data-state` attribute, indicating whether they are selected.

```css
[data-part="item"][data-state="checked|unchecked"] {
  /* styles for selected or unselected state */
}
```

### Highlighted state

When an item is highlighted, via keyboard navigation or pointer, it is given a
`data-highlighted` attribute.

```css
[data-part="item"][data-highlighted] {
  /* styles for highlighted state */
}
```

### Branch items

When an item has children (is a branch node), it is given a `data-has-children`
attribute.

```css
[data-part="item"][data-has-children] {
  /* styles for items with children (branch nodes) */
}
```

### Invalid state

When the cascade select is invalid, the label and trigger is given a
`data-invalid` attribute.

```css
[data-part="label"][data-invalid] {
  /* styles for invalid state */
}

[data-part="trigger"][data-invalid] {
  /* styles for invalid state */
}
```

### Disabled state

When the cascade select is disabled, the trigger and label is given a
`data-disabled` attribute.

```css
[data-part="trigger"][data-disabled] {
  /* styles for disabled state */
}

[data-part="label"][data-disabled] {
  /* styles for disabled label state */
}

[data-part="item"][data-disabled] {
  /* styles for disabled item state */
}
```

### Empty state

When no option is selected, the trigger is given a `data-placeholder-shown`
attribute.

```css
[data-part="trigger"][data-placeholder-shown] {
  /* styles for empty state */
}
```

## Methods and Properties

### Machine Context

The cascade select machine exposes the following context properties:

**`collection`**
Type: `TreeCollection<T> | undefined`
Description: The tree collection data

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the cascade-select elements. Useful for composition.

**`name`**
Type: `string | undefined`
Description: The name attribute of the underlying input element

**`form`**
Type: `string | undefined`
Description: The form attribute of the underlying input element

**`value`**
Type: `string[][] | undefined`
Description: The controlled value of the cascade-select

**`defaultValue`**
Type: `string[][] | undefined`
Description: The initial value of the cascade-select when rendered.
Use when you don't need to control the value.

**`highlightedValue`**
Type: `string[] | undefined`
Description: The controlled highlighted value of the cascade-select

**`defaultHighlightedValue`**
Type: `string[] | undefined`
Description: The initial highlighted value of the cascade-select when rendered.

**`multiple`**
Type: `boolean | undefined`
Description: Whether to allow multiple selections

**`open`**
Type: `boolean | undefined`
Description: The controlled open state of the cascade-select

**`defaultOpen`**
Type: `boolean | undefined`
Description: The initial open state of the cascade-select when rendered.
Use when you don't need to control the open state.

**`highlightTrigger`**
Type: `"click" | "hover" | undefined`
Description: What triggers highlighting of items

**`closeOnSelect`**
Type: `boolean | undefined`
Description: Whether the cascade-select should close when an item is selected

**`loopFocus`**
Type: `boolean | undefined`
Description: Whether the cascade-select should loop focus when navigating with keyboard

**`disabled`**
Type: `boolean | undefined`
Description: Whether the cascade-select is disabled

**`readOnly`**
Type: `boolean | undefined`
Description: Whether the cascade-select is read-only

**`required`**
Type: `boolean | undefined`
Description: Whether the cascade-select is required

**`invalid`**
Type: `boolean | undefined`
Description: Whether the cascade-select is invalid

**`positioning`**
Type: `PositioningOptions | undefined`
Description: The positioning options for the cascade-select content

**`scrollToIndexFn`**
Type: `((details: ScrollToIndexDetails) => void) | undefined`
Description: Function to scroll to a specific index in a list

**`formatValue`**
Type: `((selectedItems: T[][]) => string) | undefined`
Description: Function to format the display value

**`onValueChange`**
Type: `((details: ValueChangeDetails<T>) => void) | undefined`
Description: Called when the value changes

**`onHighlightChange`**
Type: `((details: HighlightChangeDetails<T>) => void) | undefined`
Description: Called when the highlighted value changes

**`onOpenChange`**
Type: `((details: OpenChangeDetails) => void) | undefined`
Description: Called when the open state changes

**`allowParentSelection`**
Type: `boolean | undefined`
Description: Whether parent (branch) items can be selectable

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

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

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

**`onPointerDownOutside`**
Type: `((event: PointerDownOutsideEvent) => void) | undefined`
Description: Function called when the pointer is pressed down outside the component

**`onFocusOutside`**
Type: `((event: FocusOutsideEvent) => void) | undefined`
Description: Function called when the focus is moved outside the component

**`onInteractOutside`**
Type: `((event: InteractOutsideEvent) => void) | undefined`
Description: Function called when an interaction happens outside the component

### Machine API

The cascade select `api` exposes the following methods:

**`collection`**
Type: `TreeCollection<V>`
Description: The tree collection data

**`open`**
Type: `boolean`
Description: Whether the cascade-select is open

**`focused`**
Type: `boolean`
Description: Whether the cascade-select is focused

**`multiple`**
Type: `boolean`
Description: Whether the cascade-select allows multiple selections

**`disabled`**
Type: `boolean`
Description: Whether the cascade-select is disabled

**`highlightedValue`**
Type: `string[]`
Description: The value of the highlighted item

**`highlightedItems`**
Type: `V[]`
Description: The items along the highlighted path

**`selectedItems`**
Type: `V[][]`
Description: The selected items

**`hasSelectedItems`**
Type: `boolean`
Description: Whether there's a selected option

**`empty`**
Type: `boolean`
Description: Whether the cascade-select value is empty

**`value`**
Type: `string[][]`
Description: The current value of the cascade-select

**`valueAsString`**
Type: `string`
Description: The current value as text

**`focus`**
Type: `() => void`
Description: Function to focus on the select input

**`reposition`**
Type: `(options?: any) => void`
Description: Function to set the positioning options of the cascade-select

**`setOpen`**
Type: `(open: boolean) => void`
Description: Function to open the cascade-select

**`setHighlightValue`**
Type: `(value: string | string[]) => void`
Description: Function to set the highlighted value (path or single value to find)

**`clearHighlightValue`**
Type: `() => void`
Description: Function to clear the highlighted value

**`selectValue`**
Type: `(value: string[]) => void`
Description: Function to select a value

**`setValue`**
Type: `(value: string[][]) => void`
Description: Function to set the value

**`clearValue`**
Type: `(value?: string[] | undefined) => void`
Description: Function to clear the value

**`getItemState`**
Type: `(props: ItemProps<V>) => ItemState<V>`
Description: Returns the state of a cascade-select item

### Data Attributes

**`Root`**

**`data-cascade-select-root`**: <uid>
**`data-disabled`**: Present when disabled
**`data-readonly`**: Present when read-only
**`data-invalid`**: Present when invalid
**`data-state`**: "open" | "closed"

**`Label`**

**`data-cascade-select-label`**: <uid>
**`data-disabled`**: Present when disabled
**`data-readonly`**: Present when read-only
**`data-invalid`**: Present when invalid

**`Control`**

**`data-cascade-select-control`**: <uid>
**`data-disabled`**: Present when disabled
**`data-focus`**: Present when focused
**`data-readonly`**: Present when read-only
**`data-invalid`**: Present when invalid
**`data-state`**: "open" | "closed"

**`Trigger`**

**`data-cascade-select-trigger`**: <uid>
**`data-state`**: "open" | "closed"
**`data-disabled`**: Present when disabled
**`data-readonly`**: Present when read-only
**`data-invalid`**: Present when invalid
**`data-focus`**: Present when focused
**`data-placement`**: The placement of the trigger
**`data-side`**: The side of the trigger that the trigger is positioned on
**`data-placeholder-shown`**: Present when placeholder is shown

**`ClearTrigger`**

**`data-cascade-select-clear-trigger`**: <uid>
**`data-disabled`**: Present when disabled
**`data-readonly`**: Present when read-only
**`data-invalid`**: Present when invalid

**`Content`**

**`data-cascade-select-content`**: <uid>
**`data-activedescendant`**: The id the active descendant of the content
**`data-state`**: "open" | "closed"

**`List`**

**`data-cascade-select-list`**: <uid>
**`data-depth`**: The depth of the item

**`Indicator`**

**`data-cascade-select-indicator`**: <uid>
**`data-state`**: "open" | "closed"
**`data-disabled`**: Present when disabled
**`data-readonly`**: Present when read-only
**`data-invalid`**: Present when invalid

**`Item`**

**`data-cascade-select-item`**: <uid>
**`data-value`**: The value of the item
**`data-disabled`**: Present when disabled
**`data-highlighted`**: Present when highlighted
**`data-selected`**: Present when selected
**`data-depth`**: The depth of the item
**`data-state`**: "checked" | "unchecked"
**`data-type`**: The type of the item
**`data-index-path`**: 

**`ItemText`**

**`data-cascade-select-item-text`**: <uid>
**`data-value`**: The value of the item
**`data-highlighted`**: Present when highlighted
**`data-state`**: "checked" | "unchecked"
**`data-disabled`**: Present when disabled

**`ItemIndicator`**

**`data-cascade-select-item-indicator`**: <uid>
**`data-value`**: The value of the item
**`data-highlighted`**: Present when highlighted
**`data-type`**: The type of the item
**`data-state`**: "checked" | "unchecked"

**`ValueText`**

**`data-cascade-select-value-text`**: <uid>
**`data-disabled`**: Present when disabled
**`data-invalid`**: Present when invalid
**`data-focus`**: Present when focused

### CSS Variables

<CssVarTable name="cascade-select" />

## Accessibility

Adheres to the
[ListBox WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox).

### Keyboard Interactions

**`Space`**
Description: <span>When focus is on trigger, opens the cascade select and focuses the first item.<br />When focus is on the content, selects the highlighted item.</span>

**`Enter`**
Description: <span>When focus is on trigger, opens the cascade select and focuses the first item.<br />When focus is on content, selects the highlighted item.</span>

**`ArrowDown`**
Description: <span>When focus is on trigger, opens the cascade select.<br />When focus is on content, moves focus to the next item in the current level.</span>

**`ArrowUp`**
Description: <span>When focus is on trigger, opens the cascade select and focuses the last item.<br />When focus is on content, moves focus to the previous item in the current level.</span>

**`ArrowRight`**
Description: <span>When focus is on a branch item, expands the next level and moves focus into it.</span>

**`ArrowLeft`**
Description: <span>When focus is on a nested level, collapses it and moves focus back to the parent.<br />When focus is at the root level, closes the cascade select.</span>

**`Home`**
Description: <span>Moves focus to the first item in the current level.</span>

**`End`**
Description: <span>Moves focus to the last item in the current level.</span>

**`Esc`**
Description: <span>Closes the cascade select and moves focus to trigger.</span>

A checkbox allows users to make a binary choice, i.e. a choice between one of
two possible mutually exclusive options.

## Resources


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



**Features**

- Tri-state checkbox (`indeterminate` state)
- Syncs with `disabled` state of fieldset
- Syncs with form `reset` events
- Can be toggled programmatically

## Installation

Install the checkbox package:

```bash
npm install @zag-js/checkbox @zag-js/react
# or
yarn add @zag-js/checkbox @zag-js/react
```

## Anatomy

Check the checkbox anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the checkbox package:

```tsx
import * as checkbox from "@zag-js/checkbox"
```

The checkbox 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:

```tsx
import * as checkbox from "@zag-js/checkbox"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useId } from "react"

function Checkbox() {
  const service = useMachine(checkbox.machine, { id: useId() })

  const api = checkbox.connect(service, normalizeProps)

  return (
    <label {...api.getRootProps()}>
      <span {...api.getLabelProps()}>
        Input is {api.checked ? "checked" : "unchecked"}
      </span>
      <div {...api.getControlProps()} />
      <input {...api.getHiddenInputProps()} />
    </label>
  )
}
```

### Setting the initial checked state

Set `defaultChecked` to `true` to start checked.

```tsx {2}
const service = useMachine(checkbox.machine, {
  defaultChecked: true,
})
```

### Indeterminate checkboxes

Set `defaultChecked` or `checked` to `"indeterminate"` for a tri-state checkbox.

```tsx {2}
const service = useMachine(checkbox.machine, {
  defaultChecked: "indeterminate",
})
```

### Controlled checkbox

Use `checked` and `onCheckedChange` to control state externally.

```tsx
import { useState } from "react"

export function ControlledCheckbox() {
  const [checked, setChecked] = useState(false)

  const service = useMachine(checkbox.machine, {
    checked,
    onCheckedChange(details) {
      setChecked(details.checked)
    },
  })

  return (
    // ...
  )
}
```

### Disabling the checkbox

Set `disabled` to `true` to prevent interaction.

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

### Listening for changes

When the checked state changes, `onCheckedChange` is invoked.

```tsx {2-5}
const service = useMachine(checkbox.machine, {
  onCheckedChange(details) {
    // details => { checked: boolean | "indeterminate" }
    console.log("checkbox is:", details.checked)
  },
})
```

### Read-only checkbox

Set `readOnly` to keep the checkbox focusable but prevent toggling.

```tsx {2}
const service = useMachine(checkbox.machine, {
  readOnly: true,
})
```

### Usage within forms

To use checkbox within forms, set `name` and render `api.getHiddenInputProps()`.

```tsx {2}
const service = useMachine(checkbox.machine, {
  name: "fruits",
})
```

Next, render the hidden input and ensure the value changes get propagated to the
form correctly.

```tsx
<input {...api.getHiddenInputProps()} />
```

### Customizing submitted value

Set `value` to customize the submitted form value when checked.

```tsx
const service = useMachine(checkbox.machine, {
  name: "newsletter",
  value: "subscribed",
})
```

### Associating with an external form

If the input belongs to a different form element, set `form`.

```tsx
const service = useMachine(checkbox.machine, {
  name: "newsletter",
  form: "settings-form",
})
```

## Styling guide

Each part includes a `data-part` attribute you can target in CSS.

### Checked state

When the checkbox input is checked, the `data-state` attribute is added to the
root, control and label parts.

```css
[data-part="root"][data-state="checked|unchecked|indeterminate"] {
  /* styles for when checkbox is checked */
}

[data-part="control"][data-state="checked|unchecked|indeterminate"] {
  /* styles for when checkbox is checked */
}

[data-part="label"][data-state="checked|unchecked|indeterminate"] {
  /* styles for when checkbox is checked */
}
```

### Focused State

When the checkbox input is focused, the `data-focus` attribute is added to the
root, control and label parts.

```css
[data-part="root"][data-focus] {
  /* styles for root focus state */
}

[data-part="control"][data-focus] {
  /* styles for control focus state */
}

[data-part="label"][data-focus] {
  /* styles for label focus state */
}
```

### Disabled State

When the checkbox is disabled, the `data-disabled` attribute is added to the
root, control and label parts.

```css
[data-part="root"][data-disabled] {
  /* styles for root disabled state */
}

[data-part="control"][data-disabled] {
  /* styles for control disabled state */
}

[data-part="label"][data-disabled] {
  /* styles for label disabled state */
}
```

### Invalid State

When the checkbox is invalid, the `data-invalid` attribute is added to the root,
control and label parts.

```css
[data-part="root"][data-invalid] {
  /* styles for root invalid state */
}

[data-part="control"][data-invalid] {
  /* styles for control invalid state */
}

[data-part="label"][data-invalid] {
  /* styles for label invalid state */
}
```

## Methods and Properties

### Machine Context

The checkbox machine exposes the following context properties:

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the checkbox. Useful for composition.

**`disabled`**
Type: `boolean | undefined`
Description: Whether the checkbox is disabled

**`invalid`**
Type: `boolean | undefined`
Description: Whether the checkbox is invalid

**`required`**
Type: `boolean | undefined`
Description: Whether the checkbox is required

**`checked`**
Type: `CheckedState | undefined`
Description: The controlled checked state of the checkbox

**`defaultChecked`**
Type: `CheckedState | undefined`
Description: The initial checked state of the checkbox when rendered.
Use when you don't need to control the checked state of the checkbox.

**`readOnly`**
Type: `boolean | undefined`
Description: Whether the checkbox is read-only

**`onCheckedChange`**
Type: `((details: CheckedChangeDetails) => void) | undefined`
Description: The callback invoked when the checked state changes.

**`name`**
Type: `string | undefined`
Description: The name of the input field in a checkbox.
Useful for form submission.

**`form`**
Type: `string | undefined`
Description: The id of the form that the checkbox belongs to.

**`value`**
Type: `string | undefined`
Description: The value of checkbox input. Useful for form submission.

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

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

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

### Machine API

The checkbox `api` exposes the following methods:

**`checked`**
Type: `boolean`
Description: Whether the checkbox is checked

**`disabled`**
Type: `boolean | undefined`
Description: Whether the checkbox is disabled

**`indeterminate`**
Type: `boolean`
Description: Whether the checkbox is indeterminate

**`focused`**
Type: `boolean | undefined`
Description: Whether the checkbox is focused

**`checkedState`**
Type: `CheckedState`
Description: The checked state of the checkbox

**`setChecked`**
Type: `(checked: CheckedState) => void`
Description: Function to set the checked state of the checkbox

**`toggleChecked`**
Type: `VoidFunction`
Description: Function to toggle the checked state of the checkbox

### Data Attributes

**`Root`**

**`data-checkbox-root`**: <uid>
**`data-active`**: Present when active or pressed
**`data-focus`**: Present when focused
**`data-focus-visible`**: Present when focused with keyboard
**`data-readonly`**: Present when read-only
**`data-hover`**: Present when hovered
**`data-disabled`**: Present when disabled
**`data-state`**: "indeterminate" | "checked" | "unchecked"
**`data-invalid`**: Present when invalid
**`data-required`**: Present when required

**`Label`**

**`data-checkbox-label`**: <uid>
**`data-active`**: Present when active or pressed
**`data-focus`**: Present when focused
**`data-focus-visible`**: Present when focused with keyboard
**`data-readonly`**: Present when read-only
**`data-hover`**: Present when hovered
**`data-disabled`**: Present when disabled
**`data-state`**: "indeterminate" | "checked" | "unchecked"
**`data-invalid`**: Present when invalid
**`data-required`**: Present when required

**`Control`**

**`data-checkbox-control`**: <uid>
**`data-active`**: Present when active or pressed
**`data-focus`**: Present when focused
**`data-focus-visible`**: Present when focused with keyboard
**`data-readonly`**: Present when read-only
**`data-hover`**: Present when hovered
**`data-disabled`**: Present when disabled
**`data-state`**: "indeterminate" | "checked" | "unchecked"
**`data-invalid`**: Present when invalid
**`data-required`**: Present when required

**`Indicator`**

**`data-checkbox-indicator`**: <uid>
**`data-active`**: Present when active or pressed
**`data-focus`**: Present when focused
**`data-focus-visible`**: Present when focused with keyboard
**`data-readonly`**: Present when read-only
**`data-hover`**: Present when hovered
**`data-disabled`**: Present when disabled
**`data-state`**: "indeterminate" | "checked" | "unchecked"
**`data-invalid`**: Present when invalid
**`data-required`**: Present when required

## Accessibility

### Keyboard Interactions

**`Space`**
Description: Toggle the checkbox

The clipboard machine lets users quickly copy content to the clipboard.

## Resources


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



## Installation

Install the clipboard package:

```bash
npm install @zag-js/clipboard @zag-js/react
# or
yarn add @zag-js/clipboard @zag-js/react
```

## Anatomy

Check the clipboard anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the clipboard package:

```tsx
import * as clipboard from "@zag-js/clipboard"
```

The clipboard package exports two key functions:

- `machine` - State machine logic.
- `connect` - Maps machine state to JSX props and event handlers.

> Pass a unique `id` to `useMachine` so generated element ids stay predictable.

Then use the framework integration helpers:

```tsx
import * as clipboard from "@zag-js/clipboard"
import { useMachine, normalizeProps } from "@zag-js/react"
import { ClipboardCheck, ClipboardCopyIcon } from "lucide-react"
import { useId } from "react"

function Clipboard() {
  const service = useMachine(clipboard.machine, {
    id: useId(),
    value: "https://github.com/chakra-ui/zag",
  })

  const api = clipboard.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <label {...api.getLabelProps()}>Copy this link</label>
      <div {...api.getControlProps()}>
        <input {...api.getInputProps()} />
        <button {...api.getTriggerProps()}>
          {api.copied ? <ClipboardCheck /> : <ClipboardCopyIcon />}
        </button>
      </div>
    </div>
  )
}
```

### Setting the clipboard value

Set `value` to control what gets copied.

```tsx {2}
const service = useMachine(clipboard.machine, {
  value: "Hello, world!",
})
```

### Setting an initial value

Use `defaultValue` for uncontrolled initial value.

```tsx
const service = useMachine(clipboard.machine, {
  defaultValue: "Hello, world!",
})
```

### Listening for value changes

Use `onValueChange` to react when the clipboard value changes.

```tsx
const service = useMachine(clipboard.machine, {
  onValueChange(details) {
    console.log("Value changed to", details.value)
  },
})
```

### Listening to copy events

When the value is copied, `onStatusChange` is fired.

```tsx {2}
const service = useMachine(clipboard.machine, {
  onStatusChange: (details) => {
    console.log("Copy status changed to", details.copied)
  },
})
```

### Checking if the value is copied

Use `api.copied` to check if the value was copied.

```tsx {2}
const api = clipboard.connect(service)

if (api.copied) {
  console.log("Value is copied to the clipboard")
}
```

### Changing the timeout

By default, the copied feedback resets after `3000ms`. Set `timeout` to change
this delay.

```tsx {2}
const service = useMachine(clipboard.machine, {
  timeout: 5000,
})
```

## Styling guide

Each part includes a `data-part` attribute you can target in CSS.

```css
[data-scope="clipboard"][data-part="root"] {
  /* styles for the root part */
}
```

## Methods and Properties

### Machine Context

The clipboard machine exposes the following context properties:

**`translations`**
Type: `IntlTranslations | undefined`
Description: Specifies the localized strings that identifies the accessibility elements and their states

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the clipboard. Useful for composition.

**`value`**
Type: `string | undefined`
Description: The controlled value of the clipboard

**`defaultValue`**
Type: `string | undefined`
Description: The initial value to be copied to the clipboard when rendered.
Use when you don't need to control the value of the clipboard.

**`onValueChange`**
Type: `((details: ValueChangeDetails) => void) | undefined`
Description: The function to be called when the value changes

**`onStatusChange`**
Type: `((details: CopyStatusDetails) => void) | undefined`
Description: The function to be called when the value is copied to the clipboard

**`timeout`**
Type: `number | undefined`
Description: The timeout for the copy operation

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

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

### Machine API

The clipboard `api` exposes the following methods:

**`copied`**
Type: `boolean`
Description: Whether the value has been copied to the clipboard

**`value`**
Type: `string`
Description: The value to be copied to the clipboard

**`setValue`**
Type: `(value: string) => void`
Description: Set the value to be copied to the clipboard

**`copy`**
Type: `VoidFunction`
Description: Copy the value to the clipboard

### Data Attributes

**`Root`**

**`data-clipboard-root`**: <uid>
**`data-copied`**: Present when copied state is true

**`Label`**

**`data-clipboard-label`**: <uid>
**`data-copied`**: Present when copied state is true

**`Control`**

**`data-clipboard-control`**: <uid>
**`data-copied`**: Present when copied state is true

**`Input`**

**`data-clipboard-input`**: <uid>
**`data-copied`**: Present when copied state is true
**`data-readonly`**: Present when read-only

**`Trigger`**

**`data-clipboard-trigger`**: <uid>
**`data-copied`**: Present when copied state is true

A collapsible is a component which expands and collapses a panel.

## Resources


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



**Features**

- Can be controlled or uncontrolled
- Works for width and height collapsibles

## Installation

Install the collapsible package:

```bash
npm install @zag-js/collapsible @zag-js/react
# or
yarn add @zag-js/collapsible @zag-js/react
```

## Usage

Import the collapsible package:

```tsx
import * as collapsible from "@zag-js/collapsible"
```

The collapsible package exports two key functions:

- `machine` - State logic for the collapsible.
- `connect` - Maps state to JSX props and event handlers.

> Pass a unique `id` to `useMachine` so generated element ids stay predictable.

Then use the framework integration helpers:

```tsx
import * as collapsible from "@zag-js/collapsible"
import { normalizeProps, useMachine } from "@zag-js/react"
import { useId } from "react"

function Collapsible() {
  const service = useMachine(collapsible.machine, { id: useId() })

  const api = collapsible.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <button {...api.getTriggerProps()}>Collapse Trigger</button>
      <div {...api.getContentProps()}>Collape Content</div>
    </div>
  )
}
```

### Setting the initial state

Set `defaultOpen` to control the initial open state.

```tsx
const service = useMachine(collapsible.machine, {
  defaultOpen: true,
})
```

### Controlled collapsible

Use `open` and `onOpenChange` to control the open state externally.

```tsx
import { useState } from "react"

export function ControlledCollapsible() {
  const [open, setOpen] = useState(false)

const service = useMachine(collapsible.machine, {
    open,
    onOpenChange(details) {
      setOpen(details.open)
    }
 })

  return (
    // ...
    )
}
```

### Listening for changes

When the collapsible state changes, the `onOpenChange` callback is invoked.

```tsx {2-5}
const service = useMachine(collapsible.machine, {
  onOpenChange(details) {
    // details => { open: boolean }
    console.log("collapsible open:", details.open)
  },
})
```

### Disabling the collapsible

Set `disabled` to `true` to disable interaction.

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

### Partial collapse (setting minimum dimensions)

Use `collapsedHeight` or `collapsedWidth` to create a "partially collapsed"
state. When collapsed, the content keeps the specified minimum size instead of
collapsing to `0px`.

```tsx {3}
const service = useMachine(collapsible.machine, {
  // Content shows 100px height when collapsed
  collapsedHeight: "100px",
})
```

This is useful for creating "show more/less" content sections or preview states
where a portion of the content shows even when collapsed.

### Running code after close animation

Use `onExitComplete` to run code when the close animation finishes.

```tsx
const service = useMachine(collapsible.machine, {
  onExitComplete() {
    console.log("Collapsible is fully closed")
  },
})
```

### Animating the collapsible

Use CSS animations to animate the collapsible when it expands and collapses. The
`--height` and `--width` custom properties are attached to the content part.

```css
@keyframes expand {
  from {
    height: var(--collapsed-height, 0);
  }
  to {
    height: var(--height);
  }
}

@keyframes collapse {
  from {
    height: var(--height);
  }
  to {
    height: var(--collapsed-height, 0);
  }
}

[data-scope="collapsible"][data-part="content"] {
  overflow: hidden;
  max-width: 400px;
}

[data-scope="collapsible"][data-part="content"][data-state="open"] {
  animation: expand 110ms cubic-bezier(0, 0, 0.38, 0.9);
}

[data-scope="collapsible"][data-part="content"][data-state="closed"] {
  animation: collapse 110ms cubic-bezier(0, 0, 0.38, 0.9);
}
```

## Styling guide

Each part includes a `data-part` attribute you can target in CSS.

### Open and closed state

When a collapsible opens or closes, `data-state` is set to `open` or `closed` on
the root, trigger, and content.

```css
[data-part="root"][data-state="open|closed"] {
  /* styles for the collapsible is open or closed state */
}

[data-part="trigger"][data-state="open|closed"] {
  /* styles for the collapsible is open or closed state */
}

[data-part="content"][data-state="open|closed"] {
  /* styles for the collapsible is open or closed state */
}
```

### Focused state

When a collapsible's trigger is focused, a `data-focus` attribute is set on the
root, trigger and content.

```css
[data-part="root"][data-focus] {
  /* styles for the item's focus state */
}

[data-part="trigger"][data-focus] {
  /* styles for the content's focus state */
}

[data-part="content"][data-focus] {
  /* styles for the content's focus state */
}
```

### Collapse animation

The collapsible content provides `--width`, `--height`, `--collapsed-width`, and
`--collapsed-height` CSS variables that can be used to create smooth animations.
These variables are automatically calculated and updated based on the content's
dimensions.

```css
[data-scope="collapsible"][data-part="content"][data-state="open"] {
  animation: slideDown 200ms ease;
}

[data-scope="collapsible"][data-part="content"][data-state="closed"] {
  animation: slideUp 200ms ease;
}

@keyframes slideDown {
  from {
    opacity: 0.01;
    height: 0;
  }
  to {
    opacity: 1;
    height: var(--height);
  }
}

@keyframes slideUp {
  from {
    opacity: 1;
    height: var(--height);
  }
  to {
    opacity: 0.01;
    height: 0;
  }
}
```

## Methods and Properties

The collapsible's `api` exposes the following methods and properties:

### Machine Context

The collapsible machine exposes the following context properties:

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the collapsible. Useful for composition.

**`open`**
Type: `boolean | undefined`
Description: The controlled open state of the collapsible.

**`defaultOpen`**
Type: `boolean | undefined`
Description: The initial open state of the collapsible when rendered.
Use when you don't need to control the open state of the collapsible.

**`onOpenChange`**
Type: `((details: OpenChangeDetails) => void) | undefined`
Description: The callback invoked when the open state changes.

**`onExitComplete`**
Type: `VoidFunction | undefined`
Description: The callback invoked when the exit animation completes.

**`disabled`**
Type: `boolean | undefined`
Description: Whether the collapsible is disabled.

**`collapsedHeight`**
Type: `number | string | undefined`
Description: The height of the content when collapsed.

**`collapsedWidth`**
Type: `number | string | undefined`
Description: The width of the content when collapsed.

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

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

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

### Machine API

The collapsible `api` exposes the following methods:

**`open`**
Type: `boolean`
Description: Whether the collapsible is open.

**`visible`**
Type: `boolean`
Description: Whether the collapsible is visible (open or closing)

**`disabled`**
Type: `boolean`
Description: Whether the collapsible is disabled

**`setOpen`**
Type: `(open: boolean) => void`
Description: Function to open or close the collapsible.

**`measureSize`**
Type: `VoidFunction`
Description: Function to measure the size of the content.

### Data Attributes

**`Root`**

**`data-collapsible-root`**: <uid>
**`data-state`**: "open" | "closed"

**`Content`**

**`data-collapsible-content`**: <uid>
**`data-collapsible`**: 
**`data-state`**: "open" | "closed"
**`data-disabled`**: Present when disabled
**`data-has-collapsed-size`**: Present when the content has collapsed width or height

**`Trigger`**

**`data-collapsible-trigger`**: <uid>
**`data-state`**: "open" | "closed"
**`data-disabled`**: Present when disabled

**`Indicator`**

**`data-collapsible-indicator`**: <uid>
**`data-state`**: "open" | "closed"
**`data-disabled`**: Present when disabled

### CSS Variables

<CssVarTable name="collapsible" />

## Accessibility

Adheres to the
[Disclosure WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure).

### Keyboard Interactions

**`Space`**
Description: Opens/closes the collapsible.

**`Enter`**
Description: Opens/closes the collapsible.

The color picker is an input widget used to select a color value from a
predefined list or a color area.

This component builds on top of the native `<input type=color>` experience and
provides a more customizable and consistent user experience.

## Resources


[Latest version: v2.0.0-next.1](https://www.npmjs.com/package/@zag-js/color-picker)
[Logic Visualizer](https://zag-visualizer.vercel.app/color-picker)
[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/color-picker)



**Features**

- Supports custom color area
- Supports RGBA, HSLA, HEX, HSBA, **OKLab**, and **OKLCH** formats
- Optional **sRGB gamut overlay** on the 2D area when using OKLab/OKLCH (`getGamutOverlay`, `getGamutOverlayProps`, anatomy part `gamutOverlay`)
- Supports channel inputs and sliders
- Supports mouse, touch, and keyboard interactions
- Supports form submission and reset events
- Supports named CSS colors

## Installation

Install the color picker package:

```bash
npm install @zag-js/color-picker @zag-js/react
# or
yarn add @zag-js/color-picker @zag-js/react
```

## Anatomy

To set up the color picker 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 color picker package:

```tsx
import * as colorPicker from "@zag-js/color-picker"
```

These are the key exports:

- `machine` - Behavior logic for the color picker.
- `connect` - Maps state to JSX props and event handlers.
- `parse` - Parses a color string into a `Color` object.

Then use the framework integration helpers:

```tsx
import * as colorPicker from "@zag-js/color-picker"
import { normalizeProps, useMachine } from "@zag-js/react"
import { useId } from "react"

function ColorPicker() {
  const service = useMachine(colorPicker.machine, {
    id: useId(),
    defaultValue: colorPicker.parse("hsl(0, 100%, 50%)"),
  })

  const api = colorPicker.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <label {...api.getLabelProps()}>Select Color: {api.valueAsString}</label>

      <input {...api.getHiddenInputProps()} />

      <div {...api.getControlProps()}>
        <button {...api.getTriggerProps()}>
          <div {...api.getTransparencyGridProps({ size: "10px" })} />
          <div {...api.getSwatchProps({ value: api.value })} />
        </button>
        <input {...api.getChannelInputProps({ channel: "hex" })} />
        <input {...api.getChannelInputProps({ channel: "alpha" })} />
      </div>

      <div {...api.getPositionerProps()}>
        <div {...api.getContentProps()}>
          <div {...api.getAreaProps()}>
            <div {...api.getAreaBackgroundProps()} />
            <div {...api.getAreaThumbProps()} />
          </div>

          <div {...api.getChannelSliderProps({ channel: "hue" })}>
            <div {...api.getChannelSliderTrackProps({ channel: "hue" })} />
            <div {...api.getChannelSliderThumbProps({ channel: "hue" })} />
          </div>

          <div {...api.getChannelSliderProps({ channel: "alpha" })}>
            <div {...api.getTransparencyGridProps({ size: "12px" })} />
            <div {...api.getChannelSliderTrackProps({ channel: "alpha" })} />
            <div {...api.getChannelSliderThumbProps({ channel: "alpha" })} />
          </div>
        </div>
      </div>
    </div>
  )
}
```

### Setting the initial color

Set `defaultValue` to define the initial color.

```tsx
const [current, send] = useMachine(colorPicker.machine, {
  defaultValue: colorPicker.parse("#ff0000"),
})
```

### Controlled color picker

Use `value` and `onValueChange` to control color externally.

> **Note:** We recommend preserving the value as a `Color` object rather than a
> string to prevent calculation errors by converting back and forth.

```tsx
import { useState } from "react"
import * as colorPicker from "@zag-js/color-picker"

export function ControlledColorPicker() {
  const [value, setValue] = useState(colorPicker.parse("#ff0000"))

  const service = useMachine(colorPicker.machine, {
      value,
      onValueChange(details) {
        setValue(details.value)
      }
  })

  return (
    // ...
  )
}
```

### Listening for change events

When the user selects a color using the color picker, the `onValueChange` and
`onValueChangeEnd` events will be fired.

- `onValueChange` — Fires in sync as the user selects a color
- `onValueChangeEnd` — Fires when the user stops selecting a color (useful for
  debounced updates)

```tsx
const [current, send] = useMachine(colorPicker.machine, {
  onValueChange: (details) => {
    // details => { value: Color, valueAsString: string }
  },
  onValueChangeEnd: (details) => {
    // details => { value: Color, valueAsString: string }
  },
})
```

### Using a custom color format

By default, the color picker's output format is `rgba`. You can change this
format to either `hsla` or `hsba` with `format`.

When this is set, the `value` and `valueAsString` properties of the
`onValueChange` event will be updated to reflect the new format.

```tsx
const [current, send] = useMachine(colorPicker.machine, {
  format: "hsla",
  onValueChange: (details) => {
    // details => { value: HSLAColor, valueAsString: string }
  },
})
```

### Wide gamut (OKLab / OKLCH)

The **2D color area** stays **HSBA** (saturation × brightness, **hue** on the third-axis slider) for a familiar control surface, even when the **output format** is OKLab or OKLCH.

Use **`api.getGamutOverlay(props?)`** for SVG path data (`path`, `labelPosition`) that draws the **sRGB gamut boundary** in that HSB view. The boundary is computed like Chrome DevTools (HSV interpreted in a wide working space vs sRGB). Pass the **same** `props` to **`getAreaProps`**, **`getGamutOverlay`**, and **`getGamutOverlayProps`**—including optional `xChannel` / `yChannel` overrides and optional **`pixelRatio`** (defaults to `globalThis.devicePixelRatio` in the browser for sharper curves on retina).

**`api.isInSrgbGamut`** is `true` when the current color lies inside the sRGB cube in linear RGB space. When `false`, your OKLab/OKLCH **string** may still be wide-gamut while **hex** or 8-bit **RGBA** outputs **clamp**—use this flag for badges, tooltips, or warnings.

### Setting the initial format

Use `defaultFormat` to set the initial output format.

```tsx
const [current, send] = useMachine(colorPicker.machine, {
  defaultFormat: "hsla",
})
```

### Controlled format

Use `format` and `onFormatChange` to control the active format.

```tsx
const [current, send] = useMachine(colorPicker.machine, {
  format,
  onFormatChange(details) {
    setFormat(details.format)
  },
})
```

### Showing color presets

Adding color presets as swatches can help users pick colors faster. To support
this, use the `getSwatchTriggerProps(...)` and `getSwatchProps(...)` to get the
props needed to render swatch buttons.

```tsx {18-31}
const ColorPicker = () => {
  const service = useMachine(colorPicker.machine, {
    id: useId(),
    defaultValue: colorPicker.parse("hsl(0, 100%, 50%)"),
  })

  const api = colorPicker.connect(service, normalizeProps)

  const presets = ["#ff0000", "#00ff00", "#0000ff"]

  return (
    <div {...api.getRootProps()}>
      {/* ... */}
      <div {...api.getPositionerProps()}>
        <div {...api.getContentProps()}>
          <div {...api.getSwatchGroupProps()}>
            {presets.map((preset) => (
              <button
                key={preset}
                {...api.getSwatchTriggerProps({ value: preset })}
              >
                <div style={{ position: "relative" }}>
                  <div {...api.getTransparencyGridProps({ size: "4px" })} />
                  <div {...api.getSwatchProps({ value: preset })} />
                </div>
              </button>
            ))}
          </div>
        </div>
      </div>
    </div>
  )
}
```

### Closing after swatch selection

Set `closeOnSelect` to close the popup when a swatch is selected.

```tsx
const [current, send] = useMachine(colorPicker.machine, {
  closeOnSelect: true,
})
```

### Disabling the color picker

Set `disabled` to `true` to disable user interaction.

```tsx
const [current, send] = useMachine(colorPicker.machine, {
  disabled: true,
})
```

### Controlling the open and closed state

Use `open` and `onOpenChange` to control whether the picker is visible.

```tsx
const [current, send] = useMachine(colorPicker.machine, {
  open: true,
  onOpenChange: (details) => {
    // details => { open: boolean, value: Color }
  },
})
```

You can also leverage the `api.setOpen(...)` method to control the open and
closed state of the color picker.

### Positioning the popup

Use `positioning` to control popup placement and collision behavior.

```tsx
const [current, send] = useMachine(colorPicker.machine, {
  positioning: { placement: "bottom-start", gutter: 8 },
})
```

### Setting initial focus when opened

Use `initialFocusEl` to choose which element receives focus when the popup
opens.

```tsx
const [current, send] = useMachine(colorPicker.machine, {
  initialFocusEl: () => document.getElementById("alpha-input"),
})
```

### Inline rendering

Set `inline` to render the picker without a trigger and popup.

```tsx
const [current, send] = useMachine(colorPicker.machine, {
  inline: true,
})
```

### Controlling individual color channel

In some cases, you may want to allow users to control the values of each color
channel individually. You can do this using an input element or a slider
element, or both.

To support this, use the `getChannelInputProps(...)` to show the channel inputs.

> Note: Make sure you only render the channel inputs that match the `format` of
> the color picker.

```tsx {16-38}
const ColorPicker = () => {
  const service = useMachine(colorPicker.machine, {
    id: useId(),
    defaultValue: colorPicker.parse("hsl(0, 100%, 50%)"),
  })

  const api = colorPicker.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      {/* ... */}
      <div {...api.getPositionerProps()}>
        <div {...api.getContentProps()}>
          {api.format === "rgba" && (
            <div>
              <div>
                <span>R</span>
                <input {...api.getChannelInputProps({ channel: "red" })} />
              </div>

              <div>
                <span>G</span>
                <input {...api.getChannelInputProps({ channel: "green" })} />
              </div>

              <div>
                <span>B</span>
                <input {...api.getChannelInputProps({ channel: "blue" })} />
              </div>

              <div>
                <span>A</span>
                <input {...api.getChannelInputProps({ channel: "alpha" })} />
              </div>
            </div>
          )}
        </div>
      </div>
    </div>
  )
}
```

### Showing a color preview

To display the value of a color, use the `getSwatchProps(...)` and pass the
color value. To show the current color value, use `api.value`.

```tsx {13-16}
const ColorPicker = () => {
  const service = useMachine(colorPicker.machine, {
    id: useId(),
    defaultValue: colorPicker.parse("hsl(0, 100%, 50%)"),
  })

  const api = colorPicker.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <div>
        <div {...api.getTransparencyGridProps({ size: "4px" })} />
        <div {...api.getSwatchProps({ value: api.value })} />
      </div>
      {/* ... */}
    </div>
  )
}
```

> You can pass `respectAlpha: false` to show the color value without the alpha
> channel

### Adding an eyedropper

The eye dropper tool is a native browser feature that lets users pick a color
from a current page's canvas. To support this, use the
`getEyeDropperTriggerProps(...)`.

> **Note:** The eye dropper tool only works in Chrome and Edge browsers

```tsx {16-18}
const ColorPicker = () => {
  const service = useMachine(colorPicker.machine, {
    id: useId(),
    defaultValue: colorPicker.parse("hsl(0, 100%, 50%)"),
  })

  const api = colorPicker.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      {/* ... */}
      <div {...api.getPositionerProps()}>
        <div {...api.getContentProps()}>
          <button {...api.getEyeDropperTriggerProps()}>
            <EyeDropIcon />
          </button>
        </div>
      </div>
    </div>
  )
}
```

### Usage within forms

To use the color picker in a form, set `name` and render the hidden input.

```tsx {2}
const service = useMachine(colorPicker.machine, {
  name: "color-preference",
})
```

## Styling guide

Each color picker part has a `data-part` attribute added to them to help you
identify and style them easily.

### Open and closed state

When the color picker is open or closed, the `data-state` attribute is added to
the trigger, content, control parts.

```css
[data-part="control"][data-state="open|closed"] {
  /* styles for control open or state */
}

[data-part="trigger"][data-state="open|closed"] {
  /* styles for control open or state */
}

[data-part="content"][data-state="open|closed"] {
  /* styles for control open or state */
}
```

### Focused State

When the color picker is focused, the `data-focus` attribute is added to the
control and label parts.

```css
[data-part="control"][data-focus] {
  /* styles for control focus state */
}

[data-part="label"][data-focus] {
  /* styles for label focus state */
}
```

### Disabled State

When the color picker is disabled, the `data-disabled` attribute is added to the
label, control, trigger and option parts.

```css
[data-part="label"][data-disabled] {
  /* styles for label disabled state */
}

[data-part="control"][data-disabled] {
  /* styles for control disabled state */
}

[data-part="trigger"][data-disabled] {
  /* styles for trigger disabled state */
}

[data-part="swatch-trigger"][data-disabled] {
  /* styles for item disabled state */
}
```

### Swatch State

When a swatch's color value matches the color picker's value, the
`data-state=checked` attribute is added to the swatch part.

```css
[data-part="swatch-trigger"][data-state="checked|unchecked"] {
  /* styles for swatch's checked state */
}
```

## Methods and Properties

### Machine Context

The color picker machine exposes the following context properties:

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the color picker. Useful for composition.

**`value`**
Type: `Color | undefined`
Description: The controlled color value of the color picker

**`defaultValue`**
Type: `Color | undefined`
Description: The initial color value when rendered.
Use when you don't need to control the color value of the color picker.

**`disabled`**
Type: `boolean | undefined`
Description: Whether the color picker is disabled

**`readOnly`**
Type: `boolean | undefined`
Description: Whether the color picker is read-only

**`required`**
Type: `boolean | undefined`
Description: Whether the color picker is required

**`invalid`**
Type: `boolean | undefined`
Description: Whether the color picker is invalid

**`onValueChange`**
Type: `((details: ValueChangeDetails) => void) | undefined`
Description: Handler that is called when the value changes, as the user drags.

**`onValueChangeEnd`**
Type: `((details: ValueChangeDetails) => void) | undefined`
Description: Handler that is called when the user stops dragging.

**`onOpenChange`**
Type: `((details: OpenChangeDetails) => void) | undefined`
Description: Handler that is called when the user opens or closes the color picker.

**`name`**
Type: `string | undefined`
Description: The name for the form input

**`positioning`**
Type: `PositioningOptions | undefined`
Description: The positioning options for the color picker

**`initialFocusEl`**
Type: `(() => HTMLElement | null) | undefined`
Description: The initial focus element when the color picker is opened.

**`open`**
Type: `boolean | undefined`
Description: The controlled open state of the color picker

**`defaultOpen`**
Type: `boolean | undefined`
Description: The initial open state of the color picker when rendered.
Use when you don't need to control the open state of the color picker.

**`format`**
Type: `ColorFormat | undefined`
Description: The controlled color format to use

**`defaultFormat`**
Type: `ColorFormat | undefined`
Description: The initial color format when rendered.
Use when you don't need to control the color format of the color picker.

**`onFormatChange`**
Type: `((details: FormatChangeDetails) => void) | undefined`
Description: Function called when the color format changes

**`closeOnSelect`**
Type: `boolean | undefined`
Description: Whether to close the color picker when a swatch is selected

**`openAutoFocus`**
Type: `boolean | undefined`
Description: Whether to auto focus the color picker when it is opened

**`inline`**
Type: `boolean | undefined`
Description: Whether to render the color picker inline

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

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

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

**`onPointerDownOutside`**
Type: `((event: PointerDownOutsideEvent) => void) | undefined`
Description: Function called when the pointer is pressed down outside the component

**`onFocusOutside`**
Type: `((event: FocusOutsideEvent) => void) | undefined`
Description: Function called when the focus is moved outside the component

**`onInteractOutside`**
Type: `((event: InteractOutsideEvent) => void) | undefined`
Description: Function called when an interaction happens outside the component

### Machine API

The color picker `api` exposes the following methods:

**`dragging`**
Type: `boolean`
Description: Whether the color picker is being dragged

**`open`**
Type: `boolean`
Description: Whether the color picker is open

**`inline`**
Type: `boolean`
Description: Whether the color picker is rendered inline

**`value`**
Type: `Color`
Description: The current color value (as a string)

**`valueAsString`**
Type: `string`
Description: The current color value (as a Color object)

**`isInSrgbGamut`**
Type: `boolean`
Description: Whether the current color lies inside the sRGB gamut (linear RGB cube).
When `false`, wide-gamut CSS strings may still be valid while 8-bit RGB / hex are clamped.

**`setValue`**
Type: `(value: string | Color) => void`
Description: Function to set the color value

**`getChannelValue`**
Type: `(channel: ColorChannel) => string`
Description: Function to set the color value

**`getChannelValueText`**
Type: `(channel: ColorChannel, locale: string) => string`
Description: Function to get the formatted and localized value of a specific channel

**`setChannelValue`**
Type: `(channel: ColorChannel, value: number) => void`
Description: Function to set the color value of a specific channel

**`format`**
Type: `ColorFormat`
Description: The current color format

**`setFormat`**
Type: `(format: ColorFormat) => void`
Description: Function to set the color format

**`alpha`**
Type: `number`
Description: The alpha value of the color

**`setAlpha`**
Type: `(value: number) => void`
Description: Function to set the color alpha

**`setOpen`**
Type: `(open: boolean) => void`
Description: Function to open or close the color picker

**`getGamutOverlay`**
Type: `(props?: GamutOverlayProps) => GamutOverlayData | null`
Description: SVG path + label position for the sRGB gamut boundary (oklch/oklab + HSB area only); `null` when not shown.
Use the **same** `props` as 

**`getGamutOverlayProps`**
Type: `(props?: GamutOverlayProps) => T["svg"]`
Description: Props for an `<svg>` gamut overlay; pair with 

### Data Attributes

**`Root`**

**`data-color-picker-root`**: <uid>
**`data-disabled`**: Present when disabled
**`data-readonly`**: Present when read-only
**`data-invalid`**: Present when invalid

**`Label`**

**`data-color-picker-label`**: <uid>
**`data-disabled`**: Present when disabled
**`data-readonly`**: Present when read-only
**`data-invalid`**: Present when invalid
**`data-required`**: Present when required
**`data-focus`**: Present when focused

**`Control`**

**`data-color-picker-control`**: <uid>
**`data-disabled`**: Present when disabled
**`data-readonly`**: Present when read-only
**`data-invalid`**: Present when invalid
**`data-state`**: "open" | "closed"
**`data-focus`**: Present when focused

**`Trigger`**

**`data-color-picker-trigger`**: <uid>
**`data-disabled`**: Present when disabled
**`data-readonly`**: Present when read-only
**`data-invalid`**: Present when invalid
**`data-placement`**: The placement of the trigger
**`data-side`**: The side of the trigger that the trigger is positioned on
**`data-state`**: "open" | "closed"
**`data-focus`**: Present when focused

**`Content`**

**`data-color-picker-content`**: <uid>
**`data-placement`**: The placement of the content
**`data-nested`**: popover
**`data-has-nested`**: popover
**`data-side`**: The side of the trigger that the content is positioned on
**`data-state`**: "open" | "closed"

**`ValueText`**

**`data-color-picker-value-text`**: <uid>
**`data-disabled`**: Present when disabled
**`data-focus`**: Present when focused

**`Area`**

**`data-color-picker-area`**: <uid>
**`data-invalid`**: Present when invalid
**`data-disabled`**: Present when disabled
**`data-readonly`**: Present when read-only

**`AreaBackground`**

**`data-color-picker-area-background`**: <uid>
**`data-invalid`**: Present when invalid
**`data-disabled`**: Present when disabled
**`data-readonly`**: Present when read-only

**`GamutOverlay`**

**`data-color-picker-gamut-overlay`**: <uid>
**`data-state`**: "visible" | "hidden"

**`AreaThumb`**

**`data-color-picker-area-thumb`**: <uid>
**`data-disabled`**: Present when disabled
**`data-invalid`**: Present when invalid
**`data-readonly`**: Present when read-only

**`ChannelSlider`**

**`data-color-picker-channel-slider`**: <uid>
**`data-channel`**: The color channel of the channelslider
**`data-orientation`**: The orientation of the channelslider

**`ChannelSliderTrack`**

**`data-color-picker-channel-slider-track`**: <uid>
**`data-channel`**: The color channel of the channelslidertrack
**`data-orientation`**: The orientation of the channelslidertrack

**`ChannelSliderLabel`**

**`data-color-picker-channel-slider-label`**: <uid>
**`data-channel`**: The color channel of the channelsliderlabel

**`ChannelSliderValueText`**

**`data-color-picker-channel-slider-value-text`**: <uid>
**`data-channel`**: The color channel of the channelslidervaluetext

**`ChannelSliderThumb`**

**`data-color-picker-channel-slider-thumb`**: <uid>
**`data-channel`**: The color channel of the channelsliderthumb
**`data-disabled`**: Present when disabled
**`data-orientation`**: The orientation of the channelsliderthumb

**`ChannelInput`**

**`data-color-picker-channel-input`**: <uid>
**`data-channel`**: The color channel of the channelinput
**`data-disabled`**: Present when disabled
**`data-invalid`**: Present when invalid
**`data-readonly`**: Present when read-only

**`EyeDropperTrigger`**

**`data-color-picker-eye-dropper-trigger`**: <uid>
**`data-disabled`**: Present when disabled
**`data-invalid`**: Present when invalid
**`data-readonly`**: Present when read-only

**`SwatchTrigger`**

**`data-color-picker-swatch-trigger`**: <uid>
**`data-state`**: "checked" | "unchecked"
**`data-value`**: The value of the item
**`data-disabled`**: Present when disabled

**`Swatch`**

**`data-color-picker-swatch`**: <uid>
**`data-state`**: "checked" | "unchecked"
**`data-value`**: The value of the item

### CSS Variables

<CssVarTable name="color-picker" />

## Accessibility

### Keyboard Interactions

**`Enter`**
Description: <span>When focus is on the trigger, opens the color picker<br />When focus is on a trigger of a swatch, selects the color (and closes the color picker)<br />When focus is on the input or channel inputs, selects the color</span>

**`ArrowLeft`**
Description: <span>When focus is on the color area, decreases the hue value of the color<br />When focus is on the channel sliders, decreases the value of the channel</span>

**`ArrowRight`**
Description: <span>When focus is on the color area, increases the hue value of the color<br />When focus is on the channel sliders, increases the value of the channel</span>

**`ArrowUp`**
Description: <span>When focus is on the color area, increases the saturation value of the color<br />When focus is on the channel sliders, increases the value of the channel</span>

**`ArrowDown`**
Description: <span>When focus is on the color area, decreases the saturation value of the color<br />When focus is on the channel sliders, decreases the value of the channel</span>

**`Esc`**
Description: Closes the color picker and moves focus to the trigger

A combobox is an input with a popup that lets you select a value from a
collection.

## Resources


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



**Features**

- Supports selecting multiple values
- Supports disabled options
- Supports custom user input values
- Supports mouse, touch, and keyboard interactions
- Supports opening the combobox listbox with arrow keys, including automatically
  focusing the first or last item accordingly

## Installation

Install the combobox package:

```bash
npm install @zag-js/combobox @zag-js/react
# or
yarn add @zag-js/combobox @zag-js/react
```

## Anatomy

Check the combobox anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the combobox package:

```tsx
import * as combobox from "@zag-js/combobox"
```

These are the key exports:

- `machine` - Behavior logic.
- `connect` - Maps behavior to JSX props and event handlers.
- `collection` - Creates a [collection interface](/overview/collection) from an
  array of items.

Then use the framework integration helpers:

```tsx
import * as combobox from "@zag-js/combobox"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useState, useId } from "react"

const comboboxData = [
  { label: "Zambia", code: "ZA" },
  { label: "Benin", code: "BN" },
  //...
]

export function Combobox() {
  const [options, setOptions] = useState(comboboxData)

  const collection = combobox.collection({
    items: options,
    itemToValue: (item) => item.code,
    itemToString: (item) => item.label,
  })

  const service = useMachine(combobox.machine, {
    id: useId(),
    collection,
    onOpenChange() {
      setOptions(comboboxData)
    },
    onInputValueChange({ inputValue }) {
      const filtered = comboboxData.filter((item) =>
        item.label.toLowerCase().includes(inputValue.toLowerCase()),
      )
      setOptions(filtered.length > 0 ? filtered : comboboxData)
    },
  })

  const api = combobox.connect(service, normalizeProps)

  return (
    <div>
      <div {...api.getRootProps()}>
        <label {...api.getLabelProps()}>Select country</label>
        <div {...api.getControlProps()}>
          <input {...api.getInputProps()} />
          <button {...api.getTriggerProps()}>▼</button>
        </div>
      </div>
      <div {...api.getPositionerProps()}>
        <div {...api.getContentProps()}>
          {options.length > 0 && (
            <div {...api.getListProps()}>
              {options.map((item) => (
                <div key={item.code} {...api.getItemProps({ item })}>
                  {item.label}
                </div>
              ))}
            </div>
          )}
        </div>
      </div>
    </div>
  )
}
```

### Setting the initial value

Set `defaultValue` to define the initial combobox value.

```tsx {13}
const collection = combobox.collection({
  items: [
    { label: "Nigeria", value: "ng" },
    { label: "Ghana", value: "gh" },
    { label: "Kenya", value: "ke" },
    //...
  ],
})

const service = useMachine(combobox.machine, {
  id: useId(),
  collection,
  defaultValue: ["ng"],
})
```

### Controlled combobox

Use `value` and `onValueChange` to control the value programmatically.

```tsx
import { useState } from "react"

export function ControlledCombobox() {
  const [value, setValue] = useState(["ng"])

  const service = useMachine(combobox.machine, {
      value,
      onValueChange(details) {
        setValue(details.value)
      }
  })

  return (
    // ...
    )
}
```

### Setting the initial input value

Use `defaultInputValue` to prefill the input on first render.

```tsx
const service = useMachine(combobox.machine, {
  id: useId(),
  collection,
  defaultInputValue: "Nig",
})
```

### Controlling the input value

Use `inputValue` and `onInputValueChange` when you want to filter options as you
type.

```tsx
const service = useMachine(combobox.machine, {
  id: useId(),
  collection,
  inputValue,
  onInputValueChange({ inputValue }) {
    setInputValue(inputValue)
    setOptions(filterItems(inputValue))
  },
})
```

### Selecting multiple values

Set `multiple` to `true` to allow selecting multiple values.

```tsx {4}
const service = useMachine(combobox.machine, {
  id: useId(),
  collection,
  multiple: true,
})
```

### Using a custom object format

By default, the combobox collection expects an array of items with `label` and
`value` properties. To use a custom object format, pass the `itemToString` and
`itemToValue` properties to the collection function.

- `itemToString` — A function that returns the string representation of an item.
  Used to compare items when filtering.
- `itemToValue` — A function that returns the unique value of an item.
- `itemToDisabled` — A function that returns the disabled state of an item.

```tsx
const collection = combobox.collection({
  // custom object format
  items: [
    { id: 1, fruit: "Banana", available: true, quantity: 10 },
    { id: 2, fruit: "Apple", available: false, quantity: 5 },
    { id: 3, fruit: "Orange", available: true, quantity: 3 },
    //...
  ],
  // convert item to string
  itemToString(item) {
    return item.fruit
  },
  // convert item to value
  itemToValue(item) {
    return item.id
  },
  // convert item to disabled state
  itemToDisabled(item) {
    return !item.available || item.quantity === 0
  },
})

// use the collection
const service = useMachine(combobox.machine, {
  id: useId(),
  collection,
})
```

### Rendering the selected values outside the combobox

By default, selected values are shown in the input. For multiple selection, it
is often better to render selected values outside the combobox.

To do that:

- Set the `selectionBehavior` to `clear`, which clears the input value when an
  item is selected.
- Set the `multiple` property to `true` to allow selecting multiple values.
- Render the selected values outside the combobox.

```tsx {4-6}
const service = useMachine(combobox.machine, {
  id: useId(),
  collection,
  selectionBehavior: "clear",
  multiple: true,
})
```

### Disabling the combobox

Set `disabled` to `true` to disable the combobox.

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

### Disabling an option

Pass `isItemDisabled` to disable specific options.

```tsx {6-8}
const service = useMachine(combobox.machine, {
  id: useId(),
  collection: combobox.collection({
    items: countries,
    isItemDisabled(item) {
      return item.disabled
    },
  }),
})
```

### Close on select

By default, the menu closes when an option is selected with pointer or enter
key. Set `closeOnSelect` to `false` to keep it open.

```tsx {2}
const service = useMachine(combobox.machine, {
  closeOnSelect: false,
})
```

### Controlling open state

Use `open` and `onOpenChange` for controlled popup state, or `defaultOpen` for
an uncontrolled initial state.

```tsx
const service = useMachine(combobox.machine, {
  id: useId(),
  collection,
  open,
  onOpenChange(details) {
    // details => { open: boolean; reason?: string; value: string[] }
    setOpen(details.open)
  },
})
```

```tsx
const service = useMachine(combobox.machine, {
  id: useId(),
  collection,
  defaultOpen: true,
})
```

### Configuring popup trigger behavior

Use these props to fine-tune when the popup opens:

- `openOnClick` to open when the input is clicked
- `openOnChange` to control opening on input changes
- `openOnKeyPress` to control opening on arrow key press
- `inputBehavior` to set how typing and keyboard navigation affect
  highlight/input

```tsx
const service = useMachine(combobox.machine, {
  id: useId(),
  collection,
  openOnClick: true,
  openOnChange: false,
  openOnKeyPress: false,
  inputBehavior: "autohighlight",
})
```

### Positioning the popup

Use `positioning` to control how the popup is placed.

```tsx
const service = useMachine(combobox.machine, {
  id: useId(),
  collection,
  positioning: { placement: "bottom-start" },
})
```

### Submitting forms on Enter

Set `alwaysSubmitOnEnter` to `true` if you want Enter to submit the form even
while the popup is open.

```tsx
const service = useMachine(combobox.machine, {
  id: useId(),
  collection,
  alwaysSubmitOnEnter: true,
})
```

### Making the combobox readonly

Set `readOnly` to `true` to make the combobox read-only.

```tsx {2}
const service = useMachine(combobox.machine, {
  readOnly: true,
})
```

### Required and invalid state

Set `required` and `invalid` for form validation and UI state.

```tsx
const service = useMachine(combobox.machine, {
  id: useId(),
  collection,
  required: true,
  invalid: false,
})
```

### Listening for highlight changes

Use `onHighlightChange` to listen for highlighted option changes.

```tsx {3-6}
const service = useMachine(combobox.machine, {
  id: useId(),
  onHighlightChange(details) {
    // details => { highlightedValue: string | null; highlightedItem: CollectionItem | null }
    console.log(details)
  },
})
```

### Setting the initial highlighted option

Use `defaultHighlightedValue` to set which option is highlighted when the popup
opens.

```tsx
const service = useMachine(combobox.machine, {
  id: useId(),
  collection,
  defaultHighlightedValue: "ng",
})
```

### Listening for item selection

Use `onSelect` to react to each selected item.

```tsx
const service = useMachine(combobox.machine, {
  id: useId(),
  collection,
  onSelect(details) {
    // details => { value: string[]; itemValue: string }
    console.log(details.itemValue)
  },
})
```

### Listening for value changes

Use `onValueChange` to listen for selected value changes.

```tsx {3-6}
const service = useMachine(combobox.machine, {
  onValueChange(details) {
    // details => { value: string[]; items: CollectionItem[] }
    console.log(details)
  },
})
```

### Usage within forms

The combobox works in forms when you:

- add a `name` so the selected value is included in `FormData`.

Set `name` to enable form submission support.

```tsx {2}
const service = useMachine(combobox.machine, {
  name: "countries",
})
```

If the input belongs to a different form element, also set `form`.

```tsx
const service = useMachine(combobox.machine, {
  id: useId(),
  collection,
  name: "countries",
  form: "checkout-form",
})
```

### Allowing custom values

By default, the combobox only allows values from the collection. Set
`allowCustomValue` to `true` to allow custom values.

```tsx {2}
const service = useMachine(combobox.machine, {
  allowCustomValue: true,
})
```

### Customizing accessibility labels

Use `translations` to customize the trigger and clear button labels.

```tsx
const service = useMachine(combobox.machine, {
  id: useId(),
  collection,
  translations: {
    triggerLabel: "Open countries",
    clearTriggerLabel: "Clear selection",
  },
})
```

## Styling guide

Each combobox part includes a `data-part` attribute you can target in CSS.

### Open and closed state

When the combobox opens or closes, `data-state` is added to content, control,
input, and trigger parts.

```css
[data-part="control"][data-state="open|closed"] {
  /* styles for open or closed control state */
}

[data-part="input"][data-state="open|closed"] {
  /* styles for open or closed input state */
}

[data-part="trigger"][data-state="open|closed"] {
  /* styles for open or closed trigger state */
}

[data-part="content"][data-state="open|closed"] {
  /* styles for open or closed content state */
}
```

### Focused State

When the combobox is focused, the `data-focus` attribute is added to the control
and label parts.

```css
[data-part="control"][data-focus] {
  /* styles for control focus state */
}

[data-part="label"][data-focus] {
  /* styles for label focus state */
}
```

### Disabled State

When the combobox is disabled, the `data-disabled` attribute is added to the
label, control, trigger and option parts.

```css
[data-part="label"][data-disabled] {
  /* styles for label disabled state */
}

[data-part="control"][data-disabled] {
  /* styles for control disabled state */
}

[data-part="trigger"][data-disabled] {
  /* styles for trigger disabled state */
}

[data-part="item"][data-disabled] {
  /* styles for item disabled state */
}
```

### Invalid State

When the combobox is invalid, the `data-invalid` attribute is added to the root,
label, control and input parts.

```css
[data-part="root"][data-invalid] {
  /* styles for root invalid state */
}

[data-part="label"][data-invalid] {
  /* styles for label invalid state */
}

[data-part="control"][data-invalid] {
  /* styles for control invalid state */
}

[data-part="input"][data-invalid] {
  /* styles for input invalid state */
}
```

### Selected State

When a combobox item is selected, the `data-state` attribute is added to the
item part.

```css
[data-part="item"][data-state="checked|unchecked"] {
  /* styles for item selected state */
}
```

### Highlighted State

When a combobox item is highlighted, the `data-highlighted` attribute is added
to the item part.

```css
[data-part="item"][data-highlighted] {
  /* styles for item highlighted state */
}
```

## Methods and Properties

### Machine Context

The combobox machine exposes the following context properties:

**`open`**
Type: `boolean | undefined`
Description: The controlled open state of the combobox

**`defaultOpen`**
Type: `boolean | undefined`
Description: The initial open state of the combobox when rendered.
Use when you don't need to control the open state of the combobox.

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the combobox. Useful for composition.

**`inputValue`**
Type: `string | undefined`
Description: The controlled value of the combobox's input

**`defaultInputValue`**
Type: `string | undefined`
Description: The initial value of the combobox's input when rendered.
Use when you don't need to control the value of the combobox's input.

**`name`**
Type: `string | undefined`
Description: The `name` attribute of the combobox's input. Useful for form submission

**`form`**
Type: `string | undefined`
Description: The associate form of the combobox.

**`disabled`**
Type: `boolean | undefined`
Description: Whether the combobox is disabled

**`readOnly`**
Type: `boolean | undefined`
Description: Whether the combobox is readonly. This puts the combobox in a "non-editable" mode
but the user can still interact with it

**`invalid`**
Type: `boolean | undefined`
Description: Whether the combobox is invalid

**`required`**
Type: `boolean | undefined`
Description: Whether the combobox is required

**`placeholder`**
Type: `string | undefined`
Description: The placeholder text of the combobox's input

**`defaultHighlightedValue`**
Type: `string | null | undefined`
Description: The initial highlighted value of the combobox when rendered.
Use when you don't need to control the highlighted value of the combobox.

**`highlightedValue`**
Type: `string | null | undefined`
Description: The controlled highlighted value of the combobox

**`value`**
Type: `string[] | undefined`
Description: The controlled value of the combobox's selected items

**`defaultValue`**
Type: `string[] | undefined`
Description: The initial value of the combobox's selected items when rendered.
Use when you don't need to control the value of the combobox's selected items.

**`inputBehavior`**
Type: `"autohighlight" | "autocomplete" | "none" | undefined`
Description: Defines the auto-completion behavior of the combobox.

- `autohighlight`: The first focused item is highlighted as the user types
- `autocomplete`: Navigating the listbox with the arrow keys selects the item and the input is updated

**`selectionBehavior`**
Type: `"clear" | "replace" | "preserve" | undefined`
Description: The behavior of the combobox input when an item is selected

- `replace`: The selected item string is set as the input value
- `clear`: The input value is cleared
- `preserve`: The input value is preserved

**`autoFocus`**
Type: `boolean | undefined`
Description: Whether to autofocus the input on mount

**`openOnClick`**
Type: `boolean | undefined`
Description: Whether to open the combobox popup on initial click on the input

**`openOnChange`**
Type: `boolean | ((details: InputValueChangeDetails) => boolean) | undefined`
Description: Whether to show the combobox when the input value changes

**`allowCustomValue`**
Type: `boolean | undefined`
Description: Whether to allow typing custom values in the input

**`alwaysSubmitOnEnter`**
Type: `boolean | undefined`
Description: Whether to always submit on Enter key press, even if popup is open.
Useful for single-field autocomplete forms where Enter should submit the form.

**`loopFocus`**
Type: `boolean | undefined`
Description: Whether to loop the keyboard navigation through the items

**`positioning`**
Type: `PositioningOptions | undefined`
Description: The positioning options to dynamically position the menu

**`onInputValueChange`**
Type: `((details: InputValueChangeDetails) => void) | undefined`
Description: Function called when the input's value changes

**`onValueChange`**
Type: `((details: ValueChangeDetails<T>) => void) | undefined`
Description: Function called when a new item is selected

**`onHighlightChange`**
Type: `((details: HighlightChangeDetails<T>) => void) | undefined`
Description: Function called when an item is highlighted using the pointer
or keyboard navigation.

**`onSelect`**
Type: `((details: SelectionDetails) => void) | undefined`
Description: Function called when an item is selected

**`onOpenChange`**
Type: `((details: OpenChangeDetails) => void) | undefined`
Description: Function called when the popup is opened

**`translations`**
Type: `IntlTranslations | undefined`
Description: Specifies the localized strings that identifies the accessibility elements and their states

**`collection`**
Type: `ListCollection<T> | undefined`
Description: The collection of items

**`multiple`**
Type: `boolean | undefined`
Description: Whether to allow multiple selection.

**Good to know:** When `multiple` is `true`, the `selectionBehavior` is automatically set to `clear`.
It is recommended to render the selected items in a separate container.

**`closeOnSelect`**
Type: `boolean | undefined`
Description: Whether to close the combobox when an item is selected.

**`openOnKeyPress`**
Type: `boolean | undefined`
Description: Whether to open the combobox on arrow key press

**`scrollToIndexFn`**
Type: `((details: ScrollToIndexDetails) => void) | undefined`
Description: Function to scroll to a specific index

**`disableLayer`**
Type: `boolean | undefined`
Description: Whether to disable registering this a dismissable layer

**`navigate`**
Type: `((details: NavigateDetails) => void) | null | undefined`
Description: Function to navigate to the selected item

**`popupType`**
Type: `"listbox" | "dialog" | undefined`
Description: The ARIA pattern of the popup. Drives `aria-haspopup` on the trigger, the
`role` of the content element, the trigger's keyboard handling, and the
label's click target.
- `"listbox"` (default) — input-driven combobox; popup is a passive listbox.
- `"dialog"` — popover-style combobox; popup is announced as a dialog,
  trigger is keyboard-active, label-click focuses the trigger.

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

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

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

**`onPointerDownOutside`**
Type: `((event: PointerDownOutsideEvent) => void) | undefined`
Description: Function called when the pointer is pressed down outside the component

**`onFocusOutside`**
Type: `((event: FocusOutsideEvent) => void) | undefined`
Description: Function called when the focus is moved outside the component

**`onInteractOutside`**
Type: `((event: InteractOutsideEvent) => void) | undefined`
Description: Function called when an interaction happens outside the component

### Machine API

The combobox `api` exposes the following methods:

**`focused`**
Type: `boolean`
Description: Whether the combobox is focused

**`open`**
Type: `boolean`
Description: Whether the combobox is open

**`inputValue`**
Type: `string`
Description: The value of the combobox input

**`highlightedValue`**
Type: `string | null`
Description: The value of the highlighted item

**`highlightedItem`**
Type: `V | null`
Description: The highlighted item

**`setHighlightValue`**
Type: `(value: string) => void`
Description: The value of the combobox input

**`clearHighlightValue`**
Type: `VoidFunction`
Description: Function to clear the highlighted value

**`syncSelectedItems`**
Type: `VoidFunction`
Description: Function to sync the selected items with the value.
Useful when `value` is updated from async sources.

**`selectedItems`**
Type: `V[]`
Description: The selected items

**`hasSelectedItems`**
Type: `boolean`
Description: Whether there's a selected item

**`value`**
Type: `string[]`
Description: The selected item keys

**`valueAsString`**
Type: `string`
Description: The string representation of the selected items

**`selectValue`**
Type: `(value: string) => void`
Description: Function to select a value

**`setValue`**
Type: `(value: string[]) => void`
Description: Function to set the value of the combobox

**`clearValue`**
Type: `(value?: string) => void`
Description: Function to clear the value of the combobox

**`focus`**
Type: `VoidFunction`
Description: Function to focus on the combobox input

**`setInputValue`**
Type: `(value: string, reason?: InputValueChangeReason) => void`
Description: Function to set the input value of the combobox

**`getItemState`**
Type: `(props: ItemProps) => ItemState`
Description: Returns the state of a combobox item

**`setOpen`**
Type: `(open: boolean, reason?: OpenChangeReason) => void`
Description: Function to open or close the combobox

**`collection`**
Type: `ListCollection<V>`
Description: Function to toggle the combobox

**`reposition`**
Type: `(options?: Partial<PositioningOptions>) => void`
Description: Function to set the positioning options

**`multiple`**
Type: `boolean`
Description: Whether the combobox allows multiple selections

**`disabled`**
Type: `boolean`
Description: Whether the combobox is disabled

### Data Attributes

**`Root`**

**`data-combobox-root`**: <uid>
**`data-invalid`**: Present when invalid
**`data-readonly`**: Present when read-only

**`Label`**

**`data-combobox-label`**: <uid>
**`data-readonly`**: Present when read-only
**`data-disabled`**: Present when disabled
**`data-invalid`**: Present when invalid
**`data-required`**: Present when required
**`data-focus`**: Present when focused

**`Control`**

**`data-combobox-control`**: <uid>
**`data-state`**: "open" | "closed"
**`data-focus`**: Present when focused
**`data-disabled`**: Present when disabled
**`data-invalid`**: Present when invalid

**`Input`**

**`data-combobox-input`**: <uid>
**`data-invalid`**: Present when invalid
**`data-autofocus`**: 
**`data-state`**: "open" | "closed"

**`Trigger`**

**`data-combobox-trigger`**: <uid>
**`data-state`**: "open" | "closed"
**`data-invalid`**: Present when invalid
**`data-focusable`**: 
**`data-readonly`**: Present when read-only
**`data-disabled`**: Present when disabled

**`Content`**

**`data-combobox-content`**: <uid>
**`data-state`**: "open" | "closed"
**`data-nested`**: listbox
**`data-has-nested`**: listbox
**`data-placement`**: The placement of the content
**`data-side`**: The side of the trigger that the content is positioned on
**`data-empty`**: Present when the content is empty

**`List`**

**`data-combobox-list`**: <uid>
**`data-empty`**: Present when the content is empty

**`ClearTrigger`**

**`data-combobox-clear-trigger`**: <uid>
**`data-invalid`**: Present when invalid

**`Item`**

**`data-combobox-item`**: <uid>
**`data-highlighted`**: Present when highlighted
**`data-state`**: "checked" | "unchecked"
**`data-disabled`**: Present when disabled
**`data-value`**: The value of the item

**`ItemText`**

**`data-combobox-item-text`**: <uid>
**`data-state`**: "checked" | "unchecked"
**`data-disabled`**: Present when disabled
**`data-highlighted`**: Present when highlighted

**`ItemIndicator`**

**`data-combobox-item-indicator`**: <uid>
**`data-state`**: "checked" | "unchecked"

**`ItemGroup`**

**`data-combobox-item-group`**: <uid>
**`data-empty`**: Present when the content is empty

### CSS Variables

<CssVarTable name="combobox" />

## Accessibility

Adheres to the
[Combobox WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/).

### Keyboard Interactions

**`ArrowDown`**
Description: When the combobox is closed, opens the listbox and highlights to the first option.
When the combobox is open, moves focus to the next option.

**`ArrowUp`**
Description: When the combobox is closed, opens the listbox and highlights to the last option.
When the combobox is open, moves focus to the previous option.

**`Home`**
Description: When the combobox is open, moves focus to the first option.

**`End`**
Description: When the combobox is open, moves focus to the last option.

**`Escape`**
Description: Closes the listbox.

**`Enter`**
Description: Selects the highlighted option and closes the combobox.

**`Esc`**
Description: Closes the combobox

A date input lets you enter a date by typing into segmented input fields (month, day,
year, etc.) with validation and keyboard navigation.

> **Good to know**: The date input is built on top of the
> [`@internationalized/date`](https://react-spectrum.adobe.com/internationalized/date/CalendarDate.html)
> library.

## Resources


[Latest version: v2.0.0-next.1](https://www.npmjs.com/package/@zag-js/date-input)
[Logic Visualizer](https://zag-visualizer.vercel.app/date-input)
[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/date-input)



**Features**

- Segmented input fields for each date part (month, day, year, hour, minute, second)
- Supports `single` and `range` selection modes
- Keyboard navigation and auto-advance between segments
- Placeholder management with visual distinction
- Customizable granularity (day, month, hour, minute, second)
- Optional leading zeros in numeric fields
- Works with localization and timezone
- Full accessibility with keyboard and screen reader support
- Form integration with hidden input element

## Installation

Install the date-input package:

```bash
npm install @zag-js/date-input @zag-js/react
# or
yarn add @zag-js/date-input @zag-js/react
```

## Anatomy

Check the date-input anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the package:

```tsx
import * as dateInput from "@zag-js/date-input"
```

These are the key exports:

- `machine` - State machine logic.
- `connect` - Maps machine state to JSX props and event handlers.
- `parse` - Parses an ISO 8601 date string.

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

Then use the framework integration helpers:

```tsx
import * as dateInput from "@zag-js/date-input"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useId } from "react"

function DateInput() {
  const service = useMachine(dateInput.machine, { id: useId() })

  const api = dateInput.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <label {...api.getLabelProps()}>Enter a date</label>

      <div {...api.getControlProps()}>
        <div {...api.getSegmentGroupProps()}>
          {api.getSegments().map((segment, i) => (
            <span key={i} {...api.getSegmentProps({ segment })}>
              {segment.text}
            </span>
          ))}
        </div>
      </div>

      <input {...api.getHiddenInputProps()} />
    </div>
  )
}
```

### Rendering segments

Use `api.getSegments()` to get the list of date segments. Each segment has a
`type` (e.g., `"month"`, `"day"`, `"year"`, `"literal"`) and a `text` property
for display.

```tsx
<div {...api.getControlProps()}>
  <div {...api.getSegmentGroupProps()}>
    {api.getSegments().map((segment, i) => (
      <span key={i} {...api.getSegmentProps({ segment })}>
        {segment.text}
      </span>
    ))}
  </div>
</div>
```

For range mode, pass the `index` to distinguish start and end date segments:

```tsx
<div {...api.getControlProps()}>
  <div {...api.getSegmentGroupProps({ index: 0 })}>
    {api.getSegments({ index: 0 }).map((segment, i) => (
      <span key={i} {...api.getSegmentProps({ segment, index: 0 })}>
        {segment.text}
      </span>
    ))}
  </div>

  <span> – </span>

  <div {...api.getSegmentGroupProps({ index: 1 })}>
    {api.getSegments({ index: 1 }).map((segment, i) => (
      <span key={i} {...api.getSegmentProps({ segment, index: 1 })}>
        {segment.text}
      </span>
    ))}
  </div>
</div>
```

### Setting the initial date

To set the initial value rendered by the date input, set `defaultValue`.

```tsx
const service = useMachine(dateInput.machine, {
  defaultValue: [dateInput.parse("2024-01-15")],
})
```

### Controlling the selected date

Use `value` and `onValueChange` to programmatically control the selected date.

```tsx
const service = useMachine(dateInput.machine, {
  value: [dateInput.parse("2024-01-15")],
  onValueChange(details) {
    // details => { value: DateValue[], valueAsString: string[] }
    console.log("selected date:", details.valueAsString)
  },
})
```

You can also set it with `api.setValue`.

```tsx
const nextValue = dateInput.parse("2024-01-15")
api.setValue([nextValue])
```

### Setting the min and max dates

To constrain the dates that can be entered, set the `min` and `max` properties.

```tsx
const service = useMachine(dateInput.machine, {
  min: dateInput.parse("2024-01-01"),
  max: dateInput.parse("2024-12-31"),
})
```

When typing values outside the range, invalid segments will be marked as invalid.

### Disabling the date input

Set `disabled` to `true` to make the input non-interactive.

```tsx
const service = useMachine(dateInput.machine, {
  disabled: true,
})
```

### Setting read-only mode

Set `readOnly` to `true` to prevent value changes while allowing focus.

```tsx
const service = useMachine(dateInput.machine, {
  readOnly: true,
})
```

### Required and invalid state

Use `required` and `invalid` for form validation and UI state.

```tsx
const service = useMachine(dateInput.machine, {
  required: true,
  invalid: false,
})
```

### Controlling date granularity

Set `granularity` to control the smallest unit displayed in the input.

```tsx
const service = useMachine(dateInput.machine, {
  granularity: "day", // "month" | "day" | "year" | "hour" | "minute" | "second"
})
```

The available granularities are: `"month"`, `"day"`, `"year"`, `"hour"`, `"minute"`, and
`"second"`.

### Forcing leading zeros

Set `shouldForceLeadingZeros` to always display leading zeros in numeric fields
(e.g., "01" instead of "1").

```tsx
const service = useMachine(dateInput.machine, {
  shouldForceLeadingZeros: true,
})
```

By default, leading zeros follow the locale's conventions.

### Controlling the placeholder date

Use `placeholderValue` to set the initial placeholder date, which is shown in
unfilled segments.

```tsx
const service = useMachine(dateInput.machine, {
  placeholderValue: dateInput.parse("2024-01-01"),
  defaultPlaceholderValue: dateInput.parse("2024-01-01"),
})
```

Listen for placeholder changes with `onPlaceholderChange`:

```tsx
const service = useMachine(dateInput.machine, {
  onPlaceholderChange(details) {
    // details => { placeholderValue: DateValue, value: DateValue[], valueAsString: string[] }
    console.log("placeholder changed:", details.placeholderValue)
  },
})
```

### Listening to focus changes

Use `onFocusChange` to listen for when the input gains or loses focus.

```tsx
const service = useMachine(dateInput.machine, {
  onFocusChange(details) {
    // details => { focused: boolean }
    console.log("focused:", details.focused)
  },
})
```

### Choosing a selection mode

Use `selectionMode` to allow entering a single date or a date range.

```tsx
const service = useMachine(dateInput.machine, {
  selectionMode: "range", // "single" | "range"
})
```

In range mode, the input will have segments for both start and end dates.

### Working with display values

The `displayValues` property tracks partially entered dates while the user is
typing. This is useful for showing the editing state before a complete date is
entered.

```tsx
const displayValues = api.displayValues
// Each incomplete date shows which segments have been filled in
```

### Clearing the date

Use `api.clearValue()` to clear the selected date.

```tsx
api.clearValue()
```

### Accessing segments

Use `api.getSegments()` to access the individual date segments.

```tsx
const segments = api.getSegments()

segments.forEach((segment) => {
  console.log(segment.type)      // "month", "day", "year", etc.
  console.log(segment.text)      // displayed text
  console.log(segment.value)     // numeric value
  console.log(segment.isEditable) // whether user can edit
})
```

Then render each segment:

```tsx
<div {...api.getControlProps()}>
  <div {...api.getSegmentGroupProps()}>
    {api.getSegments().map((segment, i) => (
      <span key={i} {...api.getSegmentProps({ segment })}>
        {segment.text}
      </span>
    ))}
  </div>
</div>
```

### Checking segment editability

Use `api.getSegmentState()` to determine if a segment can be edited.

```tsx
const state = api.getSegmentState({ segment })
console.log(state.editable) // true if the segment is editable
```

### Using the hidden input for forms

The date input includes a hidden input element for form submission.

```tsx
<input {...api.getHiddenInputProps()} />
```

Set the `name` attribute to include it in form data:

```tsx
const service = useMachine(dateInput.machine, {
  name: "birthDate",
})
```

Multiple date inputs (range mode) can use a `name` prop on `getHiddenInputProps`:

```tsx
<input {...api.getHiddenInputProps({ index: 0, name: "startDate" })} />
<input {...api.getHiddenInputProps({ index: 1, name: "endDate" })} />
```

### Labeling the input

Use `getLabelProps()` to properly label the input for accessibility.

```tsx
<label {...api.getLabelProps()}>Select a date</label>
<div {...api.getControlProps()}>
  {/* segments */}
</div>
```

### Setting locale and timezone

Set `locale` and `timeZone` to control date parsing and formatting.

```tsx
const service = useMachine(dateInput.machine, {
  locale: "en-GB",
  timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
})
```

### Hour cycle (12-hour vs 24-hour time)

Set `hourCycle` to control time format display.

```tsx
const service = useMachine(dateInput.machine, {
  granularity: "hour",
  hourCycle: 24, // 12 | 24
})
```

By default, this is determined by the locale.

### Custom formatter

Provide a `formatter` to customize how dates are parsed and formatted.

```tsx
import { DateFormatter } from "@internationalized/date"

const service = useMachine(dateInput.machine, {
  formatter: new DateFormatter("en-US", {
    dateStyle: "short",
    timeStyle: "short",
  }),
})
```

### Form integration

Use the date input within a form with standard HTML form handling:

```tsx
<form
  onSubmit={(e) => {
    e.preventDefault()
    const formData = new FormData(e.currentTarget)
    const date = formData.get("birthDate")
    console.log("selected date:", date)
  }}
>
  <label {...api.getLabelProps()}>Birth Date</label>
  <div {...api.getControlProps()}>
    <div {...api.getSegmentGroupProps()}>
      {api.getSegments().map((segment, i) => (
        <span key={i} {...api.getSegmentProps({ segment })}>
          {segment.text}
        </span>
      ))}
    </div>
  </div>
  <input {...api.getHiddenInputProps({ name: "birthDate" })} />
  <button type="submit">Submit</button>
</form>
```

### Listening to date changes

Use `onValueChange` to listen for date changes.

```tsx
const service = useMachine(dateInput.machine, {
  onValueChange(details) {
    // details => { value: DateValue[], valueAsString: string[] }
    console.log("selected date:", details.valueAsString)
  },
})
```

### Localization

Use `translations` to customize accessibility labels and messages.

```tsx
const service = useMachine(dateInput.machine, {
  translations: {
    placeholder: (locale) => ({
      year: "YYYY",
      month: "MM",
      day: "DD",
      hour: "HH",
      minute: "MM",
      second: "SS",
    }),
  },
})
```

## Styling guide

Each date-input part includes a `data-part` attribute you can target in CSS.

```css
[data-scope="date-input"][data-part="root"] {
  /* styles for the root container */
}

[data-scope="date-input"][data-part="label"] {
  /* styles for the label */
}

[data-scope="date-input"][data-part="control"] {
  /* styles for the control container */
}

[data-scope="date-input"][data-part="segment-group"] {
  /* styles for the segment group */
}

[data-scope="date-input"][data-part="segment"] {
  /* styles for each segment */
}

[data-scope="date-input"][data-part="hidden-input"] {
  /* styles for the hidden input */
}
```

### State attributes

```css
[data-scope="date-input"][data-part="root"] {
  &[data-disabled] {
    /* styles for disabled state */
  }

  &[data-readonly] {
    /* styles for read-only state */
  }

  &[data-invalid] {
    /* styles for invalid state */
  }
}
```

### Segment states

```css
[data-scope="date-input"][data-part="segment"] {
  &[data-placeholder-shown] {
    /* styles for placeholder segments */
  }

  &[data-type="month"] {
    /* styles for month segments */
  }

  &[data-type="day"] {
    /* styles for day segments */
  }

  &[data-type="year"] {
    /* styles for year segments */
  }

  &[data-type="hour"] {
    /* styles for hour segments */
  }

  &[data-type="minute"] {
    /* styles for minute segments */
  }

  &[data-type="second"] {
    /* styles for second segments */
  }
}
```

## Methods and Properties

### Machine Context

The date input machine exposes the following context properties:

**`locale`**
Type: `string | undefined`
Description: The locale (BCP 47 language tag) to use when formatting the date.

**`createCalendar`**
Type: `((identifier: CalendarIdentifier) => Calendar) | undefined`
Description: A function that creates a calendar object for a given calendar identifier.
Use this to support non-Gregorian calendars (e.g., Persian, Islamic, Buddhist).

**`translations`**
Type: `IntlTranslations | undefined`
Description: The localized messages to use.

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the date input. Useful for composition.

**`name`**
Type: `string | undefined`
Description: The `name` attribute of the input element.

**`form`**
Type: `string | undefined`
Description: The `form` attribute of the hidden input element.

**`timeZone`**
Type: `string | undefined`
Description: The time zone to use

**`disabled`**
Type: `boolean | undefined`
Description: Whether the date input is disabled.

**`readOnly`**
Type: `boolean | undefined`
Description: Whether the date input is read-only.

**`required`**
Type: `boolean | undefined`
Description: Whether the date input is required

**`invalid`**
Type: `boolean | undefined`
Description: Whether the date input is invalid

**`isDateUnavailable`**
Type: `((date: DateValue, locale: string) => boolean) | undefined`
Description: Returns whether a date is unavailable.
When a committed date matches, the input is marked as invalid.

**`min`**
Type: `DateValue | undefined`
Description: The minimum date that can be selected.

**`max`**
Type: `DateValue | undefined`
Description: The maximum date that can be selected.

**`value`**
Type: `DateValue[] | undefined`
Description: The controlled selected date(s).

**`defaultValue`**
Type: `DateValue[] | undefined`
Description: The initial selected date(s) when rendered.
Use when you don't need to control the selected date(s).

**`placeholderValue`**
Type: `DateValue | undefined`
Description: The controlled placeholder date.

**`defaultPlaceholderValue`**
Type: `DateValue | undefined`
Description: The initial placeholder date when rendered.

**`onValueChange`**
Type: `((details: ValueChangeDetails) => void) | undefined`
Description: Function called when the value changes.

**`onPlaceholderChange`**
Type: `((details: PlaceholderChangeDetails) => void) | undefined`
Description: A function called when the placeholder value changes.

**`onFocusChange`**
Type: `((details: FocusChangeDetails) => void) | undefined`
Description: A function called when the date input gains or loses focus.

**`selectionMode`**
Type: `SelectionMode | undefined`
Description: The selection mode of the date input.
- `single` - only one date can be entered
- `range` - a range of dates can be entered (start and end)

**`hourCycle`**
Type: `HourCycle | undefined`
Description: Whether to use 12-hour or 24-hour time format.
By default, this is determined by the locale.

**`hideTimeZone`**
Type: `boolean | undefined`
Description: Whether to hide the time zone segment when the value is a `ZonedDateTime`.
Has no effect for values without a time zone.

**`granularity`**
Type: `DateGranularity | undefined`
Description: Determines the smallest unit that is displayed in the date input.

**`shouldForceLeadingZeros`**
Type: `boolean | undefined`
Description: Whether to always show leading zeros in month, day, and hour fields.
When false, formatting follows the locale default (e.g. "1" instead of "01").

**`formatter`**
Type: `DateFormatter | undefined`
Description: The date formatter to use.

**`allSegments`**
Type: `Segments | undefined`
Description: The computed segments map for the formatter.

**`format`**
Type: `((date: DateValue, details: FormatDateDetails) => string) | undefined`
Description: The format function for converting a DateValue to a string.

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

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

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

### Machine API

The date input `api` exposes the following methods:

**`focused`**
Type: `boolean`
Description: Whether the date input is focused

**`disabled`**
Type: `boolean`
Description: Whether the date input is disabled

**`invalid`**
Type: `boolean`
Description: Whether the date input is invalid

**`value`**
Type: `DateValue[]`
Description: The selected date(s).

**`valueAsDate`**
Type: `Date[]`
Description: The selected date(s) as Date objects.

**`valueAsString`**
Type: `string[]`
Description: The selected date(s) as strings.

**`placeholderValue`**
Type: `DateValue`
Description: The placeholder date.

**`displayValues`**
Type: `IncompleteDate[]`
Description: Per-group editing state. Each IncompleteDate tracks which segments have been
filled in by the user (non-null = entered, null = placeholder).

**`focus`**
Type: `VoidFunction`
Description: Focuses the first segment.

**`setValue`**
Type: `(values: DateValue[]) => void`
Description: Sets the selected date(s) to the given values.

**`clearValue`**
Type: `VoidFunction`
Description: Clears the selected date(s).

**`getSegments`**
Type: `(props?: SegmentsProps | undefined) => DateSegment[]`
Description: Returns the segments for the given index.

**`getSegmentState`**
Type: `(props: SegmentProps) => SegmentState`
Description: Returns the state details for a given segment.

### Data Attributes

**`Root`**

**`data-date-input-root`**: <uid>
**`data-disabled`**: Present when disabled
**`data-readonly`**: Present when read-only
**`data-invalid`**: Present when invalid

**`Label`**

**`data-date-input-label`**: <uid>
**`data-disabled`**: Present when disabled
**`data-readonly`**: Present when read-only
**`data-invalid`**: Present when invalid

**`Control`**

**`data-date-input-control`**: <uid>
**`data-disabled`**: Present when disabled
**`data-readonly`**: Present when read-only
**`data-invalid`**: Present when invalid
**`data-focus`**: Present when focused

**`SegmentGroup`**

**`data-date-input-segment-group`**: <uid>
**`data-disabled`**: Present when disabled
**`data-readonly`**: Present when read-only
**`data-invalid`**: Present when invalid
**`data-focus`**: Present when focused

**`Segment`**

**`data-date-input-segment`**: <uid>
**`data-type`**: The type of the item
**`data-readonly`**: Present when read-only
**`data-disabled`**: Present when disabled
**`data-value`**: The value of the item
**`data-editable`**: 
**`data-placeholder-shown`**: Present when placeholder is shown

### CSS Variables

<CssVarTable name="date-input" />

A date picker lets you enter a date through text input or pick one from a
calendar.

> **Good to know**: The date picker is built on top of the
> [`@internationalized/date`](https://react-spectrum.adobe.com/internationalized/date/CalendarDate.html)
> library.

## Resources


[Latest version: v2.0.0-next.1](https://www.npmjs.com/package/@zag-js/date-picker)
[Logic Visualizer](https://zag-visualizer.vercel.app/date-picker)
[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/date-picker)



**Features**

- Displays a calendar view for date selection
- Supports `single`, `multiple`, and `range` selection modes
- Supports disabling specific dates
- Supports date range presets
- Supports week numbers
- Supports custom format and parse logic
- Works with localization, timezone, and custom calendar systems
- Provides keyboard accessibility for navigating the calendar.

## Installation

Install the date-picker package:

```bash
npm install @zag-js/date-picker @zag-js/react
# or
yarn add @zag-js/date-picker @zag-js/react
```

## Anatomy

Check the date-picker anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the package:

```tsx
import * as datepicker from "@zag-js/date-picker"
```

These are the key exports:

- `machine` - Behavior logic.
- `connect` - Maps behavior to JSX props and event handlers.
- `parse` - Parses an ISO 8601 date string.

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

Then use the framework integration helpers:

```tsx
import * as datepicker from "@zag-js/date-picker"
import { useMachine, normalizeProps, Portal } from "@zag-js/react"
import { useId } from "react"

function DatePicker() {
  const service = useMachine(datepicker.machine, { id: useId() })

  const api = datepicker.connect(service, normalizeProps)

  return (
    <>
      <div {...api.getControlProps()}>
        <input {...api.getInputProps()} />
        <button {...api.getTriggerProps()}>🗓</button>
      </div>

      <Portal>
        <div {...api.getPositionerProps()}>
          <div {...api.getContentProps()}>
            {/*  Day View  */}
            <div hidden={api.view !== "day"}>
              <div {...api.getViewControlProps({ view: "year" })}>
                <button {...api.getPrevTriggerProps()}>Prev</button>
                <button {...api.getViewTriggerProps()}>
                  {api.visibleRangeText.start}
                </button>
                <button {...api.getNextTriggerProps()}>Next</button>
              </div>

              <table {...api.getTableProps({ view: "day" })}>
                <thead {...api.getTableHeaderProps({ view: "day" })}>
                  <tr {...api.getTableRowProps({ view: "day" })}>
                    {api.weekDays.map((day, i) => (
                      <th scope="col" key={i} aria-label={day.long}>
                        {day.narrow}
                      </th>
                    ))}
                  </tr>
                </thead>
                <tbody {...api.getTableBodyProps({ view: "day" })}>
                  {api.weeks.map((week, i) => (
                    <tr key={i} {...api.getTableRowProps({ view: "day" })}>
                      {week.map((value, i) => (
                        <td key={i} {...api.getDayTableCellProps({ value })}>
                          <div {...api.getDayTableCellTriggerProps({ value })}>
                            {value.day}
                          </div>
                        </td>
                      ))}
                    </tr>
                  ))}
                </tbody>
              </table>
            </div>

            {/*  Month View  */}
            <div hidden={api.view !== "month"}>
              <div {...api.getViewControlProps({ view: "month" })}>
                <button {...api.getPrevTriggerProps({ view: "month" })}>
                  Prev
                </button>
                <button {...api.getViewTriggerProps({ view: "month" })}>
                  {api.visibleRange.start.year}
                </button>
                <button {...api.getNextTriggerProps({ view: "month" })}>
                  Next
                </button>
              </div>

              <table {...api.getTableProps({ view: "month", columns: 4 })}>
                <tbody {...api.getTableBodyProps({ view: "month" })}>
                  {api
                    .getMonthsGrid({ columns: 4, format: "short" })
                    .map((months, row) => (
                      <tr key={row} {...api.getTableRowProps()}>
                        {months.map((month, index) => (
                          <td
                            key={index}
                            {...api.getMonthTableCellProps({
                              ...month,
                              columns: 4,
                            })}
                          >
                            <div
                              {...api.getMonthTableCellTriggerProps({
                                ...month,
                                columns: 4,
                              })}
                            >
                              {month.label}
                            </div>
                          </td>
                        ))}
                      </tr>
                    ))}
                </tbody>
              </table>
            </div>

            {/*  Year View  */}
            <div hidden={api.view !== "year"}>
              <div {...api.getViewControlProps({ view: "year" })}>
                <button {...api.getPrevTriggerProps({ view: "year" })}>
                  Prev
                </button>
                <span>
                  {api.getDecade().start} - {api.getDecade().end}
                </span>
                <button {...api.getNextTriggerProps({ view: "year" })}>
                  Next
                </button>
              </div>

              <table {...api.getTableProps({ view: "year", columns: 4 })}>
                <tbody {...api.getTableBodyProps()}>
                  {api.getYearsGrid({ columns: 4 }).map((years, row) => (
                    <tr key={row} {...api.getTableRowProps({ view: "year" })}>
                      {years.map((year, index) => (
                        <td
                          key={index}
                          {...api.getYearTableCellProps({
                            ...year,
                            columns: 4,
                          })}
                        >
                          <div
                            {...api.getYearTableCellTriggerProps({
                              ...year,
                              columns: 4,
                            })}
                          >
                            {year.label}
                          </div>
                        </td>
                      ))}
                    </tr>
                  ))}
                </tbody>
              </table>
            </div>
          </div>
        </div>
      </Portal>
    </>
  )
}
```

### Setting the initial date

To set the initial value rendered by the date picker, set `defaultValue`.

```tsx
const service = useMachine(datepicker.machine, {
  defaultValue: [datepicker.parse("2022-01-01")],
})
```

### Controlling the selected date

Use the `value` and `onValueChange` properties to programmatically control the
selected date.

```tsx
const service = useMachine(datepicker.machine, {
  value: [datepicker.parse("2022-01-01")],
  onValueChange(details) {
    // details => { value: DateValue[], valueAsString: string[], view: "day" | "month" | "year" }
    console.log("selected date:", details.valueAsString)
  },
})
```

You can also set it with `api.setValue`.

```tsx
const nextValue = datepicker.parse("2022-01-01")
api.setValue([nextValue])
```

### Controlling the open state

Use `open` and `onOpenChange` to control the popup state.

```tsx
const service = useMachine(datepicker.machine, {
  open: true,
  onOpenChange(details) {
    // details => { open: boolean, value: DateValue[] }
    console.log("open state changed to:", details.open)
  },
})
```

You can also manage it with `api.setOpen`.

```tsx
// open the date picker
api.setOpen(true)

// close the date picker
api.setOpen(false)
```

### Setting the min and max dates

To constrain the date range that can be selected by the user, set the `min` and
`max` properties.

```tsx
const service = useMachine(datepicker.machine, {
  min: datepicker.parse("2022-01-01"),
  max: datepicker.parse("2022-12-31"),
})
```

When min or max is reached, previous/next triggers are disabled.

### Changing the start of the week

Set `startOfWeek` from `0` to `6` (`0` is Sunday, `6` is Saturday).

```tsx
const service = useMachine(datepicker.machine, {
  startOfWeek: 1, // Monday
})
```

### Disabling the date picker

Set `disabled` to `true` to disable the picker.

```tsx
const service = useMachine(datepicker.machine, {
  disabled: true,
})
```

### Rendering month and year pickers

Render month and year selects with `api.getMonthSelectProps` and
`api.getYearSelectProps`.

```tsx
<div>
  <select {...api.getMonthSelectProps()}>
    {api.getMonths().map((month, i) => (
      <option key={i} value={month.value}>
        {month.label}
      </option>
    ))}
  </select>

  <select {...api.getYearSelectProps()}>
    {getYearsRange({ from: 1_000, to: 4_000 }).map((year, i) => (
      <option key={i} value={year}>
        {year}
      </option>
    ))}
  </select>
</div>
```

### Marking unavailable dates

Set `isDateUnavailable` and return `true` for blocked dates.

```tsx
import { isWeekend } from "@internationalized/date"

const service = useMachine(datepicker.machine, {
  isDateUnavailable: (date, locale) => {
    // mark weekends as unavailable
    return isWeekend(date, locale)
  },
})
```

### Setting the calendar starting view

The default view is `day`. Set `defaultView` to `day`, `month`, or `year` to
change it.

```tsx
const service = useMachine(datepicker.machine, {
  defaultView: "month",
})
```

### Setting the read-only mode

Set `readOnly` to `true` to prevent value changes.

```tsx
const service = useMachine(datepicker.machine, {
  readOnly: true,
})
```

### Required and invalid state

Use `required` and `invalid` for form validation and UI state.

```tsx
const service = useMachine(datepicker.machine, {
  required: true,
  invalid: false,
})
```

### Setting the focused date

By default, focused date is the first selected date or today. Set
`defaultFocusedValue` to override it.

```tsx
const service = useMachine(datepicker.machine, {
  defaultFocusedValue: datepicker.parse("2022-01-01"),
})
```

### Rendering the calendar inline

To render the calendar inline, set `inline` to `true`.

```tsx
const service = useMachine(datepicker.machine, {
  inline: true,
})
```

### Usage within a form

Set `name` to include the picker in form data.

```tsx
const service = useMachine(datepicker.machine, {
  name: "date",
})
```

### Rendering fixed number of weeks

Set `fixedWeeks` to `true` to always render 6 weeks and avoid layout jumps
between months.

```tsx
const service = useMachine(datepicker.machine, {
  fixedWeeks: true,
})
```

### Showing week numbers

Set `showWeekNumbers` to `true` to enable a week-number column in day view.

```tsx
const service = useMachine(datepicker.machine, {
  showWeekNumbers: true,
})
```

Then render the week-number header and cells in your day table.

```tsx
<table {...api.getTableProps({ view: "day" })}>
  <thead {...api.getTableHeaderProps({ view: "day" })}>
    <tr {...api.getTableRowProps({ view: "day" })}>
      {api.showWeekNumbers && (
        <th {...api.getWeekNumberHeaderCellProps({ view: "day" })}>Wk</th>
      )}
      {api.weekDays.map((day, i) => (
        <th scope="col" key={i} aria-label={day.long}>
          {day.narrow}
        </th>
      ))}
    </tr>
  </thead>
  <tbody {...api.getTableBodyProps({ view: "day" })}>
    {api.weeks.map((week, weekIndex) => (
      <tr key={weekIndex} {...api.getTableRowProps({ view: "day" })}>
        {api.showWeekNumbers && (
          <td {...api.getWeekNumberCellProps({ weekIndex, week })}>
            {api.getWeekNumber(week)}
          </td>
        )}
        {week.map((value, i) => (
          <td key={i} {...api.getDayTableCellProps({ value })}>
            <div {...api.getDayTableCellTriggerProps({ value })}>
              {value.day}
            </div>
          </td>
        ))}
      </tr>
    ))}
  </tbody>
</table>
```

### Choosing a selection mode

Use `selectionMode` to switch between `single`, `multiple`, and `range`.

```tsx
const service = useMachine(datepicker.machine, {
  selectionMode: "multiple",
})
```

If you use `multiple`, you can cap selections with `maxSelectedDates`.

```tsx
const service = useMachine(datepicker.machine, {
  selectionMode: "multiple",
  maxSelectedDates: 3,
})
```

### Using range presets

In range mode, `api.getPresetTriggerProps` accepts a preset key like
`"last7Days"` or a custom `DateValue[]`.

```tsx
const service = useMachine(datepicker.machine, {
  selectionMode: "range",
})
```

```tsx
<button {...api.getPresetTriggerProps({ value: "last7Days" })}>
  Last 7 days
</button>
<button {...api.getPresetTriggerProps({ value: "last30Days" })}>
  Last 30 days
</button>
```

```tsx
<button
  {...api.getPresetTriggerProps({
    value: [datepicker.parse("2024-01-01"), datepicker.parse("2024-01-15")],
  })}
>
  First half of Jan
</button>
```

### Customizing format and parse behavior

Use `format` and `parse` to control how input text is displayed and parsed.

```tsx
const service = useMachine(datepicker.machine, {
  format: (date, details) =>
    date
      .toDate(details.timeZone)
      .toLocaleDateString(details.locale, { dateStyle: "short" }),
  parse: (value) => datepicker.parse(value),
})
```

You can also build specialized pickers:

- Month-year picker: use `minView: "month"` and `placeholder: "mm/yyyy"`
- Year picker: use `minView: "year"`, `defaultView: "year"`, and
  `placeholder: "yyyy"`

```tsx
import { CalendarDate } from "@internationalized/date"

const service = useMachine(datepicker.machine, {
  minView: "month",
  view: "month",
  placeholder: "mm/yyyy",
  format: (date) => `${String(date.month).padStart(2, "0")}/${date.year}`,
  parse: (value) => {
    const match = value.match(/^(\d{1,2})\/(\d{4})$/)
    if (!match) return undefined
    const [_, month, year] = match.map(Number)
    return new CalendarDate(year, month, 1)
  },
})
```

```tsx
import { CalendarDate } from "@internationalized/date"

const service = useMachine(datepicker.machine, {
  selectionMode: "range",
  minView: "year",
  defaultView: "year",
  placeholder: "yyyy",
  format: (date) => String(date.year),
  parse: (value) => {
    const match = value.match(/^(\d{4})$/)
    if (!match) return undefined
    const [_, year] = match.map(Number)
    return new CalendarDate(year, 1, 1)
  },
})
```

### Setting locale and timezone

Set `locale` and `timeZone` to control date rendering.

```tsx
const service = useMachine(datepicker.machine, {
  locale: "en-GB",
  timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
})
```

### Using custom calendar systems

Pass a dedicated `createCalendar` function so you only ship the calendar your
locale needs.

```tsx
import { PersianCalendar } from "@internationalized/date"

function createPersianCalendar(identifier: string) {
  if (identifier === "persian") return new PersianCalendar()
  throw new Error(`Unsupported calendar: ${identifier}`)
}

const service = useMachine(datepicker.machine, {
  locale: "fa-IR",
  createCalendar: createPersianCalendar,
})
```

```tsx
import { BuddhistCalendar } from "@internationalized/date"

function createBuddhistCalendar(identifier: string) {
  if (identifier === "buddhist") return new BuddhistCalendar()
  throw new Error(`Unsupported calendar: ${identifier}`)
}

const service = useMachine(datepicker.machine, {
  locale: "th-TH",
  createCalendar: createBuddhistCalendar,
})
```

### Restricting available views

Use `minView` and `maxView` to limit view navigation.

```tsx
const service = useMachine(datepicker.machine, {
  minView: "month",
  maxView: "year",
})
```

### Controlling open behavior

By default, the picker closes after selection and does not open on input click.
You can change both behaviors.

```tsx
const service = useMachine(datepicker.machine, {
  openOnClick: true,
  closeOnSelect: false,
})
```

Use `defaultOpen` if you want the calendar to start open in uncontrolled mode.

```tsx
const service = useMachine(datepicker.machine, {
  defaultOpen: true,
})
```

### Allowing outside-day selection

Days outside the visible month are disabled by default. Set
`outsideDaySelectable` to `true` if you want them selectable.

```tsx
const service = useMachine(datepicker.machine, {
  outsideDaySelectable: true,
})
```

### Listening to date changes

Use `onValueChange` to listen for date changes.

```tsx
const service = useMachine(datepicker.machine, {
  onValueChange(details) {
    // details => { value: DateValue[], valueAsString: string[], view: "day" | "month" | "year" }
    console.log("selected date:", details.valueAsString)
  },
})
```

### Listening to view changes

Use `onViewChange` to listen for view changes.

```tsx
const service = useMachine(datepicker.machine, {
  onViewChange(details) {
    // details => { view: "day" | "month" | "year" }
    console.log("view changed to:", details.view)
  },
})
```

### Controlling the focused date

Use `focusedValue` and `onFocusChange` to control keyboard focus in the
calendar.

```tsx
const service = useMachine(datepicker.machine, {
  focusedValue: datepicker.parse("2022-01-01"),
  onFocusChange(details) {
    console.log("focused date:", details.focusedValue)
  },
})
```

### Listening to focus and visible range changes

Use `onFocusChange` for focused-date changes and `onVisibleRangeChange` for
visible-range changes.

```tsx
const service = useMachine(datepicker.machine, {
  onFocusChange(details) {
    console.log("focused date:", details.focusedValue)
  },
  onVisibleRangeChange(details) {
    console.log("visible range:", details.visibleRange)
  },
})
```

### Rendering multiple months

To display multiple months:

- set the `numOfMonths` prop to the desired number of months
- generate the weeks for the offset months using `api.getOffset({ months: 1 })`

```tsx
const service = useMachine(datepicker.machine, {
  // ...
  numOfMonths: 2,
})

const offset = api.getOffset({ months: 1 })
```

Then render the offset months.

```tsx
<tbody {...api.getTableBodyProps({ view: "day" })}>
  {offset.weeks.map((week, i) => (
    <tr key={i} {...api.getTableRowProps({ view: "day" })}>
      {week.map((value, i) => (
        <td
          key={i}
          {...api.getDayTableCellProps({
            value,
            visibleRange: offset.visibleRange,
          })}
        >
          <div
            {...api.getDayTableCellTriggerProps({
              value,
              visibleRange: offset.visibleRange,
            })}
          >
            {value.day}
          </div>
        </td>
      ))}
    </tr>
  ))}
</tbody>
```

### Positioning

Use `positioning` to customize popup placement.

```tsx
const service = useMachine(datepicker.machine, {
  positioning: { placement: "bottom-start" },
})
```

### Localization

Use `translations` to customize accessibility labels and messages.

```tsx
const service = useMachine(datepicker.machine, {
  translations: {
    clearTrigger: "Clear date",
  },
})
```

## Styling guide

Each date-picker part includes a `data-part` attribute you can target in CSS.

```css
[data-scope="date-picker"][data-part="root"] {
  /* styles for the root part */
}

[data-scope="date-picker"][data-part="input"] {
  /* styles for the input part */
}

[data-scope="date-picker"][data-part="trigger"] {
  /* styles for the trigger part */
}

[data-scope="date-picker"][data-part="content"] {
  /* styles for the input part */
}
```

### Open State

```css
[data-scope="date-picker"][data-part="trigger"] {
  &[data-state="open"] {
    /* styles for the open state */
  }

  &[data-state="closed"] {
    /* styles for the closed state */
  }
}
```

### Cell States

```css
[data-scope="date-picker"][data-part="table-cell-trigger"] {
  /* styles for the cell */

  &[data-selected] {
    /* styles for the selected date */
  }

  &[data-focus] {
    /* styles for the focused date */
  }

  &[data-disabled] {
    /* styles for the disabled date */
  }

  &[data-unavailable] {
    /* styles for the unavailable date */
  }

  &[data-today] {
    /* styles for the today date */
  }

  &[data-weekend] {
    /* styles for the weekend date */
  }
}
```

### Range Selection States

When using `selectionMode: "range"`, additional data attributes are available on
day, month, and year table cell triggers for styling the selected and hovered
ranges.

```css
[data-scope="date-picker"][data-part="table-cell-trigger"] {
  &[data-range-start] {
    /* styles for the start of the selected range */
  }

  &[data-range-end] {
    /* styles for the end of the selected range */
  }

  &[data-in-range] {
    /* styles for dates within the selected range */
  }

  &[data-in-hover-range] {
    /* styles for dates within the hovered range preview */
  }

  &[data-hover-range-start] {
    /* styles for the start of the hovered range */
  }

  &[data-hover-range-end] {
    /* styles for the end of the hovered range */
  }
}
```

## Methods and Properties

### Machine Context

The date picker machine exposes the following context properties:

**`locale`**
Type: `string | undefined`
Description: The locale (BCP 47 language tag) to use when formatting the date.

**`createCalendar`**
Type: `((identifier: CalendarIdentifier) => Calendar) | undefined`
Description: A function that creates a Calendar object for a given calendar identifier.
Enables non-Gregorian calendar support (Persian, Buddhist, Islamic, etc.)
without bundling all calendars by default.

**`translations`**
Type: `IntlTranslations | undefined`
Description: The localized messages to use.

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the date picker. Useful for composition.

**`name`**
Type: `string | undefined`
Description: The `name` attribute of the input element.

**`timeZone`**
Type: `string | undefined`
Description: The time zone to use

**`disabled`**
Type: `boolean | undefined`
Description: Whether the calendar is disabled.

**`readOnly`**
Type: `boolean | undefined`
Description: Whether the calendar is read-only.

**`required`**
Type: `boolean | undefined`
Description: Whether the date picker is required

**`invalid`**
Type: `boolean | undefined`
Description: Whether the date picker is invalid

**`outsideDaySelectable`**
Type: `boolean | undefined`
Description: Whether day outside the visible range can be selected.

**`min`**
Type: `DateValue | undefined`
Description: The minimum date that can be selected.

**`max`**
Type: `DateValue | undefined`
Description: The maximum date that can be selected.

**`closeOnSelect`**
Type: `boolean | undefined`
Description: Whether the calendar should close after the date selection is complete.
This is ignored when the selection mode is `multiple`.

**`openOnClick`**
Type: `boolean | undefined`
Description: Whether to open the calendar when the input is clicked.

**`value`**
Type: `DateValue[] | undefined`
Description: The controlled selected date(s).

**`defaultValue`**
Type: `DateValue[] | undefined`
Description: The initial selected date(s) when rendered.
Use when you don't need to control the selected date(s) of the date picker.

**`focusedValue`**
Type: `DateValue | undefined`
Description: The controlled focused date.

**`defaultFocusedValue`**
Type: `DateValue | undefined`
Description: The initial focused date when rendered.
Use when you don't need to control the focused date of the date picker.

**`numOfMonths`**
Type: `number | undefined`
Description: The number of months to display.

**`startOfWeek`**
Type: `number | undefined`
Description: The first day of the week.
 `0` - Sunday
 `1` - Monday
 `2` - Tuesday
 `3` - Wednesday
 `4` - Thursday
 `5` - Friday
 `6` - Saturday

**`fixedWeeks`**
Type: `boolean | undefined`
Description: Whether the calendar should have a fixed number of weeks.
This renders the calendar with 6 weeks instead of 5 or 6.

**`showWeekNumbers`**
Type: `boolean | undefined`
Description: Whether to show the week number column in the day view.

**`onValueChange`**
Type: `((details: ValueChangeDetails) => void) | undefined`
Description: Function called when the value changes.

**`onFocusChange`**
Type: `((details: FocusChangeDetails) => void) | undefined`
Description: Function called when the focused date changes.

**`onViewChange`**
Type: `((details: ViewChangeDetails) => void) | undefined`
Description: Function called when the view changes.

**`onVisibleRangeChange`**
Type: `((details: VisibleRangeChangeDetails) => void) | undefined`
Description: Function called when the visible range changes.

**`onOpenChange`**
Type: `((details: OpenChangeDetails) => void) | undefined`
Description: Function called when the calendar opens or closes.

**`isDateUnavailable`**
Type: `((date: DateValue, locale: string) => boolean) | undefined`
Description: Returns whether a date of the calendar is available.

**`selectionMode`**
Type: `SelectionMode | undefined`
Description: The selection mode of the calendar.
- `single` - only one date can be selected
- `multiple` - multiple dates can be selected
- `range` - a range of dates can be selected

**`maxSelectedDates`**
Type: `number | undefined`
Description: The maximum number of dates that can be selected.
This is only applicable when `selectionMode` is `multiple`.

**`format`**
Type: `((date: DateValue, details: LocaleDetails) => string) | undefined`
Description: The format of the date to display in the input.

**`parse`**
Type: `((value: string, details: LocaleDetails) => DateValue | undefined) | undefined`
Description: Function to parse the date from the input back to a DateValue.

**`placeholder`**
Type: `string | undefined`
Description: The placeholder text to display in the input.

**`view`**
Type: `DateView | undefined`
Description: The view of the calendar

**`defaultView`**
Type: `DateView | undefined`
Description: The default view of the calendar

**`minView`**
Type: `DateView | undefined`
Description: The minimum view of the calendar

**`maxView`**
Type: `DateView | undefined`
Description: The maximum view of the calendar

**`positioning`**
Type: `PositioningOptions | undefined`
Description: The user provided options used to position the date picker content

**`open`**
Type: `boolean | undefined`
Description: The controlled open state of the date picker

**`defaultOpen`**
Type: `boolean | undefined`
Description: The initial open state of the date picker when rendered.
Use when you don't need to control the open state of the date picker.

**`inline`**
Type: `boolean | undefined`
Description: Whether to render the date picker inline

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

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

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

### Machine API

The date picker `api` exposes the following methods:

**`focused`**
Type: `boolean`
Description: Whether the input is focused

**`open`**
Type: `boolean`
Description: Whether the date picker is open

**`disabled`**
Type: `boolean`
Description: Whether the date picker is disabled

**`invalid`**
Type: `boolean`
Description: Whether the date picker is invalid

**`readOnly`**
Type: `boolean`
Description: Whether the date picker is read-only

**`inline`**
Type: `boolean`
Description: Whether the date picker is rendered inline

**`numOfMonths`**
Type: `number`
Description: The number of months to display

**`showWeekNumbers`**
Type: `boolean`
Description: Whether the week number column is shown in the day view

**`selectionMode`**
Type: `SelectionMode`
Description: The selection mode (single, multiple, or range)

**`maxSelectedDates`**
Type: `number | undefined`
Description: The maximum number of dates that can be selected (only for multiple selection mode).

**`isMaxSelected`**
Type: `boolean`
Description: Whether the maximum number of selected dates has been reached.

**`view`**
Type: `DateView`
Description: The current view of the date picker

**`getWeekNumber`**
Type: `(week: DateValue[]) => number`
Description: Returns the ISO 8601 week number (1-53) for the given week (array of dates).

**`getDaysInWeek`**
Type: `(week: number, from?: DateValue) => DateValue[]`
Description: Returns an array of days in the week index counted from the provided start date, or the first visible date if not given.

**`getOffset`**
Type: `(duration: DateDuration) => DateValueOffset`
Description: Returns the offset of the month based on the provided number of months.

**`getRangePresetValue`**
Type: `(value: DateRangePreset) => DateValue[]`
Description: Returns the range of dates based on the provided date range preset.

**`getMonthWeeks`**
Type: `(from?: DateValue) => DateValue[][]`
Description: Returns the weeks of the month from the provided date. Represented as an array of arrays of dates.

**`isUnavailable`**
Type: `(date: DateValue) => boolean`
Description: Returns whether the provided date is available (or can be selected)

**`weeks`**
Type: `DateValue[][]`
Description: The weeks of the month. Represented as an array of arrays of dates.

**`weekDays`**
Type: `WeekDay[]`
Description: The days of the week. Represented as an array of strings.

**`visibleRange`**
Type: `VisibleRange`
Description: The visible range of dates.

**`visibleRangeText`**
Type: `VisibleRangeText`
Description: The human readable text for the visible range of dates.

**`value`**
Type: `DateValue[]`
Description: The selected date.

**`valueAsDate`**
Type: `Date[]`
Description: The selected date as a Date object.

**`valueAsString`**
Type: `string[]`
Description: The selected date as a string.

**`focusedValue`**
Type: `DateValue`
Description: The focused date.

**`focusedValueAsDate`**
Type: `Date`
Description: The focused date as a Date object.

**`focusedValueAsString`**
Type: `string`
Description: The focused date as a string.

**`selectToday`**
Type: `VoidFunction`
Description: Sets the selected date to today.

**`setValue`**
Type: `(values: DateValue[]) => void`
Description: Sets the selected date to the given date.

**`setTime`**
Type: `(time: Time, index?: number) => void`
Description: Sets the time for a specific date value.
Converts CalendarDate to CalendarDateTime if needed.

**`setFocusedValue`**
Type: `(value: DateValue) => void`
Description: Sets the focused date to the given date.

**`clearValue`**
Type: `(options?: { focus?: boolean }) => void`
Description: Clears the selected date(s).

**`setOpen`**
Type: `(open: boolean) => void`
Description: Function to open or close the calendar.

**`focusMonth`**
Type: `(month: number) => void`
Description: Function to set the selected month.

**`focusYear`**
Type: `(year: number) => void`
Description: Function to set the selected year.

**`getYears`**
Type: `() => Cell[]`
Description: Returns the months of the year

**`getYearsGrid`**
Type: `(props?: YearGridProps) => YearGridValue`
Description: Returns the years of the decade based on the columns.
Represented as an array of arrays of years.

**`getDecade`**
Type: `() => Range<number | undefined>`
Description: Returns the start and end years of the decade.

**`getMonths`**
Type: `(props?: MonthFormatOptions) => Cell[]`
Description: Returns the months of the year

**`getMonthsGrid`**
Type: `(props?: MonthGridProps) => MonthGridValue`
Description: Returns the months of the year based on the columns.
Represented as an array of arrays of months.

**`format`**
Type: `(value: DateValue, opts?: Intl.DateTimeFormatOptions) => string`
Description: Formats the given date value based on the provided options.

**`setView`**
Type: `(view: DateView) => void`
Description: Sets the view of the date picker.

**`goToNext`**
Type: `VoidFunction`
Description: Goes to the next month/year/decade.

**`goToPrev`**
Type: `VoidFunction`
Description: Goes to the previous month/year/decade.

**`getDayTableCellState`**
Type: `(props: DayTableCellProps) => DayTableCellState`
Description: Returns the state details for a given cell.

**`getMonthTableCellState`**
Type: `(props: TableCellProps) => TableCellState`
Description: Returns the state details for a given month cell.

**`getYearTableCellState`**
Type: `(props: TableCellProps) => TableCellState`
Description: Returns the state details for a given year cell.

### Data Attributes

**`Root`**

**`data-date-picker-root`**: <uid>
**`data-state`**: "open" | "closed"
**`data-disabled`**: Present when disabled
**`data-readonly`**: Present when read-only
**`data-empty`**: Present when the content is empty

**`Label`**

**`data-date-picker-label`**: <uid>
**`data-state`**: "open" | "closed"
**`data-index`**: The index of the item
**`data-disabled`**: Present when disabled
**`data-readonly`**: Present when read-only

**`Control`**

**`data-date-picker-control`**: <uid>
**`data-disabled`**: Present when disabled
**`data-placeholder-shown`**: Present when placeholder is shown

**`Content`**

**`data-date-picker-content`**: <uid>
**`data-state`**: "open" | "closed"
**`data-nested`**: popover
**`data-has-nested`**: popover
**`data-placement`**: The placement of the content
**`data-side`**: The side of the trigger that the content is positioned on
**`data-inline`**: Present when the content is inline

**`Table`**

**`data-date-picker-table`**: <uid>
**`data-columns`**: 
**`data-view`**: The view of the table

**`TableHead`**

**`data-date-picker-table-head`**: <uid>
**`data-view`**: The view of the tablehead
**`data-disabled`**: Present when disabled

**`TableHeader`**

**`data-date-picker-table-header`**: <uid>
**`data-view`**: The view of the tableheader
**`data-disabled`**: Present when disabled

**`TableBody`**

**`data-date-picker-table-body`**: <uid>
**`data-view`**: The view of the tablebody
**`data-disabled`**: Present when disabled

**`TableRow`**

**`data-date-picker-table-row`**: <uid>
**`data-disabled`**: Present when disabled
**`data-view`**: The view of the tablerow

**`WeekNumberHeaderCell`**

**`data-date-picker-week-number-header-cell`**: <uid>
**`data-view`**: The view of the weeknumberheadercell
**`data-type`**: The type of the item
**`data-disabled`**: Present when disabled

**`WeekNumberCell`**

**`data-date-picker-week-number-cell`**: <uid>
**`data-view`**: The view of the weeknumbercell
**`data-week-index`**: 
**`data-type`**: The type of the item
**`data-disabled`**: Present when disabled

**`DayTableCell`**

**`data-date-picker-day-table-cell`**: <uid>
**`data-value`**: The value of the item

**`DayTableCellTrigger`**

**`data-date-picker-day-table-cell-trigger`**: <uid>
**`data-disabled`**: Present when disabled
**`data-selectable`**: 
**`data-selected`**: Present when selected
**`data-value`**: The value of the item
**`data-view`**: The view of the daytablecelltrigger
**`data-today`**: Present when the date represents today
**`data-focus`**: Present when focused
**`data-unavailable`**: Present when the date is unavailable based on the min and max date
**`data-range-start`**: Present when is the start of a range
**`data-range-end`**: Present when is the end of a range
**`data-in-range`**: Present when is within the range
**`data-outside-range`**: Present when is outside the range
**`data-weekend`**: Present when is a weekend day
**`data-in-hover-range`**: Present when in hovered range
**`data-hover-range-start`**: Present when is the start of the hovered range
**`data-hover-range-end`**: Present when is the end of the hovered range

**`MonthTableCell`**

**`data-date-picker-month-table-cell`**: <uid>
**`data-selected`**: Present when selected
**`data-value`**: The value of the item

**`MonthTableCellTrigger`**

**`data-date-picker-month-table-cell-trigger`**: <uid>
**`data-disabled`**: Present when disabled
**`data-selectable`**: 
**`data-selected`**: Present when selected
**`data-value`**: The value of the item
**`data-view`**: The view of the monthtablecelltrigger
**`data-focus`**: Present when focused
**`data-outside-range`**: Present when is outside the range
**`data-range-start`**: Present when is the start of a range
**`data-range-end`**: Present when is the end of a range
**`data-in-range`**: Present when is within the range
**`data-in-hover-range`**: Present when in hovered range
**`data-hover-range-start`**: Present when is the start of the hovered range
**`data-hover-range-end`**: Present when is the end of the hovered range

**`YearTableCell`**

**`data-date-picker-year-table-cell`**: <uid>
**`data-selected`**: Present when selected
**`data-value`**: The value of the item

**`YearTableCellTrigger`**

**`data-date-picker-year-table-cell-trigger`**: <uid>
**`data-disabled`**: Present when disabled
**`data-selectable`**: 
**`data-selected`**: Present when selected
**`data-value`**: The value of the item
**`data-view`**: The view of the yeartablecelltrigger
**`data-focus`**: Present when focused
**`data-outside-range`**: Present when is outside the range
**`data-range-start`**: Present when is the start of a range
**`data-range-end`**: Present when is the end of a range
**`data-in-range`**: Present when is within the range
**`data-in-hover-range`**: Present when in hovered range
**`data-hover-range-start`**: Present when is the start of the hovered range
**`data-hover-range-end`**: Present when is the end of the hovered range

**`NextTrigger`**

**`data-date-picker-next-trigger`**: <uid>
**`data-disabled`**: Present when disabled

**`PrevTrigger`**

**`data-date-picker-prev-trigger`**: <uid>
**`data-disabled`**: Present when disabled

**`Trigger`**

**`data-date-picker-trigger`**: <uid>
**`data-placement`**: The placement of the trigger
**`data-side`**: The side of the trigger that the trigger is positioned on
**`data-state`**: "open" | "closed"
**`data-placeholder-shown`**: Present when placeholder is shown

**`View`**

**`data-date-picker-view`**: <uid>
**`data-view`**: The view of the view

**`ViewTrigger`**

**`data-date-picker-view-trigger`**: <uid>
**`data-view`**: The view of the viewtrigger

**`ViewControl`**

**`data-date-picker-view-control`**: <uid>
**`data-view`**: The view of the viewcontrol

**`Input`**

**`data-date-picker-input`**: <uid>
**`data-index`**: The index of the item
**`data-state`**: "open" | "closed"
**`data-placeholder-shown`**: Present when placeholder is shown
**`data-invalid`**: Present when invalid

### CSS Variables

<CssVarTable name="date-picker" />

A dialog is a window overlaid on either the primary window or another dialog
window. Content behind a modal dialog is inert, meaning that users cannot
interact with it.

## Resources


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



**Features**

- Supports modal and non-modal modes
- Focus is trapped and scrolling is blocked in the modal mode
- Provides screen reader announcements via rendered title and description
- Pressing `Esc` closes the dialog
- Supports multiple triggers sharing a single dialog instance

## Installation

Install the dialog package:

```bash
npm install @zag-js/dialog @zag-js/react
# or
yarn add @zag-js/dialog @zag-js/react
```

## Anatomy

To use the dialog component 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 dialog package:

```tsx
import * as dialog from "@zag-js/dialog"
```

The dialog package exports two key functions:

- `machine` - Behavior logic for the dialog.
- `connect` - Maps behavior to JSX props and event handlers.

> Pass a unique `id` to `useMachine` so generated element ids stay predictable.

Then use the framework integration helpers:

```tsx
import * as dialog from "@zag-js/dialog"
import { useMachine, normalizeProps, Portal } from "@zag-js/react"
import { useId } from "react"

export function Dialog() {
  const service = useMachine(dialog.machine, { id: useId() })

  const api = dialog.connect(service, normalizeProps)

  return (
    <>
      <button {...api.getTriggerProps()}>Open Dialog</button>
      {api.open && (
        <Portal>
          <div {...api.getBackdropProps()} />
          <div {...api.getPositionerProps()}>
            <div {...api.getContentProps()}>
              <h2 {...api.getTitleProps()}>Edit profile</h2>
              <p {...api.getDescriptionProps()}>
                Make changes to your profile here. Click save when you are done.
              </p>
              <div>
                <input placeholder="Enter name..." />
                <button>Save</button>
              </div>
              <button {...api.getCloseTriggerProps()}>Close</button>
            </div>
          </div>
        </Portal>
      )}
    </>
  )
}
```

### Managing focus within the dialog

When the dialog opens, it focuses the first focusable element and keeps keyboard
focus inside the dialog.

To control what receives focus on open, pass `initialFocusEl`.

```tsx {3,6,13}
export function Dialog() {
  // initial focused element ref
  const inputRef = useRef(null)

  const service = useMachine(dialog.machine, {
    initialFocusEl: () => inputRef.current,
  })

  // ...

  return (
    //...
    <input ref={inputRef} />
    // ...
  )
}
```

To control what receives focus when the dialog closes, pass `finalFocusEl`.

### Dialog vs non-modal dialog

Set `modal` to `false` to allow interaction with content behind the dialog.

```tsx
const service = useMachine(dialog.machine, {
  modal: false,
})
```

### Closing the dialog on interaction outside

By default, the dialog closes when you click its overlay. You can set
`closeOnInteractOutside` to `false` if you want the modal to stay visible.

```tsx {2}
const service = useMachine(dialog.machine, {
  closeOnInteractOutside: false,
})
```

You can also customize the behavior by passing a function to the
`onInteractOutside` callback and calling `event.preventDefault()`.

```tsx {2-7}
const service = useMachine(dialog.machine, {
  onInteractOutside(event) {
    const target = event.target
    if (target?.closest("<selector>")) {
      return event.preventDefault()
    }
  },
})
```

### Listening for open state changes

When the dialog is opened or closed, the `onOpenChange` callback is invoked.

```tsx {2-7}
const service = useMachine(dialog.machine, {
  onOpenChange(details) {
    // details => { open: boolean }
    console.log("open:", details.open)
  },
})
```

### Closing with Escape

Set `closeOnEscape` to `false` if the dialog should not close on `Esc`.

```tsx
const service = useMachine(dialog.machine, {
  closeOnEscape: false,
})
```

### Controlled dialog

To control the dialog's open state, pass the `open` and `onOpenChange`
properties.

```tsx
import { useState } from "react"

export function ControlledDialog() {
  const [open, setOpen] = useState(false)

  const service = useMachine(dialog.machine, {
    open,
    onOpenChange(details) {
      setOpen(details.open)
    },
  })

  return (
    // ...
  )
}
```

### Controlling the scroll behavior

When the dialog is open, it prevents scrolling on the `body` element. To disable
this behavior, set `preventScroll` to `false`.

```tsx {2}
const service = useMachine(dialog.machine, {
  preventScroll: false,
})
```

### Creating an alert dialog

The dialog supports both `dialog` and `alertdialog` roles. It uses `dialog` by
default. Set `role` to `alertdialog` for urgent actions.

That's it! Now you have an alert dialog.

```tsx {2}
const service = useMachine(dialog.machine, {
  role: "alertdialog",
})
```

> By definition, an alert dialog will contain two or more action buttons. We
> recommend setting focus to the least destructive action via `initialFocusEl`.

### Multiple triggers

A single dialog instance can be shared across multiple trigger elements. Pass a
`value` to `getTriggerProps` to identify each trigger.

```tsx
const users = [
  { id: "1", name: "Alice Johnson" },
  { id: "2", name: "Bob Smith" },
]

const service = useMachine(dialog.machine, {
  onTriggerValueChange({ value }) {
    // value is the id of the trigger that activated the dialog
    const user = users.find((u) => u.id === value) ?? null
    setActiveUser(user)
  },
})

const api = dialog.connect(service, normalizeProps)

return (
  <>
    {users.map((user) => (
      <button {...api.getTriggerProps({ value: user.id })}>
        Edit {user.name}
      </button>
    ))}
    {/* single shared dialog */}
    <div {...api.getBackdropProps()} />
    <div {...api.getPositionerProps()}>
      <div {...api.getContentProps()}>{/* ... */}</div>
    </div>
  </>
)
```

When the dialog is open and a different trigger is activated, it switches
without closing. `aria-expanded` is scoped to the active trigger, and focus
returns to the correct trigger on close.

You can also read or set the active trigger programmatically:

```tsx
// Read the active trigger value
api.triggerValue // => string | null

// Set the active trigger value
api.setTriggerValue("2")
```

### Labeling without a visible title

If you do not render a title element, provide `aria-label`.

```tsx
const service = useMachine(dialog.machine, {
  "aria-label": "Delete project",
})
```

## Styling guide

Each part includes a `data-part` attribute you can target in CSS.

```css
[data-part="trigger"] {
  /* styles for the trigger element */
}

[data-part="backdrop"] {
  /* styles for the backdrop element */
}

[data-part="positioner"] {
  /* styles for the positioner element */
}

[data-part="content"] {
  /* styles for the content element */
}

[data-part="title"] {
  /* styles for the title element */
}

[data-part="description"] {
  /* styles for the description element */
}

[data-part="close-trigger"] {
  /* styles for the close trigger element */
}
```

### Open and closed state

The dialog has two states: `open` and `closed`. You can use the `data-state`
attribute to style the dialog or trigger based on its state.

```css
[data-part="content"][data-state="open|closed"] {
  /* styles for the open state */
}

[data-part="trigger"][data-state="open|closed"] {
  /* styles for the open state */
}
```

### Compensating for scrollbar width

When `preventScroll` is enabled, Zag applies `--scrollbar-width` on the root
element. Use this CSS variable to keep fixed or sticky elements aligned when the
dialog opens and body scrolling is locked.

```css
.app-header {
  position: fixed;
  inset-inline-end: calc(1rem + var(--scrollbar-width, 0px));
}
```

### Nested dialogs

When dialogs are nested (a dialog opened from within another dialog), the layer
stack automatically applies data attributes to help create visual hierarchy.

- `data-nested` - Applied to nested dialogs
- `data-has-nested` - Applied to dialogs that have nested dialogs open
- `--nested-layer-count` - CSS variable indicating the number of nested dialogs

```css
/* Scale down parent dialogs when they have nested children */
[data-part="content"][data-has-nested] {
  transform: scale(calc(1 - var(--nested-layer-count) * 0.05));
  transition: transform 0.2s ease-in-out;
}

/* Style nested dialogs differently */
[data-part="content"][data-nested] {
  border: 2px solid var(--accent-color);
}

/* Create depth effect using backdrop opacity */
[data-part="backdrop"][data-has-nested] {
  opacity: calc(0.4 + var(--nested-layer-count) * 0.1);
}
```

## Methods and Properties

### Machine Context

The dialog machine exposes the following context properties:

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the dialog. Useful for composition.

**`trapFocus`**
Type: `boolean | undefined`
Description: Whether to trap focus inside the dialog when it's opened

**`preventScroll`**
Type: `boolean | undefined`
Description: Whether to prevent scrolling behind the dialog when it's opened

**`modal`**
Type: `boolean | undefined`
Description: Whether to prevent pointer interaction outside the element and hide all content below it

**`initialFocusEl`**
Type: `(() => MaybeElement) | undefined`
Description: Element to receive focus when the dialog is opened

**`finalFocusEl`**
Type: `(() => MaybeElement) | undefined`
Description: Element to receive focus when the dialog is closed

**`restoreFocus`**
Type: `boolean | undefined`
Description: Whether to restore focus to the element that had focus before the dialog was opened

**`closeOnInteractOutside`**
Type: `boolean | undefined`
Description: Whether to close the dialog when the outside is clicked

**`closeOnEscape`**
Type: `boolean | undefined`
Description: Whether to close the dialog when the escape key is pressed

**`aria-label`**
Type: `string | undefined`
Description: Human readable label for the dialog, in event the dialog title is not rendered

**`role`**
Type: `"dialog" | "alertdialog" | undefined`
Description: The dialog's role

**`open`**
Type: `boolean | undefined`
Description: The controlled open state of the dialog

**`defaultOpen`**
Type: `boolean | undefined`
Description: The initial open state of the dialog when rendered.
Use when you don't need to control the open state of the dialog.

**`onOpenChange`**
Type: `((details: OpenChangeDetails) => void) | undefined`
Description: Function to call when the dialog's open state changes

**`triggerValue`**
Type: `string | null | undefined`
Description: The controlled active trigger value

**`defaultTriggerValue`**
Type: `string | null | undefined`
Description: The initial active trigger value when rendered.
Use when you don't need to control the active trigger value.

**`onTriggerValueChange`**
Type: `((details: TriggerValueChangeDetails) => void) | undefined`
Description: Function to call when the active trigger changes

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

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

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

### Machine API

The dialog `api` exposes the following methods:

**`open`**
Type: `boolean`
Description: Whether the dialog is open

**`setOpen`**
Type: `(open: boolean) => void`
Description: Function to open or close the dialog

**`triggerValue`**
Type: `string | null`
Description: The active trigger value

**`setTriggerValue`**
Type: `(value: string | null) => void`
Description: Function to set the active trigger value

### Data Attributes

**`Trigger`**

**`data-dialog-trigger`**: <uid>
**`data-value`**: The value of the item
**`data-state`**: "open" | "closed"
**`data-current`**: Present when current

**`Backdrop`**

**`data-dialog-backdrop`**: <uid>
**`data-state`**: "open" | "closed"

**`Content`**

**`data-dialog-content`**: <uid>
**`data-state`**: "open" | "closed"
**`data-nested`**: dialog
**`data-has-nested`**: dialog

### CSS Variables

<CssVarTable name="dialog" />

## Accessibility

Adheres to the
[Alert and Message Dialogs WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog).

### Keyboard Interactions

**`Enter`**
Description: When focus is on the trigger, opens the dialog.

**`Tab`**
Description: Moves focus to the next focusable element within the content. Focus is trapped within the dialog.

**`Shift + Tab`**
Description: Moves focus to the previous focusable element. Focus is trapped within the dialog.

**`Esc`**
Description: Closes the dialog and moves focus to trigger or the defined final focus element

A drawer is a panel that slides up from the bottom of the screen, often used in
mobile applications to present additional content or actions.

## Resources


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



**Features**

- Supports modal and non-modal modes
- Focus is trapped and scrolling is blocked in modal mode
- Supports customizable snap points for partial or full expansion
- Allows dragging to adjust the sheet's height or swipe to dismiss
- Provides screen reader announcements via rendered title
- Pressing `Esc` closes the drawer
- Supports touch gestures for smooth interaction on mobile devices
- Supports multiple triggers sharing a single drawer instance

## Installation

Install the drawer package:

```bash
npm install @zag-js/drawer @zag-js/react
# or
yarn add @zag-js/drawer @zag-js/react
```

## Anatomy

To use the drawer component 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 drawer package:

```tsx
import * as drawer from "@zag-js/drawer"
```

The drawer package exports two key functions:

- `machine` — State machine logic.
- `connect` — Maps machine state to JSX props and event handlers.

> Pass a unique `id` to `useMachine` so generated element ids stay predictable.

Then use the framework integration helpers:

```tsx
import * as drawer from "@zag-js/drawer"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useId } from "react"

export function Drawer() {
  const service = useMachine(drawer.machine, { id: useId() })

  const api = drawer.connect(service, normalizeProps)

  return (
    <>
      <button {...api.getTriggerProps()}>Open Drawer</button>
      <div {...api.getBackdropProps()} />
      <div {...api.getPositionerProps()}>
        <div {...api.getContentProps()}>
          <div {...api.getGrabberProps()}>
            <div {...api.getGrabberIndicatorProps()} />
          </div>
          <div>
            <div {...api.getTitleProps()}>Add New Contact</div>
            <label>
              <span>Name</span>
              <input type="text" />
            </label>
            <label>
              <span>Email</span>
              <input type="email" />
            </label>
            <div>
              <button>Add Contact</button>
              <button onClick={() => api.setOpen(false)}>Cancel</button>
            </div>
          </div>
        </div>
      </div>
    </>
  )
}
```

### Controlled drawer

To control the drawer's open state, pass the `open` and `onOpenChange`
properties.

```tsx
import { useState } from "react"

export function ControlledDrawer() {
  const [open, setOpen] = useState(false)

  const service = useMachine(drawer.machine, {
    open,
    onOpenChange(details) {
      setOpen(details.open)
    },
  })

  return (
    // ...
  )
}
```

### Listening for open state changes

When the drawer state changes, the `onOpenChange` callback is invoked.

```tsx {3-7}
const service = useMachine(drawer.machine, {
  id: useId(),
  onOpenChange(details) {
    // details => { open: boolean }
    console.log("drawer open:", details.open)
  },
})
```

### Configuring snap points

The drawer supports customizable snap points, which determine the heights at
which the sheet can "snap" when dragged. Snap points can be defined as numbers
(representing percentages of the content height, e.g., `0.5` for 50%) or pixel
values (e.g., `"200px"`). By default, it snaps to full sheet height (`1`).

```tsx
const service = useMachine(drawer.machine, {
  id: useId(),
  snapPoints: [0.3, 0.5, 1], // 30%, 50%, and 100% of sheet height
  defaultSnapPoint: 0.5, // Start at 50% height
  onSnapPointChange: ({ snapPoint }) => {
    console.log("Active snap point:", snapPoint)
  },
})
```

### Controlled snap point

Use `snapPoint` and `onSnapPointChange` to control the active snap point.

```tsx
const service = useMachine(drawer.machine, {
  id: useId(),
  snapPoints: [0.3, 0.5, 1],
  snapPoint,
  onSnapPointChange(details) {
    setSnapPoint(details.snapPoint)
  },
})
```

### Swipe-to-dismiss behavior

The drawer can be dismissed by swiping it down quickly or dragging it below a
threshold. Customize this behavior with the following properties:

- `swipeVelocityThreshold`: The minimum velocity (in pixels per second) required
  to dismiss on swipe (default: `700`).
- `closeThreshold`: The percentage of content height below which the sheet
  closes when dragged (default: `0.25`).

```tsx {3-4}
const service = useMachine(drawer.machine, {
  id: useId(),
  swipeVelocityThreshold: 800,
  closeThreshold: 0.3,
})
```

### Choosing swipe direction

Set `swipeDirection` to control where the drawer can be dismissed.

```tsx
const service = useMachine(drawer.machine, {
  id: useId(),
  swipeDirection: "down",
})
```

### Sequential snap points

Set `snapToSequentialPoints` to force dragging through snap points in order.

```tsx
const service = useMachine(drawer.machine, {
  id: useId(),
  snapPoints: [0.25, 0.5, 1],
  snapToSequentialPoints: true,
})
```

### Preventing dragging during scroll

By default, dragging is prevented if the content inside the drawer is scrollable
and not at the top or bottom. To allow dragging even during scrolling, set
`preventDragOnScroll` to `false`:

```tsx {3}
const service = useMachine(drawer.machine, {
  id: useId(),
  preventDragOnScroll: false,
})
```

### Non-modal drawer

Set `modal` to `false` to allow interaction behind the drawer.

```tsx
const service = useMachine(drawer.machine, {
  id: useId(),
  modal: false,
})
```

### Swipe area

Use `getSwipeAreaProps` to render a region outside the drawer that users can
swipe to open it (for example, an edge swipe gesture on mobile). The swipe area
is automatically disabled while the drawer is already open.

```tsx
<div {...api.getSwipeAreaProps()}>
  {/* invisible hit area along the screen edge */}
</div>
```

You can customize the swipe area's direction and disabled state:

```tsx
// Disable the swipe area
api.getSwipeAreaProps({ disabled: true })

// Override the open direction (defaults to opposite of drawer's swipeDirection)
api.getSwipeAreaProps({ swipeDirection: "up" })
```

### Multiple triggers

A single drawer instance can be shared across multiple trigger elements. Pass a
`value` to `getTriggerProps` to identify each trigger.

```tsx
const service = useMachine(drawer.machine, {
  id: useId(),
  onTriggerValueChange({ value }) {
    // value is the id of the trigger that activated the drawer
    console.log("active trigger:", value)
  },
})

const api = drawer.connect(service, normalizeProps)

return (
  <>
    <button {...api.getTriggerProps({ value: "settings" })}>Settings</button>
    <button {...api.getTriggerProps({ value: "profile" })}>Profile</button>
    {/* single shared drawer */}
    <div {...api.getBackdropProps()} />
    <div {...api.getPositionerProps()}>
      <div {...api.getContentProps()}>{/* ... */}</div>
    </div>
  </>
)
```

When the drawer is open and a different trigger is activated, it switches without
closing. Focus returns to the correct trigger on close.

### Content draggable

By default the drawer content itself can be dragged to dismiss or snap. To
restrict dragging to only the grabber, pass `draggable: false` to
`getContentProps`.

```tsx
<div {...api.getContentProps({ draggable: false })}>
  <div {...api.getGrabberProps()}>
    <div {...api.getGrabberIndicatorProps()} />
  </div>
  {/* Content here is not draggable */}
</div>
```

### Using drawer stack

When your app shows multiple drawers that stack on top of each other (with
indent and background effects), use `createStack` and `connectStack` to
coordinate them.

```tsx
import * as drawer from "@zag-js/drawer"

// Create a shared stack (once, at the app level)
const stack = drawer.createStack()
```

Pass the `stack` to each drawer machine:

```tsx
const service = useMachine(drawer.machine, {
  id: useId(),
  stack,
})
```

Subscribe to the stack snapshot and connect it to render indent layers:

```tsx
const snapshot = useSyncExternalStore(stack.subscribe, stack.getSnapshot)
const stackApi = drawer.connectStack(snapshot, normalizeProps)

return (
  <div {...stackApi.getIndentProps()}>
    <div {...stackApi.getIndentBackgroundProps()} />
    {/* drawer instances */}
  </div>
)
```

The indent element exposes `data-active` / `data-inactive` attributes and the
CSS variables `--drawer-swipe-progress` and `--drawer-frontmost-height` for
styling.

### Closing with Escape

Set `closeOnEscape` to `false` if the drawer should not close on `Esc`.

```tsx
const service = useMachine(drawer.machine, {
  id: useId(),
  closeOnEscape: false,
})
```

### Reading drawer state

The `api` provides methods to read the drawer's current position:

- `api.getOpenPercentage()` — returns a value between `0` (fully closed) and `1`
  (fully open at the current snap point).
- `api.getSnapPointIndex()` — returns the index of the active snap point in the
  `snapPoints` array, or `-1` if none matches.
- `api.getContentSize()` — returns the drawer content size in pixels (along the
  swipe axis), or `null` if not yet measured.

```tsx
const percentage = api.getOpenPercentage()
const index = api.getSnapPointIndex()
const size = api.getContentSize()
```

## Styling guide

Each part includes a `data-part` attribute you can target in CSS.

### Open and closed state

The drawer exposes `data-state` attributes you can use for open/closed styles:

```css
[data-part="content"][data-state="open|closed"] {
  /* styles for the content in different states */
}

[data-part="trigger"][data-state="open|closed"] {
  /* styles for the trigger in different states */
}
```

### Swipe and drag state

Target active swipe or drag interactions:

```css
[data-part="content"][data-swiping] {
  /* during any swipe or drag interaction */
}

[data-part="content"][data-dragging] {
  /* during drag only (not swipe-to-open) */
}

[data-part="content"][data-expanded] {
  /* when at the fully expanded snap point */
}

[data-part="content"][data-swipe-direction] {
  /* physical swipe direction: "up" | "down" | "left" | "right" */
}

[data-part="backdrop"][data-swiping] {
  /* backdrop during swipe or drag */
}

[data-part="swipeArea"][data-disabled] {
  /* when swipe area is disabled */
}

[data-part="swipeArea"][data-swipe-direction] {
  /* physical open direction */
}
```

### Animating the drawer

The content element uses
`transform: translate3d(var(--drawer-translate-x, 0px), var(--drawer-translate-y, 0px), 0)`
by default. Reference these variables in your keyframes:

```css
@keyframes slideIn {
  from {
    transform: translate3d(0, 100%, 0);
  }
  to {
    transform: translate3d(
      var(--drawer-translate-x, 0px),
      var(--drawer-translate-y, 0px),
      0
    );
  }
}

@keyframes slideOut {
  from {
    transform: translate3d(
      var(--drawer-translate-x, 0px),
      var(--drawer-translate-y, 0px),
      0
    );
  }
  to {
    transform: translate3d(0, 100%, 0);
  }
}

[data-scope="drawer"][data-part="content"][data-state="open"] {
  animation: slideIn 500ms cubic-bezier(0.32, 0.72, 0, 1);
}

[data-scope="drawer"][data-part="content"][data-state="closed"] {
  animation: slideOut 500ms cubic-bezier(0.32, 0.72, 0, 1);
}
```

### Animation CSS variables

The following CSS variables are set on the content element:

| Variable                       | Description                      |
| ------------------------------ | -------------------------------- |
| `--drawer-translate-x`         | Horizontal translate value       |
| `--drawer-translate-y`         | Vertical translate value         |
| `--drawer-snap-point-offset-x` | Snap point offset on the x-axis  |
| `--drawer-snap-point-offset-y` | Snap point offset on the y-axis  |
| `--drawer-swipe-movement-x`    | Current swipe movement on x-axis |
| `--drawer-swipe-movement-y`    | Current swipe movement on y-axis |
| `--drawer-swipe-strength`      | Numeric swipe strength           |

The following CSS variables are set on the backdrop element:

| Variable                  | Description                                     |
| ------------------------- | ----------------------------------------------- |
| `--drawer-swipe-progress` | 0-1 progress value, useful for backdrop opacity |
| `--drawer-swipe-strength` | Numeric swipe strength                          |

## Methods and Properties

The drawer's `api` exposes the following methods and properties:

### Machine Context

The drawer machine exposes the following context properties:

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the drawer. Useful for composition.

**`trapFocus`**
Type: `boolean | undefined`
Description: Whether to trap focus inside the sheet when it's opened.

**`preventScroll`**
Type: `boolean | undefined`
Description: Whether to prevent scrolling behind the sheet when it's opened

**`modal`**
Type: `boolean | undefined`
Description: Whether to prevent pointer interaction outside the element and hide all content below it.

**`initialFocusEl`**
Type: `(() => MaybeElement) | undefined`
Description: Element to receive focus when the sheet is opened.

**`finalFocusEl`**
Type: `(() => MaybeElement) | undefined`
Description: Element to receive focus when the sheet is closed.

**`restoreFocus`**
Type: `boolean | undefined`
Description: Whether to restore focus to the element that had focus before the sheet was opened.

**`role`**
Type: `"dialog" | "alertdialog" | undefined`
Description: The sheet's role

**`triggerValue`**
Type: `string | null | undefined`
Description: The value of the trigger that currently controls the drawer.

**`defaultTriggerValue`**
Type: `string | null | undefined`
Description: The default trigger value (uncontrolled).

**`onTriggerValueChange`**
Type: `((details: TriggerValueChangeDetails) => void) | undefined`
Description: Callback when the active trigger value changes.

**`open`**
Type: `boolean | undefined`
Description: Whether the drawer is open.

**`defaultOpen`**
Type: `boolean | undefined`
Description: The initial open state of the drawer.

**`onOpenChange`**
Type: `((details: OpenChangeDetails) => void) | undefined`
Description: Function called when the open state changes.

**`closeOnInteractOutside`**
Type: `boolean | undefined`
Description: Whether to close the drawer when the outside is clicked.

**`closeOnEscape`**
Type: `boolean | undefined`
Description: Whether to close the drawer when the escape key is pressed.

**`snapPoints`**
Type: `SnapPoint[] | undefined`
Description: The snap points of the drawer.
Array of numbers or strings representing the snap points.

**`swipeDirection`**
Type: `SwipeDirection | undefined`
Description: The direction in which the drawer can be swiped.

**`snapToSequentialPoints`**
Type: `boolean | undefined`
Description: Whether the drawer should snap to sequential points when swiping.

**`swipeVelocityThreshold`**
Type: `number | undefined`
Description: The threshold velocity (in pixels/s) for closing the drawer.

**`closeThreshold`**
Type: `number | undefined`
Description: The threshold distance for dismissing the drawer.

**`preventDragOnScroll`**
Type: `boolean | undefined`
Description: Whether to prevent dragging on scrollable elements.
When enabled, the sheet will not start dragging if the user is interacting with a scrollable element.

**`snapPoint`**
Type: `SnapPoint | null | undefined`
Description: The currently active snap point.

**`defaultSnapPoint`**
Type: `SnapPoint | null | undefined`
Description: The default snap point of the drawer.

**`onSnapPointChange`**
Type: `((details: SnapPointChangeDetails) => void) | undefined`
Description: Callback fired when the snap point changes.

**`stack`**
Type: `DrawerStack | undefined`
Description: Optional external store for coordinating app-level drawer stack visuals
(e.g. indent and background layers).

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

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

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

### Machine API

The drawer `api` exposes the following methods:

**`open`**
Type: `boolean`
Description: Whether the drawer is open.

**`dragging`**
Type: `boolean`
Description: Whether the drawer is currently being dragged.

**`triggerValue`**
Type: `string | null`
Description: The value of the active trigger.

**`setTriggerValue`**
Type: `(value: string | null) => void`
Description: Set the active trigger value.

**`setOpen`**
Type: `(open: boolean) => void`
Description: Function to open or close the menu.

**`snapPoints`**
Type: `SnapPoint[]`
Description: The snap points of the drawer.

**`swipeDirection`**
Type: `SwipeDirection`
Description: The swipe direction of the drawer.

**`snapPoint`**
Type: `SnapPoint | null`
Description: The currently active snap point.

**`setSnapPoint`**
Type: `(snapPoint: SnapPoint | null) => void`
Description: Function to set the active snap point.

**`getOpenPercentage`**
Type: `() => number`
Description: Get the current open percentage of the drawer.

**`getSnapPointIndex`**
Type: `() => number`
Description: Get the index of the currently active snap point.

**`getContentSize`**
Type: `() => number | null`
Description: Get the current main-axis size of the drawer content.

### Data Attributes

**`Positioner`**

**`data-drawer-positioner`**: <uid>
**`data-state`**: "open" | "closed"
**`data-swipe-direction`**: 

**`Content`**

**`data-drawer-content`**: <uid>
**`data-state`**: "open" | "closed"
**`data-expanded`**: Present when expanded
**`data-swipe-direction`**: 
**`data-swiping`**: 
**`data-dragging`**: Present when in the dragging state
**`data-nested-drawer-open`**: 
**`data-nested-drawer-swiping`**: 

**`Trigger`**

**`data-drawer-trigger`**: <uid>
**`data-value`**: The value of the item
**`data-state`**: "open" | "closed"
**`data-current`**: Present when current

**`Backdrop`**

**`data-drawer-backdrop`**: <uid>
**`data-state`**: "open" | "closed"
**`data-swiping`**: 

**`SwipeArea`**

**`data-drawer-swipe-area`**: <uid>
**`data-state`**: "open" | "closed"
**`data-swiping`**: 
**`data-swipe-direction`**: 
**`data-disabled`**: Present when disabled

### CSS Variables

<CssVarTable name="drawer" />

Editable is an input field used for editing a single line of text. It renders as
static text and transforms into a text input field when the edit interaction is
triggered (click, focus, or double-click).

## Resources


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



**Features**

- Use custom controls for the editable
- Pressing `Enter` commits the input value
- Pressing `Esc` reverts the value
- Activate edit mode by double-clicking or focusing on the preview text
- Auto-resize input to fit content

## Installation

Install the editable package:

```bash
npm install @zag-js/editable @zag-js/react
# or
yarn add @zag-js/editable @zag-js/react
```

## Anatomy

Check the editable anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the editable package:

```tsx
import * as editable from "@zag-js/editable"
```

The editable package exports two key functions:

- `machine` - Behavior logic for the editable.
- `connect` - Maps behavior to JSX props and event handlers.

> Pass a unique `id` to `useMachine` so generated element ids stay predictable.

Then use the framework integration helpers:

```tsx
import * as editable from "@zag-js/editable"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useId } from "react"

export default function Editable() {
  const service = useMachine(editable.machine, { id: useId() })

  const api = editable.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <div {...api.getAreaProps()}>
        <input {...api.getInputProps()} />
        <span {...api.getPreviewProps()} />
      </div>
    </div>
  )
}
```

### Setting the initial value

Set `defaultValue` to define the initial value.

```tsx {2}
const service = useMachine(editable.machine, {
  defaultValue: "Hello World",
})
```

### Controlled value

Use `value` and `onValueChange` to control the value externally.

```tsx
const service = useMachine(editable.machine, {
  value,
  onValueChange(details) {
    setValue(details.value)
  },
})
```

### Controlled edit state

Use `edit` and `onEditChange` to control whether the field is in edit mode.

```tsx
const service = useMachine(editable.machine, {
  edit,
  onEditChange(details) {
    setEdit(details.edit)
  },
})
```

### Listening for value changes

Editable supports two ways of listening for value changes:

- `onValueChange`: called when value changes.
- `onValueCommit`: called when the value is committed.

```tsx {2-4}
const service = useMachine(editable.machine, {
  onValueChange(details) {
    console.log("Value changed", details.value)
  },
  onValueCommit(details) {
    console.log("Value submitted", details.value)
  },
})
```

### Listening for revert events

Use `onValueRevert` to react when a user cancels editing.

```tsx
const service = useMachine(editable.machine, {
  onValueRevert(details) {
    console.log("Value reverted", details.value)
  },
})
```

### Using custom controls

In some cases, you might need to use custom controls to toggle the edit and read
mode. We use the render prop pattern to provide access to the internal state of
the component.

```tsx
import * as editable from "@zag-js/editable"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useId } from "react"

export default function Editable() {
  const service = useMachine(editable.machine, { id: useId() })

  const api = editable.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <div {...api.getAreaProps()}>
        <input {...api.getInputProps()} />
        <span {...api.getPreviewProps()} />
      </div>
      <div>
        {!api.editing && <button {...api.getEditTriggerProps()}>Edit</button>}
        {api.editing && (
          <div>
            <button {...api.getSubmitTriggerProps()}>Save</button>
            <button {...api.getCancelTriggerProps()}>Cancel</button>
          </div>
        )}
      </div>
    </div>
  )
}
```

### Auto-resizing

Set `autoResize` to `true` to auto-grow the editable as content changes.

```tsx {2}
const service = useMachine(editable.machine, {
  autoResize: true,
})
```

When using autoresize, the input and preview elements should not have any
styles. Use `all: unset` if needed and pass any styles to the "area" element
since it's shared by the input and preview elements.

### Setting a maxWidth

It is common to set a max width when auto-resizing.

```tsx {2-3}
const service = useMachine(editable.machine, {
  autoResize: true,
  maxWidth: "320px",
})
```

When the editable reaches the specified max-width, it'll clip the preview text
with an ellipsis.

### Editing with double click

The editable supports two modes of activating the "edit" state:

- when the preview part is focused (with pointer or keyboard).
- when the preview part is double-clicked.

Set `activationMode` to `"dblclick"` to only enter edit mode on double click.

```tsx {2}
const service = useMachine(editable.machine, {
  activationMode: "dblclick",
})
```

### Customizing submit behavior

Use `submitMode` to control when edits are committed.

```tsx
const service = useMachine(editable.machine, {
  submitMode: "enter", // "enter" | "blur" | "both" | "none"
})
```

### Usage with Textarea

Editable supports using a `textarea` instead of an `input` field. When a
textarea is used, the editable will commit the value on `Cmd + Enter` or
`Ctrl + Enter`.

> Use `api.getInputProps()` to spread input props to the textarea. You might
> need to cast the input props to the correct type.

```tsx {2}
<textarea
  {...(api.getInputProps() as HTMLTextareaProps<HTMLTextareaElement>)}
/>
```

### Customizing placeholder text

Set `placeholder` as a string or per-mode object.

```tsx
const service = useMachine(editable.machine, {
  placeholder: {
    preview: "Click to edit",
    edit: "Type a value",
  },
})
```

### Customizing accessibility labels

Use `translations` to customize control labels.

```tsx
const service = useMachine(editable.machine, {
  translations: {
    edit: "Edit value",
    submit: "Save",
    cancel: "Cancel",
    input: "Editable input",
  },
})
```

### Submitting with an external form

Set `form` if the hidden input should submit with a form outside the current DOM
subtree.

```tsx
const service = useMachine(editable.machine, {
  name: "value",
  form: "checkout-form",
})
```

## Styling guide

Each part includes a `data-part` attribute you can target in CSS.

### Focused state

When the editable is in the focused mode, we set a `data-focus` attribute on the
"area" part.

```css
[data-part="area"][data-focus] {
  /* CSS for the editable's focus state */
}
```

### Empty state

When the editable's value is empty, we set a `data-empty` attribute on the
"area" part.

```css
[data-part="area"][data-empty] {
  /* CSS for the editable's focus state */
}
```

### Disabled state

When the editable is disabled, we set a `data-disabled` attribute on the "area"
part.

```css
[data-part="area"][data-disabled] {
  /* CSS for the editable's focus state */
}
```

## Methods and Properties

### Machine Context

The editable machine exposes the following context properties:

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the editable. Useful for composition.

**`invalid`**
Type: `boolean | undefined`
Description: Whether the input's value is invalid.

**`name`**
Type: `string | undefined`
Description: The name attribute of the editable component. Used for form submission.

**`form`**
Type: `string | undefined`
Description: The associate form of the underlying input.

**`autoResize`**
Type: `boolean | undefined`
Description: Whether the editable should auto-resize to fit the content.

**`activationMode`**
Type: `ActivationMode | undefined`
Description: The activation mode for the preview element.

- "focus" - Enter edit mode when the preview is focused
- "dblclick" - Enter edit mode when the preview is double-clicked
- "click" - Enter edit mode when the preview is clicked
- "none" - Edit can be triggered programmatically only

**`submitMode`**
Type: `SubmitMode | undefined`
Description: The action that triggers submit in the edit mode:

- "enter" - Trigger submit when the enter key is pressed
- "blur" - Trigger submit when the editable is blurred
- "none" - No action will trigger submit. You need to use the submit button
- "both" - Pressing `Enter` and blurring the input will trigger submit

**`selectOnFocus`**
Type: `boolean | undefined`
Description: Whether to select the text in the input when it is focused.

**`edit`**
Type: `boolean | undefined`
Description: Whether the editable is in edit mode.

**`defaultEdit`**
Type: `boolean | undefined`
Description: Whether the editable is in edit mode by default.

**`onEditChange`**
Type: `((details: EditChangeDetails) => void) | undefined`
Description: Function to call when the edit mode changes.

**`maxLength`**
Type: `number | undefined`
Description: The maximum number of characters allowed in the editable

**`disabled`**
Type: `boolean | undefined`
Description: Whether the editable is disabled.

**`readOnly`**
Type: `boolean | undefined`
Description: Whether the editable is read-only.

**`required`**
Type: `boolean | undefined`
Description: Whether the editable is required.

**`placeholder`**
Type: `string | { edit: string; preview: string } | undefined`
Description: The placeholder text for the editable.

**`translations`**
Type: `IntlTranslations | undefined`
Description: The translations for the editable.

**`finalFocusEl`**
Type: `(() => HTMLElement | null) | undefined`
Description: The element to receive focus when the editable is closed.

**`value`**
Type: `string | undefined`
Description: The controlled value of the editable.

**`defaultValue`**
Type: `string | undefined`
Description: The initial value of the editable when rendered.
Use when you don't need to control the value of the editable.

**`onValueChange`**
Type: `((details: ValueChangeDetails) => void) | undefined`
Description: Function to call when the value changes.

**`onValueRevert`**
Type: `((details: ValueChangeDetails) => void) | undefined`
Description: Function to call when the value is reverted.

**`onValueCommit`**
Type: `((details: ValueChangeDetails) => void) | undefined`
Description: Function to call when the value is committed.

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

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

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

**`onPointerDownOutside`**
Type: `((event: PointerDownOutsideEvent) => void) | undefined`
Description: Function called when the pointer is pressed down outside the component

**`onFocusOutside`**
Type: `((event: FocusOutsideEvent) => void) | undefined`
Description: Function called when the focus is moved outside the component

**`onInteractOutside`**
Type: `((event: InteractOutsideEvent) => void) | undefined`
Description: Function called when an interaction happens outside the component

### Machine API

The editable `api` exposes the following methods:

**`editing`**
Type: `boolean`
Description: Whether the editable is in edit mode

**`empty`**
Type: `boolean`
Description: Whether the editable value is empty

**`value`**
Type: `string`
Description: The current value of the editable

**`valueText`**
Type: `string`
Description: The current value of the editable, or the placeholder if the value is empty

**`setValue`**
Type: `(value: string) => void`
Description: Function to set the value of the editable

**`clearValue`**
Type: `VoidFunction`
Description: Function to clear the value of the editable

**`edit`**
Type: `VoidFunction`
Description: Function to enter edit mode

**`cancel`**
Type: `VoidFunction`
Description: Function to exit edit mode, and discard any changes

**`submit`**
Type: `VoidFunction`
Description: Function to exit edit mode, and submit any changes

### Data Attributes

**`Area`**

**`data-editable-area`**: <uid>
**`data-focus`**: Present when focused
**`data-disabled`**: Present when disabled
**`data-placeholder-shown`**: Present when placeholder is shown

**`Label`**

**`data-editable-label`**: <uid>
**`data-focus`**: Present when focused
**`data-invalid`**: Present when invalid
**`data-required`**: Present when required

**`Input`**

**`data-editable-input`**: <uid>
**`data-disabled`**: Present when disabled
**`data-readonly`**: Present when read-only
**`data-invalid`**: Present when invalid
**`data-autoresize`**: 

**`Preview`**

**`data-editable-preview`**: <uid>
**`data-placeholder-shown`**: Present when placeholder is shown
**`data-readonly`**: Present when read-only
**`data-disabled`**: Present when disabled
**`data-invalid`**: Present when invalid
**`data-autoresize`**: 

## Accessibility

### Keyboard Interactions

**`Enter`**
Description: Saves the edited content and exits edit mode.

**`Escape`**
Description: Discards the changes and exits edit mode.

A file upload component lets users select and manage files.

The native input file element is quite difficult to style and doesn't provide a
drag-n-drop version.

> The file upload component doesn't handle the actual file uploading process. It
> only handles the UI and the state of the file upload.

## Resources


[Latest version: v2.0.0-next.1](https://www.npmjs.com/package/@zag-js/file-upload)
[Logic Visualizer](https://zag-visualizer.vercel.app/file-upload)
[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/file-upload)



**Features**

- Supports a button to open the file dialog
- Supports drag and drop to upload files
- Set the maximum number of files that can be uploaded
- Set the maximum size of the files that can be uploaded
- Set the accepted file types

## Installation

Install the file upload package:

```bash
npm install @zag-js/file-upload @zag-js/react
# or
yarn add @zag-js/file-upload @zag-js/react
```

## Anatomy

To set up the file upload 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 file upload package:

```tsx
import * as fileUpload from "@zag-js/file-upload"
```

The file upload package exports two key functions:

- `machine` - Behavior logic.
- `connect` - Maps behavior to JSX props and event handlers.

Then use the framework integration helpers:

```tsx
import * as fileUpload from "@zag-js/file-upload"
import { normalizeProps, useMachine } from "@zag-js/react"
import { useId } from "react"

export function FileUpload() {
  const service = useMachine(fileUpload.machine, {
    id: useId(),
  })

  const api = fileUpload.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <div {...api.getDropzoneProps()}>
        <input {...api.getHiddenInputProps()} />
        <span>Drag your file(s) here</span>
      </div>

      <button {...api.getTriggerProps()}>Choose file(s)</button>

      <ul {...api.getItemGroupProps()}>
        {api.acceptedFiles.map((file) => (
          <li key={file.name} {...api.getItemProps({ file })}>
            <div {...api.getItemNameProps({ file })}>{file.name}</div>
            <button {...api.getItemDeleteTriggerProps({ file })}>Delete</button>
          </li>
        ))}
      </ul>
    </div>
  )
}
```

### Setting the accepted file types

Use the `accept` attribute to set the accepted file types.

```tsx
const service = useMachine(fileUpload.machine, {
  accept: "image/*",
})
```

Alternatively, you can provide an object with a MIME type and an array of file
extensions.

```tsx
const service = useMachine(fileUpload.machine, {
  accept: {
    "image/png": [".png"],
    "text/html": [".html", ".htm"],
  },
})
```

### Setting the maximum number of files

Use `maxFiles` to set how many files can be selected.

```tsx
const service = useMachine(fileUpload.machine, {
  maxFiles: 5,
})
```

### Setting the minimum size per file

Use `minFileSize` to reject files smaller than a minimum size.

```tsx
const service = useMachine(fileUpload.machine, {
  minFileSize: 1024, // 1KB
})
```

### Setting the maximum size per file

Use the `maxFileSize` attribute to set the maximum size per file that can be
uploaded.

```tsx
const service = useMachine(fileUpload.machine, {
  maxFileSize: 1024 * 1024 * 10, // 10MB
})
```

### Setting initial files

Use `defaultAcceptedFiles` to prefill the accepted files list.

```tsx
const service = useMachine(fileUpload.machine, {
  defaultAcceptedFiles: [
    new File(["hello"], "hello.txt", { type: "text/plain" }),
  ],
})
```

### Controlled files

Use `acceptedFiles` and `onFileChange` to control accepted files externally.

```tsx
const service = useMachine(fileUpload.machine, {
  acceptedFiles,
  onFileChange(details) {
    setAcceptedFiles(details.acceptedFiles)
  },
})
```

### Listening to file changes

When files are uploaded, the `onFileChange` callback is invoked with the details
of the accepted and rejected files.

```tsx
const service = useMachine(fileUpload.machine, {
  onFileChange(details) {
    // details => { acceptedFiles: File[], rejectedFiles: { file: File, errors: FileError[] }[] }
    console.log(details.acceptedFiles)
    console.log(details.rejectedFiles)
  },
})
```

### Listening to accept and reject events

Use `onFileAccept` and `onFileReject` for separated success/failure flows.

```tsx
const service = useMachine(fileUpload.machine, {
  onFileAccept(details) {
    console.log("Accepted:", details.files)
  },
  onFileReject(details) {
    console.log("Rejected:", details.files)
  },
})
```

### Usage within a form

To use file upload in a form, set `name` and render `api.getHiddenInputProps()`.

```tsx
const service = useMachine(fileUpload.machine, {
  name: "avatar",
})
```

```tsx
<input {...api.getHiddenInputProps()} />
```

### Displaying image preview

To display a preview of the uploaded image, use the built-in FileReader API to
read the file and set the `src` attribute of an image element.

```tsx
const service = useMachine(fileUpload.machine, {
  onFileChange(details) {
    const reader = new FileReader()
    reader.onload = (event) => {
      const image = event.target.result
      // set the image as the src of an image element
    }
    reader.readAsDataURL(details.acceptedFiles[0])
  },
})
```

### Applying custom validation

To apply custom validation, set `validate` to a function that returns an **array
of error strings**.

The returned array can contain any string as an error message. While zagjs
supports default errors such as `TOO_MANY_FILES`, `FILE_INVALID_TYPE`,
`FILE_TOO_LARGE`, or `FILE_TOO_SMALL`, you can return any string that represents
your custom validation errors.

> Return `null` if no validation errors are detected.

```tsx
const service = useMachine(fileUpload.machine, {
  validate(file, details) {
    // Check if file size exceeds 10MB
    if (file.size > 1024 * 1024 * 10) {
      return ["FILE_TOO_LARGE"]
    }
    // details => { acceptedFiles, rejectedFiles }
    console.log(details.acceptedFiles.length)
    return null
  },
})
```

Apply multiple validation errors:

```js
const service = useMachine(fileUpload.machine, {
  validate(file, details) {
    const errors = []

    // Check file size
    if (file.size > 10 * 1024 * 1024) {
      errors.push("FILE_TOO_LARGE") // Default error enum
    }

    // Ensure file is a PDF
    if (!file.name.endsWith(".pdf")) {
      errors.push("ONLY_PDF_ALLOWED") // Custom error
    }

    // Custom check: Reject duplicate files
    const isDuplicate = details.acceptedFiles.some(
      (acceptedFile) => acceptedFile.name === file.name,
    )
    if (isDuplicate) {
      errors.push("FILE_EXISTS")
    }

    return errors.length > 0 ? errors : null
  },
})
```

### Disabling drag and drop

Set `allowDrop` to `false` to disable drag and drop.

```tsx
const service = useMachine(fileUpload.machine, {
  allowDrop: false,
})
```

### Preventing document-level drop

Set `preventDocumentDrop` to `false` if you do not want this component to block
file drops outside the dropzone.

```tsx
const service = useMachine(fileUpload.machine, {
  preventDocumentDrop: false,
})
```

### Read-only mode

Set `readOnly` to prevent adding or removing files.

```tsx
const service = useMachine(fileUpload.machine, {
  readOnly: true,
})
```

### Allowing directory selection

Set the `directory` property to `true` to enable selecting directories instead
of files.

This maps to the native input `webkitdirectory` HTML attribute and allows users
to select directories and their contents.

> Please note that support for this feature varies from browser to browser.

```tsx
const service = useMachine(fileUpload.machine, {
  directory: true,
})
```

### Supporting media capture on mobile devices

Set the `capture` property to specify the media capture mechanism to capture
media on the spot. The value can be:

- `user` for capturing media from the user-facing camera
- `environment` for the outward-facing camera

> This behavior only works on mobile devices. On desktop devices, it will open
> the file system like normal.

```tsx
const service = useMachine(fileUpload.machine, {
  capture: "user",
})
```

### Pasting files from clipboard

After a user copies an image, to allow pasting the files from the clipboard, you
can listen for the paste event and use the `api.setFiles` method to set the
files.

Here's an example of how to do this in React.

```tsx
function Demo() {
  const service = useMachine(fileUpload.machine, {
    accept: "image/*",
  })

  const api = fileUpload.connect(service, normalizeProps)

  return (
    <textarea
      onPaste={(event) => {
        if (event.clipboardData?.files) {
          api.setFiles(Array.from(event.clipboardData.files))
        }
      }}
    />
  )
}
```

### Transforming files before acceptance

Use the `transformFiles` callback to process files before they're added to
`acceptedFiles`. This is useful for scenarios like image cropping, compression,
or format conversion.

The `transformFiles` function receives the selected files and should return a
promise that resolves with the transformed files.

```tsx
const service = useMachine(fileUpload.machine, {
  accept: "image/*",
  transformFiles: async (files) => {
    return Promise.all(
      files.map(async (file) => {
        // Compress or transform the file
        const transformedBlob = await processImage(file)
        return new File([transformedBlob], file.name, { type: file.type })
      }),
    )
  },
})
```

While files are being transformed, the `api.transforming` boolean is `true`,
allowing you to show loading states in your UI.

### Customizing accessibility labels

Use `translations` to customize dropzone and item action labels.

```tsx
const service = useMachine(fileUpload.machine, {
  translations: {
    dropzone: "Drop files here",
    deleteFile: (file) => `Remove ${file.name}`,
  },
})
```

## Styling guide

Each part includes a `data-part` attribute you can target in CSS.

```css
[data-part="root"] {
  /* styles for root element*/
}

[data-part="dropzone"] {
  /* styles for root element*/
}

[data-part="trigger"] {
  /* styles for file picker trigger */
}

[data-part="label"] {
  /* styles for the input's label */
}
```

### Dragging State

When the user drags a file over the file upload, the `data-dragging` attribute
is added to the `root` and `dropzone` parts.

```css
[data-part="root"][data-dragging] {
  /* styles for when the user is dragging a file over the file upload */
}

[data-part="dropzone"][data-dragging] {
  /* styles for when the user is dragging a file over the file upload */
}
```

### Disabled State

When the file upload is disabled, the `data-disabled` attribute is added to the
component parts.

```css
[data-part="root"][data-disabled] {
  /* styles for when the file upload is disabled */
}

[data-part="dropzone"][data-disabled] {
  /* styles for when the file upload is disabled */
}

[data-part="trigger"][data-disabled] {
  /* styles for when the file upload is disabled */
}

[data-part="label"][data-disabled] {
  /* styles for when the file upload is disabled */
}
```

## Methods and Properties

### Machine Context

The file upload machine exposes the following context properties:

**`name`**
Type: `string | undefined`
Description: The name of the underlying file input

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements. Useful for composition.

**`translations`**
Type: `IntlTranslations | undefined`
Description: The localized messages to use.

**`accept`**
Type: `Record<string, string[]> | FileMimeType | FileMimeType[] | undefined`
Description: The accept file types

**`disabled`**
Type: `boolean | undefined`
Description: Whether the file input is disabled

**`required`**
Type: `boolean | undefined`
Description: Whether the file input is required

**`allowDrop`**
Type: `boolean | undefined`
Description: Whether to allow drag and drop in the dropzone element

**`maxFileSize`**
Type: `number | undefined`
Description: The maximum file size in bytes

**`minFileSize`**
Type: `number | undefined`
Description: The minimum file size in bytes

**`maxFiles`**
Type: `number | undefined`
Description: The maximum number of files

**`preventDocumentDrop`**
Type: `boolean | undefined`
Description: Whether to prevent the drop event on the document

**`validate`**
Type: `((file: File, details: FileValidateDetails) => FileError[] | null) | undefined`
Description: Function to validate a file

**`defaultAcceptedFiles`**
Type: `File[] | undefined`
Description: The default accepted files when rendered.
Use when you don't need to control the accepted files of the input.

**`acceptedFiles`**
Type: `File[] | undefined`
Description: The controlled accepted files

**`onFileChange`**
Type: `((details: FileChangeDetails) => void) | undefined`
Description: Function called when the value changes, whether accepted or rejected

**`onFileAccept`**
Type: `((details: FileAcceptDetails) => void) | undefined`
Description: Function called when the file is accepted

**`onFileReject`**
Type: `((details: FileRejectDetails) => void) | undefined`
Description: Function called when the file is rejected

**`capture`**
Type: `"user" | "environment" | undefined`
Description: The default camera to use when capturing media

**`directory`**
Type: `boolean | undefined`
Description: Whether to accept directories, only works in webkit browsers

**`invalid`**
Type: `boolean | undefined`
Description: Whether the file input is invalid

**`readOnly`**
Type: `boolean | undefined`
Description: Whether the file input is read-only

**`transformFiles`**
Type: `((files: File[]) => Promise<File[]>) | undefined`
Description: Function to transform the accepted files to apply transformations

**`locale`**
Type: `string | undefined`
Description: The current locale. Based on the BCP 47 definition.

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

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

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

### Machine API

The file upload `api` exposes the following methods:

**`dragging`**
Type: `boolean`
Description: Whether the user is dragging something over the root element

**`focused`**
Type: `boolean`
Description: Whether the user is focused on the dropzone element

**`disabled`**
Type: `boolean`
Description: Whether the file input is disabled

**`readOnly`**
Type: `boolean`
Description: Whether the file input is in read-only mode

**`transforming`**
Type: `boolean`
Description: Whether files are currently being transformed via `transformFiles`

**`maxFilesReached`**
Type: `boolean`
Description: Whether the maximum number of files has been reached

**`remainingFiles`**
Type: `number`
Description: The number of files that can still be added

**`openFilePicker`**
Type: `VoidFunction`
Description: Function to open the file dialog

**`deleteFile`**
Type: `(file: File, type?: ItemType | undefined) => void`
Description: Function to delete the file from the list

**`acceptedFiles`**
Type: `File[]`
Description: The accepted files that have been dropped or selected

**`rejectedFiles`**
Type: `FileRejection[]`
Description: The files that have been rejected

**`setFiles`**
Type: `(files: File[]) => void`
Description: Sets the accepted files

**`clearFiles`**
Type: `VoidFunction`
Description: Clears the accepted files

**`clearRejectedFiles`**
Type: `VoidFunction`
Description: Clears the rejected files

**`getFileSize`**
Type: `(file: File) => string`
Description: Returns the formatted file size (e.g. 1.2MB)

**`createFileUrl`**
Type: `(file: File, cb: (url: string) => void) => VoidFunction`
Description: Returns the preview url of a file.
Returns a function to revoke the url.

**`setClipboardFiles`**
Type: `(dt: DataTransfer | null) => boolean`
Description: Sets the clipboard files
Returns `true` if the clipboard data contains files, `false` otherwise.

### Data Attributes

**`Root`**

**`data-file-upload-root`**: <uid>
**`data-disabled`**: Present when disabled
**`data-readonly`**: Present when read-only
**`data-dragging`**: Present when in the dragging state

**`Dropzone`**

**`data-file-upload-dropzone`**: <uid>
**`data-invalid`**: Present when invalid
**`data-disabled`**: Present when disabled
**`data-readonly`**: Present when read-only
**`data-dragging`**: Present when in the dragging state

**`Trigger`**

**`data-file-upload-trigger`**: <uid>
**`data-disabled`**: Present when disabled
**`data-readonly`**: Present when read-only
**`data-invalid`**: Present when invalid

**`ItemGroup`**

**`data-file-upload-item-group`**: <uid>
**`data-disabled`**: Present when disabled
**`data-type`**: The type of the item

**`Item`**

**`data-file-upload-item`**: <uid>
**`data-disabled`**: Present when disabled
**`data-type`**: The type of the item

**`ItemName`**

**`data-file-upload-item-name`**: <uid>
**`data-disabled`**: Present when disabled
**`data-type`**: The type of the item

**`ItemSizeText`**

**`data-file-upload-item-size-text`**: <uid>
**`data-disabled`**: Present when disabled
**`data-type`**: The type of the item

**`ItemPreview`**

**`data-file-upload-item-preview`**: <uid>
**`data-disabled`**: Present when disabled
**`data-type`**: The type of the item

**`ItemPreviewImage`**

**`data-file-upload-item-preview-image`**: <uid>
**`data-disabled`**: Present when disabled
**`data-type`**: The type of the item

**`ItemDeleteTrigger`**

**`data-file-upload-item-delete-trigger`**: <uid>
**`data-disabled`**: Present when disabled
**`data-readonly`**: Present when read-only
**`data-type`**: The type of the item

**`Label`**

**`data-file-upload-label`**: <uid>
**`data-disabled`**: Present when disabled
**`data-required`**: Present when required

**`ClearTrigger`**

**`data-file-upload-clear-trigger`**: <uid>
**`data-disabled`**: Present when disabled
**`data-readonly`**: Present when read-only

A floating panel is a detachable window that floats above the main interface,
typically used for displaying and editing properties. The panel can be dragged,
resized, and positioned anywhere on the screen for optimal workflow.

> Think of the panel that pops up in Figma when you click `variables` or try to
> set a color.

## Resources


[Latest version: v]()
[Logic Visualizer](https://zag-visualizer.vercel.app/floating-panel)
[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/floating-panel)



**Features**

- Allows interaction with the main content
- Supports dragging and resizing
- Supports minimizing and maximizing the panel
- Controlled and uncontrolled size and position
- Supports snapping to a grid
- Supports locking the aspect ratio
- Supports closing on escape key
- Supports persisting size and position when closed

## Installation

Install the floating panel package:

```bash
npm install @zag-js/floating-panel @zag-js/react
# or
yarn add @zag-js/floating-panel @zag-js/react
```

## Anatomy

Check the floating panel anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the floating panel package:

```tsx
import * as floatingPanel from "@zag-js/floating-panel"
```

These are the key exports:

- `machine` - State machine logic.
- `connect` - Maps behavior to JSX props and event handlers.

Then use the framework integration helpers:

```tsx
import * as floatingPanel from "@zag-js/floating-panel"
import { useMachine, normalizeProps } from "@zag-js/react"
import { ArrowDownLeft, Maximize2, Minus, XIcon } from "lucide-react"
import { useId } from "react"

function FloatingPanel() {
  const service = useMachine(floatingPanel.machine, { id: useId() })

  const api = floatingPanel.connect(service, normalizeProps)

  return (
    <>
      <button {...api.getTriggerProps()}>Toggle Panel</button>
      <div {...api.getPositionerProps()}>
        <div {...api.getContentProps()}>
          <div {...api.getDragTriggerProps()}>
            <div {...api.getHeaderProps()}>
              <p {...api.getTitleProps()}>Floating Panel</p>
              <div {...api.getControlProps()}>
                <button {...api.getStageTriggerProps({ stage: "minimized" })}>
                  <Minus />
                </button>
                <button {...api.getStageTriggerProps({ stage: "maximized" })}>
                  <Maximize2 />
                </button>
                <button {...api.getStageTriggerProps({ stage: "default" })}>
                  <ArrowDownLeft />
                </button>
                <button {...api.getCloseTriggerProps()}>
                  <XIcon />
                </button>
              </div>
            </div>
          </div>
          <div {...api.getBodyProps()}>
            <p>Some content</p>
          </div>

          <div {...api.getResizeTriggerProps({ placement: "n" })} />
          <div {...api.getResizeTriggerProps({ placement: "e" })} />
          <div {...api.getResizeTriggerProps({ placement: "w" })} />
          <div {...api.getResizeTriggerProps({ placement: "s" })} />
          <div {...api.getResizeTriggerProps({ placement: "ne" })} />
          <div {...api.getResizeTriggerProps({ placement: "se" })} />
          <div {...api.getResizeTriggerProps({ placement: "sw" })} />
          <div {...api.getResizeTriggerProps({ placement: "nw" })} />
        </div>
      </div>
    </>
  )
}
```

### Resizing

#### Setting the initial size

To set the initial size of the floating panel, you can pass the `defaultSize`
prop to the machine.

```tsx {2}
const service = useMachine(floatingPanel.machine, {
  defaultSize: { width: 300, height: 300 },
})
```

#### Controlling the size

Use `size` and `onSizeChange` to control size externally.

```tsx {2}
const service = useMachine(floatingPanel.machine, {
  size: { width: 300, height: 300 },
  onSizeChange(details) {
    // details => { size: { width: number, height: number } }
    console.log("floating panel is:", details.size.width, details.size.height)
  },
})
```

#### Disable resizing

By default, the panel can be resized by dragging its edges (resize handles). To
disable this behavior, set the `resizable` prop to `false`.

```tsx {2}
const service = useMachine(floatingPanel.machine, {
  resizable: false,
})
```

#### Setting size constraints

You can also control the minimum allowed dimensions of the panel by using the
`minSize` and `maxSize` props.

```tsx {2,3}
const service = useMachine(floatingPanel.machine, {
  minSize: { width: 100, height: 100 },
  maxSize: { width: 500, height: 500 },
})
```

### Aspect ratio

To lock the aspect ratio of the floating panel, set the `lockAspectRatio` prop.
This will ensure the panel maintains a consistent aspect ratio while being
resized.

```tsx {2}
const service = useMachine(floatingPanel.machine, {
  lockAspectRatio: true,
})
```

### Positioning

#### Setting the initial position

To specify the initial position of the floating panel, use the `defaultPosition`
prop. If `defaultPosition` is not provided, the floating panel will be initially
positioned at the center of the viewport.

```tsx {2}
const service = useMachine(floatingPanel.machine, {
  defaultPosition: { x: 500, y: 200 },
})
```

#### Anchor position

An alternative to setting the initial position is to provide a function that
returns the anchor position. This function is called when the panel is opened
and receives the `triggerRect` and `boundaryRect`.

```tsx {2}
const service = useMachine(floatingPanel.machine, {
  getAnchorPosition({ triggerRect, boundaryRect }) {
    return {
      x: boundaryRect.x + (boundaryRect.width - triggerRect.width) / 2,
      y: boundaryRect.y + (boundaryRect.height - triggerRect.height) / 2,
    }
  },
})
```

#### Controlling the position

To control the position of the floating panel programmatically, you can pass the
`position` and `onPositionChange` prop to the machine.

```tsx {2}
const service = useMachine(floatingPanel.machine, {
  position: { x: 500, y: 200 },
  onPositionChange(details) {
    // details => { position: { x: number, y: number } }
    console.log("floating panel is:", details.position.x, details.position.y)
  },
})
```

#### Disable dragging

The floating panel enables you to set its position and move it by dragging. To
disable this behavior, set the `draggable` prop to `false`.

```tsx
const service = useMachine(floatingPanel.machine, {
  draggable: false,
})
```

#### Controlling positioning strategy

Use `strategy` to control positioning behavior (`fixed` or `absolute`).

```tsx
const service = useMachine(floatingPanel.machine, {
  strategy: "absolute",
})
```

#### Snapping to a grid

Use `gridSize` to snap drag and resize interactions to a grid.

```tsx
const service = useMachine(floatingPanel.machine, {
  gridSize: 8,
})
```

#### Allowing overflow outside boundaries

Set `allowOverflow` to `true` to let the panel move outside boundary limits.

```tsx
const service = useMachine(floatingPanel.machine, {
  allowOverflow: true,
})
```

### Events

The floating panel generates a variety of events that you can handle.

#### Open State

When the floating panel is `opened` or `closed`, the `onOpenChange` callback is
invoked.

```tsx {2-5}
const service = useMachine(floatingPanel.machine, {
  onOpenChange(details) {
    // details => { open: boolean }
    console.log("floating panel is:", details.open ? "opened" : "closed")
  },
})
```

#### Position Change

When the position of the floating panel changes, these callbacks are invoked:

- `onPositionChange` — When the position of the floating panel changes.
- `onPositionChangeEnd` — When the position of the floating panel changes ends.

```tsx {2-5}
const service = useMachine(floatingPanel.machine, {
  onPositionChange(details) {
    // details => { position: { x: number, y: number } }
    console.log("floating panel is:", details.position.x, details.position.y)
  },
  onPositionChangeEnd(details) {
    // details => { position: { x: number, y: number } }
    console.log("floating panel is:", details.position.x, details.position.y)
  },
})
```

#### Resize

When the size of the floating panel changes, these callbacks are invoked:

- `onSizeChange` — When the panel size changes.
- `onSizeChangeEnd` — When panel resizing ends.

```tsx {2-5}
const service = useMachine(floatingPanel.machine, {
  onSizeChange(details) {
    // details => { size: { width: number, height: number } }
    console.log("floating panel is:", details.size.width, details.size.height)
  },
  onSizeChangeEnd(details) {
    // details => { size: { width: number, height: number } }
    console.log("floating panel is:", details.size.width, details.size.height)
  },
})
```

#### Minimizing and Maximizing

The floating panel can be minimized, default, and maximized by clicking the
respective buttons in the header. We refer to this as the panel's `stage`.

- When the panel is minimized, the body is hidden and the panel is resized to a
  minimum size.

- When the panel is maximized, the panel scales to the match the size of the
  defined boundary rect (via `getBoundaryEl` prop).

- When the panel is restored, the panel is resized back to the previously known
  size.

When the stage changes, the `onStageChange` callback is invoked.

```tsx {2-5}
const service = useMachine(floatingPanel.machine, {
  onStageChange(details) {
    // details => { stage: "minimized" | "maximized" | "default" }
    console.log("floating panel is:", details.stage)
  },
})
```

### Persisting size and position when closed

Set `persistRect` to `true` to preserve size and position across close and
reopen.

```tsx
const service = useMachine(floatingPanel.machine, {
  persistRect: true,
})
```

### Customizing accessibility labels

Use `translations` to customize stage control labels.

```tsx
const service = useMachine(floatingPanel.machine, {
  translations: {
    minimize: "Minimize panel",
    maximize: "Maximize panel",
    restore: "Restore panel",
  },
})
```

## Styling guide

The floating panel component uses data attributes to style its various parts.
Each part has a `data-scope="floating-panel"` and `data-part` attribute that you
can use to target specific elements.

```css
[data-scope="floating-panel"][data-part="content"] {
  /* Add styles for the main panel container */
}

[data-scope="floating-panel"][data-part="body"] {
  /* Add styles for the panel's content area */
}

[data-scope="floating-panel"][data-part="header"] {
  /* Add styles for the panel's header */
}

[data-scope="floating-panel"][data-part="stage-trigger"] {
  /* Add styles for state buttons in the header */
}

[data-scope="floating-panel"][data-part="resize-trigger"] {
  /* Add styles for resize handles */
}

/* North and south resize handles */
[data-scope="floating-panel"][data-part="resize-trigger"][data-placement="n"],
[data-scope="floating-panel"][data-part="resize-trigger"][data-placement="s"] {
  /* Add styles for north and south resize handles */
}

/* East and west resize handles */
[data-scope="floating-panel"][data-part="resize-trigger"][data-placement="e"],
[data-scope="floating-panel"][data-part="resize-trigger"][data-placement="w"] {
  /* Add styles for east and west resize handles */
}

/* Corner resize handles */
[data-scope="floating-panel"][data-part="resize-trigger"][data-placement="ne"],
[data-scope="floating-panel"][data-part="resize-trigger"][data-placement="nw"],
[data-scope="floating-panel"][data-part="resize-trigger"][data-placement="se"],
[data-scope="floating-panel"][data-part="resize-trigger"][data-placement="sw"] {
  /* Add styles for corner resize handles */
}
```

### Dragging

When dragging the panel, the `[data-dragging]` attribute is applied to the
panel.

```css
[data-scope="floating-panel"][data-part="content"][data-dragging] {
  /* Add styles for dragging state */
}
```

### Stacking

The floating panel has several states that can be targeted using data
attributes:

```css
/* When the panel is the topmost element */
[data-scope="floating-panel"][data-part="content"][data-topmost] {
  /* Add styles for topmost state */
}

/* When the panel is behind another panel */
[data-scope="floating-panel"][data-part="content"][data-behind] {
  /* Add styles for behind state */
}
```

## Methods and Properties

### Machine Context

The floating panel machine exposes the following context properties:

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the floating panel. Useful for composition.

**`translations`**
Type: `IntlTranslations | undefined`
Description: The translations for the floating panel.

**`strategy`**
Type: `"absolute" | "fixed" | undefined`
Description: The strategy to use for positioning

**`allowOverflow`**
Type: `boolean | undefined`
Description: Whether the panel should be strictly contained within the boundary when dragging

**`open`**
Type: `boolean | undefined`
Description: The controlled open state of the panel

**`defaultOpen`**
Type: `boolean | undefined`
Description: The initial open state of the panel when rendered.
Use when you don't need to control the open state of the panel.

**`draggable`**
Type: `boolean | undefined`
Description: Whether the panel is draggable

**`resizable`**
Type: `boolean | undefined`
Description: Whether the panel is resizable

**`size`**
Type: `Size | undefined`
Description: The size of the panel

**`defaultSize`**
Type: `Size | undefined`
Description: The default size of the panel

**`minSize`**
Type: `Size | undefined`
Description: The minimum size of the panel

**`maxSize`**
Type: `Size | undefined`
Description: The maximum size of the panel

**`position`**
Type: `Point | undefined`
Description: The controlled position of the panel

**`defaultPosition`**
Type: `Point | undefined`
Description: The initial position of the panel when rendered.
Use when you don't need to control the position of the panel.

**`getAnchorPosition`**
Type: `((details: AnchorPositionDetails) => Point) | undefined`
Description: Function that returns the initial position of the panel when it is opened.
If provided, will be used instead of the default position.

**`lockAspectRatio`**
Type: `boolean | undefined`
Description: Whether the panel is locked to its aspect ratio

**`closeOnEscape`**
Type: `boolean | undefined`
Description: Whether the panel should close when the escape key is pressed

**`getBoundaryEl`**
Type: `(() => HTMLElement | null) | undefined`
Description: The boundary of the panel. Useful for recalculating the boundary rect when
the it is resized.

**`initialFocusEl`**
Type: `(() => HTMLElement | null) | undefined`
Description: Element to receive focus when the panel is opened.
By default, the first focusable element in the content is focused.

**`finalFocusEl`**
Type: `(() => HTMLElement | null) | undefined`
Description: Element to receive focus when the panel is closed.
By default, the trigger element is focused.

**`restoreFocus`**
Type: `boolean | undefined`
Description: Whether to restore focus to the trigger when the panel is closed.

**`disabled`**
Type: `boolean | undefined`
Description: Whether the panel is disabled

**`onPositionChange`**
Type: `((details: PositionChangeDetails) => void) | undefined`
Description: Function called when the position of the panel changes via dragging

**`onPositionChangeEnd`**
Type: `((details: PositionChangeDetails) => void) | undefined`
Description: Function called when the position of the panel changes via dragging ends

**`onOpenChange`**
Type: `((details: OpenChangeDetails) => void) | undefined`
Description: Function called when the panel is opened or closed

**`onSizeChange`**
Type: `((details: SizeChangeDetails) => void) | undefined`
Description: Function called when the size of the panel changes via resizing

**`onSizeChangeEnd`**
Type: `((details: SizeChangeDetails) => void) | undefined`
Description: Function called when the size of the panel changes via resizing ends

**`persistRect`**
Type: `boolean | undefined`
Description: Whether the panel size and position should be preserved when it is closed

**`gridSize`**
Type: `number | undefined`
Description: The snap grid for the panel

**`onStageChange`**
Type: `((details: StageChangeDetails) => void) | undefined`
Description: Function called when the stage of the panel changes

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

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

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

### Machine API

The floating panel `api` exposes the following methods:

**`open`**
Type: `boolean`
Description: Whether the panel is open

**`setOpen`**
Type: `(open: boolean) => void`
Description: Function to open or close the panel

**`dragging`**
Type: `boolean`
Description: Whether the panel is being dragged

**`resizing`**
Type: `boolean`
Description: Whether the panel is being resized

**`position`**
Type: `Point`
Description: The position of the panel

**`setPosition`**
Type: `(position: Point) => void`
Description: Function to set the position of the panel

**`size`**
Type: `Size`
Description: The size of the panel

**`setSize`**
Type: `(size: Size) => void`
Description: Function to set the size of the panel

**`minimize`**
Type: `VoidFunction`
Description: Function to minimize the panel

**`maximize`**
Type: `VoidFunction`
Description: Function to maximize the panel

**`restore`**
Type: `VoidFunction`
Description: Function to restore the panel before it was minimized or maximized

**`resizable`**
Type: `boolean`
Description: Whether the panel is resizable

**`draggable`**
Type: `boolean`
Description: Whether the panel is draggable

### Data Attributes

**`Trigger`**

**`data-floating-panel-trigger`**: <uid>
**`data-state`**: "open" | "closed"
**`data-dragging`**: Present when in the dragging state

**`Content`**

**`data-floating-panel-content`**: <uid>
**`data-state`**: "open" | "closed"
**`data-dragging`**: Present when in the dragging state
**`data-topmost`**: Present when topmost
**`data-behind`**: Present when not topmost
**`data-minimized`**: Present when minimized
**`data-maximized`**: Present when maximized
**`data-staged`**: Present when not in default stage

**`StageTrigger`**

**`data-floating-panel-stage-trigger`**: <uid>
**`data-stage`**: The stage of the stagetrigger

**`ResizeTrigger`**

**`data-floating-panel-resize-trigger`**: <uid>
**`data-disabled`**: Present when disabled
**`data-placement`**: The placement of the resizetrigger

**`DragTrigger`**

**`data-floating-panel-drag-trigger`**: <uid>
**`data-disabled`**: Present when disabled

**`Control`**

**`data-floating-panel-control`**: <uid>
**`data-disabled`**: Present when disabled
**`data-stage`**: The stage of the control
**`data-minimized`**: Present when minimized
**`data-maximized`**: Present when maximized
**`data-staged`**: Present when not in default stage

**`Header`**

**`data-floating-panel-header`**: <uid>
**`data-dragging`**: Present when in the dragging state
**`data-topmost`**: Present when topmost
**`data-behind`**: Present when not topmost
**`data-minimized`**: Present when minimized
**`data-maximized`**: Present when maximized
**`data-staged`**: Present when not in default stage

**`Body`**

**`data-floating-panel-body`**: <uid>
**`data-dragging`**: Present when in the dragging state
**`data-minimized`**: Present when minimized
**`data-maximized`**: Present when maximized
**`data-staged`**: Present when not in default stage

### CSS Variables

<CssVarTable name="floating-panel" />

A hover card lets sighted users preview content behind a link.

## Resources


[Latest version: v2.0.0-next.1](https://www.npmjs.com/package/@zag-js/hover-card)
[Logic Visualizer](https://zag-visualizer.vercel.app/hover-card)
[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/hover-card)



**Features**

- Customize side, alignment, offsets
- Optionally render a pointing arrow
- Supports custom open and close delays
- Opens on hover only
- Ignored by screen readers
- Supports multiple triggers sharing a single hover card instance

## Installation

Install the hover card package:

```bash
npm install @zag-js/hover-card @zag-js/react
# or
yarn add @zag-js/hover-card @zag-js/react
```

## Anatomy

To set up the hover card 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 hover card package:

```tsx
import * as hoverCard from "@zag-js/hover-card"
```

The hover card 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:

```tsx
import * as hoverCard from "@zag-js/hover-card"
import { useMachine, normalizeProps, Portal } from "@zag-js/react"
import { useId } from "react"

function HoverCard() {
  const service = useMachine(hoverCard.machine, { id: useId() })

  const api = hoverCard.connect(service, normalizeProps)

  return (
    <>
      <a
        href="https://twitter.com/zag_js"
        target="_blank"
        {...api.getTriggerProps()}
      >
        Twitter
      </a>

      {api.open && (
        <Portal>
          <div {...api.getPositionerProps()}>
            <div {...api.getContentProps()}>
              <div {...api.getArrowProps()}>
                <div {...api.getArrowTipProps()} />
              </div>
              Twitter Preview
            </div>
          </div>
        </Portal>
      )}
    </>
  )
}
```

### Setting the initial state

Set `defaultOpen` to `true` to start with the hover card open.

```tsx {2}
const service = useMachine(hoverCard.machine, {
  defaultOpen: true,
})
```

### Controlled open state

Use `open` and `onOpenChange` to control visibility externally.

```tsx
const service = useMachine(hoverCard.machine, {
  open,
  onOpenChange(details) {
    setOpen(details.open)
  },
})
```

### Customizing open and close delays

Use `openDelay` and `closeDelay` to control hover timing.

```tsx
const service = useMachine(hoverCard.machine, {
  openDelay: 300,
  closeDelay: 150,
})
```

### Positioning the hover card

Use `positioning` to control placement and offsets.

```tsx
const service = useMachine(hoverCard.machine, {
  positioning: {
    placement: "bottom-start",
    offset: { mainAxis: 8, crossAxis: 4 },
  },
})
```

### Multiple triggers

A single hover card instance can be shared across multiple trigger elements.
Pass a `value` to `getTriggerProps` to identify each trigger.

```tsx
const users = [
  { id: "1", name: "Alice", avatar: "/alice.png" },
  { id: "2", name: "Bob", avatar: "/bob.png" },
]

const service = useMachine(hoverCard.machine, {
  onTriggerValueChange({ value }) {
    const user = users.find((u) => u.id === value) ?? null
    setActiveUser(user)
  },
})

const api = hoverCard.connect(service, normalizeProps)

return (
  <>
    {users.map((user) => (
      <a {...api.getTriggerProps({ value: user.id })}>{user.name}</a>
    ))}
    <div {...api.getPositionerProps()}>
      <div {...api.getContentProps()}>
        {/* Content updates based on activeUser */}
      </div>
    </div>
  </>
)
```

When hovering a different trigger while the card is open, it repositions without
closing.

### Disabling the hover card

Set `disabled` to `true` to prevent it from opening.

```tsx
const service = useMachine(hoverCard.machine, {
  disabled: true,
})
```

### Listening for open state changes

When the hover card is `opened` or `closed`, the `onOpenChange` callback is
invoked.

```tsx {2-5}
const service = useMachine(hoverCard.machine, {
  onOpenChange(details) {
    // details => { open: boolean }
    console.log("hovercard is:", details.open ? "opened" : "closed")
  },
})
```

## Styling guide

Each part includes a `data-part` attribute you can target in CSS.

```css
[data-part="trigger"] {
  /* styles for trigger */
}

[data-part="content"] {
  /* styles for content */
}
```

### Open and closed state

The hover card exposes a `data-state` attribute that can be used to style the
hover card based on its open-close state.

```css
[data-part="trigger"][data-state="open|closed"] {
  /* styles for open or closed state */
}

[data-part="content"][data-state="open|closed"] {
  /* styles for open or closed state */
}
```

### Arrow

You can use CSS variables to style the arrow.

```css
[data-part="arrow"] {
  /* styles for arrow */
  --arrow-background: white;
  --arrow-size: 8px;
}
```

## Methods and Properties

### Machine Context

The hover card machine exposes the following context properties:

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the popover. Useful for composition.

**`onOpenChange`**
Type: `((details: OpenChangeDetails) => void) | undefined`
Description: Function called when the hover card opens or closes.

**`openDelay`**
Type: `number | undefined`
Description: The duration from when the mouse enters the trigger until the hover card opens.

**`closeDelay`**
Type: `number | undefined`
Description: The duration from when the mouse leaves the trigger or content until the hover card closes.

**`disabled`**
Type: `boolean | undefined`
Description: Whether the hover card is disabled

**`open`**
Type: `boolean | undefined`
Description: The controlled open state of the hover card

**`defaultOpen`**
Type: `boolean | undefined`
Description: The initial open state of the hover card when rendered.
Use when you don't need to control the open state of the hover card.

**`positioning`**
Type: `PositioningOptions | undefined`
Description: The user provided options used to position the popover content

**`triggerValue`**
Type: `string | null | undefined`
Description: The controlled trigger value

**`defaultTriggerValue`**
Type: `string | null | undefined`
Description: The initial trigger value when rendered.
Use when you don't need to control the trigger value.

**`onTriggerValueChange`**
Type: `((details: TriggerValueChangeDetails) => void) | undefined`
Description: Function called when the trigger value changes.

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

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

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

**`onPointerDownOutside`**
Type: `((event: PointerDownOutsideEvent) => void) | undefined`
Description: Function called when the pointer is pressed down outside the component

**`onFocusOutside`**
Type: `((event: FocusOutsideEvent) => void) | undefined`
Description: Function called when the focus is moved outside the component

**`onInteractOutside`**
Type: `((event: InteractOutsideEvent) => void) | undefined`
Description: Function called when an interaction happens outside the component

### Machine API

The hover card `api` exposes the following methods:

**`open`**
Type: `boolean`
Description: Whether the hover card is open

**`setOpen`**
Type: `(open: boolean) => void`
Description: Function to open the hover card

**`triggerValue`**
Type: `string | null`
Description: The trigger value

**`setTriggerValue`**
Type: `(value: string | null) => void`
Description: Function to set the trigger value

**`reposition`**
Type: `(options?: Partial<PositioningOptions>) => void`
Description: Function to reposition the popover

### Data Attributes

**`Trigger`**

**`data-hover-card-trigger`**: <uid>
**`data-placement`**: The placement of the trigger
**`data-side`**: The side of the trigger that the trigger is positioned on
**`data-value`**: The value of the item
**`data-current`**: Present when current
**`data-state`**: "open" | "closed"

**`Content`**

**`data-hover-card-content`**: <uid>
**`data-state`**: "open" | "closed"
**`data-nested`**: popover
**`data-has-nested`**: popover
**`data-placement`**: The placement of the content
**`data-side`**: The side of the trigger that the content is positioned on

### CSS Variables

<CssVarTable name="hover-card" />

## Accessibility

### Keyboard Interactions

The hover card is intended for mouse users only so will not respond to keyboard
navigation.

Image cropper lets users select and edit an image crop area with pan, zoom,
rotation, and flip controls.

## Resources


[Latest version: v2.0.0-next.1](https://www.npmjs.com/package/@zag-js/image-cropper)
[Logic Visualizer](https://zag-visualizer.vercel.app/image-cropper)
[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/image-cropper)



**Features**

- Pan, zoom, rotate, and flip with pointer, wheel, and pinch gestures
- Rectangle or circle crops with optional fixed area and aspect ratio
- Min/max crop dimensions and keyboard nudging
- Controlled zoom/rotation/flip with change callbacks
- Programmatic helpers like `api.resize` and `api.getCroppedImage`
- Accessibility labels, translations, and styling data attributes

## Installation

Install the image cropper package:

```bash
npm install @zag-js/image-cropper @zag-js/react
# or
yarn add @zag-js/image-cropper @zag-js/react
```

## Anatomy

To set up the image cropper 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 image cropper package:

```tsx
import * as imageCropper from "@zag-js/image-cropper"
```

The 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:

```tsx
import * as imageCropper from "@zag-js/image-cropper"
import { normalizeProps, useMachine } from "@zag-js/react"
import { useId } from "react"

export function ImageCropper() {
  const service = useMachine(imageCropper.machine, {
    id: useId(),
  })

  const api = imageCropper.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <div {...api.getViewportProps()}>
        <img
          src="https://picsum.photos/seed/crop/640/400"
          crossOrigin="anonymous"
          {...api.getImageProps()}
        />

        <div {...api.getSelectionProps()}>
          {imageCropper.handles.map((placement) => (
            <div key={placement} {...api.getHandleProps({ placement })}>
              <span />
            </div>
          ))}
        </div>
      </div>
    </div>
  )
}
```

### Setting the initial crop

Pass an `initialCrop` to start from a specific rectangle. The size is
constrained to your min/max and viewport, and the position is clamped within the
viewport.

```tsx {2-6}
const service = useMachine(imageCropper.machine, {
  initialCrop: { x: 40, y: 40, width: 240, height: 240 },
  aspectRatio: 1, // optional, lock to square
})
const api = imageCropper.connect(service, normalizeProps)
```

### Fixed crop area

Lock the crop window and allow only panning/zooming of the image beneath it by
setting `fixedCropArea: true`.

```tsx {2}
const service = useMachine(imageCropper.machine, {
  fixedCropArea: true,
})
```

### Crop shape and aspect ratio

- `cropShape` can be `"rectangle"` or `"circle"`.
- `aspectRatio` can lock the crop to a width/height ratio. When `aspectRatio` is
  not set and `cropShape` is `"rectangle"`, holding Shift while resizing locks
  to the current ratio.

```tsx {2-3}
const service = useMachine(imageCropper.machine, {
  cropShape: "circle",
  aspectRatio: 1, // ignored for circle
})
```

### Controlling zoom, rotation, and flip

You can configure defaults and limits, and also control them programmatically
using the API.

```tsx {2-6}
const service = useMachine(imageCropper.machine, {
  defaultZoom: 1.25,
  minZoom: 1,
  maxZoom: 5,
  defaultRotation: 0,
  defaultFlip: { horizontal: false, vertical: false },
})
const api = imageCropper.connect(service, normalizeProps)

// Programmatic controls
api.setZoom(2) // zoom to 2x
api.setRotation(90) // rotate to 90 degrees
api.flipHorizontally() // toggle horizontal flip
api.setFlip({ vertical: true }) // set vertical flip on
```

### Controlled transform values

Use controlled props and callbacks when transform values are managed by your
state.

```tsx
const service = useMachine(imageCropper.machine, {
  zoom,
  rotation,
  flip,
  onZoomChange(details) {
    setZoom(details.zoom)
  },
  onRotationChange(details) {
    setRotation(details.rotation)
  },
  onFlipChange(details) {
    setFlip(details.flip)
  },
})
```

### Listening for crop changes

Use `onCropChange` to react when the crop rectangle changes.

```tsx
const service = useMachine(imageCropper.machine, {
  onCropChange(details) {
    // details => { crop: Rect }
    console.log(details.crop)
  },
})
```

### Programmatic resizing

Use `api.resize(handle, delta)` to resize from any handle programmatically.
Positive `delta` grows outward, negative shrinks inward.

```tsx
// Grow the selection by 8px from the right edge
api.resize("right", 8)
// Shrink from top-left corner by 4px in both axes
api.resize("top-left", -4)
```

### Getting the cropped image

Use `api.getCroppedImage` to export the current crop, taking
zoom/rotation/flip/pan into account.

```tsx
// Blob (default)
const blob = await api.getCroppedImage({ type: "image/png", quality: 0.92 })

// Data URL
const dataUrl = await api.getCroppedImage({
  output: "dataUrl",
  type: "image/jpeg",
  quality: 0.85,
})

// Example usage
if (blob) {
  const url = URL.createObjectURL(blob)
  previewImg.src = url
}
```

### Understanding coordinate systems

The image cropper uses two different coordinate systems:

#### 1. Viewport Coordinates (`api.crop`)

These are the coordinates you see in the UI, relative to the visible viewport:

```tsx
console.log(api.crop)
// { x: 50, y: 30, width: 200, height: 150 }
```

**Characteristics:**

- Relative to the viewport dimensions
- Changes as you zoom and pan
- Perfect for UI rendering and controls
- Used by `initialCrop`

#### 2. Natural Image Coordinates (`api.getCropData()`)

These are the absolute pixel coordinates in the original image:

```tsx
const cropData = api.getCropData()
console.log(cropData)
// {
//   x: 250,
//   y: 150,
//   width: 1000,
//   height: 750,
//   rotate: 0,
//   flipX: false,
//   flipY: false
// }
```

**Characteristics:**

- Relative to the original image dimensions
- Independent of zoom/pan/viewport size
- Essential for server-side cropping
- Perfect for state persistence and undo/redo

#### When to use each

**Use viewport coordinates (`api.crop`)** when:

- Rendering UI controls (sliders, displays)
- Setting initial crop area
- Building custom crop UI

**Use natural coordinates (`api.getCropData()`)** when:

- Sending crop data to your backend for server-side processing
- Persisting state (localStorage, database)
- Implementing undo/redo functionality
- Exporting crop configuration to external tools

#### Example: Server-side cropping

```tsx
// Frontend: Get natural coordinates
const cropData = api.getCropData()

// Send to backend
await fetch("/api/crop-image", {
  method: "POST",
  body: JSON.stringify({
    imageId: "photo-123",
    crop: cropData, // Natural pixel coordinates
  }),
})

// Backend: Crop the original image file
// Use cropData.x, cropData.y, cropData.width, cropData.height
// to crop the actual image file at full resolution
```

#### Transformation example

Here's how the coordinates relate with a zoom of 2x:

```tsx
// Original image: 3000 × 2000 pixels
// Viewport: 600 × 400 pixels
// Zoom: 2x

// Viewport coordinates (what you see)
api.crop
// { x: 100, y: 80, width: 200, height: 150 }

// Natural coordinates (original image)
api.getCropData()
// { x: 500, y: 400, width: 1000, height: 750, ... }
// Scale factor: 3000 / 600 = 5x
// So 100px in viewport = 500px in original image
```

### Touch and wheel gestures

- Use the mouse wheel over the viewport to zoom at the pointer location.
- Pinch with two fingers to zoom and pan; the machine smooths tiny changes and
  tracks the pinch midpoint.
- Drag on the viewport background to pan the image (when not dragging the
  selection).

### Keyboard nudges

Configure keyboard nudge steps for move/resize:

```tsx {2-4}
const service = useMachine(imageCropper.machine, {
  nudgeStep: 1,
  nudgeStepShift: 10,
  nudgeStepCtrl: 50,
})
```

### Accessibility

- The root is a live region with helpful descriptions of crop, zoom, and
  rotation status.
- The selection exposes slider-like semantics to assistive tech and supports
  keyboard movement, resizing (Alt+Arrows), and zooming (+/-).
- Customize accessible labels and descriptions via `translations`:

```tsx {2-7}
const service = useMachine(imageCropper.machine, {
  translations: {
    rootLabel: "Product image cropper",
    selectionInstructions:
      "Use arrow keys to move, Alt+arrows to resize, and +/- to zoom.",
  },
})
```

## Styling guide

Each part includes a `data-part` attribute you can target in CSS.

```css
[data-scope="image-cropper"][data-part="root"] {
  /* styles for the root part */
}

[data-scope="image-cropper"][data-part="viewport"] {
  /* styles for the viewport part */
}

[data-scope="image-cropper"][data-part="image"] {
  /* styles for the image part */
}

[data-scope="image-cropper"][data-part="selection"] {
  /* styles for the selection part */
}

[data-scope="image-cropper"][data-part="handle"] {
  /* styles for the handle part */
}
```

### Selection shapes

The selection can be styled based on its shape:

```css
[data-part="selection"][data-shape="circle"] {
  /* styles for circular selection */
}

[data-part="selection"][data-shape="rectangle"] {
  /* styles for rectangular selection */
}
```

### States

Various states can be styled using data attributes:

```css
[data-part="root"][data-dragging] {
  /* styles when dragging the selection */
}

[data-part="root"][data-fixed] {
  /* styles when the crop area is fixed */
}
```

## Accessibility

Adheres to the
[Slider WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/slider)
for the crop area handles.

### Keyboard Interactions

**`ArrowUp`**
Description: Moves the crop selection upward by the configured nudge step. Hold Shift for the `nudgeStepShift` value or Ctrl/Cmd for `nudgeStepCtrl`.

**`ArrowDown`**
Description: Moves the crop selection downward by the configured nudge step. Hold Shift for the `nudgeStepShift` value or Ctrl/Cmd for `nudgeStepCtrl`.

**`ArrowLeft`**
Description: Moves the crop selection to the left by the configured nudge step. Hold Shift for the `nudgeStepShift` value or Ctrl/Cmd for `nudgeStepCtrl`.

**`ArrowRight`**
Description: Moves the crop selection to the right by the configured nudge step. Hold Shift for the `nudgeStepShift` value or Ctrl/Cmd for `nudgeStepCtrl`.

**`Alt + ArrowUp`**
Description: Resizes the crop vertically from the bottom handle, reducing the height. Hold Shift or Ctrl/Cmd for the larger nudge steps.

**`Alt + ArrowDown`**
Description: Resizes the crop vertically from the bottom handle, increasing the height. Hold Shift or Ctrl/Cmd for the larger nudge steps.

**`Alt + ArrowLeft`**
Description: Resizes the crop horizontally from the right handle, reducing the width. Hold Shift or Ctrl/Cmd for the larger nudge steps.

**`Alt + ArrowRight`**
Description: Resizes the crop horizontally from the right handle, increasing the width. Hold Shift or Ctrl/Cmd for the larger nudge steps.

**`+`**
Description: Zooms in on the image. The `=` key performs the same action on keyboards where both symbols share a key.

**`-`**
Description: Zooms out of the image. The `_` key performs the same action on keyboards where both symbols share a key.

## Methods and Properties

### Machine Context

The image cropper machine exposes the following context properties:

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the image cropper elements

**`translations`**
Type: `IntlTranslations | undefined`
Description: Specifies the localized strings that identify accessibility elements and their states.

**`initialCrop`**
Type: `Rect | undefined`
Description: The initial rectangle of the crop area.
If not provided, a smart default will be computed based on viewport size and aspect ratio.

**`minWidth`**
Type: `number | undefined`
Description: The minimum width of the crop area

**`minHeight`**
Type: `number | undefined`
Description: The minimum height of the crop area

**`maxWidth`**
Type: `number | undefined`
Description: The maximum width of the crop area

**`maxHeight`**
Type: `number | undefined`
Description: The maximum height of the crop area

**`aspectRatio`**
Type: `number | undefined`
Description: The aspect ratio to maintain for the crop area (width / height).
For example, an aspect ratio of 16 / 9 will maintain a width to height ratio of 16:9.
If not provided, the crop area can be freely resized.

**`cropShape`**
Type: `"rectangle" | "circle" | undefined`
Description: The shape of the crop area.

**`zoom`**
Type: `number | undefined`
Description: The controlled zoom level of the image.

**`rotation`**
Type: `number | undefined`
Description: The controlled rotation of the image in degrees (0 - 360).

**`flip`**
Type: `FlipState | undefined`
Description: The controlled flip state of the image.

**`defaultZoom`**
Type: `number | undefined`
Description: The initial zoom factor to apply to the image.

**`defaultRotation`**
Type: `number | undefined`
Description: The initial rotation to apply to the image in degrees.

**`defaultFlip`**
Type: `FlipState | undefined`
Description: The initial flip state to apply to the image.

**`zoomStep`**
Type: `number | undefined`
Description: The amount of zoom applied per wheel step.

**`zoomSensitivity`**
Type: `number | undefined`
Description: Controls how responsive pinch-to-zoom is.

**`minZoom`**
Type: `number | undefined`
Description: The minimum zoom factor allowed.

**`maxZoom`**
Type: `number | undefined`
Description: The maximum zoom factor allowed.

**`nudgeStep`**
Type: `number | undefined`
Description: The base nudge step for keyboard arrow keys (in pixels).

**`nudgeStepShift`**
Type: `number | undefined`
Description: The nudge step when Shift key is held (in pixels).

**`nudgeStepCtrl`**
Type: `number | undefined`
Description: The nudge step when Ctrl/Cmd key is held (in pixels).

**`onZoomChange`**
Type: `((details: ZoomChangeDetails) => void) | undefined`
Description: Callback fired when the zoom level changes.

**`onRotationChange`**
Type: `((details: RotationChangeDetails) => void) | undefined`
Description: Callback fired when the rotation changes.

**`onFlipChange`**
Type: `((details: FlipChangeDetails) => void) | undefined`
Description: Callback fired when the flip state changes.

**`onCropChange`**
Type: `((details: CropChangeDetails) => void) | undefined`
Description: Callback fired when the crop area changes.

**`fixedCropArea`**
Type: `boolean | undefined`
Description: Whether the crop area is fixed in size and position.

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

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

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

### Machine API

The image cropper `api` exposes the following methods:

**`zoom`**
Type: `number`
Description: The current zoom level of the image.

**`rotation`**
Type: `number`
Description: The current rotation of the image in degrees.

**`flip`**
Type: `FlipState`
Description: The current flip state of the image.

**`crop`**
Type: `Rect`
Description: The current crop area rectangle in viewport coordinates.

**`offset`**
Type: `Point`
Description: The current offset (pan position) of the image.

**`naturalSize`**
Type: `Size`
Description: The natural (original) size of the image.

**`viewportRect`**
Type: `BoundingRect`
Description: The viewport rectangle dimensions and position.

**`dragging`**
Type: `boolean`
Description: Whether the crop area is currently being dragged.

**`panning`**
Type: `boolean`
Description: Whether the image is currently being panned.

**`setZoom`**
Type: `(zoom: number) => void`
Description: Function to set the zoom level of the image.

**`zoomBy`**
Type: `(delta: number) => void`
Description: Function to zoom the image by a relative amount.

**`setRotation`**
Type: `(rotation: number) => void`
Description: Function to set the rotation of the image.

**`rotateBy`**
Type: `(degrees: number) => void`
Description: Function to rotate the image by a relative amount in degrees.

**`setFlip`**
Type: `(flip: Partial<FlipState>) => void`
Description: Function to set the flip state of the image.

**`flipHorizontally`**
Type: `(value?: boolean) => void`
Description: Function to flip the image horizontally. Pass a boolean to set explicitly or omit to toggle.

**`flipVertically`**
Type: `(value?: boolean) => void`
Description: Function to flip the image vertically. Pass a boolean to set explicitly or omit to toggle.

**`resize`**
Type: `(handlePosition: HandlePosition, delta: number) => void`
Description: Function to resize the crop area from a handle programmatically.

**`reset`**
Type: `() => void`
Description: Function to reset the cropper to its initial state.

**`getCroppedImage`**
Type: `(options?: GetCroppedImageOptions) => Promise<Blob | string | null>`
Description: Function to get the cropped image with all transformations applied.
Returns a Promise that resolves to either a Blob or data URL.

**`getCropData`**
Type: `() => CropData`
Description: Function to get the crop data in natural image pixel coordinates.
These coordinates are relative to the original image dimensions,
accounting for zoom, rotation, and flip transformations.
Use this for server-side cropping or state persistence.

### Data Attributes

**`Root`**

**`data-image-cropper-root`**: <uid>
**`data-fixed`**: 
**`data-shape`**: 
**`data-pinch`**: 
**`data-dragging`**: Present when in the dragging state
**`data-panning`**: 

**`Viewport`**

**`data-image-cropper-viewport`**: <uid>
**`data-disabled`**: Present when disabled

**`Image`**

**`data-image-cropper-image`**: <uid>
**`data-ready`**: 
**`data-flip-horizontal`**: 
**`data-flip-vertical`**: 

**`Selection`**

**`data-image-cropper-selection`**: <uid>
**`data-disabled`**: Present when disabled
**`data-shape`**: 
**`data-measured`**: 
**`data-dragging`**: Present when in the dragging state
**`data-panning`**: 

**`Handle`**

**`data-image-cropper-handle`**: <uid>
**`data-placement`**: The placement of the handle
**`data-disabled`**: Present when disabled

**`Grid`**

**`data-image-cropper-grid`**: <uid>
**`data-axis`**: The axis to resize
**`data-dragging`**: Present when in the dragging state
**`data-panning`**: 

### CSS Variables

<CssVarTable name="image-cropper" />

A listbox displays selectable options in single or multiple selection modes.

## Resources


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



**Features**

- Supports single, multiple, or no selection
- Can be controlled or uncontrolled
- Fully managed keyboard navigation (arrow keys, home, end, etc.)
- Vertical and horizontal orientation
- Typeahead to allow focusing the matching item
- Supports items, labels, groups of items
- Supports grid and list layouts

## Installation

Install the listbox package:

```bash
npm install @zag-js/listbox @zag-js/react
# or
yarn add @zag-js/listbox @zag-js/react
```

## Anatomy

Check the listbox anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the listbox package:

```tsx
import * as listbox from "@zag-js/listbox"
```

The listbox package exports two key functions:

- `machine` - State machine logic.
- `connect` - Maps machine state to JSX props and event handlers.

> Pass a unique `id` to `useMachine` so generated element ids stay predictable.

Then use the framework integration helpers:

```tsx
import * as listbox from "@zag-js/listbox"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useId } from "react"

const data = [
  { label: "Nigeria", value: "NG" },
  { label: "United States", value: "US" },
  { label: "Canada", value: "CA" },
  { label: "Japan", value: "JP" },
]

function Listbox() {
  const collection = listbox.collection({ items: data })

  const service = useMachine(listbox.machine, {
    id: useId(),
    collection,
  })

  const api = listbox.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <label {...api.getLabelProps()}>Select country</label>
      <div {...api.getContentProps()}>
        <ul {...api.getListProps()}>
          {data.map((item) => (
            <li key={item.value} {...api.getItemProps({ item })}>
              <span {...api.getItemTextProps({ item })}>{item.label}</span>
              <span {...api.getItemIndicatorProps({ item })}>✓</span>
            </li>
          ))}
        </ul>
      </div>
    </div>
  )
}
```

### Setting the initial selection

To set the initial selection, you can use the `defaultValue` property.

```tsx
const service = useMachine(listbox.machine, {
  // ...
  defaultValue: ["item-1", "item-2"],
})
```

### Controlling the selection

Use `value` and `onValueChange` to control selection externally.

```tsx
const service = useMachine(listbox.machine, {
  value: ["item-1", "item-2"],
  onValueChange(details) {
    // details => { value: string[]; items: CollectionItem[] }
    console.log(details.value)
  },
})
```

### Controlling the highlighted item

Use `highlightedValue` and `onHighlightChange` to control highlighted state.

```tsx
const service = useMachine(listbox.machine, {
  highlightedValue,
  onHighlightChange(details) {
    // details => { highlightedValue: string | null, highlightedItem, highlightedIndex }
    setHighlightedValue(details.highlightedValue)
  },
})
```

### Filtering

The listbox component supports filtering of items via `api.getInputProps`.
Here's an example of how to support searching through a list of items.

```tsx
import * as listbox from "@zag-js/listbox"
import { createFilter } from "@zag-js/i18n-utils"
import { normalizeProps, useMachine } from "@zag-js/react"
import { useId, useMemo, useState } from "react"

interface Item {
  label: string
  value: string
}

const data: Item[] = [
  { label: "Nigeria", value: "NG" },
  { label: "United States", value: "US" },
  { label: "Canada", value: "CA" },
  { label: "Japan", value: "JP" },
]

const filter = createFilter({ sensitivity: "base" })

function ListboxFiltering() {
  const [search, setSearch] = useState("")

  const collection = useMemo(() => {
    const items = data.filter((item) => filter.startsWith(item.label, search))
    return listbox.collection({ items })
  }, [search])

  const service = useMachine(listbox.machine as listbox.Machine<Item>, {
    collection,
    id: useId(),
    typeahead: false,
  })

  const api = listbox.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <div {...api.getContentProps()}>
        <input
          {...api.getInputProps({ autoHighlight: true })}
          onChange={(e) => setSearch(e.target.value)}
          value={search}
        />
        <ul {...api.getListProps()}>
          {collection.items.map((item) => (
            <li key={item.value} {...api.getItemProps({ item })}>
              <span {...api.getItemTextProps({ item })}>{item.label}</span>
              <span {...api.getItemIndicatorProps({ item })}>✓</span>
            </li>
          ))}
        </ul>
      </div>
    </div>
  )
}
```

### Selecting multiple items

To enable multiple selection, set the `selectionMode` property to `multiple` or
`extended`.

```tsx
const service = useMachine(listbox.machine, {
  // ...
  selectionMode: "multiple",
})
```

### Selection Modes

Use `selectionMode` to control selection behavior:

- **single**: A user can select a single item using the space bar, mouse click,
  or touch tap.
- **multiple**: A user can select multiple items using the space bar, mouse
  click, or touch tap to toggle selection on the focused item. Using the arrow
  keys, a user can move focus independently of selection.
- **extended**: With no modifier keys like `Ctrl`, `Cmd` or `Shift`: the
  behavior is the same as single selection.

```tsx
const service = useMachine(listbox.machine, {
  // ...
  selectionMode: "extended",
})
```

### Selecting on highlight

Set `selectOnHighlight` to `true` to select items as they become highlighted.

```tsx
const service = useMachine(listbox.machine, {
  selectOnHighlight: true,
})
```

### Disallowing select-all shortcuts

Set `disallowSelectAll` to disable `Cmd/Ctrl + A` selection.

```tsx
const service = useMachine(listbox.machine, {
  selectionMode: "multiple",
  disallowSelectAll: true,
})
```

### Listening for item selection

Use `onSelect` to react whenever an item is selected.

```tsx
const service = useMachine(listbox.machine, {
  onSelect(details) {
    // details => { value: string }
    console.log(details.value)
  },
})
```

### Disabling items

To disable an item, you can use the `disabled` property.

```tsx
api.getItemProps({
  // ...
  disabled: true,
})
```

To disable the entire listbox, you can use the `disabled` property.

```tsx
const service = useMachine(listbox.machine, {
  disabled: true,
})
```

### Grid layout

To enable a grid layout, provide a grid collection to the `collection` property.

```tsx
const service = useMachine(listbox.machine, {
  collection: listbox.gridCollection({
    items: [],
    columnCount: 3,
  }),
})
```

```tsx
import * as listbox from "@zag-js/listbox"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useId } from "react"

const data = [
  { label: "Red", value: "red" },
  { label: "Green", value: "green" },
  { label: "Blue", value: "blue" },
  { label: "Yellow", value: "yellow" },
  { label: "Purple", value: "purple" },
  { label: "Orange", value: "orange" },
]

function ListboxGrid() {
  const collection = listbox.gridCollection({
    items: data,
    columnCount: 3,
  })

  const service = useMachine(listbox.machine, {
    id: useId(),
    collection,
  })

  const api = listbox.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <label {...api.getLabelProps()}>Select color</label>
      <div {...api.getContentProps()}>
        <div
          {...api.getListProps()}
          style={{
            display: "grid",
            gridTemplateColumns: "repeat(3, 1fr)",
            gap: "8px",
          }}
        >
          {collection.items.map((item) => (
            <div key={item.value} {...api.getItemProps({ item })}>
              <span {...api.getItemTextProps({ item })}>{item.label}</span>
              <span {...api.getItemIndicatorProps({ item })}>✓</span>
            </div>
          ))}
        </div>
      </div>
    </div>
  )
}
```

### Horizontal orientation

Set `orientation` to `horizontal` for horizontal keyboard navigation.

```tsx
const service = useMachine(listbox.machine, {
  orientation: "horizontal",
  collection,
})
```

## Styling guide

Each part includes a `data-part` attribute you can target in CSS.

```css
[data-scope="listbox"][data-part="root"] {
  /* styles for the root part */
}

[data-scope="listbox"][data-part="label"] {
  /* styles for the label part */
}

[data-scope="listbox"][data-part="content"] {
  /* styles for the content part */
}

[data-scope="listbox"][data-part="list"] {
  /* styles for the list part (carries role=listbox) */
}

[data-scope="listbox"][data-part="item"] {
  /* styles for the item part */
}

[data-scope="listbox"][data-part="itemGroup"] {
  /* styles for the item group part */
}
```

### Focused state

The focused state is applied to the item that is currently focused.

```css
[data-scope="listbox"][data-part="item"][data-focused] {
  /* styles for the focused item part */
}
```

### Selected state

The selected state is applied to the item that is currently selected.

```css
[data-scope="listbox"][data-part="item"][data-selected] {
  /* styles for the selected item part */
}
```

### Disabled state

The disabled state is applied to the item that is currently disabled.

```css
[data-scope="listbox"][data-part="item"][data-disabled] {
  /* styles for the disabled item part */
}
```

## Methods and Properties

### Machine Context

The listbox machine exposes the following context properties:

**`orientation`**
Type: `"horizontal" | "vertical" | undefined`
Description: The orientation of the listbox.

**`collection`**
Type: `ListCollection<T> | GridCollection<T>`
Description: The item collection

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the listbox. Useful for composition.

**`disabled`**
Type: `boolean | undefined`
Description: Whether the listbox is disabled

**`disallowSelectAll`**
Type: `boolean | undefined`
Description: Whether to disallow selecting all items when `meta+a` is pressed

**`onHighlightChange`**
Type: `((details: HighlightChangeDetails<T>) => void) | undefined`
Description: The callback fired when the highlighted item changes.

**`onValueChange`**
Type: `((details: ValueChangeDetails<T>) => void) | undefined`
Description: The callback fired when the selected item changes.

**`value`**
Type: `string[] | undefined`
Description: The controlled keys of the selected items

**`defaultValue`**
Type: `string[] | undefined`
Description: The initial default value of the listbox when rendered.
Use when you don't need to control the value of the listbox.

**`highlightedValue`**
Type: `string | null | undefined`
Description: The controlled key of the highlighted item

**`defaultHighlightedValue`**
Type: `string | null | undefined`
Description: The initial value of the highlighted item when opened.
Use when you don't need to control the highlighted value of the listbox.

**`loopFocus`**
Type: `boolean | undefined`
Description: Whether to loop the keyboard navigation through the options

**`selectionMode`**
Type: `SelectionMode | undefined`
Description: How multiple selection should behave in the listbox.

- `single`: The user can select a single item.
- `multiple`: The user can select multiple items without using modifier keys.
- `extended`: The user can select multiple items by using modifier keys.

**`scrollToIndexFn`**
Type: `((details: ScrollToIndexDetails) => void) | undefined`
Description: Function to scroll to a specific index

**`selectOnHighlight`**
Type: `boolean | undefined`
Description: Whether to select the item when it is highlighted

**`deselectable`**
Type: `boolean | undefined`
Description: Whether to disallow empty selection

**`typeahead`**
Type: `boolean | undefined`
Description: Whether to enable typeahead on the listbox

**`onSelect`**
Type: `((details: SelectionDetails) => void) | undefined`
Description: Function called when an item is selected

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

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

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

### Machine API

The listbox `api` exposes the following methods:

**`empty`**
Type: `boolean`
Description: Whether the select value is empty

**`highlightedValue`**
Type: `string | null`
Description: The value of the highlighted item

**`highlightedItem`**
Type: `V | null`
Description: The highlighted item

**`highlightValue`**
Type: `(value: string) => void`
Description: Function to highlight a value

**`highlightFirst`**
Type: `VoidFunction`
Description: Function to highlight the first value

**`highlightLast`**
Type: `VoidFunction`
Description: Function to highlight the last value

**`highlightNext`**
Type: `VoidFunction`
Description: Function to highlight the next value

**`highlightPrevious`**
Type: `VoidFunction`
Description: Function to highlight the previous value

**`clearHighlightedValue`**
Type: `VoidFunction`
Description: Function to clear the highlighted value

**`selectedItems`**
Type: `V[]`
Description: The selected items

**`hasSelectedItems`**
Type: `boolean`
Description: Whether there's a selected option

**`value`**
Type: `string[]`
Description: The selected item keys

**`valueAsString`**
Type: `string`
Description: The string representation of the selected items

**`selectValue`**
Type: `(value: string) => void`
Description: Function to select a value

**`selectAll`**
Type: `VoidFunction`
Description: Function to select all values.

**Note**: This should only be called when the selectionMode is `multiple` or `extended`.
Otherwise, an exception will be thrown.

**`setValue`**
Type: `(value: string[]) => void`
Description: Function to set the value of the select

**`clearValue`**
Type: `(value?: string) => void`
Description: Function to clear the value of the select.
If a value is provided, it will only clear that value, otherwise, it will clear all values.

**`getItemState`**
Type: `(props: ItemProps) => ItemState`
Description: Returns the state of a select item

**`collection`**
Type: `ListCollection<V>`
Description: Function to toggle the select

**`disabled`**
Type: `boolean`
Description: Whether the select is disabled

### Data Attributes

**`Root`**

**`data-listbox-root`**: <uid>
**`data-orientation`**: The orientation of the listbox
**`data-disabled`**: Present when disabled

**`Input`**

**`data-listbox-input`**: <uid>
**`data-disabled`**: Present when disabled

**`Label`**

**`data-listbox-label`**: <uid>
**`data-disabled`**: Present when disabled

**`ValueText`**

**`data-listbox-value-text`**: <uid>
**`data-disabled`**: Present when disabled

**`Item`**

**`data-listbox-item`**: <uid>
**`data-value`**: The value of the item
**`data-selected`**: Present when selected
**`data-layout`**: 
**`data-state`**: "checked" | "unchecked"
**`data-orientation`**: The orientation of the item
**`data-highlighted`**: Present when highlighted
**`data-disabled`**: Present when disabled

**`ItemText`**

**`data-listbox-item-text`**: <uid>
**`data-state`**: "checked" | "unchecked"
**`data-disabled`**: Present when disabled
**`data-highlighted`**: Present when highlighted

**`ItemIndicator`**

**`data-listbox-item-indicator`**: <uid>
**`data-state`**: "checked" | "unchecked"

**`ItemGroup`**

**`data-listbox-item-group`**: <uid>
**`data-disabled`**: Present when disabled
**`data-orientation`**: The orientation of the item
**`data-empty`**: Present when the content is empty

**`Content`**

**`data-listbox-content`**: <uid>
**`data-orientation`**: The orientation of the content
**`data-layout`**: 
**`data-empty`**: Present when the content is empty

**`List`**

**`data-listbox-list`**: <uid>
**`data-activedescendant`**: The id the active descendant of the list
**`data-orientation`**: The orientation of the list
**`data-layout`**: 
**`data-empty`**: Present when the content is empty

### CSS Variables

<CssVarTable name="listbox" />

## Accessibility

Adheres to the
[Listbox WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/).

A marquee auto-scrolls content like logos, announcements, or featured items.

## Resources


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



**Features**

- Horizontal and vertical scrolling with RTL support
- Pause on hover and keyboard focus
- Customizable speed, spacing, delay, and loop count
- Auto-fill mode to prevent visible gaps
- Respects `prefers-reduced-motion`

## Installation

Install the marquee package:

```bash
npm install @zag-js/marquee @zag-js/react
# or
yarn add @zag-js/marquee @zag-js/react
```

## Anatomy

Check the marquee anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the marquee package:

```tsx
import * as marquee from "@zag-js/marquee"
```

The marquee package exports two key functions:

- `machine` - State machine logic.
- `connect` - Maps machine state to JSX props and event handlers.

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

Then use the framework integration helpers:

```tsx
import * as marquee from "@zag-js/marquee"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useId } from "react"

const logos = [
  { name: "Microsoft", logo: "🏢" },
  { name: "Apple", logo: "🍎" },
  { name: "Google", logo: "🔍" },
  { name: "Amazon", logo: "📦" },
]

function Marquee() {
  const service = useMachine(marquee.machine, {
    id: useId(),
    autoFill: true,
  })

  const api = marquee.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      {/* Optional: Add fade gradient at start */}
      <div {...api.getEdgeProps({ side: "start" })} />

      <div {...api.getViewportProps()}>
        {/* Render content (original + clones) */}
        {Array.from({ length: api.contentCount }).map((_, index) => (
          <div key={index} {...api.getContentProps({ index })}>
            {logos.map((item, i) => (
              <div key={i} {...api.getItemProps()}>
                <span className="logo">{item.logo}</span>
                <span className="name">{item.name}</span>
              </div>
            ))}
          </div>
        ))}
      </div>

      {/* Optional: Add fade gradient at end */}
      <div {...api.getEdgeProps({ side: "end" })} />
    </div>
  )
}
```

### Auto-filling content

To automatically duplicate content to fill the container and prevent gaps during
animation, set the `autoFill` property in the machine's context to `true`.

```tsx {2}
const service = useMachine(marquee.machine, {
  autoFill: true,
})
```

The `api.contentCount` property tells you the total number of content elements
to render (original + clones). Use this value in your loop:

```tsx
{
  Array.from({ length: api.contentCount }).map((_, index) => (
    <div key={index} {...api.getContentProps({ index })}>
      {/* Your content */}
    </div>
  ))
}
```

> **Note:** The `api.multiplier` property is also available if you need to know
> the duplication factor specifically (number of clones excluding the original).

### Changing the scroll direction

To change the scroll direction, set the `side` property in the machine's context
to one of: `"start"`, `"end"`, `"top"`, or `"bottom"`.

```tsx {2}
const service = useMachine(marquee.machine, {
  side: "end", // scrolls from right to left in LTR
})
```

**Directional behavior:**

- `"start"` — Scrolls from inline-start to inline-end (respects RTL)
- `"end"` — Scrolls from inline-end to inline-start (respects RTL)
- `"top"` — Scrolls from bottom to top (vertical)
- `"bottom"` — Scrolls from top to bottom (vertical)

### Adjusting animation speed

To control how fast the marquee scrolls, set the `speed` property in the
machine's context. The value is in pixels per second.

```tsx {2}
const service = useMachine(marquee.machine, {
  speed: 100, // 100 pixels per second
})
```

**Considerations:**

- Higher values create faster scrolling
- Lower values create slower, more readable scrolling
- Speed is automatically adjusted based on content and container size

### Setting spacing between items

To customize the gap between marquee items, set the `spacing` property in the
machine's context to a valid CSS unit.

```tsx {2}
const service = useMachine(marquee.machine, {
  spacing: "2rem",
})
```

### Reversing the animation direction

To reverse the animation direction without changing the scroll side, set the
`reverse` property in the machine's context to `true`.

```tsx {2}
const service = useMachine(marquee.machine, {
  reverse: true,
})
```

### Pausing on user interaction

To pause the marquee when the user hovers or focuses any element inside it, set
the `pauseOnInteraction` property in the machine's context to `true`.

```tsx {2}
const service = useMachine(marquee.machine, {
  pauseOnInteraction: true,
})
```

This is especially important for accessibility when your marquee contains
interactive elements like links or buttons.

### Setting initial paused state

To start the marquee in a paused state, set the `defaultPaused` property in the
machine's context to `true`.

```tsx {2}
const service = useMachine(marquee.machine, {
  defaultPaused: true,
})
```

### Controlled paused state

Use `paused` and `onPauseChange` to control playback externally.

```tsx
const service = useMachine(marquee.machine, {
  paused,
  onPauseChange(details) {
    setPaused(details.paused)
  },
})
```

### Delaying the animation start

To add a delay before the animation starts, set the `delay` property in the
machine's context to a value in seconds.

```tsx {2}
const service = useMachine(marquee.machine, {
  delay: 2, // 2 second delay
})
```

### Limiting loop iterations

By default, the marquee loops infinitely. To limit the number of loops, set the
`loopCount` property in the machine's context.

```tsx {2}
const service = useMachine(marquee.machine, {
  loopCount: 3, // stops after 3 complete loops
})
```

> Setting `loopCount` to `0` (default) creates an infinite loop.

### Listening for loop completion

When the marquee completes a single loop iteration, the `onLoopComplete`
callback is invoked.

```tsx {2-4}
const service = useMachine(marquee.machine, {
  onLoopComplete() {
    console.log("Completed one loop")
  },
})
```

### Listening for animation completion

When the marquee completes all loops and stops (only for finite loops), the
`onComplete` callback is invoked.

```tsx {2-4}
const service = useMachine(marquee.machine, {
  loopCount: 3,
  onComplete() {
    console.log("Marquee finished all loops")
  },
})
```

### Controlling the marquee programmatically

The marquee API provides methods to control playback:

```tsx
// Pause the marquee
api.pause()

// Resume the marquee
api.resume()

// Toggle pause state
api.togglePause()

// Restart the animation from the beginning
api.restart()
```

### Monitoring pause state changes

When the marquee pause state changes, the `onPauseChange` callback is invoked.

```tsx {2-5}
const service = useMachine(marquee.machine, {
  onPauseChange(details) {
    // details => { paused: boolean }
    console.log("Marquee is now:", details.paused ? "paused" : "playing")
  },
})
```

### Adding fade gradients at edges

To add fade gradients at the edges of the marquee, use the `getEdgeProps`
method:

```tsx
<div {...api.getRootProps()}>
  {/* Fade gradient at start */}
  <div {...api.getEdgeProps({ side: "start" })} />

  <div {...api.getViewportProps()}>{/* Content */}</div>

  {/* Fade gradient at end */}
  <div {...api.getEdgeProps({ side: "end" })} />
</div>
```

Style the edge gradients using CSS:

```css
[data-part="edge"][data-side="start"] {
  width: 100px;
  background: linear-gradient(to right, white, transparent);
}

[data-part="edge"][data-side="end"] {
  width: 100px;
  background: linear-gradient(to left, white, transparent);
}
```

## Styling guide

### Required keyframe animations

For the marquee to work, you **must** include the required keyframe animations
in your CSS. These animations control the scrolling behavior:

```css
@keyframes marqueeX {
  0% {
    transform: translateX(0%);
  }
  100% {
    transform: translateX(var(--marquee-translate));
  }
}

@keyframes marqueeY {
  0% {
    transform: translateY(0%);
  }
  100% {
    transform: translateY(var(--marquee-translate));
  }
}
```

**Important:** The animations use the `--marquee-translate` CSS variable which
is automatically set by the machine based on the `side` and `dir` props. This
enables seamless looping when combined with the cloned content.

### Base content styles

To apply the animations, add these base styles to your content elements:

```css
[data-scope="marquee"][data-part="content"] {
  animation-timing-function: linear;
  animation-duration: var(--marquee-duration);
  animation-delay: var(--marquee-delay);
  animation-iteration-count: var(--marquee-loop-count);
}

[data-part="content"][data-side="start"],
[data-part="content"][data-side="end"] {
  animation-name: marqueeX;
}

[data-part="content"][data-side="top"],
[data-part="content"][data-side="bottom"] {
  animation-name: marqueeY;
}

[data-part="content"][data-reverse] {
  animation-direction: reverse;
}

@media (prefers-reduced-motion: reduce) {
  [data-part="content"] {
    animation: none !important;
  }
}
```

**Note:** The machine automatically handles layout styles (`display`,
`flex-direction`, `flex-shrink`) and performance optimizations
(`backface-visibility`, `will-change`, `transform: translateZ(0)`), so you only
need to add the animation properties.

### CSS variables

The machine automatically sets these CSS variables:

- `--marquee-duration` — Animation duration in seconds
- `--marquee-spacing` — Spacing between items
- `--marquee-delay` — Delay before animation starts
- `--marquee-loop-count` — Number of iterations (or "infinite")
- `--marquee-translate` — Transform value for animations

### Styling parts

Each part includes a `data-part` attribute you can target in CSS.

```css
[data-scope="marquee"][data-part="root"] {
  /* styles for the root container */
}

[data-scope="marquee"][data-part="viewport"] {
  /* styles for the viewport */
}

[data-scope="marquee"][data-part="content"] {
  /* styles for each content container */
}

[data-scope="marquee"][data-part="item"] {
  /* styles for individual marquee items */
}

[data-scope="marquee"][data-part="edge"] {
  /* styles for fade edge gradients */
}
```

### Orientation-specific styles

The marquee adds a `data-orientation` attribute for orientation-specific
styling:

```css
[data-part="root"][data-orientation="horizontal"] {
  /* styles for horizontal marquee */
}

[data-part="root"][data-orientation="vertical"] {
  /* styles for vertical marquee */
}
```

### Paused state

When the marquee is paused, a `data-paused` attribute is set on the root:

```css
[data-part="root"][data-paused] {
  /* styles for paused state */
}
```

### Clone identification

Cloned content elements have a `data-clone` attribute for styling duplicates
differently:

```css
[data-part="content"][data-clone] {
  /* styles for cloned content */
}
```

### Side-specific styles

Each content element has a `data-side` attribute indicating the scroll
direction:

```css
[data-part="content"][data-side="start"] {
  /* styles for content scrolling to inline-end */
}

[data-part="content"][data-side="end"] {
  /* styles for content scrolling to inline-start */
}

[data-part="content"][data-side="top"] {
  /* styles for content scrolling up */
}

[data-part="content"][data-side="bottom"] {
  /* styles for content scrolling down */
}
```

## Methods and Properties

### Machine Context

The marquee machine exposes the following context properties:

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the marquee. Useful for composition.

**`translations`**
Type: `IntlTranslations | undefined`
Description: The localized messages to use.

**`side`**
Type: `Side | undefined`
Description: The side/direction the marquee scrolls towards.

**`speed`**
Type: `number | undefined`
Description: The speed of the marquee animation in pixels per second.

**`delay`**
Type: `number | undefined`
Description: The delay before the animation starts (in seconds).

**`loopCount`**
Type: `number | undefined`
Description: The number of times to loop the animation (0 = infinite).

**`spacing`**
Type: `string | undefined`
Description: The spacing between marquee items.

**`autoFill`**
Type: `boolean | undefined`
Description: Whether to automatically duplicate content to fill the container.

**`pauseOnInteraction`**
Type: `boolean | undefined`
Description: Whether to pause the marquee on user interaction (hover, focus).

**`reverse`**
Type: `boolean | undefined`
Description: Whether to reverse the animation direction.

**`paused`**
Type: `boolean | undefined`
Description: Whether the marquee is paused.

**`defaultPaused`**
Type: `boolean | undefined`
Description: Whether the marquee is paused by default.

**`onPauseChange`**
Type: `((details: PauseStatusDetails) => void) | undefined`
Description: Function called when the pause status changes.

**`onLoopComplete`**
Type: `(() => void) | undefined`
Description: Function called when the marquee completes one loop iteration.

**`onComplete`**
Type: `(() => void) | undefined`
Description: Function called when the marquee completes all loops and stops.
Only fires for finite loops (loopCount > 0).

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

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

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

### Machine API

The marquee `api` exposes the following methods:

**`paused`**
Type: `boolean`
Description: Whether the marquee is currently paused.

**`orientation`**
Type: `"horizontal" | "vertical"`
Description: The current orientation of the marquee.

**`side`**
Type: `Side`
Description: The current side/direction of the marquee.

**`multiplier`**
Type: `number`
Description: The multiplier for auto-fill. Indicates how many times to duplicate content.
When autoFill is enabled and content is smaller than container, this returns
the number of additional copies needed. Otherwise returns 1.

**`contentCount`**
Type: `number`
Description: The total number of content elements to render (original + clones).
Use this value when rendering your content in a loop.

**`pause`**
Type: `VoidFunction`
Description: Pause the marquee animation.

**`resume`**
Type: `VoidFunction`
Description: Resume the marquee animation.

**`togglePause`**
Type: `VoidFunction`
Description: Toggle the pause state.

**`restart`**
Type: `VoidFunction`
Description: Restart the marquee animation from the beginning.

### Data Attributes

**`Root`**

**`data-marquee-root`**: <uid>
**`data-state`**: "paused" | "idle"
**`data-orientation`**: The orientation of the marquee
**`data-paused`**: Present when paused

**`Viewport`**

**`data-marquee-viewport`**: <uid>
**`data-orientation`**: The orientation of the viewport
**`data-side`**: The side of the trigger that the viewport is positioned on

**`Content`**

**`data-marquee-content`**: <uid>
**`data-index`**: The index of the item
**`data-orientation`**: The orientation of the content
**`data-side`**: The side of the trigger that the content is positioned on
**`data-reverse`**: 
**`data-clone`**: 

**`Edge`**

**`data-marquee-edge`**: <uid>
**`data-side`**: The side of the trigger that the edge is positioned on
**`data-orientation`**: The orientation of the edge

### CSS Variables

<CssVarTable name="marquee" />

## Accessibility

### ARIA attributes

The marquee component includes proper ARIA attributes:

- `role="region"` with `aria-roledescription="marquee"` for proper semantics
- `aria-label` describing the marquee content
- `aria-hidden="true"` on cloned content to prevent duplicate announcements

### Keyboard Interactions

When `pauseOnInteraction` is enabled:

- **Focus** — Pauses the marquee when any child element receives focus
- **Blur** — Resumes the marquee when focus leaves the component

### Motion preferences

The marquee automatically respects the user's motion preferences via the
`prefers-reduced-motion` media query, disabling animations when requested.

### Best practices

1. **Use descriptive labels** — Set a meaningful `aria-label` via the
   `translations.root` property:

   ```tsx
   const service = useMachine(marquee.machine, {
     translations: {
       root: "Featured partner logos", // instead of generic "Marquee content"
     },
   })
   ```

2. **Enable pause on interaction** — Essential for accessibility when content
   contains links or important information:

   ```tsx
   const service = useMachine(marquee.machine, {
     pauseOnInteraction: true,
   })
   ```

3. **Consider infinite loops carefully** — Infinite animations can cause
   discomfort for users with vestibular disorders. Consider providing pause
   controls or limiting loop iterations for critical content.

4. **Decorative vs. informational** — Marquees work best for decorative content
   (logos, testimonials). For important information, consider static displays or
   user-controlled carousels instead.

An accessible dropdown and context menu that is used to display a list of
actions or options that a user can choose.

## Resources


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



**Features**

- Supports items, labels, groups of items
- Focus is fully managed using `aria-activedescendant` pattern
- Typeahead to allow focusing items by typing text
- Keyboard navigation support including arrow keys, home/end, page up/down
- Supports multiple triggers sharing a single menu instance

## Installation

Install the menu package:

```bash
npm install @zag-js/menu @zag-js/react
# or
yarn add @zag-js/menu @zag-js/react
```

## Anatomy

Check the menu anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the menu package:

```tsx
import * as menu from "@zag-js/menu"
```

The menu package exports two key functions:

- `machine` - State machine logic.
- `connect` - Maps machine state to JSX props and event handlers.

> Pass a unique `id` to `useMachine` so generated element ids stay predictable.

Then use the framework integration helpers:

```tsx
import * as menu from "@zag-js/menu"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useId } from "react"

export function Menu() {
  const service = useMachine(menu.machine, { id: useId() })

  const api = menu.connect(service, normalizeProps)

  return (
    <div>
      <button {...api.getTriggerProps()}>
        Actions <span {...api.getIndicatorProps()}>▾</span>
      </button>
      <div {...api.getPositionerProps()}>
        <ul {...api.getContentProps()}>
          <li {...api.getItemProps({ value: "edit" })}>Edit</li>
          <li {...api.getItemProps({ value: "duplicate" })}>Duplicate</li>
          <li {...api.getItemProps({ value: "delete" })}>Delete</li>
          <li {...api.getItemProps({ value: "export" })}>Export...</li>
        </ul>
      </div>
    </div>
  )
}
```

### Listening for item selection

When a menu item is clicked, the `onSelect` callback is invoked.

```tsx {3-6}
const service = useMachine(menu.machine, {
  onSelect(details) {
    // details => { value: string }
    console.log("selected value is ", details.value)
  },
})
```

### Listening for open state changes

When a menu is opened or closed, the `onOpenChange` callback is invoked.

```tsx {3-6}
const service = useMachine(menu.machine, {
  onOpenChange(details) {
    // details => { open: boolean }
    console.log("open state is ", details.open)
  },
})
```

### Controlled open state

Use `open` and `onOpenChange` to control visibility externally.

```tsx
const service = useMachine(menu.machine, {
  open,
  onOpenChange(details) {
    setOpen(details.open)
  },
})
```

### Listening for highlighted items

Use `onHighlightChange` to react when highlighted item changes.

```tsx
const service = useMachine(menu.machine, {
  onHighlightChange(details) {
    // details => { highlightedValue: string | null }
    console.log(details.highlightedValue)
  },
})
```

### Setting initial highlighted item

Use `defaultHighlightedValue` to set the initially highlighted item.

```tsx
const service = useMachine(menu.machine, {
  defaultHighlightedValue: "settings",
})
```

### Grouping menu items

When you have many menu items, it can help to group related options:

- Wrap the menu items within an element.
- Spread `api.getGroupProps(...)` props on the group element, providing an `id`.
- Render a label for the menu group, providing the `id` of the group element.

```tsx
//...
<div {...api.getContentProps()}>
  {/* ... */}
  <hr {...api.getSeparatorProps()} />
  <p {...api.getItemGroupLabelProps({ htmlFor: "account" })}>Accounts</p>
  <div {...api.getItemGroupProps({ id: "account" })}>
    <button {...api.getItemProps({ value: "account-1" })}>Account 1</button>
    <button {...api.getItemProps({ value: "account-2" })}>Account 2</button>
  </div>
</div>
//...
```

### Checkbox and Radio option items

To use checkbox or radio option items, you'll need to:

- Add a `value` property to the machine's context whose value is an object
  describing the state of the option items.
- Use the `api.getOptionItemProps(...)` function to get the props for the option
  item.

A common requirement for the option item that you pass the `name`, `value` and
`type` properties.

- `type` — The type of option item. Either `"checkbox"` or `"radio"`.
- `value` — The value of the option item.
- `checked` — The checked state of the option item.
- `onCheckedChange` — The callback to invoke when the checked state changes.

```tsx
import * as menu from "@zag-js/menu"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useState } from "react"

const data = {
  order: [
    { label: "Ascending", value: "asc" },
    { label: "Descending", value: "desc" },
    { label: "None", value: "none" },
  ],
  type: [
    { label: "Email", value: "email" },
    { label: "Phone", value: "phone" },
    { label: "Address", value: "address" },
  ],
}

export function Menu() {
  const [order, setOrder] = useState("")
  const [type, setType] = useState([])

  const service = useMachine(menu.machine, { id: "1" })

  const api = menu.connect(service, normalizeProps)

  const radios = data.order.map((item) => ({
    type: "radio",
    name: "order",
    value: item.value,
    label: item.label,
    checked: order === item.value,
    onCheckedChange: (checked) => setOrder(checked ? item.value : ""),
  }))

  const checkboxes = data.type.map((item) => ({
    type: "checkbox",
    name: "type",
    value: item.value,
    label: item.label,
    checked: type.includes(item.value),
    onCheckedChange: (checked) =>
      setType((prev) =>
        checked ? [...prev, item.value] : prev.filter((x) => x !== item.value),
      ),
  }))

  return (
    <>
      <button {...api.getTriggerProps()}>Trigger</button>
      <div {...api.getPositionerProps()}>
        <div {...api.getContentProps()}>
          {radios.map((item) => {
            return (
              <div key={item.value} {...api.getOptionItemProps(item)}>
                <span {...api.getItemIndicatorProps(item)}>✅</span>
                <span {...api.getItemTextProps(item)}>{item.label}</span>
              </div>
            )
          })}
          <hr {...api.getSeparatorProps()} />
          {checkboxes.map((item) => {
            return (
              <div key={item.value} {...api.getOptionItemProps(item)}>
                <span {...api.getItemIndicatorProps(item)}>✅</span>
                <span {...api.getItemTextProps(item)}>{item.label}</span>
              </div>
            )
          })}
        </div>
      </div>
    </>
  )
}
```

### Default open state

Use `defaultOpen` to start with the menu opened in uncontrolled mode.

```tsx
const service = useMachine(menu.machine, {
  defaultOpen: true,
})
```

### Keeping menu open after selection

Set `closeOnSelect` to `false` to keep the menu open after selecting an item.

```tsx
const service = useMachine(menu.machine, {
  closeOnSelect: false,
})
```

### Positioning the menu

Use `positioning` to configure menu placement.

```tsx
const service = useMachine(menu.machine, {
  positioning: { placement: "bottom-start" },
})
```

### Multiple triggers

A single menu instance can be shared across multiple trigger elements. Pass a
`value` to `getTriggerProps` to identify each trigger.

```tsx
const service = useMachine(menu.machine, {
  onTriggerValueChange({ value }) {
    console.log("active trigger:", value)
  },
})

const api = menu.connect(service, normalizeProps)

return (
  <>
    <button {...api.getTriggerProps({ value: "file" })}>File</button>
    <button {...api.getTriggerProps({ value: "edit" })}>Edit</button>
    <div {...api.getPositionerProps()}>
      <div {...api.getContentProps()}>
        {/* Menu items based on api.triggerValue */}
      </div>
    </div>
  </>
)
```

When the menu is open and a different trigger is activated, it repositions
without closing. `aria-expanded` is scoped to the active trigger, and focus
returns to the correct trigger on close.

### Labeling the menu without visible text

If you do not render a visible label, provide `aria-label`.

```tsx
const service = useMachine(menu.machine, {
  "aria-label": "Actions",
})
```

## Styling guide

Each menu part includes a `data-part` attribute you can target in CSS.

### Open and closed state

When the menu is open or closed, the content and trigger parts will have the
`data-state` attribute.

```css
[data-part="content"][data-state="open|closed"] {
  /* styles for open or closed state */
}

[data-part="trigger"][data-state="open|closed"] {
  /* styles for open or closed state */
}
```

### Highlighted item state

When an item is highlighted, via keyboard navigation or pointer, it is given a
`data-highlighted` attribute.

```css
[data-part="item"][data-highlighted] {
  /* styles for highlighted state */
}

[data-part="item"][data-type="radio|checkbox"][data-highlighted] {
  /* styles for highlighted state */
}
```

### Disabled item state

When an item or an option item is disabled, it is given a `data-disabled`
attribute.

```css
[data-part="item"][data-disabled] {
  /* styles for disabled state */
}

[data-part="item"][data-type="radio|checkbox"][data-disabled] {
  /* styles for disabled state */
}
```

### Using arrows

When using arrows within the menu, you can style it using CSS variables.

```css
[data-part="arrow"] {
  --arrow-size: 20px;
  --arrow-background: red;
}
```

### Checked option item state

When an option item is checked, it is given a `data-state` attribute.

```css
[data-part="item"][data-type="radio|checkbox"][data-state="checked"] {
  /* styles for checked state */
}
```

## Methods and Properties

### Machine Context

The menu machine exposes the following context properties:

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the menu. Useful for composition.

**`defaultHighlightedValue`**
Type: `string | null | undefined`
Description: The initial highlighted value of the menu item when rendered.
Use when you don't need to control the highlighted value of the menu item.

**`highlightedValue`**
Type: `string | null | undefined`
Description: The controlled highlighted value of the menu item.

**`onHighlightChange`**
Type: `((details: HighlightChangeDetails) => void) | undefined`
Description: Function called when the highlighted menu item changes.

**`onSelect`**
Type: `((details: SelectionDetails) => void) | undefined`
Description: Function called when a menu item is selected.

**`anchorPoint`**
Type: `Point | null | undefined`
Description: The positioning point for the menu. Can be set by the context menu trigger or the button trigger.

**`loopFocus`**
Type: `boolean | undefined`
Description: Whether to loop the keyboard navigation.

**`positioning`**
Type: `PositioningOptions | undefined`
Description: The options used to dynamically position the menu

**`closeOnSelect`**
Type: `boolean | undefined`
Description: Whether to close the menu when an option is selected

**`aria-label`**
Type: `string | undefined`
Description: The accessibility label for the menu

**`open`**
Type: `boolean | undefined`
Description: The controlled open state of the menu

**`onOpenChange`**
Type: `((details: OpenChangeDetails) => void) | undefined`
Description: Function called when the menu opens or closes

**`defaultOpen`**
Type: `boolean | undefined`
Description: The initial open state of the menu when rendered.
Use when you don't need to control the open state of the menu.

**`typeahead`**
Type: `boolean | undefined`
Description: Whether the pressing printable characters should trigger typeahead navigation

**`composite`**
Type: `boolean | undefined`
Description: Whether the menu is a composed with other composite widgets like a combobox or tabs

**`navigate`**
Type: `((details: NavigateDetails) => void) | null | undefined`
Description: Function to navigate to the selected item if it's an anchor element

**`triggerValue`**
Type: `string | null | undefined`
Description: The controlled trigger value

**`defaultTriggerValue`**
Type: `string | null | undefined`
Description: The initial trigger value when rendered.
Use when you don't need to control the trigger value.

**`onTriggerValueChange`**
Type: `((details: TriggerValueChangeDetails) => void) | undefined`
Description: Function called when the trigger value changes.

**`menubar`**
Type: `MenubarContext | undefined`
Description: Config provided by a parent menubar. When set, this menu acts as a menubar menu:
its trigger becomes a `menuitem` and it coordinates open/close/focus with sibling menus.
Adapters typically populate this from a menubar context. Omit it for submenus.

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

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

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

### Machine API

The menu `api` exposes the following methods:

**`open`**
Type: `boolean`
Description: Whether the menu is open

**`setOpen`**
Type: `(open: boolean) => void`
Description: Function to open or close the menu

**`triggerValue`**
Type: `string | null`
Description: The trigger value

**`setTriggerValue`**
Type: `(value: string | null) => void`
Description: Function to set the trigger value

**`highlightedValue`**
Type: `string | null`
Description: The id of the currently highlighted menuitem

**`setHighlightedValue`**
Type: `(value: string) => void`
Description: Function to set the highlighted menuitem

**`setParent`**
Type: `(parent: MenuService) => void`
Description: Function to register a parent menu. This is used for submenus

**`setChild`**
Type: `(child: MenuService) => void`
Description: Function to register a child menu. This is used for submenus

**`reposition`**
Type: `(options?: Partial<PositioningOptions>) => void`
Description: Function to reposition the popover

**`getOptionItemState`**
Type: `(props: OptionItemProps) => OptionItemState`
Description: Returns the state of the option item

**`getItemState`**
Type: `(props: ItemProps) => ItemState`
Description: Returns the state of the menu item

**`addItemListener`**
Type: `(props: ItemListenerProps) => VoidFunction | undefined`
Description: Setup the custom event listener for item selection event

### Data Attributes

**`ContextTrigger`**

**`data-menu-context-trigger`**: <uid>
**`data-value`**: The value of the item
**`data-current`**: Present when current
**`data-state`**: "open" | "closed"

**`Trigger`**

**`data-menu-trigger`**: <uid>
**`data-disabled`**: Present when disabled
**`data-placement`**: The placement of the trigger
**`data-side`**: The side of the trigger that the trigger is positioned on
**`data-value`**: The value of the item
**`data-current`**: Present when current
**`data-controls`**: 
**`data-state`**: "open" | "closed"

**`Indicator`**

**`data-menu-indicator`**: <uid>
**`data-state`**: "open" | "closed"

**`Content`**

**`data-menu-content`**: <uid>
**`data-state`**: "open" | "closed"
**`data-nested`**: menu
**`data-has-nested`**: menu
**`data-placement`**: The placement of the content
**`data-side`**: The side of the trigger that the content is positioned on

**`Item`**

**`data-menu-item`**: <uid>
**`data-disabled`**: Present when disabled
**`data-highlighted`**: Present when highlighted
**`data-value`**: The value of the item
**`data-valuetext`**: The human-readable value

**`OptionItem`**

**`data-menu-option-item`**: <uid>
**`data-type`**: The type of the item
**`data-value`**: The value of the item
**`data-state`**: "checked" | "unchecked"
**`data-disabled`**: Present when disabled
**`data-highlighted`**: Present when highlighted
**`data-valuetext`**: The human-readable value

**`ItemIndicator`**

**`data-menu-item-indicator`**: <uid>
**`data-disabled`**: Present when disabled
**`data-highlighted`**: Present when highlighted
**`data-state`**: "checked"

**`ItemText`**

**`data-menu-item-text`**: <uid>
**`data-disabled`**: Present when disabled
**`data-highlighted`**: Present when highlighted
**`data-state`**: "checked"

### CSS Variables

<CssVarTable name="menu" />

## Accessibility

Uses
[aria-activedescendant](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/examples/menu-button-actions-active-descendant/)
pattern to manage focus movement among menu items.

### Keyboard Interactions

**`Space`**
Description: Activates/Selects the highlighted item

**`Enter`**
Description: Activates/Selects the highlighted item

**`ArrowDown`**
Description: Highlights the next item in the menu

**`ArrowUp`**
Description: Highlights the previous item in the menu

**`ArrowRight + ArrowLeft`**
Description: <span>When focus is on trigger, opens or closes the submenu depending on reading direction.</span>

**`Esc`**
Description: Closes the menu and moves focus to the trigger

An accessible dropdown and context menu that is used to display a list of
actions or options that a user can choose.

## Resources


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



**Features**

- Supports items, labels, groups of items
- Focus is fully managed using `aria-activedescendant` pattern
- Typeahead to allow focusing items by typing text
- Keyboard navigation support including arrow keys, home/end, page up/down

## Installation

Install the menu package:

```bash
npm install @zag-js/menu @zag-js/react
# or
yarn add @zag-js/menu @zag-js/react
```

## Anatomy

Check the menu anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the menu package:

```tsx
import * as menu from "@zag-js/menu"
```

The menu package exports two key functions:

- `machine` - Behavior logic for the menu.
- `connect` - Maps behavior to JSX props and event handlers.

> Pass a unique `id` to `useMachine` so generated element ids stay predictable.

Then use the framework integration helpers:

- Destructure the service returned from `useMachine`.
- Use the exposed `setParent` and `setChild` functions provided by the menu's
  connect function to assign the parent and child menus respectively.
- Create trigger items using `api.getTriggerItemProps(...)`.

When building nested menus, you'll need to use:

- `setParent(...)` - Registers the parent menu on the child menu.
- `setChild(...)` - Registers the child menu on the parent menu.

```tsx
import * as menu from "@zag-js/menu"
import { useMachine, normalizeProps, Portal } from "@zag-js/react"
import { useEffect, useId } from "react"

export function NestedMenu() {
  // Level 1 - File Menu
  const fileMenuService = useMachine(menu.machine, {
    id: useId(),
    "aria-label": "File",
  })

  const fileMenu = menu.connect(fileMenuService, normalizeProps)

  // Level 2 - Share Menu
  const shareMenuService = useMachine(menu.machine, {
    id: useId(),
    "aria-label": "Share",
  })

  const shareMenu = menu.connect(shareMenuService, normalizeProps)

  useEffect(() => {
    setTimeout(() => {
      fileMenu.setChild(shareMenuService)
      shareMenu.setParent(fileMenuService)
    })
  }, [])

  // Share menu trigger
  const shareMenuTriggerProps = fileMenu.getTriggerItemProps(shareMenu)

  return (
    <>
      <button {...fileMenu.getTriggerProps()}>Click me</button>

      <Portal>
        <div {...fileMenu.getPositionerProps()}>
          <ul {...fileMenu.getContentProps()}>
            <li {...fileMenu.getItemProps({ value: "new-tab" })}>New tab</li>
            <li {...fileMenu.getItemProps({ value: "new-win" })}>New window</li>
            <li {...shareMenuTriggerProps}>Share</li>
            <li {...fileMenu.getItemProps({ value: "print" })}>Print...</li>
            <li {...fileMenu.getItemProps({ value: "help" })}>Help</li>
          </ul>
        </div>
      </Portal>

      <Portal>
        <div {...shareMenu.getPositionerProps()}>
          <ul {...shareMenu.getContentProps()}>
            <li {...shareMenu.getItemProps({ value: "messages" })}>Messages</li>
            <li {...shareMenu.getItemProps({ value: "airdrop" })}>Airdrop</li>
            <li {...shareMenu.getItemProps({ value: "whatsapp" })}>WhatsApp</li>
          </ul>
        </div>
      </Portal>
    </>
  )
}
```

### Controlling open state

Use `open` and `onOpenChange` to control the open state.

```tsx
const service = useMachine(menu.machine, {
  open,
  onOpenChange(details) {
    // details => { open: boolean }
    setOpen(details.open)
  },
})
```

### Default open state

Use `defaultOpen` for an uncontrolled initial state.

```tsx
const service = useMachine(menu.machine, {
  defaultOpen: true,
})
```

### Listening for highlighted changes

Use `onHighlightChange` to react when keyboard or pointer highlight changes.

```tsx
const service = useMachine(menu.machine, {
  onHighlightChange(details) {
    // details => { highlightedValue: string | null }
    console.log(details.highlightedValue)
  },
})
```

### Setting the initial highlighted item

Use `defaultHighlightedValue` to set the initially highlighted menu item.

```tsx
const service = useMachine(menu.machine, {
  defaultHighlightedValue: "copy",
})
```

### Listening for item selection

Use `onSelect` to react when an item is selected.

```tsx
const service = useMachine(menu.machine, {
  onSelect(details) {
    // details => { value: string }
    console.log(details.value)
  },
})
```

### Positioning submenus

Use `positioning` to configure submenu placement.

```tsx
const service = useMachine(menu.machine, {
  positioning: { placement: "right-start" },
})
```

## Styling guide

Each menu part includes a `data-part` attribute you can target in CSS.

### Highlighted item state

When an item is highlighted, via keyboard navigation or pointer, it is given a
`data-highlighted` attribute.

```css
[data-part="item"][data-highlighted] {
  /* styles for highlighted state */
}

[data-part="item"][data-type="radio|checkbox"][data-highlighted] {
  /* styles for highlighted state */
}
```

### Disabled item state

When an item or an option item is disabled, it is given a `data-disabled`
attribute.

```css
[data-part="item"][data-disabled] {
  /* styles for disabled state */
}

[data-part="item"][data-type="radio|checkbox"][data-disabled] {
  /* styles for disabled state */
}
```

### Using arrows

When using arrows within the menu, you can style it using CSS variables.

```css
[data-part="arrow"] {
  --arrow-size: 20px;
  --arrow-background: red;
}
```

### Checked option item state

When an option item is checked, it is given a `data-state` attribute.

```css
[data-part="item"][data-type="radio|checkbox"][data-state="checked"] {
  /* styles for checked state */
}
```

## Methods and Properties

### Machine Context

The menu machine exposes the following context properties:

<ContextTable name="menu" />

### Machine API

The menu `api` exposes the following methods:

<ApiTable name="menu" />

### Data Attributes

<DataAttrTable name="menu" />

### CSS Variables

<CssVarTable name="menu" />

## Accessibility

Uses
[aria-activedescendant](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/examples/menu-button-actions-active-descendant/)
pattern to manage focus movement among menu items.

### Keyboard Interactions

**`Space`**
Description: Opens/closes the nested menu.

**`Enter`**
Description: Opens/closes the nested menu.

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

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

**`ArrowRight`**
Description: Opens the nested menu.

**`ArrowLeft`**
Description: Closes the nested menu.

**`Esc`**
Description: Closes the nested menu and moves focus to the parent menu item.

A menubar groups several menus — like the File / Edit / View bar in a desktop
app — into a single widget. Each menu is a regular Zag.js menu; the menubar
coordinates focus and open state between them.

## Resources


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



**Features**

- Acts as a single tab stop, with arrow keys moving focus between menus.
- Once a menu is open, hovering or arrowing to a sibling switches to it without
  a click.
- Typeahead to jump to a menu by typing its label.
- Works with nested submenus.
- Horizontal or vertical orientation.

## Installation

Install the menubar package. You'll use it alongside `@zag-js/menu`.

```bash
npm install @zag-js/menubar @zag-js/menu @zag-js/react
# or
yarn add @zag-js/menubar @zag-js/menu @zag-js/react
```

## Usage

A menubar is made of two machines: one `menubar` machine for the bar, and one
`menu` machine for each top-level menu.

```tsx
import * as menu from "@zag-js/menu"
import * as menubar from "@zag-js/menubar"
```

The menubar gives each menu a small config object through
`api.getMenuContext()`. Pass it to the menu's `menubar` prop — that's what makes
the menu behave as part of the bar instead of a standalone dropdown. A context
is the easiest way to thread it down:

```tsx
const MenubarContext = createContext<menu.MenubarContext | undefined>(undefined)

function Menu(props: { id: string; label: string; items: string[] }) {
  const menubarContext = useContext(MenubarContext)
  const service = useMachine(menu.machine, {
    id: props.id,
    menubar: menubarContext,
  })
  const api = menu.connect(service, normalizeProps)

  return (
    <>
      <button {...api.getTriggerProps()}>{props.label}</button>
      {api.open && (
        <Portal>
          <div {...api.getPositionerProps()}>
            <ul {...api.getContentProps()}>
              {props.items.map((item) => (
                <li key={item} {...api.getItemProps({ value: item })}>
                  {item}
                </li>
              ))}
            </ul>
          </div>
        </Portal>
      )}
    </>
  )
}

function Menubar() {
  const service = useMachine(menubar.machine, { id: useId() })
  const api = menubar.connect(service, normalizeProps)

  return (
    <MenubarContext.Provider value={api.getMenuContext()}>
      <div {...api.getRootProps()}>
        <Menu id="file" label="File" items={["New", "Open", "Save"]} />
        <Menu id="edit" label="Edit" items={["Undo", "Redo"]} />
        <Menu id="view" label="View" items={["Zoom In", "Zoom Out"]} />
      </div>
    </MenubarContext.Provider>
  )
}
```

The config carries the menubar's `rootId`, `activeId`, `disabled`, and
`orientation`, so a menu always reflects the bar it belongs to.

### Nested submenus

A submenu inside a menubar menu works like any nested menu — link it to its
parent with `setChild` / `setParent` and render its trigger with
`getTriggerItemProps`.

```tsx
const parent = useMachine(menu.machine, { id: "edit", menubar: menubarContext })
const sub = useMachine(menu.machine, { id: "find" })

useEffect(() => {
  parentApi.setChild(sub)
  subApi.setParent(parent)
}, [])
```

Only the top-level menu gets the `menubar` prop. The submenu doesn't — it's a
child of the menu, not of the bar.

With the keyboard, `ArrowRight` on a submenu trigger opens the submenu, while
`ArrowRight` on a regular item moves to the next menu in the bar.

### Vertical orientation

Set `orientation` to `"vertical"` to stack the triggers. Use `positioning` so
the menus open to the side instead of below.

```tsx
const service = useMachine(menubar.machine, {
  id: useId(),
  orientation: "vertical",
})

// each menu
const service = useMachine(menu.machine, {
  id,
  menubar: menubarContext,
  positioning: { placement: "right-start" },
})
```

In a vertical menubar, `Up` / `Down` move between triggers, `ArrowRight` opens a
menu, and `ArrowLeft` closes it back to its trigger.

### Disabling the menubar

Set `disabled` on the menubar to disable every trigger at once.

```tsx
const service = useMachine(menubar.machine, {
  id: useId(),
  disabled: true,
})
```

### Looping focus

By default, arrowing past the first or last trigger wraps around. Set
`loopFocus` to `false` to stop at the ends.

```tsx
const service = useMachine(menubar.machine, {
  id: useId(),
  loopFocus: false,
})
```

## Styling guide

The menubar root exposes a few attributes you can target in CSS.

```css
[data-part="root"][data-orientation="horizontal|vertical"] {
  /* styles per orientation */
}

[data-part="root"][data-disabled] {
  /* styles when the whole bar is disabled */
}

/* present while any menu in the bar is open */
[data-part="root"][data-has-open-menu="true"] {
  /* ... */
}
```

Triggers are owned by the menu, so style them with the menu's `trigger` part.
See the [menu styling guide](/components/menu#styling-guide).

## Methods and Properties

### Machine Context

The menubar machine exposes the following context properties:

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the menubar. Useful for composition.

**`orientation`**
Type: `Orientation | undefined`
Description: The orientation of the menubar.

**`loopFocus`**
Type: `boolean | undefined`
Description: Whether to loop the keyboard navigation across the triggers.

**`disabled`**
Type: `boolean | undefined`
Description: Whether the menubar (and all its menu triggers) is disabled.

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

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

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

### Machine API

The menubar `api` exposes the following methods:

**`hasOpenMenu`**
Type: `boolean`
Description: Whether any menu within the menubar is open.

**`orientation`**
Type: `Orientation`
Description: The orientation of the menubar.

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

**`getMenuContext`**
Type: `() => MenubarMenuContext`
Description: Returns the config to pass to each top-level menu's `menubar` prop. Adapters
usually expose this via a context so nested `<Menu>`s can read it.

### Data Attributes

**`Root`**

**`data-menubar-root`**: <uid>
**`data-orientation`**: The orientation of the menubar
**`data-disabled`**: Present when disabled
**`data-has-open-menu`**: Present when a menu in the menubar is open

## Accessibility

Follows the
[WAI-ARIA Menubar pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/) —
the bar is a single tab stop and arrow keys move focus between menus.

### Keyboard Interactions

**`ArrowRight + ArrowLeft`**
Description: In a horizontal menubar, moves focus to the next/previous menu. If a menu is open, opens the sibling menu.

**`ArrowDown + ArrowUp`**
Description: In a vertical menubar, moves focus to the next/previous menu. In a horizontal menubar, opens the focused menu.

**`Enter + Space`**
Description: Opens the focused menu and highlights its first item.

**`Home + End`**
Description: Moves focus to the first/last menu.

**`Esc`**
Description: Closes the open menu and returns focus to its trigger.

An accessible dropdown and context menu that is used to display a list of
actions or options that a user can choose when a trigger element is
right-clicked or long pressed.

## Resources


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



**Features**

- Supports items, labels, groups of items
- Focus is fully managed using `aria-activedescendant` pattern
- Typeahead to allow focusing items by typing text
- Keyboard navigation support including arrow keys, home/end, page up/down

## Installation

Install the menu package:

```bash
npm install @zag-js/menu @zag-js/react
# or
yarn add @zag-js/menu @zag-js/react
```

## Anatomy

Check the menu anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the menu package:

```tsx
import * as menu from "@zag-js/menu"
```

The menu package exports two key functions:

- `machine` - Behavior logic for the menu.
- `connect` - Maps behavior to JSX props and event handlers.

> Pass a unique `id` to `useMachine` so generated element ids stay predictable.

Then use the framework integration helpers:

To show the menu when a trigger element is right-clicked, use
`api.getContextTriggerProps()`.

Context menus also open during a long-press of roughly `700ms` when the pointer
is pen or touch.

```tsx
import * as menu from "@zag-js/menu"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useId } from "react"

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

  return (
    <div>
      <div {...api.getContextTriggerProps()}>
        <div>Open context menu</div>
      </div>
      <div {...api.getPositionerProps()}>
        <ul {...api.getContentProps()}>
          <li {...api.getItemProps({ value: "edit" })}>Edit</li>
          <li {...api.getItemProps({ value: "duplicate" })}>Duplicate</li>
          <li {...api.getItemProps({ value: "delete" })}>Delete</li>
          <li {...api.getItemProps({ value: "export" })}>Export...</li>
        </ul>
      </div>
    </div>
  )
}
```

### Default open state

Use `defaultOpen` for an uncontrolled initial state.

```tsx
const service = useMachine(menu.machine, {
  defaultOpen: true,
})
```

### Controlling open state

Use `open` and `onOpenChange` to control the open state.

```tsx
const service = useMachine(menu.machine, {
  open,
  onOpenChange(details) {
    // details => { open: boolean }
    setOpen(details.open)
  },
})
```

### Listening for highlighted items

Use `onHighlightChange` to react when keyboard or pointer highlight changes.

```tsx
const service = useMachine(menu.machine, {
  onHighlightChange(details) {
    // details => { highlightedValue: string | null }
    console.log(details.highlightedValue)
  },
})
```

### Listening for item selection

Use `onSelect` to react when an item is selected.

```tsx
const service = useMachine(menu.machine, {
  onSelect(details) {
    // details => { value: string }
    console.log(details.value)
  },
})
```

### Positioning the menu

Use `positioning` to configure menu placement.

```tsx
const service = useMachine(menu.machine, {
  positioning: { placement: "right-start" },
})
```

### Keeping the menu open after selection

Set `closeOnSelect` to `false` to keep the menu open after selecting an item.

```tsx
const service = useMachine(menu.machine, {
  closeOnSelect: false,
})
```

## Styling guide

Each menu part includes a `data-part` attribute you can target in CSS.

### Highlighted item state

When an item is highlighted, via keyboard navigation or pointer, it is given a
`data-highlighted` attribute.

```css
[data-part="item"][data-highlighted] {
  /* styles for highlighted state */
}

[data-part="item"][data-type="radio|checkbox"][data-highlighted] {
  /* styles for highlighted state */
}
```

### Disabled item state

When an item or an option item is disabled, it is given a `data-disabled`
attribute.

```css
[data-part="item"][data-disabled] {
  /* styles for disabled state */
}

[data-part="item"][data-type="radio|checkbox"][data-disabled] {
  /* styles for disabled state */
}
```

### Using arrows

When using arrows within the menu, you can style it using CSS variables.

```css
[data-part="arrow"] {
  --arrow-size: 20px;
  --arrow-background: red;
}
```

### Checked option item state

When an option item is checked, it is given a `data-state` attribute.

```css
[data-part="item"][data-type="radio|checkbox"][data-state="checked"] {
  /* styles for checked state */
}
```

## Methods and Properties

### Machine Context

The menu machine exposes the following context properties:

<ContextTable name="menu" />

### Machine API

The menu `api` exposes the following methods:

<ApiTable name="menu" />

### Data Attributes

<DataAttrTable name="menu" />

### CSS Variables

<CssVarTable name="menu" />

## Accessibility

Uses
[aria-activedescendant](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/examples/menu-button-actions-active-descendant/)
pattern to manage focus movement among menu items.

### Keyboard Interactions

**`Space`**
Description: Activates/Selects the highlighted item

**`Enter`**
Description: Activates/Selects the highlighted item

**`ArrowDown`**
Description: Highlights the next item in the menu

**`ArrowUp`**
Description: Highlights the previous item in the menu

**`ArrowRight + ArrowLeft`**
Description: When focus is on trigger, opens or closes the submenu depending on reading direction.

**`Esc`**
Description: Closes the context menu

A navigation menu displays links with optional dropdown content.

## Resources


[Latest version: v2.0.0-next.1](https://www.npmjs.com/package/@zag-js/navigation-menu)
[Logic Visualizer](https://zag-visualizer.vercel.app/navigation-menu)
[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/navigation-menu)



**Features**

- Supports basic (inline content) and viewport (shared viewport) patterns
- Hover and click trigger support with configurable delays
- Keyboard navigation with arrow keys, Tab, Home/End
- Animated indicator that follows the active trigger
- Smooth content animations with viewport positioning
- Horizontal and vertical orientation
- RTL (right-to-left) support
- Dismissible with click outside or Escape key

## Installation

Install the navigation menu package:

```bash
npm install @zag-js/navigation-menu @zag-js/react
# or
yarn add @zag-js/navigation-menu @zag-js/react
```

## Anatomy

Check the navigation menu anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the navigation menu package:

```tsx
import * as navigationMenu from "@zag-js/navigation-menu"
```

The navigation menu package exports two key functions:

- `machine` - State machine logic.
- `connect` - Maps machine state to JSX props and event handlers.

> Pass a unique `id` to `useMachine` so generated element ids stay predictable.

Then use the framework integration helpers:

```tsx
import * as navigationMenu from "@zag-js/navigation-menu"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useId } from "react"

export function NavigationMenu() {
  const service = useMachine(navigationMenu.machine, {
    id: useId(),
  })

  const api = navigationMenu.connect(service, normalizeProps)

  return (
    <nav {...api.getRootProps()}>
      <ul {...api.getListProps()}>
        {/* Item with dropdown content */}
        <li {...api.getItemProps({ value: "products" })}>
          <button {...api.getTriggerProps({ value: "products" })}>
            Products
          </button>
          <div {...api.getContentProps({ value: "products" })}>
            <a {...api.getLinkProps({ value: "products" })} href="/analytics">
              Analytics
            </a>
            <a {...api.getLinkProps({ value: "products" })} href="/marketing">
              Marketing
            </a>
          </div>
        </li>

        {/* Simple link item */}
        <li {...api.getItemProps({ value: "pricing" })}>
          <a {...api.getLinkProps({ value: "pricing" })} href="/pricing">
            Pricing
          </a>
        </li>
      </ul>
    </nav>
  )
}
```

The basic pattern places content directly within each item. This is suitable for
simple dropdown menus where each dropdown appears below its trigger.

### Advanced pattern with viewport

The viewport pattern uses a shared viewport container for all content. This
enables smooth transitions and better performance for complex navigation
layouts.

In this pattern:

- Content is rendered inside a shared `viewport` element
- The viewport automatically positions itself relative to the active trigger
- You must include `triggerProxy` and `viewportProxy` for proper focus
  management

```tsx
import * as navigationMenu from "@zag-js/navigation-menu"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useId } from "react"

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

  return (
    <nav {...api.getRootProps()}>
      <div {...api.getIndicatorTrackProps()}>
        <ul {...api.getListProps()}>
          {/* Item with trigger */}
          <li {...api.getItemProps({ value: "products" })}>
            <button {...api.getTriggerProps({ value: "products" })}>
              Products
            </button>
            {/* Focus management proxies */}
            <span {...api.getTriggerProxyProps({ value: "products" })} />
            <span {...api.getViewportProxyProps({ value: "products" })} />
          </li>

          {/* Simple link */}
          <li {...api.getItemProps({ value: "pricing" })}>
            <a {...api.getLinkProps({ value: "pricing" })} href="/pricing">
              Pricing
            </a>
          </li>

          {/* Indicator */}
          <div {...api.getIndicatorProps()}>
            <div {...api.getArrowProps()} />
          </div>
        </ul>
      </div>

      {/* Shared viewport for all content */}
      <div {...api.getViewportPositionerProps()}>
        <div {...api.getViewportProps()}>
          {/* Content for products */}
          <div {...api.getContentProps({ value: "products" })}>
            <a {...api.getLinkProps({ value: "products" })} href="/analytics">
              Analytics
            </a>
            <a {...api.getLinkProps({ value: "products" })} href="/marketing">
              Marketing
            </a>
          </div>
        </div>
      </div>
    </nav>
  )
}
```

**When to use viewport pattern:**

- Complex navigation with varying content sizes
- Smooth animated transitions between different content
- Header navigation bars (like on e-commerce sites)
- When you want a single shared container for all dropdowns

### Controlling the navigation menu

To control which item is currently open, pass the `value` and `onValueChange`
properties to the machine.

```tsx {1,4-8}
import { useState } from "react"

export function NavigationMenu() {
  const [value, setValue] = useState("")

  const service = useMachine(navigationMenu.machine, {
    id: useId(),
    value,
    onValueChange: (details) => setValue(details.value),
  })

  const api = navigationMenu.connect(service, normalizeProps)

  return (
    <div>
      <button onClick={() => setValue("products")}>Open Products</button>
      <button onClick={() => setValue("")}>Close All</button>

      <nav {...api.getRootProps()}>{/* ... navigation items ... */}</nav>
    </div>
  )
}
```

### Setting initial open item

Use `defaultValue` to start with a specific item open.

```tsx
const service = useMachine(navigationMenu.machine, {
  defaultValue: "products",
})
```

### Listening for value changes

When the open item changes, the `onValueChange` callback is invoked with the new
value.

```tsx {3-6}
const service = useMachine(navigationMenu.machine, {
  id: "nav",
  onValueChange(details) {
    // details => { value: string }
    console.log("Current open item:", details.value)
  },
})
```

### Adding an animated indicator

To show a visual indicator that animates to the active trigger, render the
indicator within the list container:

```tsx {3-5}
<nav {...api.getRootProps()}>
  <div {...api.getListProps()}>
    {/* ... items ... */}

    <div {...api.getIndicatorProps()}>
      <div {...api.getArrowProps()} />
    </div>
  </div>
</nav>
```

The indicator automatically transitions to match the active trigger's position
and size using CSS variables.

### Configuring hover delays

You can customize the delay before opening and closing on hover:

```tsx {2-3}
const service = useMachine(navigationMenu.machine, {
  openDelay: 300, // Delay before opening on hover (default: 200ms)
  closeDelay: 400, // Delay before closing on pointer leave (default: 300ms)
})
```

**Tip**: Longer delays provide a more forgiving user experience but can feel
less responsive.

### Disabling hover or click triggers

You can disable hover or click triggers independently:

```tsx {2-6}
const service = useMachine(navigationMenu.machine, {
  disableHoverTrigger: true, // Only open on click
  // OR
  disableClickTrigger: true, // Only open on hover
  // OR
  disablePointerLeaveClose: true, // Prevents closing when pointer leaves
})
```

- `disableHoverTrigger` — Prevents opening on hover (click only)
- `disableClickTrigger` — Prevents opening on click (hover only)
- `disablePointerLeaveClose` — Prevents closing when pointer leaves

### Changing orientation

The default orientation is horizontal. To create a vertical navigation menu:

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

This affects keyboard navigation (arrow keys) and indicator positioning.

### Disabling items

To disable a navigation item, pass `disabled: true` to the item props:

```tsx
<div {...api.getItemProps({ value: "products", disabled: true })}>
  <button {...api.getTriggerProps({ value: "products", disabled: true })}>
    Products
  </button>
</div>
```

Disabled items cannot be opened and are skipped during keyboard navigation.

### Indicating current page

To highlight the current page link, use the `current` prop:

```tsx
<a {...api.getLinkProps({ value: "products", current: true })}>Products</a>
```

This adds `data-current` attribute and `aria-current="page"` for accessibility.

### Controlling link close behavior

Use `closeOnClick` in `getLinkProps` to keep content open after link click.

```tsx
<a
  {...api.getLinkProps({
    value: "products",
    closeOnClick: false,
  })}
>
  Products
</a>
```

### Aligning the shared viewport

When using the viewport pattern, set `align` on `getViewportProps` or
`getViewportPositionerProps`.

```tsx
<div
  {...api.getViewportProps({
    align: "start",
  })}
/>
```

### RTL support

The navigation menu supports right-to-left languages. Set the `dir` property to
`rtl`:

```tsx {2}
const service = useMachine(navigationMenu.machine, {
  dir: "rtl",
})
```

## Styling guide

Each part includes a `data-part` attribute you can target in CSS.

### Open and closed states

When content is open or closed, it receives a `data-state` attribute:

```css
[data-part="content"][data-state="open|closed"] {
  /* Styles for open or closed content */
}

[data-part="trigger"][data-state="open|closed"] {
  /* Styles for open or closed trigger */
}

[data-part="viewport"][data-state="open|closed"] {
  /* Styles for viewport open/closed state */
}
```

### Selected item state

When an item is selected (open), it receives `data-state="open"`:

```css
[data-part="item"][data-state="open"] {
  /* Styles for open item */
}
```

### Disabled state

Disabled items have a `data-disabled` attribute:

```css
[data-part="item"][data-disabled] {
  /* Styles for disabled items */
}

[data-part="trigger"][data-disabled] {
  /* Styles for disabled triggers */
}
```

### Orientation styles

All parts have a `data-orientation` attribute:

```css
[data-part="root"][data-orientation="horizontal|vertical"] {
  /* Orientation-specific styles */
}

[data-part="list"][data-orientation="horizontal"] {
  display: flex;
  flex-direction: row;
}

[data-part="list"][data-orientation="vertical"] {
  display: flex;
  flex-direction: column;
}
```

### Current link state

Links marked as current have a `data-current` attribute:

```css
[data-part="link"][data-current] {
  /* Styles for current page link */
}
```

### Styling the indicator

The indicator uses CSS variables for positioning and sizing:

```css
[data-part="indicator"] {
  position: absolute;
  transition:
    translate 250ms ease,
    width 250ms ease,
    height 250ms ease;
}

[data-part="indicator"][data-orientation="horizontal"] {
  left: 0;
  translate: var(--trigger-x) 0;
  width: var(--trigger-width);
}

[data-part="indicator"][data-orientation="vertical"] {
  top: 0;
  translate: 0 var(--trigger-y);
  height: var(--trigger-height);
}
```

### Styling the viewport

The viewport uses CSS variables for positioning and sizing:

```css
[data-part="viewport"] {
  position: absolute;
  width: var(--viewport-width);
  height: var(--viewport-height);
  transition:
    width 300ms ease,
    height 300ms ease;
}
```

### Arrow styling

The arrow can be styled using CSS variables:

```css
[data-part="root"] {
  --arrow-size: 20px;
}

[data-part="arrow"] {
  width: var(--arrow-size);
  height: var(--arrow-size);
  background: white;
  rotate: 45deg;
}
```

### Motion attributes

When using the viewport pattern, content elements receive `data-motion`
attributes for directional animations:

```css
[data-part="content"][data-motion="from-start"] {
  animation: slideFromStart 250ms ease;
}

[data-part="content"][data-motion="from-end"] {
  animation: slideFromEnd 250ms ease;
}

[data-part="content"][data-motion="to-start"] {
  animation: slideToStart 250ms ease;
}

[data-part="content"][data-motion="to-end"] {
  animation: slideToEnd 250ms ease;
}
```

**Tip**: The motion direction indicates where the content is coming from
(from-start/from-end) or going to (to-start/to-end), enabling context-aware
animations when switching between items.

## Methods and Properties

### Machine Context

The navigation menu machine exposes the following context properties:

**`translations`**
Type: `IntlTranslations | undefined`
Description: Specifies the localized strings that identifies the accessibility elements and their states

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the machine.

**`value`**
Type: `string | undefined`
Description: The controlled value of the navigation menu

**`defaultValue`**
Type: `string | undefined`
Description: The default value of the navigation menu.
Use when you don't want to control the value of the menu.

**`onValueChange`**
Type: `((details: ValueChangeDetails) => void) | undefined`
Description: Function called when the value of the menu changes

**`openDelay`**
Type: `number | undefined`
Description: The delay before the menu opens

**`closeDelay`**
Type: `number | undefined`
Description: The delay before the menu closes

**`disableClickTrigger`**
Type: `boolean | undefined`
Description: Whether to disable the click trigger

**`disableHoverTrigger`**
Type: `boolean | undefined`
Description: Whether to disable the hover trigger

**`disablePointerLeaveClose`**
Type: `boolean | undefined`
Description: Whether to disable the pointer leave close

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

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

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

**`orientation`**
Type: `"horizontal" | "vertical" | undefined`
Description: The orientation of the element.

### Machine API

The navigation menu `api` exposes the following methods:

**`value`**
Type: `string | null`
Description: The current value of the menu

**`setValue`**
Type: `(value: string) => void`
Description: Sets the value of the menu

**`open`**
Type: `boolean`
Description: Whether the menu is open

**`isViewportRendered`**
Type: `boolean`
Description: Whether the viewport is rendered

**`getViewportNode`**
Type: `() => HTMLElement | null`
Description: Gets the viewport node element

**`orientation`**
Type: `Orientation`
Description: The orientation of the menu

**`reposition`**
Type: `VoidFunction`
Description: Function to reposition the viewport

### Data Attributes

**`Root`**

**`data-navigation-menu-root`**: <uid>
**`data-orientation`**: The orientation of the navigation-menu

**`List`**

**`data-navigation-menu-list`**: <uid>
**`data-orientation`**: The orientation of the list

**`Item`**

**`data-navigation-menu-item`**: <uid>
**`data-value`**: The value of the item
**`data-state`**: "open" | "closed"
**`data-orientation`**: The orientation of the item
**`data-disabled`**: Present when disabled

**`Indicator`**

**`data-navigation-menu-indicator`**: <uid>
**`data-state`**: "open" | "closed"
**`data-orientation`**: The orientation of the indicator

**`Arrow`**

**`data-navigation-menu-arrow`**: <uid>
**`data-orientation`**: The orientation of the arrow

**`Trigger`**

**`data-navigation-menu-trigger`**: <uid>
**`data-trigger-proxy-id`**: 
**`data-value`**: The value of the item
**`data-state`**: "open" | "closed"
**`data-disabled`**: Present when disabled

**`TriggerProxy`**

**`data-navigation-menu-trigger-proxy`**: <uid>
**`data-trigger-proxy`**: 
**`data-trigger-id`**: 

**`Link`**

**`data-navigation-menu-link`**: <uid>
**`data-value`**: The value of the item
**`data-current`**: Present when current

**`Content`**

**`data-navigation-menu-content`**: <uid>
**`data-state`**: "open" | "closed"
**`data-orientation`**: The orientation of the content
**`data-value`**: The value of the item

**`ViewportPositioner`**

**`data-navigation-menu-viewport-positioner`**: <uid>
**`data-orientation`**: The orientation of the viewportpositioner
**`data-align`**: 

**`Viewport`**

**`data-navigation-menu-viewport`**: <uid>
**`data-state`**: "open" | "closed"
**`data-orientation`**: The orientation of the viewport
**`data-align`**: 

**`ItemIndicator`**

**`data-navigation-menu-item-indicator`**: <uid>
**`data-state`**: "open" | "closed"
**`data-orientation`**: The orientation of the item
**`data-value`**: The value of the item

### CSS Variables

<CssVarTable name="navigation-menu" />

## Accessibility

### Keyboard Interactions

**`ArrowDown`**
Description: When focus is on trigger (vertical orientation), moves focus to the next trigger.

**`ArrowUp`**
Description: When focus is on trigger (vertical orientation), moves focus to the previous trigger.

**`ArrowRight`**
Description: <span>When focus is on trigger (horizontal orientation), moves focus to the next trigger.<br />When focus is on content, moves focus to the next link.</span>

**`ArrowLeft`**
Description: <span>When focus is on trigger (horizontal orientation), moves focus to the previous trigger.<br />When focus is on content, moves focus to the previous link.</span>

**`Home`**
Description: <span>When focus is on trigger, moves focus to the first trigger.<br />When focus is on content, moves focus to the first link.</span>

**`End`**
Description: <span>When focus is on trigger, moves focus to the last trigger.<br />When focus is on content, moves focus to the last link.</span>

The number input provides controls for editing, incrementing or decrementing
numeric values using the keyboard or pointer.

## Resources


[Latest version: v2.0.0-next.1](https://www.npmjs.com/package/@zag-js/number-input)
[Logic Visualizer](https://zag-visualizer.vercel.app/number-input)
[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/number-input)



**Features**

- Based on the spinbutton pattern
- Supports using the scroll wheel to increment and decrement the value
- Handles floating point rounding errors when incrementing, decrementing, and
  snapping to step
- Supports pressing and holding the spin buttons to continuously increment or
  decrement
- Supports rounding value to specific number of fraction digits
- Supports scrubbing interaction

## Installation

Install the number input package:

```bash
npm install @zag-js/number-input @zag-js/react
# or
yarn add @zag-js/number-input @zag-js/react
```

## Anatomy

To set up the number input 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 number input package:

```tsx
import * as numberInput from "@zag-js/number-input"
```

The number input package exports two key functions:

- `machine` - State machine logic.
- `connect` - Maps machine state to JSX props and event handlers.

> Pass a unique `id` to `useMachine` so generated element ids stay predictable.

Then use the framework integration helpers:

```tsx
import * as numberInput from "@zag-js/number-input"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useId } from "react"

export function NumberInput() {
  const service = useMachine(numberInput.machine, { id: useId() })

  const api = numberInput.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <label {...api.getLabelProps()}>Enter number:</label>
      <div>
        <button {...api.getDecrementTriggerProps()}>DEC</button>
        <input {...api.getInputProps()} />
        <button {...api.getIncrementTriggerProps()}>INC</button>
      </div>
    </div>
  )
}
```

### Setting the initial value

Set `defaultValue` to define the initial value. The value must be a `string`.

```tsx {2}
const service = useMachine(numberInput.machine, {
  defaultValue: "13",
})
```

### Controlled value

Use `value` and `onValueChange` to control the value externally.

> **Note:** Since the value can be formatted, it's important to preserve the
> value as a string.

```tsx
import { useState } from "react"

export function ControlledNumberInput() {
  const [value, setValue] = useState("")

  const service = useMachine(numberInput.machine, {
    value,
    onValueChange(details) {
      setValue(details.value)
    },
  })
}
```

### Setting a minimum and maximum value

Pass the `min` prop or `max` prop to set an upper and lower limit for the input.
By default, the input will restrict the value to stay within the specified
range.

```tsx {2,3}
const service = useMachine(numberInput.machine, {
  min: 10,
  max: 200,
})
```

> To allow the value overflow the specified min or max, set the
> `allowOverflow: true` in the context.

### Validating overflow and underflow

Use `onValueInvalid` to react when the value goes below `min` or above `max`.

```tsx
const service = useMachine(numberInput.machine, {
  min: 0,
  max: 10,
  allowOverflow: true,
  onValueInvalid(details) {
    // details => { value: string, valueAsNumber: number, reason: "rangeUnderflow" | "rangeOverflow" }
    console.log(details.reason)
  },
})
```

### Scrubbing the input value

Number input supports the scrubber interaction pattern. To use this pattern,
spread `api.getScrubberProps()` on the scrubbing element.

It uses the Pointer lock API and tracks the pointer movement. It also renders a
virtual cursor which mimics the real cursor's pointer.

```tsx {13}
import * as numberInput from "@zag-js/number-input"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useId } from "react"

export function NumberInput() {
  const service = useMachine(numberInput.machine, { id: useId() })

  const api = numberInput.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <label {...api.getLabelProps()}>Enter number:</label>
      <div>
        <div {...api.getScrubberProps()} />
        <input {...api.getInputProps()} />
      </div>
    </div>
  )
}
```

### Using the mousewheel to change value

The number input machine exposes a way to increment/decrement the value using
the mouse wheel event. To activate this, pass the `allowMouseWheel` property to
the machine's context.

```tsx {2}
const service = useMachine(numberInput.machine, {
  allowMouseWheel: true,
})
```

### Clamp value when user blurs the input

In most cases, users can type custom values in the input field. If the typed
value is greater than the max, the value is reset to max when the user blurs the
input.

To disable this behavior, pass `clampValueOnBlur` and set to `false`.

```tsx {2}
const service = useMachine(numberInput.machine, {
  clampValueOnBlur: false,
})
```

### Listening for value changes

When the value changes, the `onValueChange` callback is invoked.

```tsx {2-7}
const service = useMachine(numberInput.machine, {
  onValueChange(details) {
    // details => { value: string, valueAsNumber: number }
    console.log("value is:", details.value)
  },
})
```

### Listening for value commit

Use `onValueCommit` to react when the value is committed (blur or Enter).

```tsx
const service = useMachine(numberInput.machine, {
  onValueCommit(details) {
    // details => { value: string, valueAsNumber: number }
    console.log("committed:", details.value)
  },
})
```

### Listening for focus changes

Use `onFocusChange` to react to focus and blur transitions.

```tsx
const service = useMachine(numberInput.machine, {
  onFocusChange(details) {
    // details => { focused: boolean, value: string, valueAsNumber: number }
    console.log("focused:", details.focused)
  },
})
```

### Usage within forms

To use the number input within forms, set the `name` property in the machine's
context.

```tsx {2}
const service = useMachine(numberInput.machine, {
  name: "quantity",
})
```

### Adjusting the precision of the value

To format the input value to be rounded to specific decimal points, set the
`formatOptions` and provide `Intl.NumberFormatOptions` such as
`maximumFractionDigits` or `minimumFractionDigits`

```tsx {2-5}
const service = useMachine(numberInput.machine, {
  formatOptions: {
    maximumFractionDigits: 4,
    minimumFractionDigits: 2,
  },
})
```

### Disabling long press spin

To disable the long press spin, set the `spinOnPress` to `false`.

```tsx {2}
const service = useMachine(numberInput.machine, {
  spinOnPress: false,
})
```

### Choosing mobile keyboard type

Set `inputMode` to hint the keyboard type on mobile.

```tsx
const service = useMachine(numberInput.machine, {
  inputMode: "numeric", // "text" | "tel" | "numeric" | "decimal"
})
```

### Format and parse value

To apply custom formatting to the input's value, set the `formatOptions` and
provide `Intl.NumberFormatOptions` such as `style` and `currency`

```tsx {2-5}
const service = useMachine(numberInput.machine, {
  formatOptions: {
    style: "currency",
    currency: "USD",
  },
})
```

### Customizing accessibility labels

Use `translations` to customize increment/decrement labels and value text.

```tsx
const service = useMachine(numberInput.machine, {
  translations: {
    incrementLabel: "Increase quantity",
    decrementLabel: "Decrease quantity",
    valueText: (value) => `${value} units`,
  },
})
```

### Submitting with an external form

Set `form` if the hidden input should submit with a form outside the current DOM
subtree.

```tsx
const service = useMachine(numberInput.machine, {
  name: "value",
  form: "checkout-form",
})
```

## Styling guide

Each part includes a `data-part` attribute you can target in CSS.

### Disabled state

When the number input is disabled, the root, label and input parts will have
`data-disabled` attribute added to them.

The increment and decrement spin buttons are disabled when the number input is
disabled and the min/max is reached.

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

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

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

[data-part="increment-trigger"][data-disabled] {
  /* disabled styles for the increment button */
}

[data-part="decrement-trigger"][data-disabled] {
  /* disabled styles for the decrement button */
}
```

### Invalid state

The number input is invalid, either by passing `invalid: true` or when the value
exceeds the max and `allowOverflow: true` is passed. When this happens, the
root, label and input parts will have `data-invalid` attribute added to them.

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

[data-part="input"][data-invalid] {
  /* invalid styles for the input */
}

[data-part="label"][data-invalid] {
  /* invalid styles for the label */
}
```

### Readonly state

When the number input is readonly, the input part will have `data-readonly`
added.

```css
[data-part="input"][data-readonly] {
  /* readonly styles for the input */
}
```

### Increment and decrement spin buttons

The spin buttons can be styled individually with their respective `data-part`
attribute.

```css
[data-part="increment-trigger"] {
  /* styles for the increment trigger element */
}

[data-part="decrement-trigger"] {
  /* styles for the decrement trigger element */
}
```

## Methods and Properties

### Machine Context

The number input machine exposes the following context properties:

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the number input. Useful for composition.

**`name`**
Type: `string | undefined`
Description: The name attribute of the number input. Useful for form submission.

**`form`**
Type: `string | undefined`
Description: The associate form of the input element.

**`disabled`**
Type: `boolean | undefined`
Description: Whether the number input is disabled.

**`readOnly`**
Type: `boolean | undefined`
Description: Whether the number input is readonly

**`invalid`**
Type: `boolean | undefined`
Description: Whether the number input value is invalid.

**`required`**
Type: `boolean | undefined`
Description: Whether the number input is required

**`pattern`**
Type: `string | undefined`
Description: The pattern used to check the <input> element's value against

**`value`**
Type: `string | undefined`
Description: The controlled value of the input

**`defaultValue`**
Type: `string | undefined`
Description: The initial value of the input when rendered.
Use when you don't need to control the value of the input.

**`min`**
Type: `number | undefined`
Description: The minimum value of the number input

**`max`**
Type: `number | undefined`
Description: The maximum value of the number input

**`step`**
Type: `number | undefined`
Description: The amount to increment or decrement the value by

**`allowMouseWheel`**
Type: `boolean | undefined`
Description: Whether to allow mouse wheel to change the value

**`allowOverflow`**
Type: `boolean | undefined`
Description: Whether to allow the value overflow the min/max range

**`clampValueOnBlur`**
Type: `boolean | undefined`
Description: Whether to clamp the value when the input loses focus (blur)

**`focusInputOnChange`**
Type: `boolean | undefined`
Description: Whether to focus input when the value changes

**`translations`**
Type: `IntlTranslations | undefined`
Description: Specifies the localized strings that identifies the accessibility elements and their states

**`formatOptions`**
Type: `Intl.NumberFormatOptions | undefined`
Description: The options to pass to the `Intl.NumberFormat` constructor

**`inputMode`**
Type: `InputMode | undefined`
Description: Hints at the type of data that might be entered by the user. It also determines
the type of keyboard shown to the user on mobile devices

**`onValueChange`**
Type: `((details: ValueChangeDetails) => void) | undefined`
Description: Function invoked when the value changes

**`onValueInvalid`**
Type: `((details: ValueInvalidDetails) => void) | undefined`
Description: Function invoked when the value overflows or underflows the min/max range

**`onFocusChange`**
Type: `((details: FocusChangeDetails) => void) | undefined`
Description: Function invoked when the number input is focused

**`onValueCommit`**
Type: `((details: ValueChangeDetails) => void) | undefined`
Description: Function invoked when the value is committed (when the input is blurred or the Enter key is pressed)

**`spinOnPress`**
Type: `boolean | undefined`
Description: Whether to spin the value when the increment/decrement button is pressed

**`largeStep`**
Type: `number | undefined`
Description: Step value when Shift key is held (large increments).

**`smallStep`**
Type: `number | undefined`
Description: Step value when Alt/Option key is held (fine control).

**`scrubberPixelSensitivity`**
Type: `number | undefined`
Description: How many pixels the pointer must move to change the value by one step.
Higher values mean more precise control. Lower values mean more sensitivity.

**`scrubberTeleportDistance`**
Type: `number | undefined`
Description: Distance in pixels before the virtual cursor wraps around.
When not set, the viewport bounds are used (default behavior).

**`scrubberDirection`**
Type: `"horizontal" | "vertical" | undefined`
Description: The direction of scrubbing.

**`snapOnStep`**
Type: `boolean | undefined`
Description: Whether values snap to step multiples when scrubbing.

**`locale`**
Type: `string | undefined`
Description: The current locale. Based on the BCP 47 definition.

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

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

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

### Machine API

The number input `api` exposes the following methods:

**`focused`**
Type: `boolean`
Description: Whether the input is focused.

**`scrubbing`**
Type: `boolean`
Description: Whether the input is being scrubbed.

**`invalid`**
Type: `boolean`
Description: Whether the input is invalid.

**`empty`**
Type: `boolean`
Description: Whether the input value is empty.

**`value`**
Type: `string`
Description: The formatted value of the input.

**`valueAsNumber`**
Type: `number`
Description: The value of the input as a number.

**`setValue`**
Type: `(value: number) => void`
Description: Function to set the value of the input.

**`clearValue`**
Type: `VoidFunction`
Description: Function to clear the value of the input.

**`increment`**
Type: `VoidFunction`
Description: Function to increment the value of the input by the step.

**`decrement`**
Type: `VoidFunction`
Description: Function to decrement the value of the input by the step.

**`setToMax`**
Type: `VoidFunction`
Description: Function to set the value of the input to the max.

**`setToMin`**
Type: `VoidFunction`
Description: Function to set the value of the input to the min.

**`focus`**
Type: `VoidFunction`
Description: Function to focus the input.

### Data Attributes

**`Root`**

**`data-number-input-root`**: <uid>
**`data-disabled`**: Present when disabled
**`data-focus`**: Present when focused
**`data-invalid`**: Present when invalid
**`data-scrubbing`**: 

**`Label`**

**`data-number-input-label`**: <uid>
**`data-disabled`**: Present when disabled
**`data-focus`**: Present when focused
**`data-invalid`**: Present when invalid
**`data-required`**: Present when required
**`data-scrubbing`**: 

**`Control`**

**`data-number-input-control`**: <uid>
**`data-focus`**: Present when focused
**`data-disabled`**: Present when disabled
**`data-invalid`**: Present when invalid
**`data-scrubbing`**: 

**`ValueText`**

**`data-number-input-value-text`**: <uid>
**`data-disabled`**: Present when disabled
**`data-invalid`**: Present when invalid
**`data-focus`**: Present when focused
**`data-scrubbing`**: 

**`Input`**

**`data-number-input-input`**: <uid>
**`data-invalid`**: Present when invalid
**`data-disabled`**: Present when disabled
**`data-scrubbing`**: 

**`DecrementTrigger`**

**`data-number-input-decrement-trigger`**: <uid>
**`data-disabled`**: Present when disabled
**`data-scrubbing`**: 

**`IncrementTrigger`**

**`data-number-input-increment-trigger`**: <uid>
**`data-disabled`**: Present when disabled
**`data-scrubbing`**: 

**`Scrubber`**

**`data-number-input-scrubber`**: <uid>
**`data-disabled`**: Present when disabled
**`data-scrubbing`**: 

## Accessibility

### Keyboard Interactions

**`ArrowUp`**
Description: Increments the value of the number input by a predefined step.

**`ArrowDown`**
Description: Decrements the value of the number input by a predefined step.

**`Shift + ArrowUp`**
Description: Increments the value of the number input by the `largeStep` amount.

**`Shift + ArrowDown`**
Description: Decrements the value of the number input by the `largeStep` amount.

**`Alt + ArrowUp`**
Description: Increments the value of the number input by the `smallStep` amount.

**`Alt + ArrowDown`**
Description: Decrements the value of the number input by the `smallStep` amount.

**`Home`**
Description: Sets the value of the number input to its minimum allowed value.

**`End`**
Description: Sets the value of the number input to its maximum allowed value.

**`Enter`**
Description: Submits the value entered in the number input.

Pagination lets users navigate data split across multiple pages.

## Resources


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



## Installation

Install the pagination package:

```bash
npm install @zag-js/pagination @zag-js/react
# or
yarn add @zag-js/pagination @zag-js/react
```

## Anatomy

To set up the pagination 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 pagination package:

```tsx
import * as pagination from "@zag-js/pagination"
```

The pagination package exports two key functions:

- `machine` - State machine logic.
- `connect` - Maps machine state to JSX props and event handlers.

> Pass a unique `id` to `useMachine` so generated element ids stay predictable.

```tsx
import * as pagination from "@zag-js/pagination"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useId } from "react"
import { data } from "./data"

function Pagination() {
  const service = useMachine(pagination.machine, {
    id: useId(),
    count: data.length,
  })

  const api = pagination.connect(service, normalizeProps)

  return (
    <div>
      {api.totalPages > 1 && (
        <nav {...api.getRootProps()}>
          <ul>
            <li>
              <a href="#previous" {...api.getPrevTriggerProps()}>
                Previous <span className="visually-hidden">Page</span>
              </a>
            </li>
            {api.pages.map((page, i) => {
              if (page.type === "page")
                return (
                  <li key={page.value}>
                    <a href={`#${page.value}`} {...api.getItemProps(page)}>
                      {page.value}
                    </a>
                  </li>
                )
              else
                return (
                  <li key={`ellipsis-${i}`}>
                    <span {...api.getEllipsisProps({ index: i })}>&#8230;</span>
                  </li>
                )
            })}
            <li>
              <a href="#next" {...api.getNextTriggerProps()}>
                Next <span className="visually-hidden">Page</span>
              </a>
            </li>
          </ul>
        </nav>
      )}
    </div>
  )
}
```

```tsx
const api = pagination.connect(service)

// You can slice the data, to get data for current page
const currentPageData = data.slice(api.pageRange.start, api.pageRange.end)

api.page
// => 1

api.setPage(3)
// page => 3

api.previousPage
// => 2

api.nextPage
// => 4

api.pages
/*
    [
      {
        "type": "page",
        "value": 1,
      },
      {
        "type": "page",
        "value": 2,
      },
      {
        "type": "ellipsis",
      },
      {
        "type": "page",
        "value": 3,
      },
      {
        "type": "page",
        "value": 4,
      },
    ]
*/

api.pageRange
// => { start: 4, end: 13 }
```

### Controlled page

Use `page` and `onPageChange` to control the current page externally.

```tsx
const service = useMachine(pagination.machine, {
  count: 500,
  pageSize: 20,
  page,
  onPageChange(details) {
    setPage(details.page)
  },
})
```

### Controlled page size

Use `pageSize` and `onPageSizeChange` to control page size.

```tsx
const service = useMachine(pagination.machine, {
  count: 500,
  pageSize,
  onPageSizeChange(details) {
    setPageSize(details.pageSize)
  },
})
```

### Initial page and page size

Use `defaultPage` and `defaultPageSize` for uncontrolled initial values.

```tsx
const service = useMachine(pagination.machine, {
  count: 500,
  defaultPage: 3,
  defaultPageSize: 20,
})
```

### Link-based pagination

Set `type: "link"` and provide `getPageUrl` to render real navigation links.

```tsx
const service = useMachine(pagination.machine, {
  count: 500,
  type: "link",
  getPageUrl(details) {
    return `/products?page=${details.page}&pageSize=${details.pageSize}`
  },
})
```

### Customizing visible page ranges

Use `siblingCount` and `boundaryCount` to control how many page items are shown.

```tsx
const service = useMachine(pagination.machine, {
  count: 500,
  siblingCount: 2,
  boundaryCount: 2,
})
```

### Customizing accessibility labels

Use `translations` to customize trigger and page labels.

```tsx
const service = useMachine(pagination.machine, {
  count: 500,
  translations: {
    rootLabel: "Results pages",
    prevTriggerLabel: "Previous page",
    nextTriggerLabel: "Next page",
    itemLabel: ({ page, totalPages }) => `Page ${page} of ${totalPages}`,
  },
})
```

## Styling guide

Each part includes a `data-part` attribute you can target in CSS.

```css
[data-part="root"] {
  /* styles for the pagination's root */
}

[data-part="item"] {
  /* styles for the pagination's items */
}

[data-part="ellipsis"] {
  /* styles for the pagination's ellipsis */
}

[data-part="prev-trigger"] {
  /* styles for the pagination's previous page trigger */
}

[data-part="next-trigger"] {
  /* styles for the pagination's next page trigger */
}

/* We add a data-disabled attribute to the prev/next items when on the first/last page  */

[data-part="prev-trigger"][data-disabled] {
  /* styles for the pagination's previous page trigger when on first page */
}

[data-part="next-trigger"][data-disabled] {
  /* styles for the pagination's next page trigger when on first page */
}
```

## Methods and Properties

### Machine Context

The pagination machine exposes the following context properties:

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the accordion. Useful for composition.

**`translations`**
Type: `IntlTranslations | undefined`
Description: Specifies the localized strings that identifies the accessibility elements and their states

**`count`**
Type: `number | undefined`
Description: Total number of data items

**`pageSize`**
Type: `number | undefined`
Description: The controlled number of data items per page

**`defaultPageSize`**
Type: `number | undefined`
Description: The initial number of data items per page when rendered.
Use when you don't need to control the page size of the pagination.

**`siblingCount`**
Type: `number | undefined`
Description: Number of pages to show beside active page

**`boundaryCount`**
Type: `number | undefined`
Description: Number of pages to show at the beginning and end

**`page`**
Type: `number | undefined`
Description: The controlled active page

**`defaultPage`**
Type: `number | undefined`
Description: The initial active page when rendered.
Use when you don't need to control the active page of the pagination.

**`onPageChange`**
Type: `((details: PageChangeDetails) => void) | undefined`
Description: Called when the page number is changed

**`onPageSizeChange`**
Type: `((details: PageSizeChangeDetails) => void) | undefined`
Description: Called when the page size is changed

**`type`**
Type: `"button" | "link" | undefined`
Description: The type of the trigger element

**`getPageUrl`**
Type: `((details: PageUrlDetails) => string) | undefined`
Description: Function to generate href attributes for pagination links.
Only used when `type` is set to "link".

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

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

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

### Machine API

The pagination `api` exposes the following methods:

**`page`**
Type: `number`
Description: The current page.

**`count`**
Type: `number`
Description: The total number of data items.

**`pageSize`**
Type: `number`
Description: The number of data items per page.

**`totalPages`**
Type: `number`
Description: The total number of pages.

**`pages`**
Type: `Pages`
Description: The page range. Represented as an array of page numbers (including ellipsis)

**`previousPage`**
Type: `number | null`
Description: The previous page.

**`nextPage`**
Type: `number | null`
Description: The next page.

**`pageRange`**
Type: `PageRange`
Description: The page range. Represented as an object with `start` and `end` properties.

**`slice`**
Type: `<V>(data: V[]) => V[]`
Description: Function to slice an array of data based on the current page.

**`setPageSize`**
Type: `(size: number) => void`
Description: Function to set the page size.

**`setPage`**
Type: `(page: number) => void`
Description: Function to set the current page.

**`goToNextPage`**
Type: `VoidFunction`
Description: Function to go to the next page.

**`goToPrevPage`**
Type: `VoidFunction`
Description: Function to go to the previous page.

**`goToFirstPage`**
Type: `VoidFunction`
Description: Function to go to the first page.

**`goToLastPage`**
Type: `VoidFunction`
Description: Function to go to the last page.

### Data Attributes

**`Ellipsis`**

**`data-pagination-ellipsis`**: <uid>
**`data-index`**: The index of the item

**`Item`**

**`data-pagination-item`**: <uid>
**`data-index`**: The index of the item
**`data-selected`**: Present when selected

**`PrevTrigger`**

**`data-pagination-prev-trigger`**: <uid>
**`data-disabled`**: Present when disabled

**`FirstTrigger`**

**`data-pagination-first-trigger`**: <uid>
**`data-disabled`**: Present when disabled

**`NextTrigger`**

**`data-pagination-next-trigger`**: <uid>
**`data-disabled`**: Present when disabled

**`LastTrigger`**

**`data-pagination-last-trigger`**: <uid>
**`data-disabled`**: Present when disabled

## Resources


[Latest version: v2.0.0-next.1](https://www.npmjs.com/package/@zag-js/password-input)
[Logic Visualizer](https://zag-visualizer.vercel.app/password-input)
[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/password-input)



**Features**

- Includes button to toggle visibility of the password
- Automatic focus restoration to the input
- Resets visibility to hidden after form submission
- Can ignore supported password managers

## Installation

Install the password-input package:

```bash
npm install @zag-js/password-input @zag-js/react
# or
yarn add @zag-js/password-input @zag-js/react
```

## Anatomy

Check the password-input anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the password-input package:

```tsx
import * as passwordInput from "@zag-js/password-input"
```

The password-input package exports two key functions:

- `machine` - State machine logic.
- `connect` - Maps machine state to JSX props and event handlers.

> Pass a unique `id` to `useMachine` so generated element ids stay predictable.

Then use the framework integration helpers:

```tsx
import * as passwordInput from "@zag-js/password-input"
import { useMachine, normalizeProps } from "@zag-js/react"
import { EyeIcon, EyeOffIcon } from "lucide-react"
import { useId } from "react"

function PasswordInput() {
  const service = useMachine(passwordInput.machine, { id: useId() })

  const api = passwordInput.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <label {...api.getLabelProps()}>Password</label>
      <div {...api.getControlProps()}>
        <input {...api.getInputProps()} />
        <button {...api.getVisibilityTriggerProps()}>
          <span {...api.getIndicatorProps()}>
            {api.visible ? <EyeIcon /> : <EyeOffIcon />}
          </span>
        </button>
      </div>
    </div>
  )
}
```

### Setting the initial visibility

Set `defaultVisible` to define the initial visibility.

```tsx {3}
const service = useMachine(passwordInput.machine, {
  id: useId(),
  defaultVisible: true,
})
```

### Controlling the visibility

Use `visible` and `onVisibilityChange` to control visibility externally.

```tsx {3-5}
const service = useMachine(passwordInput.machine, {
  id: useId(),
  visible: true,
  onVisibilityChange(details) {
    // details => { visible: boolean }
    console.log(details.visible)
  },
})
```

### Ignoring password managers

Set `ignorePasswordManagers` to `true` to ignore supported password managers.

This is useful when you want to ensure that the password input is not managed by
password managers. **Currently, this only works for 1Password, LastPass,
Bitwarden, Dashlane, and Proton Pass.**

```tsx {3}
const service = useMachine(passwordInput.machine, {
  id: useId(),
  ignorePasswordManagers: true,
})
```

**Why is this useful?**

- You might want to use this primitive for non-login scenarios (e.g., "secure
  notes", "temporary passwords")

- In a verify password step, you might want to disable password managers for the
  confirm password field to ensure manual entry

- Building a security-sensitive app where password managers violate compliance
  requirements.

### Managing autocompletion

Set `autoComplete` to control password autofill behavior.

- `new-password` — The user is creating a new password.
- `current-password` — The user is entering an existing password.

```tsx {3}
const service = useMachine(passwordInput.machine, {
  id: useId(),
  autoComplete: "new-password",
})
```

### Making the input required

Set `required` to `true` to make the input required.

```tsx {3}
const service = useMachine(passwordInput.machine, {
  id: useId(),
  required: true,
})
```

### Making the input read only

Set `readOnly` to `true` to make the input read only.

```tsx {3}
const service = useMachine(passwordInput.machine, {
  id: useId(),
  readOnly: true,
})
```

### Setting the input name

Set `name` to include the password field in form submission.

```tsx
const service = useMachine(passwordInput.machine, {
  id: useId(),
  name: "password",
})
```

### Customizing accessibility labels

Use `translations.visibilityTrigger` to customize the toggle button label.

```tsx
const service = useMachine(passwordInput.machine, {
  id: useId(),
  translations: {
    visibilityTrigger: (visible) =>
      visible ? "Hide password" : "Show password",
  },
})
```

## Styling guide

Each part includes a `data-part` attribute you can target in CSS.

```css
[data-scope="password-input"][data-part="root"] {
  /* styles for the root part */
}

[data-scope="password-input"][data-part="input"] {
  /* styles for the input part */
}

[data-scope="password-input"][data-part="visibility-trigger"] {
  /* styles for the visibility trigger part */
}

[data-scope="password-input"][data-part="indicator"] {
  /* styles for the indicator part */
}

[data-scope="password-input"][data-part="control"] {
  /* styles for the control part */
}

[data-scope="password-input"][data-part="label"] {
  /* styles for the label part */
}
```

### Visibility State

Use the `[data-state="visible"]` and `[data-state="hidden"]` attributes to style
the password input when it is visible or hidden.

```css
[data-scope="password-input"][data-part="input"][data-state="visible"] {
  /* styles for the visible state (for input) */
}

[data-scope="password-input"][data-part="visibility-trigger"][data-state="visible"] {
  /* styles for the visible state (for visibility trigger) */
}
```

### Disabled State

Use the `[data-disabled]` attribute to style the password input when it is
disabled.

```css
[data-scope="password-input"][data-part="input"][data-disabled] {
  /* styles for the disabled state */
}
```

### Invalid State

Use the `[data-invalid]` attribute to style the password input when it is
invalid.

```css
[data-scope="password-input"][data-part="input"][data-invalid] {
  /* styles for the invalid state */
}
```

### Readonly State

Use the `[data-readonly]` attribute to style the password input when it is read
only.

```css
[data-scope="password-input"][data-part="input"][data-readonly] {
  /* styles for the readonly state */
}
```

## Methods and Properties

### Machine Context

The password-input machine exposes the following context properties:

**`defaultVisible`**
Type: `boolean | undefined`
Description: The default visibility of the password input.

**`visible`**
Type: `boolean | undefined`
Description: Whether the password input is visible.

**`onVisibilityChange`**
Type: `((details: VisibilityChangeDetails) => void) | undefined`
Description: Function called when the visibility changes.

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the password input parts

**`disabled`**
Type: `boolean | undefined`
Description: Whether the password input is disabled.

**`invalid`**
Type: `boolean | undefined`
Description: The invalid state of the password input.

**`readOnly`**
Type: `boolean | undefined`
Description: Whether the password input is read only.

**`required`**
Type: `boolean | undefined`
Description: Whether the password input is required.

**`translations`**
Type: `IntlTranslations | undefined`
Description: The localized messages to use.

**`ignorePasswordManagers`**
Type: `boolean | undefined`
Description: When `true`, the input will ignore password managers.

**Only works for the following password managers**
- 1Password, LastPass, Bitwarden, Dashlane, Proton Pass

**`autoComplete`**
Type: `"current-password" | "new-password" | undefined`
Description: The autocomplete attribute for the password input.

**`name`**
Type: `string | undefined`
Description: The name of the password input.

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

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

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

### Machine API

The password-input `api` exposes the following methods:

**`visible`**
Type: `boolean`
Description: Whether the password input is visible.

**`disabled`**
Type: `boolean`
Description: Whether the password input is disabled.

**`invalid`**
Type: `boolean`
Description: Whether the password input is invalid.

**`focus`**
Type: `VoidFunction`
Description: Focus the password input.

**`setVisible`**
Type: `(value: boolean) => void`
Description: Set the visibility of the password input.

**`toggleVisible`**
Type: `VoidFunction`
Description: Toggle the visibility of the password input.

The pin input is optimized for entering a sequence of digits or letters. The
input fields allow one character at a time. When the digit or letter is entered,
focus transfers to the next input in the sequence, until every input is filled.

## Resources


[Latest version: v2.0.0-next.1](https://www.npmjs.com/package/@zag-js/pin-input)
[Logic Visualizer](https://zag-visualizer.vercel.app/pin-input)
[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/pin-input)



**Features**

- Automatically focuses the next field on typing and focuses the previous field
  on deletion
- Supports numeric and alphanumeric values
- Supports masking value (for sensitive data)
- Supports copy/paste to autofill all fields
- Supports fast paste SMS-code

## Installation

Install the pin input package:

```bash
npm install @zag-js/pin-input @zag-js/react
# or
yarn add @zag-js/pin-input @zag-js/react
```

## Anatomy

Check the pin input anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the pin input package:

```tsx
import * as pinInput from "@zag-js/pin-input"
```

These are the key exports:

- `machine` - State machine logic.
- `connect` - Maps machine state to JSX props and event handlers.

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

Then use the framework integration helpers:

```tsx
import * as pinInput from "@zag-js/pin-input"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useId } from "react"

export function PinInput() {
  const service = useMachine(pinInput.machine, { id: useId() })

  const api = pinInput.connect(service, normalizeProps)

  return (
    <div>
      <div {...api.getRootProps()}>
        <input {...api.getInputProps({ index: 0 })} />
        <input {...api.getInputProps({ index: 1 })} />
        <input {...api.getInputProps({ index: 2 })} />
      </div>
      <button onClick={api.clearValue}>Clear</button>
    </div>
  )
}
```

### Setting a default value

Set `defaultValue` to define the initial pin value. It must be an array of
strings.

```tsx {2}
const service = useMachine(pinInput.machine, {
  defaultValue: ["1", "2", ""],
})
```

### Controlled value

Use the `value` and `onValueChange` properties to programmatically control the
value of the pin input.

```tsx
import { useState } from "react"

export function ControlledPinInput() {
  const [value, setValue] = useState(["", "", "", ""])

  const service = useMachine(pinInput.machine, {
    value,
    onValueChange(details) {
      setValue(details.value)
    },
  })
}
```

### Setting input count

Set `count` to define the number of input fields to render.

```tsx
const service = useMachine(pinInput.machine, {
  count: 6,
})
```

### Changing the placeholder

To customize the default pin input placeholder (○) for each input, pass the
`placeholder` prop and set it to your desired value.

```tsx {2}
const service = useMachine(pinInput.machine, {
  placeholder: "*",
})
```

### Blur on complete

By default, the last input maintains focus when filled and `onValueComplete` is
invoked. To blur the last input when the user completes the input, set the
`blurOnComplete: true` in the machine's context.

```tsx {2}
const service = useMachine(pinInput.machine, {
  blurOnComplete: true,
})
```

### Auto-submitting on complete

Set `autoSubmit` to automatically submit the owning form when all inputs are
filled.

```tsx {2}
const service = useMachine(pinInput.machine, {
  autoSubmit: true,
})
```

### Allowing alphanumeric values

By default, the pin input accepts only number values but you can choose between
`numeric`, `alphanumeric` and `alphabetic` values. To change the input mode,
pass the `type` context property and set its value to `alphanumeric`.

```tsx {2}
const service = useMachine(pinInput.machine, {
  type: "alphanumeric",
})
```

### Using a custom pattern

Use `pattern` to provide a custom regex for validating input values. Each
character entered is checked against this pattern.

```tsx {2}
const service = useMachine(pinInput.machine, {
  pattern: "[0-9a-fA-F]", // hex characters only
})
```

### Using OTP mode

To trigger smartphone OTP auto-suggestion, it is recommended to set the
`autocomplete` attribute to "one-time-code". The pin-input machine provides
support for this automatically when you set the `otp` context property to
`true`.

```tsx {2}
const service = useMachine(pinInput.machine, {
  otp: true,
})
```

### Securing the text input

When collecting private or sensitive information using the pin input, you might
need to mask the value entered, similar to `<input type="password"/>`. Pass the
`mask` context property and set it to `true`.

```tsx {2}
const service = useMachine(pinInput.machine, {
  mask: true,
})
```

### Listening for changes

The pin input machine invokes several callback functions when the user enters:

- `onValueChange` — Function invoked when the value is changed.
- `onValueComplete` — Function invoked when all fields have been completed (by
  typing or pasting).
- `onValueInvalid` — Function invoked when an invalid value is entered into the
  input. An invalid value is any value that doesn't match the specified "type".

```tsx
const service = useMachine(pinInput.machine, {
  onValueChange(details) {
    // details => { value: string[], valueAsString: string }
    console.log("value changed to:", details.value)
  },
  onValueComplete(details) {
    // details => { value: string[], valueAsString: string }
    console.log("completed value:", details)
  },
  onValueInvalid(details) {
    // details => { index: number, value: string }
    console.log("invalid value:", details)
  },
})
```

### Sanitizing pasted values

Use `sanitizeValue` to strip dashes, spaces, or other formatting from pasted
values before validation.

```tsx
const service = useMachine(pinInput.machine, {
  sanitizeValue: (value) => value.replace(/[-\s]/g, ""),
})
```

### Autofocus and selection behavior

Use `autoFocus` to focus the first input on mount, and `selectOnFocus` to select
the active character on focus.

```tsx
const service = useMachine(pinInput.machine, {
  autoFocus: true,
  selectOnFocus: true,
})
```

### RTL support

The pin input machine supports RTL writing directions. Set `dir` to `rtl`.

When this attribute is set, we attach a `dir` attribute to the root part.

```tsx {2}
const service = useMachine(pinInput.machine, {
  dir: "rtl",
})
```

### Submitting with an external form

Set `form` if the hidden input should submit with a form outside the current DOM
subtree. Use `required` to mark the input as required for form validation.

```tsx
const service = useMachine(pinInput.machine, {
  name: "otp",
  form: "checkout-form",
  required: true,
})
```

### Customizing accessibility labels

Use `translations.inputLabel` to customize screen-reader labels per input.

```tsx
const service = useMachine(pinInput.machine, {
  count: 4,
  translations: {
    inputLabel: (index, length) => `Digit ${index + 1} of ${length}`,
  },
})
```

## Styling guide

Each part includes a `data-part` attribute you can target in CSS.

### Completed state

When all values have been filled, we attach a `data-complete` attribute to the
root and input parts.

```css
[data-part="root"][data-complete] {
  /* styles for when all value has been filled */
}

[data-part="input"][data-complete] {
  /* styles for when all value has been filled */
}
```

### Invalid state

When an invalid value is entered, we attach a `data-invalid` attribute to the
affected input part.

```css
[data-part="input"][data-invalid] {
  /* styles for when the input is invalid */
}
```

### Disabled state

When the pin-input is disabled, we attach a `data-disabled` attribute to the
root and input parts.

```css
[data-part="root"][data-disabled] {
  /* styles for when the input is disabled */
}

[data-part="input"][data-disabled] {
  /* styles for when the input is disabled */
}
```

## Methods and Properties

### Machine Context

The pin input machine exposes the following context properties:

**`name`**
Type: `string | undefined`
Description: The name of the input element. Useful for form submission.

**`form`**
Type: `string | undefined`
Description: The associate form of the underlying input element.

**`pattern`**
Type: `string | undefined`
Description: The regular expression that the user-entered input value is checked against.

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the pin input. Useful for composition.

**`disabled`**
Type: `boolean | undefined`
Description: Whether the inputs are disabled

**`placeholder`**
Type: `string | undefined`
Description: The placeholder text for the input

**`autoFocus`**
Type: `boolean | undefined`
Description: Whether to auto-focus the first input.

**`invalid`**
Type: `boolean | undefined`
Description: Whether the pin input is in the invalid state

**`required`**
Type: `boolean | undefined`
Description: Whether the pin input is required

**`readOnly`**
Type: `boolean | undefined`
Description: Whether the pin input is in the valid state

**`otp`**
Type: `boolean | undefined`
Description: If `true`, the pin input component signals to its fields that they should
use `autocomplete="one-time-code"`.

**`value`**
Type: `string[] | undefined`
Description: The controlled value of the the pin input.

**`defaultValue`**
Type: `string[] | undefined`
Description: The initial value of the the pin input when rendered.
Use when you don't need to control the value of the pin input.

**`type`**
Type: `"alphanumeric" | "numeric" | "alphabetic" | undefined`
Description: The type of value the pin-input should allow

**`onValueComplete`**
Type: `((details: ValueChangeDetails) => void) | undefined`
Description: Function called when all inputs have valid values

**`onValueChange`**
Type: `((details: ValueChangeDetails) => void) | undefined`
Description: Function called on input change

**`onValueInvalid`**
Type: `((details: ValueInvalidDetails) => void) | undefined`
Description: Function called when an invalid value is entered

**`mask`**
Type: `boolean | undefined`
Description: If `true`, the input's value will be masked just like `type=password`

**`autoSubmit`**
Type: `boolean | undefined`
Description: Whether to auto-submit the owning form when all inputs are filled.

**`blurOnComplete`**
Type: `boolean | undefined`
Description: Whether to blur the input when the value is complete

**`selectOnFocus`**
Type: `boolean | undefined`
Description: Whether to select input value when input is focused

**`sanitizeValue`**
Type: `((value: string) => string) | undefined`
Description: Function to sanitize pasted values before validation.
Useful for stripping dashes, spaces, or other formatting.

**`translations`**
Type: `IntlTranslations | undefined`
Description: Specifies the localized strings that identifies the accessibility elements and their states

**`count`**
Type: `number`
Description: The number of pin input fields.

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

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

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

### Machine API

The pin input `api` exposes the following methods:

**`value`**
Type: `string[]`
Description: The value of the input as an array of strings.

**`valueAsString`**
Type: `string`
Description: The value of the input as a string.

**`complete`**
Type: `boolean`
Description: Whether all inputs are filled.

**`count`**
Type: `number`
Description: The number of inputs to render

**`items`**
Type: `number[]`
Description: The array of input values.

**`setValue`**
Type: `(value: string[]) => void`
Description: Function to set the value of the inputs.

**`clearValue`**
Type: `VoidFunction`
Description: Function to clear the value of the inputs.

**`setValueAtIndex`**
Type: `(index: number, value: string) => void`
Description: Function to set the value of the input at a specific index.

**`focus`**
Type: `VoidFunction`
Description: Function to focus the pin-input. This will focus the first input.

### Data Attributes

**`Root`**

**`data-pin-input-root`**: <uid>
**`data-invalid`**: Present when invalid
**`data-disabled`**: Present when disabled
**`data-complete`**: Present when the pin-input value is complete
**`data-readonly`**: Present when read-only

**`Label`**

**`data-pin-input-label`**: <uid>
**`data-invalid`**: Present when invalid
**`data-disabled`**: Present when disabled
**`data-complete`**: Present when the label value is complete
**`data-required`**: Present when required
**`data-readonly`**: Present when read-only

**`Input`**

**`data-pin-input-input`**: <uid>
**`data-disabled`**: Present when disabled
**`data-complete`**: Present when the input value is complete
**`data-filled`**: 
**`data-index`**: The index of the item
**`data-invalid`**: Present when invalid

## Accessibility

### Keyboard Interactions

**`ArrowLeft`**
Description: Moves focus to the previous input

**`ArrowRight`**
Description: Moves focus to the next input

**`Backspace`**
Description: Deletes the value in the current input and moves focus to the previous input

**`Delete`**
Description: Deletes the value in the current input

**`Control + V`**
Description: Pastes the value into the input fields

A popover is a non-modal dialog that floats around a trigger. It is used to
display contextual information to the user, and should be paired with a
clickable trigger element.

## Resources


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



**Features**

- Focus is managed and can be customized
- Supports modal and non-modal modes
- Ensures correct DOM order after tabbing out of the popover
- Supports multiple triggers sharing a single popover instance

## Installation

Install the popover package:

```bash
npm install @zag-js/popover @zag-js/react
# or
yarn add @zag-js/popover @zag-js/react
```

## Anatomy

Check the popover anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the popover package:

```tsx
import * as popover from "@zag-js/popover"
```

The popover package exports two key functions:

- `machine` - State machine logic.
- `connect` - Maps machine state to JSX props and event handlers.

> Pass a unique `id` to `useMachine` so generated element ids stay predictable.

Then use the framework integration helpers:

```tsx
import { useId } from "react"
import * as popover from "@zag-js/popover"
import { useMachine, normalizeProps, Portal } from "@zag-js/react"

export function Popover() {
  const service = useMachine(popover.machine, { id: useId() })

  const api = popover.connect(service, normalizeProps)

  return (
    <div>
      <button {...api.getTriggerProps()}>Click me</button>
      <Portal>
        <div {...api.getPositionerProps()}>
          <div {...api.getContentProps()}>
            <div {...api.getTitleProps()}>Presenters</div>
            <div {...api.getDescriptionProps()}>Description</div>
            <button>Action Button</button>
            <button {...api.getCloseTriggerProps()}>X</button>
          </div>
        </div>
      </Portal>
    </div>
  )
}
```

The positioner is rendered in a `Portal` (or `Teleport`/`use:portal` depending
on your framework). Zag automatically preserves the correct tab order after the
trigger, even though the content lives elsewhere in the DOM.

### Managing focus within popover

When the popover opens, focus moves to the first focusable element. To customize
this, set `initialFocusEl`.

```tsx {3,7,14}
export function Popover() {
  // initial focused element ref
  const inputRef = useRef(null)

  const service = useMachine(popover.machine, {
    id: "1",
    initialFocusEl: () => inputRef.current,
  })

  // ...

  return (
    //...
    <input ref={inputRef} />
    // ...
  )
}
```

To disable automatic focus on open, set `autoFocus` to `false`.

```tsx
const service = useMachine(popover.machine, {
  autoFocus: false,
})
```

### Changing the modality

In some cases, you might want the popover to be **modal**. This means that
it'll:

- trap focus within its content
- block scrolling on the `body`
- disable pointer interactions outside the popover
- hide content behind the popover from screen readers

To make the popover modal, set the `modal: true` property in the machine's
context.

```tsx {2}
const service = useMachine(popover.machine, {
  modal: true,
})
```

### Close behavior

The popover is designed to close on blur and when the `esc` key is pressed.

To prevent it from closing on blur (clicking or focusing outside), pass the
`closeOnInteractOutside` property and set it to `false`.

```tsx {2}
const service = useMachine(popover.machine, {
  closeOnInteractOutside: false,
})
```

To prevent it from closing when the `esc` key is pressed, pass the
`closeOnEscape` property and set it to `false`.

```tsx {2}
const service = useMachine(popover.machine, {
  closeOnEscape: false,
})
```

### Controlled open state

Use `open` and `onOpenChange` to control visibility externally.

```tsx
const service = useMachine(popover.machine, {
  open,
  onOpenChange(details) {
    setOpen(details.open)
  },
})
```

### Adding an arrow

To render an arrow within the popover, use the `api.getArrowProps()` and
`api.getArrowTipProps()`.

```tsx {6-8}
//...
const api = popover.connect(service, normalizeProps)
//...
return (
  <div {...api.getPositionerProps()}>
    <div {...api.getContentProps()}>
      <div {...api.getArrowProps()}>
        <div {...api.getArrowTipProps()} />
      </div>
      //...
    </div>
  </div>
)
//...
```

### Changing the placement

To change the placement of the popover, set the `positioning.placement` property
in the machine's context.

```tsx {2-4}
const service = useMachine(popover.machine, {
  positioning: {
    placement: "top-start",
  },
})
```

### Listening for open state changes

When the popover is opened or closed, the `onOpenChange` callback is invoked.

```tsx {2-7}
const service = useMachine(popover.machine, {
  onOpenChange(details) {
    // details => { open: boolean }
    console.log("Popover", details.open)
  },
})
```

### Multiple triggers

A single popover instance can be shared across multiple trigger elements. Pass a
`value` to `getTriggerProps` to identify each trigger.

```tsx
const service = useMachine(popover.machine, {
  onTriggerValueChange({ value }) {
    console.log("active trigger:", value)
  },
})

const api = popover.connect(service, normalizeProps)

return (
  <>
    <button {...api.getTriggerProps({ value: "info" })}>Info</button>
    <button {...api.getTriggerProps({ value: "help" })}>Help</button>
    <div {...api.getPositionerProps()}>
      <div {...api.getContentProps()}>
        {api.triggerValue === "info" ? "Info content" : "Help content"}
      </div>
    </div>
  </>
)
```

When the popover is open and a different trigger is clicked, it repositions
without closing. Focus returns to the correct trigger on close.

### Usage within dialog

When using the popover within a dialog, avoid rendering the popover in a
`Portal` or `Teleport`. This is because the dialog will trap focus within it,
and the popover will be rendered outside the dialog.

## Styling guide

Each part includes a `data-part` attribute you can target in CSS.

### Open and closed state

When the popover is expanded, we add a `data-state` and `data-placement`
attribute to the trigger.

```css
[data-part="trigger"][data-state="open|closed"] {
  /* styles for the expanded state */
}

[data-part="content"][data-state="open|closed"] {
  /* styles for the expanded state */
}

[data-part="trigger"][data-placement="(top|bottom)-(start|end)"] {
  /* styles for computed placement */
}
```

### Position aware

When the popover is expanded, `data-placement` is added to trigger and content.

```css
[data-part="trigger"][data-placement="(top|bottom)-(start|end)"] {
  /* styles for computed placement */
}

[data-part="content"][data-placement="(top|bottom)-(start|end)"] {
  /* styles for computed placement */
}
```

### Compensating for scrollbar width

When `modal` is `true`, Zag applies `--scrollbar-width` on the root element. Use
this CSS variable to keep fixed or sticky elements aligned when the popover
opens and body scrolling is locked.

```css
.app-header {
  position: fixed;
  inset-inline-end: calc(1rem + var(--scrollbar-width, 0px));
}
```

### Arrow

The arrow element requires specific css variables to be set for it to show
correctly.

```css
[data-part="arrow"] {
  --arrow-background: white;
  --arrow-size: 16px;
}
```

A common technique for adding a shadow to the arrow is to use
`filter: drop-shadow(...)` on the content element. Alternatively, you can use
the `--arrow-shadow-color` variable.

```css
[data-part="arrow"] {
  --arrow-shadow-color: gray;
}
```

## Methods and Properties

### Machine Context

The popover machine exposes the following context properties:

**`translations`**
Type: `IntlTranslations | undefined`
Description: Specifies the localized strings that identifies the accessibility elements and their states

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the popover. Useful for composition.

**`modal`**
Type: `boolean | undefined`
Description: Whether the popover should be modal. When set to `true`:
- interaction with outside elements will be disabled
- only popover content will be visible to screen readers
- scrolling is blocked
- focus is trapped within the popover

**`autoFocus`**
Type: `boolean | undefined`
Description: Whether to automatically set focus on the first focusable
content within the popover when opened.

**`initialFocusEl`**
Type: `(() => HTMLElement | null) | undefined`
Description: The element to focus on when the popover is opened.

**`finalFocusEl`**
Type: `(() => MaybeElement) | undefined`
Description: Element to receive focus when the popover is closed.

**`restoreFocus`**
Type: `boolean | undefined`
Description: Whether to restore focus to the element that had focus before the popover was opened.

**`closeOnInteractOutside`**
Type: `boolean | undefined`
Description: Whether to close the popover when the user clicks outside of the popover.

**`closeOnEscape`**
Type: `boolean | undefined`
Description: Whether to close the popover when the escape key is pressed.

**`onOpenChange`**
Type: `((details: OpenChangeDetails) => void) | undefined`
Description: Function invoked when the popover opens or closes

**`positioning`**
Type: `PositioningOptions | undefined`
Description: The user provided options used to position the popover content

**`open`**
Type: `boolean | undefined`
Description: The controlled open state of the popover

**`defaultOpen`**
Type: `boolean | undefined`
Description: The initial open state of the popover when rendered.
Use when you don't need to control the open state of the popover.

**`triggerValue`**
Type: `string | null | undefined`
Description: The controlled trigger value

**`defaultTriggerValue`**
Type: `string | null | undefined`
Description: The initial trigger value when rendered.
Use when you don't need to control the trigger value.

**`onTriggerValueChange`**
Type: `((details: TriggerValueChangeDetails) => void) | undefined`
Description: Function called when the trigger value changes.

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

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

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

### Machine API

The popover `api` exposes the following methods:

**`open`**
Type: `boolean`
Description: Whether the popover is open

**`setOpen`**
Type: `(open: boolean) => void`
Description: Function to open or close the popover

**`triggerValue`**
Type: `string | null`
Description: The trigger value

**`setTriggerValue`**
Type: `(value: string | null) => void`
Description: Function to set the trigger value

**`reposition`**
Type: `(options?: Partial<PositioningOptions>) => void`
Description: Function to reposition the popover

### Data Attributes

**`Trigger`**

**`data-popover-trigger`**: <uid>
**`data-placement`**: The placement of the trigger
**`data-side`**: The side of the trigger that the trigger is positioned on
**`data-value`**: The value of the item
**`data-current`**: Present when current
**`data-state`**: "open" | "closed"

**`Indicator`**

**`data-popover-indicator`**: <uid>
**`data-state`**: "open" | "closed"

**`Content`**

**`data-popover-content`**: <uid>
**`data-state`**: "open" | "closed"
**`data-nested`**: popover
**`data-has-nested`**: popover
**`data-expanded`**: Present when expanded
**`data-placement`**: The placement of the content
**`data-side`**: The side of the trigger that the content is positioned on

### CSS Variables

<CssVarTable name="popover" />

## Accessibility

Adheres to the
[Dialog WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialogmodal).

### Keyboard Interactions

**`Space`**
Description: Opens/closes the popover.

**`Enter`**
Description: Opens/closes the popover.

**`Tab`**
Description: <span>Moves focus to the next focusable element within the content.<br /><strong>Note:</strong> If there are no focusable elements, focus is moved to the next focusable element after the trigger.</span>

**`Shift + Tab`**
Description: <span>Moves focus to the previous focusable element within the content<br /><strong>Note:</strong> If there are no focusable elements, focus is moved to the trigger.</span>

**`Esc`**
Description: <span>Closes the popover and moves focus to the trigger.</span>

Presence helps manage mount/unmount transitions with exit animations.

When a component is hidden or removed, the DOM usually removes it immediately.
Presence keeps it mounted long enough for exit animations to finish.

> The presence machine requires using **CSS animations** to animate the
> component's exit.

## Resources


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



## Installation

Install the presence package:

```bash
npm install @zag-js/presence @zag-js/react
# or
yarn add @zag-js/presence @zag-js/react
```

## Usage

Import the presence package:

```tsx
import * as presence from "@zag-js/presence"
```

The presence 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:

```tsx
import * as presence from "@zag-js/presence"
import { useMachine, normalizeProps } from "@zag-js/react"

interface PresenceProps {
  present: boolean
  unmountOnExit?: boolean
  onExitComplete?: () => void
}

function Presence(props: PresenceProps) {
  const { unmountOnExit, present, onExitComplete, ...rest } = props

  const service = useMachine(presence.machine, {
    present,
    onExitComplete,
  })

  const api = presence.connect(service, normalizeProps)

  if (!api.present && unmountOnExit) return null

  return (
    <div
      hidden={!api.present}
      data-state={api.skip ? undefined : present ? "open" : "closed"}
      ref={api.setNode}
      {...rest}
    />
  )
}
```

### Running code after exit animation

Use `onExitComplete` to run logic after the exit animation finishes.

```tsx
const service = useMachine(presence.machine, {
  present: open,
  onExitComplete() {
    console.log("Exit animation finished")
  },
})
```

### Applying presence changes immediately

Set `immediate` to `true` to skip deferring present-state changes to the next
frame.

```tsx
const service = useMachine(presence.machine, {
  present: open,
  immediate: true,
})
```

## Styling guide

To style any entry and exit animations, set up the `@keyframes` and apply the
animations.

```css
@keyframes enter {
  from {
    scale: 0.9;
    opacity: 0;
  }

  to {
    opacity: 1;
    scale: 1;
  }
}

@keyframes exit {
  to {
    opacity: 0;
    scale: 0.9;
  }
}

[data-state="open"] {
  animation: enter 0.15s ease-out;
}

[data-state="closed"] {
  animation: exit 0.1s ease-in;
}
```

You can then use the `Presence` component in your project.

```tsx
function Example() {
  const [open, setOpen] = React.useState(true)
  return (
    <>
      <button onClick={() => setOpen((c) => !c)}>Toggle</button>
      <Presence present={open} unmountOnExit>
        <div>Content</div>
      </Presence>
    </>
  )
}
```

## Methods and Properties

### Machine Context

The presence machine exposes the following context properties:

**`present`**
Type: `boolean | undefined`
Description: Whether the node is present (controlled by the user)

**`onExitComplete`**
Type: `VoidFunction | undefined`
Description: Function called when the animation ends in the closed state

**`immediate`**
Type: `boolean | undefined`
Description: Whether to synchronize the present change immediately or defer it to the next frame

### Machine API

The presence `api` exposes the following methods:

**`skip`**
Type: `boolean`
Description: Whether the animation should be skipped.

**`present`**
Type: `boolean`
Description: Whether the node is present in the DOM.

**`setNode`**
Type: `(node: HTMLElement | null) => void`
Description: Function to set the node (as early as possible)

**`unmount`**
Type: `VoidFunction`
Description: Function to programmatically unmount the node

Linear progress is a simple progress bar that can be used to show the progress
of a task such as downloading a file, uploading an image, etc.

## Resources


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



**Features**

- Supports minimum and maximum values
- Supports indeterminate progress bars

## Installation

Install the progress package:

```bash
npm install @zag-js/progress @zag-js/react
# or
yarn add @zag-js/progress @zag-js/react
```

## Anatomy

Check the progress anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the progress package:

```tsx
import * as progress from "@zag-js/progress"
```

The progress package exports two key functions:

- `machine` - State machine logic.
- `connect` - Maps machine state to JSX props and event handlers.

> Pass a unique `id` to `useMachine` so generated element ids stay predictable.

Then use the framework integration helpers:

```tsx
import * as progress from "@zag-js/progress"
import { normalizeProps, useMachine } from "@zag-js/react"
import { useId } from "react"

function Progress() {
  const service = useMachine(progress.machine, { id: useId() })

  const api = progress.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <div {...api.getLabelProps()}>Upload progress</div>
      <div {...api.getTrackProps()}>
        <div {...api.getRangeProps()} />
      </div>
    </div>
  )
}
```

### Setting the value

Use `defaultValue` for uncontrolled state, or `value` for controlled state.

```tsx {2}
const service = useMachine(progress.machine, {
  value: 50,
})
```

Subsequently, you can use the `api.setValue` method to set the value of the
progress bar.

```tsx
api.setValue(50)
```

### Listening for value changes

Use `onValueChange` to react to progress updates.

```tsx
const service = useMachine(progress.machine, {
  onValueChange(details) {
    // details => { value: number | null }
    console.log(details.value)
  },
})
```

### Setting the minimum and maximum values

By default, the progress bar has a minimum value of `0` and a maximum value of
`100`. You can change these values by passing the `min` and `max` options to the
machine.

```tsx {2-3}
const service = useMachine(progress.machine, {
  min: 0,
  max: 1000,
})
```

### Vertical orientation

Set `orientation` to `vertical` for a vertical progress bar.

```tsx
const service = useMachine(progress.machine, {
  orientation: "vertical",
})
```

### Using the indeterminate state

The progress component is determinate by default, with the value and max set to
`50` and `100` respectively.

Set `value` to `null` to indicate an indeterminate value for operations whose
progress can't be determined (e.g., attempting to reconnect to a server).

```tsx {2}
const service = useMachine(progress.machine, {
  value: null,
})
```

### Customizing value text

Progress bars can only be interpreted by sighted users. To include a text
description to support assistive technologies like screen readers, use the
`valueText` part.

```tsx
const service = useMachine(progress.machine, {
  translations: {
    value: ({ value, max }) =>
      value == null ? "Loading..." : `${value} of ${max} items loaded`,
  },
})
```

Then you need to render the `valueText` part in your component.

```tsx
<div {...api.getValueTextProps()}>{api.valueAsString}</div>
```

### Localizing percentage formatting

Use `locale` and `formatOptions` to customize number formatting.

```tsx
const service = useMachine(progress.machine, {
  locale: "fr-FR",
  formatOptions: { style: "percent", maximumFractionDigits: 1 },
})
```

## Styling guide

Each part includes a `data-part` attribute you can target in CSS.

```css
[data-scope="progress"][data-part="root"] {
  /* Styles for the root part */
}

[data-scope="progress"][data-part="track"] {
  /* Styles for the track part */
}

[data-scope="progress"][data-part="range"] {
  /* Styles for the range part */
}
```

### Indeterminate state

To style the indeterminate state, you can use the `[data-state=indeterminate]`
selector.

```css
[data-scope="progress"][data-part="root"][data-state="indeterminate"] {
  /* Styles for the root indeterminate state */
}

[data-scope="progress"][data-part="track"][data-state="indeterminate"] {
  /* Styles for the root indeterminate state */
}

[data-scope="progress"][data-part="range"][data-state="indeterminate"] {
  /* Styles for the root indeterminate state */
}
```

## Methods and Properties

### Machine Context

The progress machine exposes the following context properties:

<ContextTable name="progress" />

### Machine API

The progress `api` exposes the following methods:

<ApiTable name="progress" />

### Data Attributes

<DataAttrTable name="progress" />

### CSS Variables

<CssVarTable name="progress" />

Circular progress is a circular progress bar that can be used to show the
progress of a task such as downloading a file, uploading an image, etc.

## Resources


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



**Features**

- Supports minimum and maximum values
- Supports indeterminate progress bars

## Installation

Install the progress package:

```bash
npm install @zag-js/progress @zag-js/react
# or
yarn add @zag-js/progress @zag-js/react
```

## Anatomy

Check the progress anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the progress package:

```tsx
import * as progress from "@zag-js/progress"
```

The progress package exports two key functions:

- `machine` - State machine logic.
- `connect` - Maps machine state to JSX props and event handlers.

> Pass a unique `id` to `useMachine` so generated element ids stay predictable.

Then use the framework integration helpers:

```tsx
import * as progress from "@zag-js/progress"
import { normalizeProps, useMachine } from "@zag-js/react"
import { useId } from "react"

function Progress() {
  const service = useMachine(progress.machine, { id: useId() })

  const api = progress.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <div {...api.getLabelProps()}>Upload progress</div>
      <svg {...api.getCircleProps()}>
        <circle {...api.getCircleTrackProps()} />
        <circle {...api.getCircleRangeProps()} />
      </svg>
    </div>
  )
}
```

### Setting the value

Use `defaultValue` for uncontrolled state, or `value` for controlled state.

```tsx {2}
const service = useMachine(progress.machine, {
  defaultValue: 50,
})
```

Subsequently, you can use the `api.setValue` method to set the value of the
progress bar.

```tsx
api.setValue(50)
```

### Listening for value changes

Use `onValueChange` to react to progress updates.

```tsx
const service = useMachine(progress.machine, {
  onValueChange(details) {
    // details => { value: number | null }
    console.log(details.value)
  },
})
```

### Setting the minimum and maximum values

By default, the progress bar has a minimum value of `0` and a maximum value of
`100`. You can change these values by passing the `min` and `max` options to the
machine.

```tsx {2-3}
const service = useMachine(progress.machine, {
  min: 0,
  max: 1000,
})
```

### Using the indeterminate state

The progress component is determinate by default, with the value and max set to
`50` and `100` respectively.

Set `value` to `null` to indicate an indeterminate value for operations whose
progress can't be determined (e.g., attempting to reconnect to a server).

```tsx {2}
const service = useMachine(progress.machine, {
  defaultValue: null,
})
```

### Customizing value text

Progress bars can only be interpreted by sighted users. To include a text
description to support assistive technologies like screen readers, use the
`valueText` part.

```tsx
const service = useMachine(progress.machine, {
  translations: {
    value: ({ value, max }) =>
      value == null ? "Loading..." : `${value} of ${max} items loaded`,
  },
})
```

### Setting the size of the progress bar

Use the `--size` CSS variable to set the size of the progress bar.

```css
[data-scope="progress"][data-part="circle"] {
  --size: 400px;
}
```

### Setting the thickness of the progress bar

Use the `--thickness` CSS variable to set the size of the progress bar.

```css
[data-scope="progress"][data-part="circle"] {
  --thickness: 4px;
}
```

Then you need to render the `valueText` part in your component.

```tsx
<div {...api.getValueTextProps()}>{api.valueAsString}</div>
```

### Localizing percentage formatting

Use `locale` and `formatOptions` to customize number formatting.

```tsx
const service = useMachine(progress.machine, {
  locale: "fr-FR",
  formatOptions: { style: "percent", maximumFractionDigits: 1 },
})
```

## Styling guide

Each part includes a `data-part` attribute you can target in CSS.

```css
[data-scope="progress"][data-part="root"] {
  /* Styles for the root part */
}

[data-scope="progress"][data-part="circle-track"] {
  /* Styles for the track part */
}

[data-scope="progress"][data-part="circle-range"] {
  /* Styles for the range part */
}
```

### Indeterminate state

To style the indeterminate state, you can use the `[data-state=indeterminate]`
selector.

```css
[data-scope="progress"][data-part="root"][data-state="indeterminate"] {
  /* Styles for the root indeterminate state */
}

[data-scope="progress"][data-part="circle-track"][data-state="indeterminate"] {
  /* Styles for the root indeterminate state */
}

[data-scope="progress"][data-part="circle-range"][data-state="indeterminate"] {
  /* Styles for the root indeterminate state */
}
```

## Methods and Properties

### Machine Context

The progress machine exposes the following context properties:

<ContextTable name="progress" />

### Machine API

The progress `api` exposes the following methods:

<ApiTable name="progress" />

### Data Attributes

<DataAttrTable name="progress" />

A QR code encodes information or links that can be scanned with a phone or app.

> **Good to know**: The QR code encoding logic is built on top of the
> [`uqr`](https://github.com/unjs/uqr) library.

## Resources


[Latest version: v2.0.0-next.1](https://www.npmjs.com/package/@zag-js/qr-code)
[Logic Visualizer](https://zag-visualizer.vercel.app/qr-code)
[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/qr-code)



**Features**

- Renders an SVG element (good for SSR)
- Customize the size of the QR code in pixels
- Set the error correction level
- Customize the background and foreground color

## Installation

Install the QR code package:

```bash
npm install @zag-js/qr-code @zag-js/react
# or
yarn add @zag-js/qr-code @zag-js/react
```

## Anatomy

Check the QR code anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the QR code package:

```tsx
import * as qrCode from "@zag-js/qr-code"
```

These are the key exports:

- `machine` - State machine logic.
- `connect` - Maps machine state to JSX props and event handlers.

Then use the framework integration helpers:

```tsx
import * as qrCode from "@zag-js/qr-code"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useId } from "react"

export function QRCode() {
  const service = useMachine(qrCode.machine, {
    id: useId(),
    value: "https://github.com/chakra-ui",
  })

  const api = qrCode.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <svg {...api.getFrameProps()}>
        <path {...api.getPatternProps()} />
      </svg>
      <div {...api.getOverlayProps()}>
        <img
          src="https://avatars.githubusercontent.com/u/54212428?s=88&v=4"
          alt=""
        />
      </div>
    </div>
  )
}
```

### Setting the QR code value

Set `value` to control the encoded content.

```tsx {3}
const service = useMachine(qrCode.machine, {
  // ...
  value: "https://example.com",
})
```

### Setting an initial value

Use `defaultValue` for an uncontrolled initial value.

```tsx
const service = useMachine(qrCode.machine, {
  defaultValue: "https://example.com",
})
```

### Listening for value changes

Use `onValueChange` to react when the encoded value changes.

```tsx
const service = useMachine(qrCode.machine, {
  onValueChange(details) {
    // details => { value: string }
    console.log(details.value)
  },
})
```

### Setting pixel size

Use `pixelSize` to control QR code density.

```tsx
const service = useMachine(qrCode.machine, {
  value: "https://example.com",
  pixelSize: 8,
})
```

### Setting the correction level

Error correction allows for the QR code to be blocked or resized while still
recognizable. In some cases where the link is too long or the logo overlay
covers a significant area, the error correction level can be increased.

The QR code machine accepts the following error correction levels:

- `L`: Allows recovery of up to 7% data loss (default)
- `M`: Allows recovery of up to 15% data loss
- `Q`: Allows recovery of up to 25% data loss
- `H`: Allows recovery of up to 30% data loss

To set the error correction level, pass the `encoding.ecc` or
`encoding.boostEcc` context property.

```tsx {3}
const service = useMachine(qrCode.machine, {
  value: "...",
  encoding: { ecc: "H" },
})
```

> The alternative is to enlarge the QRCode by increasing the size of the `svg`
> element.

### Adding an overlay logo

To add a logo overlay to the QR code, render the image part. The logo will be
automatically centered within the QR code.

```tsx {3}
<div {...api.getRootProps()}>
  <svg {...api.getFrameProps()}>{/** ... */}</svg>
  <div {...api.getOverlayProps()}>
    <img src="..." alt="" />
  </div>
</div>
```

### Changing the color

To change the color of the QR code, set the `fill` attribute on the `path` part.

```css
[data-scope="qr-code"][data-part="pattern"] {
  fill: green;
}
```

To change the background color of the QR code, set the `background-color`

```css
[data-scope="qr-code"][data-part="frame"] {
  background-color: white;
}
```

### Exporting the QR code

To export the QR code as an image, use `api.getDataUrl`.

```ts
api.getDataUrl("image/png").then((url) => {
  // do something with the URL (like download it)
})
```

You can also use `api.getDownloadTriggerProps` to create a download button.

```tsx
<button
  {...api.getDownloadTriggerProps({
    mimeType: "image/png",
    fileName: "qr-code",
  })}
>
  Download QR
</button>
```

## Styling guide

Each part includes a `data-part` attribute you can target in CSS.

```css
[data-scope="qr-code"][data-part="root"] {
  /* Styles for the root part */
}

[data-scope="qr-code"][data-part="frame"] {
  /* Styles for the svg part */
}

[data-scope="qr-code"][data-part="pattern"] {
  /* Styles for the path */
}

[data-scope="qr-code"][data-part="overlay"] {
  /* Styles for the logo */
}
```

## Methods and Properties

### Machine Context

The QR code machine exposes the following context properties:

**`value`**
Type: `string | undefined`
Description: The controlled value to encode.

**`defaultValue`**
Type: `string | undefined`
Description: The initial value to encode when rendered.
Use when you don't need to control the value of the qr code.

**`ids`**
Type: `ElementIds | undefined`
Description: The element ids.

**`encoding`**
Type: `QrCodeGenerateOptions | undefined`
Description: The qr code encoding options.

**`onValueChange`**
Type: `((details: ValueChangeDetails) => void) | undefined`
Description: Callback fired when the value changes.

**`pixelSize`**
Type: `number | undefined`
Description: The pixel size of the qr code.

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

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

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

### Machine API

The QR code `api` exposes the following methods:

**`value`**
Type: `string`
Description: The value to encode.

**`setValue`**
Type: `(value: string) => void`
Description: Set the value to encode.

**`getDataUrl`**
Type: `(type: DataUrlType, quality?: number) => Promise<string>`
Description: Returns the data URL of the qr code.

A radio group lets users select one option from a set.

## Resources


[Latest version: v2.0.0-next.1](https://www.npmjs.com/package/@zag-js/radio-group)
[Logic Visualizer](https://zag-visualizer.vercel.app/radio-group)
[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/radio-group)



**Features**

- Syncs with `disabled` state of fieldset
- Syncs with form `reset` events
- Can programmatically set radio group value
- Can programmatically focus and blur radio items

## Installation

Install the radio package:

```bash
npm install @zag-js/radio-group @zag-js/react
# or
yarn add @zag-js/radio-group @zag-js/react
```

## Anatomy

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

Import the radio group package:

```tsx
import * as radio from "@zag-js/radio-group"
```

The radio package exports two key functions:

- `machine` - State machine logic.
- `connect` - Maps machine state to JSX props and event handlers.

> Pass a unique `id` to `useMachine` so generated element ids stay predictable.

Then use the framework integration helpers:

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

const items = [
  { id: "apple", label: "Apples" },
  { id: "orange", label: "Oranges" },
  { id: "mango", label: "Mangoes" },
  { id: "grape", label: "Grapes" },
]

function Radio() {
  const service = useMachine(radio.machine, { id: useId() })

  const api = radio.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <h3 {...api.getLabelProps()}>Fruits</h3>
      {items.map((opt) => (
        <label key={opt.id} {...api.getItemProps({ value: opt.id })}>
          <span {...api.getItemTextProps({ value: opt.id })}>{opt.label}</span>
          <input {...api.getItemHiddenInputProps({ value: opt.id })} />
          <div {...api.getItemControlProps({ value: opt.id })} />
        </label>
      ))}
    </div>
  )
}
```

### Disabling the radio group

Set `disabled` to `true` to disable all radio items.

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

### Setting the initial value

Use the `defaultValue` property to set the radio group's initial value.

```tsx {2}
const service = useMachine(radio.machine, {
  defaultValue: "apple",
})
```

### Controlled value

Use `value` and `onValueChange` to control selection externally.

```tsx
const service = useMachine(radio.machine, {
  value,
  onValueChange(details) {
    setValue(details.value)
  },
})
```

### Listening for changes

When the radio group value changes, the `onValueChange` callback is invoked.

```tsx {2-7}
const service = useMachine(radio.machine, {
  onValueChange(details) {
    // details => { value: string | null }
    console.log("radio value is:", details.value)
  },
})
```

### Usage within forms

To use radio group in forms, set `name`.

```tsx {2}
const service = useMachine(radio.machine, {
  name: "fruits",
})
```

Set `form` if the radio inputs should submit with a form outside the current DOM
subtree.

```tsx
const service = useMachine(radio.machine, {
  name: "fruits",
  form: "checkout-form",
})
```

### Vertical orientation

Set `orientation` when you need a vertical layout.

```tsx
const service = useMachine(radio.machine, {
  orientation: "vertical",
})
```

### Read-only and required state

Use `readOnly` and `required` to control form behavior.

```tsx
const service = useMachine(radio.machine, {
  readOnly: true,
  required: true,
})
```

### Invalid state

Set `invalid` to style and expose invalid form state.

```tsx
const service = useMachine(radio.machine, {
  invalid: true,
})
```

## Styling guide

Each radio part includes a `data-part` attribute you can target in CSS.

### Checked State

When the radio input is checked, the `data-state` attribute is added to the
item, control, and label parts.

```css
[data-part="radio"][data-state="checked|unchecked"] {
  /* styles for radio checked or unchecked state */
}

[data-part="radio-control"][data-state="checked|unchecked"] {
  /* styles for radio checked or unchecked state */
}

[data-part="radio-label"][data-state="checked|unchecked"] {
  /* styles for radio checked or unchecked state */
}
```

### Focused State

When the radio input is focused, the `data-focus` attribute is added to the
root, control and label parts.

```css
[data-part="radio"][data-focus] {
  /* styles for radio focus state */
}

[data-part="radio-control"][data-focus] {
  /* styles for radio control focus state */
}

[data-part="radio-label"][data-focus] {
  /* styles for radio label focus state */
}
```

### Disabled State

When the radio is disabled, the `data-disabled` attribute is added to the root,
control and label parts.

```css
[data-part="radio"][data-disabled] {
  /* styles for radio disabled state */
}

[data-part="radio-control"][data-disabled] {
  /* styles for radio control disabled state */
}

[data-part="radio-label"][data-disabled] {
  /* styles for radio label disabled state */
}
```

### Invalid State

When the radio is invalid, the `data-invalid` attribute is added to the root,
control and label parts.

```css
[data-part="radio"][data-invalid] {
  /* styles for radio invalid state */
}

[data-part="radio-control"][data-invalid] {
  /* styles for radio control invalid state */
}

[data-part="radio-label"][data-invalid] {
  /* styles for radio label invalid state */
}
```

## Methods and Properties

### Machine Context

The radio group machine exposes the following context properties:

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the radio. Useful for composition.

**`value`**
Type: `string | null | undefined`
Description: The controlled value of the radio group

**`defaultValue`**
Type: `string | null | undefined`
Description: The initial value of the checked radio when rendered.
Use when you don't need to control the value of the radio group.

**`name`**
Type: `string | undefined`
Description: The name of the input fields in the radio
(Useful for form submission).

**`form`**
Type: `string | undefined`
Description: The associate form of the underlying input.

**`disabled`**
Type: `boolean | undefined`
Description: If `true`, the radio group will be disabled

**`invalid`**
Type: `boolean | undefined`
Description: If `true`, the radio group is marked as invalid.

**`required`**
Type: `boolean | undefined`
Description: If `true`, the radio group is marked as required.

**`readOnly`**
Type: `boolean | undefined`
Description: Whether the radio group is read-only

**`onValueChange`**
Type: `((details: ValueChangeDetails) => void) | undefined`
Description: Function called once a radio is checked

**`orientation`**
Type: `"horizontal" | "vertical" | undefined`
Description: Orientation of the radio group

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

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

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

### Machine API

The radio group `api` exposes the following methods:

**`value`**
Type: `string | null`
Description: The current value of the radio group

**`setValue`**
Type: `(value: string) => void`
Description: Function to set the value of the radio group

**`clearValue`**
Type: `VoidFunction`
Description: Function to clear the value of the radio group

**`focus`**
Type: `VoidFunction`
Description: Function to focus the radio group

**`getItemState`**
Type: `(props: ItemProps) => ItemState`
Description: Returns the state details of a radio input

## Accessibility

Adheres to the
[Radio Group WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radiobutton)

### Keyboard Interactions

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

**`Space`**
Description: When focus is on an unchecked radio item, checks it.

**`ArrowDown`**
Description: Moves focus and checks the next radio item in the group.

**`ArrowRight`**
Description: Moves focus and checks the next radio item in the group.

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

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

Rating group lets users assign a rating value to an item.

## Resources


[Latest version: v2.0.0-next.1](https://www.npmjs.com/package/@zag-js/rating-group)
[Logic Visualizer](https://zag-visualizer.vercel.app/rating-group)
[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/rating-group)



**Features**

- Syncs with `disabled` state of `fieldset`
- Supports form `reset` events

## Installation

Install the rating group package:

```bash
npm install @zag-js/rating-group @zag-js/react
# or
yarn add @zag-js/rating-group @zag-js/react
```

## Anatomy

Check the rating anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the rating package:

```tsx
import * as rating from "@zag-js/rating-group"
```

The rating 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:

```tsx
import * as rating from "@zag-js/rating-group"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useId } from "react"
import { HalfStar, Star } from "./icons"

function Rating() {
  const service = useMachine(rating.machine, { id: useId() })

  const api = rating.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <label {...api.getLabelProps()}>Rate:</label>
      <div {...api.getControlProps()}>
        {api.items.map((index) => {
          const state = api.getItemState({ index })
          return (
            <span key={index} {...api.getItemProps({ index })}>
              {state.half ? <HalfStar /> : <Star />}
            </span>
          )
        })}
      </div>
      <input {...api.getHiddenInputProps()} />
    </div>
  )
}
```

### Setting the initial value

Use the `defaultValue` property to set the rating's initial value.

```tsx {2}
const service = useMachine(rating.machine, {
  defaultValue: 2.5,
})
```

### Controlled rating value

Use `value` and `onValueChange` to control the rating externally.

```tsx
const service = useMachine(rating.machine, {
  value,
  onValueChange(details) {
    setValue(details.value)
  },
})
```

### Setting and clearing value programmatically

Use `api.setValue` or `api.clearValue` when you need imperative control.

```tsx
api.setValue(4)
api.clearValue()
```

### Allowing half ratings

Enable `allowHalf` when your UX needs fractional ratings.

```tsx
const service = useMachine(rating.machine, {
  allowHalf: true,
})
```

### Listening for changes

When the rating value changes, the `onValueChange` callback is invoked.

```tsx {2-7}
const service = useMachine(rating.machine, {
  onValueChange({ value }) {
    console.log("rating value is:", value)
    // 1 | 2.5 | 4
  },
})
```

### Listening for hover changes

Use `onHoverChange` to react to hover previews before selection.

```tsx
const service = useMachine(rating.machine, {
  onHoverChange(details) {
    console.log("hovered rating:", details.hoveredValue)
  },
})
```

### Customizing screen reader value text

Use `translations.ratingValueText` to customize how each rating item is
announced.

```tsx
const service = useMachine(rating.machine, {
  translations: {
    ratingValueText: (index) => `${index} out of 5`,
  },
})
```

### Usage within forms

To use rating in forms, set `name` and render `api.getHiddenInputProps()`.

```tsx {2}
const service = useMachine(rating.machine, {
  name: "rating",
})
```

## Styling guide

Each rating part includes a `data-part` attribute you can target in CSS.

### Disabled State

When the rating is disabled, the `data-disabled` attribute is added to the
rating, control and label parts.

```css
[data-part="rating"][data-disabled] {
  /* styles for rating disabled state */
}

[data-part="label"][data-disabled] {
  /* styles for rating control disabled state */
}

[data-part="input"][data-disabled] {
  /* styles for rating label disabled state */
}
```

### Checked State

When the rating is checked, the `data-checked` attribute is added to the rating
part.

```css
[data-part="rating"][data-checked] {
  /* styles for rating checked state */
}
```

### Readonly State

When the rating is readonly, the `data-readonly` attribute is added to the
rating part.

```css
[data-part="rating"][data-readonly] {
  /* styles for rating readonly state */
}
```

### Highlighted

When a rating is highlighted, the `data-highlighted` attribute is added to the
rating part.

```css
[data-part="rating"][data-highlighted] {
  /* styles for highlighted rating */
}
```

### Half rating

When a rating is half, the `data-half` attribute is added to the rating part.

```css
[data-part="rating"][data-half] {
  /* styles for half rating */
}
```

## Methods and Properties

### Machine Context

The rating group machine exposes the following context properties:

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the rating. Useful for composition.

**`translations`**
Type: `IntlTranslations | undefined`
Description: Specifies the localized strings that identifies the accessibility elements and their states

**`count`**
Type: `number | undefined`
Description: The total number of ratings.

**`name`**
Type: `string | undefined`
Description: The name attribute of the rating element (used in forms).

**`form`**
Type: `string | undefined`
Description: The associate form of the underlying input element.

**`value`**
Type: `number | undefined`
Description: The controlled value of the rating

**`defaultValue`**
Type: `number | undefined`
Description: The initial value of the rating when rendered.
Use when you don't need to control the value of the rating.

**`readOnly`**
Type: `boolean | undefined`
Description: Whether the rating is readonly.

**`disabled`**
Type: `boolean | undefined`
Description: Whether the rating is disabled.

**`required`**
Type: `boolean | undefined`
Description: Whether the rating is required.

**`allowHalf`**
Type: `boolean | undefined`
Description: Whether to allow half stars.

**`autoFocus`**
Type: `boolean | undefined`
Description: Whether to autofocus the rating.

**`onValueChange`**
Type: `((details: ValueChangeDetails) => void) | undefined`
Description: Function to be called when the rating value changes.

**`onHoverChange`**
Type: `((details: HoverChangeDetails) => void) | undefined`
Description: Function to be called when the rating value is hovered.

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

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

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

### Machine API

The rating group `api` exposes the following methods:

**`setValue`**
Type: `(value: number) => void`
Description: Sets the value of the rating group

**`clearValue`**
Type: `VoidFunction`
Description: Clears the value of the rating group

**`hovering`**
Type: `boolean`
Description: Whether the rating group is being hovered

**`value`**
Type: `number`
Description: The current value of the rating group

**`hoveredValue`**
Type: `number`
Description: The value of the currently hovered rating

**`count`**
Type: `number`
Description: The total number of ratings

**`items`**
Type: `number[]`
Description: The array of rating values. Returns an array of numbers from 1 to the max value.

**`getItemState`**
Type: `(props: ItemProps) => ItemState`
Description: Returns the state of a rating item

### Data Attributes

**`Label`**

**`data-rating-group-label`**: <uid>
**`data-disabled`**: Present when disabled
**`data-required`**: Present when required

**`Control`**

**`data-rating-group-control`**: <uid>
**`data-readonly`**: Present when read-only
**`data-disabled`**: Present when disabled

**`Item`**

**`data-rating-group-item`**: <uid>
**`data-disabled`**: Present when disabled
**`data-readonly`**: Present when read-only
**`data-checked`**: Present when checked
**`data-highlighted`**: Present when highlighted
**`data-half`**: 

## Accessibility

### Keyboard Interactions

**`ArrowRight`**
Description: Moves focus to the next star, increasing the rating value based on the `allowHalf` property.

**`ArrowLeft`**
Description: Moves focus to the previous star, decreasing the rating value based on the `allowHalf` property.

**`Enter`**
Description: Selects the focused star in the rating group.

A scroll area provides a custom-scrollbar viewport for overflow content.

## Resources


[Latest version: v2.0.0-next.1](https://www.npmjs.com/package/@zag-js/scroll-area)
[Logic Visualizer](https://zag-visualizer.vercel.app/scroll-area)
[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/scroll-area)



**Features**

- Programmatic scrolling to edges or coordinates
- Scroll position and overflow state helpers
- Scrollbar state for styling (`hovering`, `scrolling`, `hidden`)
- Horizontal and vertical scrollbar support

## Installation

Install the scroll area package:

```bash
npm install @zag-js/scroll-area @zag-js/react
# or
yarn add @zag-js/scroll-area @zag-js/react
```

## Anatomy

To set up the scroll area 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 scroll area package:

```tsx
import * as scrollArea from "@zag-js/scroll-area"
```

The scroll area 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:

```tsx
import * as scrollArea from "@zag-js/scroll-area"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useId } from "react"

function ScrollArea() {
  const service = useMachine(scrollArea.machine, {
    id: useId(),
  })

  const api = scrollArea.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <div {...api.getViewportProps()}>
        <div {...api.getContentProps()}>
          {/* Your scrollable content here */}
        </div>
      </div>
      <div {...api.getScrollbarProps()}>
        <div {...api.getThumbProps()} />
      </div>
    </div>
  )
}
```

### Programmatic scrolling to edges

You can programmatically scroll to any edge of the scroll area using the
`scrollToEdge` method:

```tsx
// Scroll to bottom
api.scrollToEdge({ edge: "bottom" })

// Scroll to top with custom easing
api.scrollToEdge({
  edge: "top",
  duration: 500,
  easing: (t) => t * t,
})
```

### Programmatic scrolling to coordinates

Use the `scrollTo` method to scroll to specific coordinates:

```tsx
// Scroll to specific position
api.scrollTo({
  top: 100,
  left: 50,
})

// Scroll with smooth behavior
api.scrollTo({
  top: 200,
  behavior: "smooth",
  duration: 300,
})
```

### Reading scroll position and overflow

The API provides several properties to check the current scroll state:

```tsx
// Check if at edges
console.log(api.isAtTop) // boolean
console.log(api.isAtBottom) // boolean
console.log(api.isAtLeft) // boolean
console.log(api.isAtRight) // boolean

// Check for overflow
console.log(api.hasOverflowX) // boolean
console.log(api.hasOverflowY) // boolean

// Get scroll progress (0-1)
const progress = api.getScrollProgress() // { x: number, y: number }
```

### Rendering scrollbars only when needed

Only render scrollbars when there's overflow content:

```tsx
{
  api.hasOverflowY && (
    <div {...api.getScrollbarProps({ orientation: "vertical" })}>
      <div {...api.getThumbProps({ orientation: "vertical" })} />
    </div>
  )
}

{
  api.hasOverflowX && (
    <div {...api.getScrollbarProps({ orientation: "horizontal" })}>
      <div {...api.getThumbProps({ orientation: "horizontal" })} />
    </div>
  )
}
```

### Scrollbar state

Get the current state of a scrollbar for styling purposes:

```tsx
const verticalState = api.getScrollbarState({ orientation: "vertical" })
// Returns: { hovering: boolean, scrolling: boolean, hidden: boolean }
```

## Styling guide

Each part includes a `data-part` attribute you can target in CSS.

### Required styles

The scroll area requires the following styles on the viewport element to hide
the native scrollbar:

```css
[data-scope="scroll-area"][data-part="viewport"] {
  scrollbar-width: none;
  &::-webkit-scrollbar {
    display: none;
  }
}
```

### Scrolling state

When the user is actively scrolling, a `data-scrolling` attribute is set on the
scrollbar elements:

```css
[data-part="scrollbar"][data-scrolling] {
  /* styles when actively scrolling */
}

[data-part="thumb"][data-scrolling] {
  /* styles for thumb when scrolling */
}
```

### Hover state

When hovering over the scroll area or scrollbar, a `data-hover` attribute is
applied:

```css
[data-part="root"][data-hover] {
  /* styles when hovering over scroll area */
}

[data-part="scrollbar"][data-hover] {
  /* styles when hovering over scrollbar */
}
```

### Hidden state

Scrollbars can be automatically hidden when not needed:

```css
[data-part="scrollbar"][data-hidden] {
  /* styles for hidden scrollbar */
  opacity: 0;
  pointer-events: none;
}
```

### Orientation

Different styles can be applied based on scrollbar orientation:

```css
[data-part="scrollbar"][data-orientation="vertical"] {
  /* vertical scrollbar styles */
}

[data-part="scrollbar"][data-orientation="horizontal"] {
  /* horizontal scrollbar styles */
}
```

## Methods and Properties

The scroll area's `api` exposes the following methods and properties:

### Machine Context

The scroll area machine exposes the following context properties:

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the scroll area elements

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

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

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

### Machine API

The scroll area `api` exposes the following methods:

**`isAtTop`**
Type: `boolean`
Description: Whether the scroll area is at the top

**`isAtBottom`**
Type: `boolean`
Description: Whether the scroll area is at the bottom

**`isAtLeft`**
Type: `boolean`
Description: Whether the scroll area is at the left

**`isAtRight`**
Type: `boolean`
Description: Whether the scroll area is at the right

**`hasOverflowX`**
Type: `boolean`
Description: Whether the scroll area has horizontal overflow

**`hasOverflowY`**
Type: `boolean`
Description: Whether the scroll area has vertical overflow

**`getScrollProgress`**
Type: `() => Point`
Description: Get the scroll progress as values between 0 and 1

**`scrollToEdge`**
Type: `(details: ScrollToEdgeDetails) => void`
Description: Scroll to the edge of the scroll area

**`scrollTo`**
Type: `(details: ScrollToDetails) => void`
Description: Scroll to specific coordinates

**`getScrollbarState`**
Type: `(props: ScrollbarProps) => ScrollbarState`
Description: Returns the state of the scrollbar

### Data Attributes

**`Root`**

**`data-scroll-area-root`**: <uid>
**`data-overflow-x`**: Present when the content overflows the x-axis
**`data-overflow-y`**: Present when the content overflows the y-axis

**`Viewport`**

**`data-scroll-area-viewport`**: <uid>
**`data-at-top`**: Present when scrolled to the top edge
**`data-at-bottom`**: Present when scrolled to the bottom edge
**`data-at-left`**: Present when scrolled to the left edge
**`data-at-right`**: Present when scrolled to the right edge
**`data-overflow-x`**: Present when the content overflows the x-axis
**`data-overflow-y`**: Present when the content overflows the y-axis

**`Content`**

**`data-scroll-area-content`**: <uid>
**`data-overflow-x`**: Present when the content overflows the x-axis
**`data-overflow-y`**: Present when the content overflows the y-axis

**`Scrollbar`**

**`data-scroll-area-scrollbar`**: <uid>
**`data-orientation`**: The orientation of the scrollbar
**`data-scrolling`**: Present when scrolling
**`data-hover`**: Present when hovered
**`data-dragging`**: Present when in the dragging state
**`data-overflow-x`**: Present when the content overflows the x-axis
**`data-overflow-y`**: Present when the content overflows the y-axis

**`Thumb`**

**`data-scroll-area-thumb`**: <uid>
**`data-orientation`**: The orientation of the thumb
**`data-hover`**: Present when hovered
**`data-dragging`**: Present when in the dragging state

**`Corner`**

**`data-scroll-area-corner`**: <uid>
**`data-hover`**: Present when hovered
**`data-state`**: "hidden" | "visible"
**`data-overflow-x`**: Present when the content overflows the x-axis
**`data-overflow-y`**: Present when the content overflows the y-axis

### CSS Variables

<CssVarTable name="scroll-area" />

A segmented control lets users pick one option from a small set.

## Resources


[Latest version: v2.0.0-next.1](https://www.npmjs.com/package/@zag-js/radio-group)
[Logic Visualizer](https://zag-visualizer.vercel.app/segmented-control)
[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/segmented-control)



**Features**

- Syncs with `disabled` state of fieldset
- Syncs with form `reset` events
- Can programmatically set segmented control value
- Can programmatically focus segmented control items

## Installation

Install the radio group package:

```bash
npm install @zag-js/radio-group @zag-js/react
# or
yarn add @zag-js/radio-group @zag-js/react
```

## Anatomy

Check the segmented control anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the radio group package:

```tsx
import * as radio from "@zag-js/radio-group"
```

These are the key exports:

- `machine` - State machine logic.
- `connect` - Maps machine state to JSX props and event handlers.

Then use the framework integration helpers:

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

const items = [
  { label: "React", value: "react" },
  { label: "Angular", value: "ng" },
  { label: "Vue", value: "vue" },
  { label: "Svelte", value: "svelte" },
]

function Radio() {
  const service = useMachine(radio.machine, { id: useId() })

  const api = radio.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <div {...api.getIndicatorProps()} />
      {items.map((opt) => (
        <label key={opt.value} {...api.getItemProps({ value: opt.value })}>
          <span {...api.getItemTextProps({ value: opt.value })}>
            {opt.label}
          </span>
          <input {...api.getItemHiddenInputProps({ value: opt.value })} />
        </label>
      ))}
    </div>
  )
}
```

### Setting the initial value

Use the `defaultValue` property to set the segmented control's initial value.

```tsx {2}
const service = useMachine(radio.machine, {
  defaultValue: "apple",
})
```

### Controlled segmented value

Use `value` and `onValueChange` for controlled usage.

```tsx
const service = useMachine(radio.machine, {
  value,
  onValueChange(details) {
    setValue(details.value)
  },
})
```

### Programmatic value control

Use the connected API when you need imperative updates.

```tsx
api.setValue("orange")
api.clearValue()
```

### Focusing from code

Use `api.focus()` to move focus to the selected item (or first enabled item).

```tsx
api.focus()
```

### Listening for changes

When the segmented control value changes, the `onValueChange` callback is
invoked.

```tsx {2-7}
const service = useMachine(radio.machine, {
  onValueChange(details) {
    // details => { value: string | null }
    console.log("segmented control value is:", details.value)
  },
})
```

### Usage within forms

To use segmented control in forms, set `name` and render
`api.getItemHiddenInputProps({ value })` for each item.

```tsx {2}
const service = useMachine(radio.machine, {
  name: "fruits",
})
```

### Vertical orientation

Set `orientation` when you need a vertical layout.

```tsx
const service = useMachine(radio.machine, {
  orientation: "vertical",
})
```

## Styling guide

Each part includes a `data-part` attribute you can target in CSS.

### Indicator

Style the segmented control Indicator through the `indicator` part.

```css
[data-part="indicator"] {
  /* styles for indicator */
}
```

### Focused State

When the radio input is focused, the `data-focus` attribute is added to the root
and label parts.

```css
[data-part="radio"][data-focus] {
  /* styles for radio focus state */
}

[data-part="radio-label"][data-focus] {
  /* styles for radio label focus state */
}
```

### Disabled State

When the radio is disabled, the `data-disabled` attribute is added to the root
and label parts.

```css
[data-part="radio"][data-disabled] {
  /* styles for radio disabled state */
}

[data-part="radio-label"][data-disabled] {
  /* styles for radio label disabled state */
}
```

### Invalid State

When the radio is invalid, the `data-invalid` attribute is added to the root and
label parts.

```css
[data-part="radio"][data-invalid] {
  /* styles for radio invalid state */
}

[data-part="radio-label"][data-invalid] {
  /* styles for radio label invalid state */
}
```

## Methods and Properties

### Machine Context

The radio group machine exposes the following context properties:

<ContextTable name="radio-group" />

### Machine API

The radio group `api` exposes the following methods:

<ApiTable name="radio-group" />

### Data Attributes

<DataAttrTable name="radio-group" />

A select component lets you pick a value from predefined options.

## Resources


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



**Features**

- Supports single and multiple selection
- Supports typeahead, keyboard navigation, and RTL
- Supports controlled open, value, and highlight state
- Supports form submission and browser autofill

## Installation

Install the select package:

```bash
npm install @zag-js/select @zag-js/react
# or
yarn add @zag-js/select @zag-js/react
```

## Anatomy

Check the select anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the select package:

```tsx
import * as select from "@zag-js/select"
```

These are the key exports:

- `machine` - State machine logic.
- `connect` - Maps machine state to JSX props and event handlers.
- `collection` - Creates a [collection interface](/overview/collection) from an
  array of items.

Then use the framework integration helpers:

```tsx
import * as select from "@zag-js/select"
import { useMachine, normalizeProps, Portal } from "@zag-js/react"
import { useId } from "react"

const selectData = [
  { label: "Nigeria", value: "NG" },
  { label: "Japan", value: "JP" },
  { label: "Korea", value: "KO" },
  { label: "Kenya", value: "KE" },
  { label: "United Kingdom", value: "UK" },
  { label: "Ghana", value: "GH" },
  { label: "Uganda", value: "UG" },
]

export function Select() {
  const collection = select.collection({
    items: selectData,
    itemToString: (item) => item.label,
    itemToValue: (item) => item.value,
  })

  const service = useMachine(select.machine, {
    id: useId(),
    collection,
  })

  const api = select.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <div {...api.getControlProps()}>
        <label {...api.getLabelProps()}>Label</label>
        <button {...api.getTriggerProps()}>
          {api.valueAsString || "Select option"}
        </button>
      </div>

      <Portal>
        <div {...api.getPositionerProps()}>
          <div {...api.getContentProps()}>
            <div {...api.getListProps()}>
              {selectData.map((item) => (
                <div key={item.value} {...api.getItemProps({ item })}>
                  <span>{item.label}</span>
                  <span {...api.getItemIndicatorProps({ item })}>✓</span>
                </div>
              ))}
            </div>
          </div>
        </div>
      </Portal>
    </div>
  )
}
```

### Setting the initial value

Use the `defaultValue` property to set the initial value of the select.

> The `value` property must be an array of strings. If selecting a single value,
> pass an array with a single string.

```tsx {13}
const collection = select.collection({
  items: [
    { label: "Nigeria", value: "ng" },
    { label: "Ghana", value: "gh" },
    { label: "Kenya", value: "ke" },
    //...
  ],
})

const service = useMachine(select.machine, {
  id: useId(),
  collection,
  defaultValue: ["ng"],
})
```

### Selecting multiple values

Set `multiple` to `true` to allow selecting multiple values.

```tsx {5}
const service = useMachine(select.machine, {
  id: useId(),
  collection,
  multiple: true,
})
```

### Controlled select value

Use `value` and `onValueChange` for controlled selection.

```tsx
const service = useMachine(select.machine, {
  id: useId(),
  collection,
  value,
  onValueChange(details) {
    setValue(details.value)
  },
})
```

### Using a custom object format

By default, the select collection expects an array of items with `label` and
`value` properties. To use a custom object format, pass the `itemToString` and
`itemToValue` properties to the collection function.

- `itemToString` — A function that returns the string representation of an item.
  Used to compare items when filtering.
- `itemToValue` — A function that returns the unique value of an item.
- `itemToDisabled` — A function that returns the disabled state of an item.
- `groupBy` — A function that returns the group of an item.
- `groupSort` — An array or function to sort the groups.

```tsx
const collection = select.collection({
  // custom object format
  items: [
    { id: 1, fruit: "Banana", available: true, quantity: 10 },
    { id: 2, fruit: "Apple", available: false, quantity: 5 },
    { id: 3, fruit: "Orange", available: true, quantity: 3 },
    //...
  ],
  // convert item to string
  itemToString(item) {
    return item.fruit
  },
  // convert item to value
  itemToValue(item) {
    return item.id
  },
  // convert item to disabled state
  itemToDisabled(item) {
    return !item.available || item.quantity === 0
  },
  groupBy(item) {
    return item.available ? "available" : "unavailable"
  },
  groupSort: ["available", "unavailable"],
})

// use the collection
const service = useMachine(select.machine, {
  id: useId(),
  collection,
})
```

### Usage within a form

To use select in a form, set `name` and render `api.getHiddenSelectProps()`.

```tsx
import * as select from "@zag-js/select"
import { useMachine, normalizeProps, Portal } from "@zag-js/react"
import { useId } from "react"

const selectData = [
  { label: "Nigeria", value: "NG" },
  { label: "Japan", value: "JP" },
  { label: "Korea", value: "KO" },
  { label: "Kenya", value: "KE" },
  { label: "United Kingdom", value: "UK" },
  { label: "Ghana", value: "GH" },
  { label: "Uganda", value: "UG" },
]

export function SelectWithForm() {
  const service = useMachine(select.machine, {
    id: useId(),
    collection: select.collection({ items: selectData }),
    name: "country",
  })

  const api = select.connect(service, normalizeProps)

  return (
    <form>
      {/* Hidden select */}
      <select {...api.getHiddenSelectProps()}>
        {selectData.map((option) => (
          <option key={option.value} value={option.value}>
            {option.label}
          </option>
        ))}
      </select>

      {/* Custom Select */}
      <div {...api.getControlProps()}>
        <label {...api.getLabelProps()}>Label</label>
        <button type="button" {...api.getTriggerProps()}>
          <span>{api.valueAsString || "Select option"}</span>
          <CaretIcon />
        </button>
      </div>

      <Portal>
        <div {...api.getPositionerProps()}>
          <div {...api.getContentProps()}>
            <div {...api.getListProps()}>
              {selectData.map((item) => (
                <div key={item.value} {...api.getItemProps({ item })}>
                  <span>{item.label}</span>
                  <span {...api.getItemIndicatorProps({ item })}>✓</span>
                </div>
              ))}
            </div>
          </div>
        </div>
      </Portal>
    </form>
  )
}
```

### Browser autofill support

To support browser autofill for form fields like state or province, set
`autoComplete` on the machine.

```tsx
const service = useMachine(select.machine, {
  id: useId(),
  collection,
  name: "state",
  autoComplete: "address-level1",
})
```

### Disabling an item

To disable a select item, use `itemToDisabled` in the collection.

```tsx {3-4}
const collection = select.collection({
  items: countries,
  itemToDisabled(item) {
    return item.disabled
  },
})

const service = useMachine(select.machine, {
  id: useId(),
  collection,
})
```

### Close on select

By default, the menu closes when you select an item with pointer, space, or
enter. Set `closeOnSelect` to `false` to keep it open.

```tsx {4}
const service = useMachine(select.machine, {
  id: useId(),
  collection,
  closeOnSelect: false,
})
```

### Programmatic selection control

Use the API for imperative updates.

```tsx
api.selectValue("ng")
api.setValue(["ng", "ke"])
api.clearValue() // or api.clearValue("ng")
```

### Controlling open state

Use `open` and `onOpenChange` for controlled open state, or `defaultOpen` for
uncontrolled initial state.

```tsx
const service = useMachine(select.machine, {
  id: useId(),
  collection,
  open,
  onOpenChange(details) {
    setOpen(details.open)
    // details => { open: boolean, value: string[] }
  },
})
```

```tsx
const service = useMachine(select.machine, {
  id: useId(),
  collection,
  defaultOpen: true,
})
```

### Controlling highlighted item

Use `highlightedValue` and `onHighlightChange` to manage item highlight.

```tsx
const service = useMachine(select.machine, {
  id: useId(),
  collection,
  highlightedValue,
  onHighlightChange(details) {
    setHighlightedValue(details.highlightedValue)
    // details => { highlightedValue, highlightedItem, highlightedIndex }
  },
})
```

### Positioning the popup

Use `positioning` to control popup placement and behavior.

```tsx
const service = useMachine(select.machine, {
  id: useId(),
  collection,
  positioning: { placement: "bottom-start" },
})
```

### Looping the keyboard navigation

By default, arrow key navigation stops at the first and last options. Set
`loopFocus: true` to loop back around.

```tsx {4}
const service = useMachine(select.machine, {
  id: useId(),
  collection,
  loopFocus: true,
})
```

### Allowing deselection in single-select mode

Set `deselectable` to allow clicking the selected item again to clear the value.

```tsx
const service = useMachine(select.machine, {
  id: useId(),
  collection,
  deselectable: true,
})
```

### Listening for highlight changes

Use `onHighlightChange` to listen for highlighted item changes.

```tsx {3-6}
const service = useMachine(select.machine, {
  id: useId(),
  collection,
  onHighlightChange(details) {
    // details => { highlightedValue, highlightedItem, highlightedIndex }
    console.log(details)
  },
})
```

### Listening for selection changes

Use `onValueChange` to listen for selected item changes.

```tsx {4-6}
const service = useMachine(select.machine, {
  id: useId(),
  collection,
  onValueChange(details) {
    // details => { value: string[], items: Item[] }
    console.log(details)
  },
})
```

### Listening for item selection

Use `onSelect` when you need the selected item value immediately.

```tsx
const service = useMachine(select.machine, {
  id: useId(),
  collection,
  onSelect(details) {
    // details => { value: string }
    console.log(details.value)
  },
})
```

### Listening for open and close events

Use `onOpenChange` to listen for open and close events.

```tsx {4-7}
const service = useMachine(select.machine, {
  id: useId(),
  collection,
  onOpenChange(details) {
    // details => { open: boolean, value: string[] }
    console.log(details.open)
  },
})
```

### Grouping items

The select relies on the collection, so rendered items must match collection
items.

Set `groupBy` on the collection to define item groups.

```tsx
const collection = select.collection({
  items: [],
  itemToValue: (item) => item.value,
  itemToString: (item) => item.label,
  groupBy: (item) => item.group || "default",
})
```

Then, use the `collection.group()` method to render the grouped items inside
`getListProps()`.

```tsx
<div {...api.getListProps()}>
  {collection.group().map(([group, items], index) => (
    <div key={`${group}-${index}`}>
      <div {...api.getItemGroupProps({ id: group })}>{group}</div>
      {items.map((item, index) => (
        <div key={`${item.value}-${index}`} {...api.getItemProps({ item })}>
          <span {...api.getItemTextProps({ item })}>{item.label}</span>
          <span {...api.getItemIndicatorProps({ item })}>✓</span>
        </div>
      ))}
    </div>
  ))}
</div>
```

### Usage with large data

For large lists, combine select with a virtualization library like
`react-window` or `@tanstack/react-virtual`.

Example with `@tanstack/react-virtual`:

```tsx
function Demo() {
  const selectData = []

  const listRef = useRef(null)

  const rowVirtualizer = useVirtualizer({
    count: selectData.length,
    getScrollElement: () => listRef.current,
    estimateSize: () => 32,
  })

  const service = useMachine(select.machine, {
    id: useId(),
    collection,
    scrollToIndexFn(details) {
      rowVirtualizer.scrollToIndex(details.index, {
        align: "center",
        behavior: "auto",
      })
    },
  })

  const api = select.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      {/* ... */}
      <Portal>
        <div {...api.getPositionerProps()}>
          <div {...api.getContentProps()}>
            <div ref={listRef} {...api.getListProps()}>
              <div
                style={{
                  height: `${rowVirtualizer.getTotalSize()}px`,
                  width: "100%",
                  position: "relative",
                }}
              >
                {rowVirtualizer.getVirtualItems().map((virtualItem) => {
                  const item = selectData[virtualItem.index]
                  return (
                    <div
                      key={item.value}
                      {...api.getItemProps({ item })}
                      style={{
                        position: "absolute",
                        top: 0,
                        left: 0,
                        width: "100%",
                        height: `${virtualItem.size}px`,
                        transform: `translateY(${virtualItem.start}px)`,
                        whiteSpace: "nowrap",
                        overflow: "hidden",
                        textOverflow: "ellipsis",
                      }}
                    >
                      <span>{item.label}</span>
                      <span {...api.getItemIndicatorProps({ item })}>✓</span>
                    </div>
                  )
                })}
              </div>
            </div>
          </div>
        </div>
      </Portal>
    </div>
  )
}
```

### Usage within dialog

When using select in a dialog, avoid rendering it in a `Portal` or `Teleport`
outside the dialog focus scope.

### Composing with other widgets

The popup is split into two layers:

- `content` — the dismissable popup wrapper (presentational by default, or
  `role="dialog"` when `popupType="dialog"`).
- `list` — the listbox role-bearer that contains items.

This lets you render headers, search inputs, footers, or other widgets inside
`content` without polluting the listbox's accessibility tree.

```tsx
<div {...api.getContentProps()}>
  <input ref={inputRef} placeholder="Filter..." />
  <div {...api.getListProps()}>
    {items.map((item) => (
      <div key={item.value} {...api.getItemProps({ item })}>
        {item.label}
      </div>
    ))}
  </div>
  <div>{items.length} of {total}</div>
</div>
```

Set `popupType: "dialog"` when content is a complex composition (search input,
tabs) so the popup is announced as a dialog by assistive technology and
`aria-haspopup="dialog"` is set on the trigger.

```tsx
const service = useMachine(select.machine, {
  collection,
  popupType: "dialog",
})
```

### Redirecting initial focus

By default, focus moves to the `list` element when the popup opens. To redirect
focus to a different element (such as a search input or composed widget), pass
`initialFocusEl`:

```tsx
const inputRef = useRef<HTMLInputElement>(null)

const service = useMachine(select.machine, {
  id: useId(),
  collection,
  popupType: "dialog",
  initialFocusEl: () => inputRef.current,
})
```

## Styling guide

Each select part includes a `data-part` attribute you can target in CSS.

### Open and closed state

When the select is open, the trigger and content is given a `data-state`
attribute.

```css
[data-part="trigger"][data-state="open|closed"] {
  /* styles for open or closed state */
}

[data-part="content"][data-state="open|closed"] {
  /* styles for open or closed state */
}

[data-part="list"] {
  /* the listbox container — carries role=listbox */
}
```

### Selected state

Items are given a `data-state` attribute, indicating whether they are selected.

```css
[data-part="item"][data-state="checked|unchecked"] {
  /* styles for selected or unselected state */
}
```

### Highlighted state

When an item is highlighted, via keyboard navigation or pointer, it is given a
`data-highlighted` attribute.

```css
[data-part="item"][data-highlighted] {
  /* styles for highlighted state */
}
```

### Invalid state

When the select is invalid, the label and trigger is given a `data-invalid`
attribute.

```css
[data-part="label"][data-invalid] {
  /* styles for invalid state */
}

[data-part="trigger"][data-invalid] {
  /* styles for invalid state */
}
```

### Disabled state

When the select is disabled, the trigger and label is given a `data-disabled`
attribute.

```css
[data-part="trigger"][data-disabled] {
  /* styles for disabled select state */
}

[data-part="label"][data-disabled] {
  /* styles for disabled label state */
}

[data-part="item"][data-disabled] {
  /* styles for disabled option state */
}
```

> Optionally, when an item is disabled, it is given a `data-disabled` attribute.

### Empty state

When no option is selected, the trigger is given a `data-placeholder-shown`
attribute.

```css
[data-part="trigger"][data-placeholder-shown] {
  /* styles for empty select state */
}
```

## Methods and Properties

### Machine Context

The select machine exposes the following context properties:

**`translations`**
Type: `IntlTranslations | undefined`
Description: Specifies the localized strings that identifies the accessibility elements and their states

**`collection`**
Type: `ListCollection<T>`
Description: The item collection

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the select. Useful for composition.

**`name`**
Type: `string | undefined`
Description: The `name` attribute of the underlying select.

**`form`**
Type: `string | undefined`
Description: The associate form of the underlying select.

**`autoComplete`**
Type: `string | undefined`
Description: The autocomplete attribute for the hidden select. Enables browser autofill (e.g. "address-level1" for state).

**`disabled`**
Type: `boolean | undefined`
Description: Whether the select is disabled

**`invalid`**
Type: `boolean | undefined`
Description: Whether the select is invalid

**`readOnly`**
Type: `boolean | undefined`
Description: Whether the select is read-only

**`required`**
Type: `boolean | undefined`
Description: Whether the select is required

**`closeOnSelect`**
Type: `boolean | undefined`
Description: Whether the select should close after an item is selected

**`onSelect`**
Type: `((details: SelectionDetails) => void) | undefined`
Description: Function called when an item is selected

**`onHighlightChange`**
Type: `((details: HighlightChangeDetails<T>) => void) | undefined`
Description: The callback fired when the highlighted item changes.

**`onValueChange`**
Type: `((details: ValueChangeDetails<T>) => void) | undefined`
Description: The callback fired when the selected item changes.

**`onOpenChange`**
Type: `((details: OpenChangeDetails) => void) | undefined`
Description: Function called when the popup is opened

**`positioning`**
Type: `PositioningOptions | undefined`
Description: The positioning options of the menu.

**`value`**
Type: `string[] | undefined`
Description: The controlled keys of the selected items

**`defaultValue`**
Type: `string[] | undefined`
Description: The initial default value of the select when rendered.
Use when you don't need to control the value of the select.

**`highlightedValue`**
Type: `string | null | undefined`
Description: The controlled key of the highlighted item

**`defaultHighlightedValue`**
Type: `string | null | undefined`
Description: The initial value of the highlighted item when opened.
Use when you don't need to control the highlighted value of the select.

**`loopFocus`**
Type: `boolean | undefined`
Description: Whether to loop the keyboard navigation through the options

**`multiple`**
Type: `boolean | undefined`
Description: Whether to allow multiple selection

**`open`**
Type: `boolean | undefined`
Description: Whether the select menu is open

**`defaultOpen`**
Type: `boolean | undefined`
Description: Whether the select's open state is controlled by the user

**`scrollToIndexFn`**
Type: `((details: ScrollToIndexDetails) => void) | undefined`
Description: Function to scroll to a specific index

**`deselectable`**
Type: `boolean | undefined`
Description: Whether the value can be cleared by clicking the selected item.

**Note:** this is only applicable for single selection

**`alignItemWithTrigger`**
Type: `boolean | undefined`
Description: Whether the positioner overlaps the trigger so the selected item's text is
aligned with the trigger's value text. Only applies to mouse/keyboard input
and is automatically disabled for touch or when there is not enough space.

**`initialFocusEl`**
Type: `(() => HTMLElement | null) | undefined`
Description: Element to receive focus when the select is opened. Defaults to the first
tabbable element inside the content (typically the list).

**`popupType`**
Type: `"listbox" | "dialog" | undefined`
Description: The ARIA pattern of the popup. Drives `aria-haspopup` on the trigger and
the `role` of the content element.
- `"listbox"` (default) — content is a passthrough wrapper; the list bears `role="listbox"`.
- `"dialog"` — content is announced as a dialog; useful when composing search inputs, tabs, or other widgets inside the popup.

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

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

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

**`onPointerDownOutside`**
Type: `((event: PointerDownOutsideEvent) => void) | undefined`
Description: Function called when the pointer is pressed down outside the component

**`onFocusOutside`**
Type: `((event: FocusOutsideEvent) => void) | undefined`
Description: Function called when the focus is moved outside the component

**`onInteractOutside`**
Type: `((event: InteractOutsideEvent) => void) | undefined`
Description: Function called when an interaction happens outside the component

### Machine API

The select `api` exposes the following methods:

**`scrollArrowVisibility`**
Type: `"none" | "top" | "bottom" | "both"`
Description: Which scroll arrows should be visible based on the content's scroll position.
- `"none"`: content fits, no scrolling needed
- `"top"`: scrolled past the top (top arrow visible)
- `"bottom"`: more content below (bottom arrow visible)
- `"both"`: scrolled somewhere in the middle (both arrows visible)

**`focused`**
Type: `boolean`
Description: Whether the select is focused

**`open`**
Type: `boolean`
Description: Whether the select is open

**`empty`**
Type: `boolean`
Description: Whether the select value is empty

**`highlightedValue`**
Type: `string | null`
Description: The value of the highlighted item

**`highlightedItem`**
Type: `V | null`
Description: The highlighted item

**`setHighlightValue`**
Type: `(value: string) => void`
Description: Function to highlight a value

**`clearHighlightValue`**
Type: `VoidFunction`
Description: Function to clear the highlighted value

**`selectedItems`**
Type: `V[]`
Description: The selected items

**`hasSelectedItems`**
Type: `boolean`
Description: Whether there's a selected option

**`value`**
Type: `string[]`
Description: The selected item keys

**`valueAsString`**
Type: `string`
Description: The string representation of the selected items

**`selectValue`**
Type: `(value: string) => void`
Description: Function to select a value

**`selectAll`**
Type: `VoidFunction`
Description: Function to select all values

**`setValue`**
Type: `(value: string[]) => void`
Description: Function to set the value of the select

**`clearValue`**
Type: `(value?: string) => void`
Description: Function to clear the value of the select.
If a value is provided, it will only clear that value, otherwise, it will clear all values.

**`focus`**
Type: `VoidFunction`
Description: Function to focus on the select input

**`getItemState`**
Type: `(props: ItemProps) => ItemState`
Description: Returns the state of a select item

**`setOpen`**
Type: `(open: boolean) => void`
Description: Function to open or close the select

**`collection`**
Type: `ListCollection<V>`
Description: Function to toggle the select

**`reposition`**
Type: `(options?: Partial<PositioningOptions>) => void`
Description: Function to set the positioning options of the select

**`multiple`**
Type: `boolean`
Description: Whether the select allows multiple selections

**`disabled`**
Type: `boolean`
Description: Whether the select is disabled

### Data Attributes

**`Root`**

**`data-select-root`**: <uid>
**`data-invalid`**: Present when invalid
**`data-readonly`**: Present when read-only

**`Label`**

**`data-select-label`**: <uid>
**`data-disabled`**: Present when disabled
**`data-invalid`**: Present when invalid
**`data-readonly`**: Present when read-only
**`data-required`**: Present when required

**`Control`**

**`data-select-control`**: <uid>
**`data-state`**: "open" | "closed"
**`data-focus`**: Present when focused
**`data-disabled`**: Present when disabled
**`data-invalid`**: Present when invalid

**`ValueText`**

**`data-select-value-text`**: <uid>
**`data-disabled`**: Present when disabled
**`data-invalid`**: Present when invalid
**`data-focus`**: Present when focused

**`Trigger`**

**`data-select-trigger`**: <uid>
**`data-state`**: "open" | "closed"
**`data-disabled`**: Present when disabled
**`data-invalid`**: Present when invalid
**`data-readonly`**: Present when read-only
**`data-placement`**: The placement of the trigger
**`data-align-with-trigger`**: 
**`data-side`**: The side of the trigger that the trigger is positioned on
**`data-placeholder-shown`**: Present when placeholder is shown

**`Indicator`**

**`data-select-indicator`**: <uid>
**`data-state`**: "open" | "closed"
**`data-disabled`**: Present when disabled
**`data-invalid`**: Present when invalid
**`data-readonly`**: Present when read-only

**`Item`**

**`data-select-item`**: <uid>
**`data-value`**: The value of the item
**`data-state`**: "checked" | "unchecked"
**`data-highlighted`**: Present when highlighted
**`data-disabled`**: Present when disabled

**`ItemText`**

**`data-select-item-text`**: <uid>
**`data-state`**: "checked" | "unchecked"
**`data-disabled`**: Present when disabled
**`data-highlighted`**: Present when highlighted

**`ItemIndicator`**

**`data-select-item-indicator`**: <uid>
**`data-state`**: "checked" | "unchecked"

**`ItemGroup`**

**`data-select-item-group`**: <uid>
**`data-disabled`**: Present when disabled

**`ClearTrigger`**

**`data-select-clear-trigger`**: <uid>
**`data-invalid`**: Present when invalid

**`ScrollArrow`**

**`data-select-scroll-arrow`**: <uid>
**`data-placement`**: The placement of the scrollarrow
**`data-state`**: "visible" | "hidden"

**`Content`**

**`data-select-content`**: <uid>
**`data-state`**: "open" | "closed"
**`data-nested`**: listbox
**`data-has-nested`**: listbox
**`data-placement`**: The placement of the content
**`data-align-with-trigger`**: 
**`data-side`**: The side of the trigger that the content is positioned on

**`List`**

**`data-select-list`**: <uid>
**`data-activedescendant`**: The id the active descendant of the list

### CSS Variables

<CssVarTable name="select" />

## Accessibility

Adheres to the
[ListBox WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox).

### Keyboard Interactions

**`Space`**
Description: <span>When focus is on trigger, opens the select and focuses the first selected item.<br />When focus is on the content, selects the highlighted item.</span>

**`Enter`**
Description: <span>When focus is on trigger, opens the select and focuses the first selected item.<br />When focus is on content, selects the focused item.</span>

**`ArrowDown`**
Description: <span>When focus is on trigger, opens the select.<br />When focus is on content, moves focus to the next item.</span>

**`ArrowUp`**
Description: <span>When focus is on trigger, opens the select.<br />When focus is on content, moves focus to the previous item.</span>

**`Esc`**
Description: <span>Closes the select and moves focus to trigger.</span>

**`A-Z + a-z`**
Description: <span>When focus is on trigger, selects the item whose label starts with the typed character.<br />When focus is on the listbox, moves focus to the next item with a label that starts with the typed character.</span>

A signature pad lets users draw handwritten signatures with pointer or touch
input.

## Resources


[Latest version: v2.0.0-next.1](https://www.npmjs.com/package/@zag-js/signature-pad)
[Logic Visualizer](https://zag-visualizer.vercel.app/signature-pad)
[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/signature-pad)



**Features**

- Draw signatures using touch or pointer input
- Export signatures as data URLs
- Clear signatures programmatically

## Installation

Install the signature pad package:

```bash
npm install @zag-js/signature-pad @zag-js/react
# or
yarn add @zag-js/signature-pad @zag-js/react
```

## Anatomy

To set up the signature pad 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 signature pad package:

```tsx
import * as signaturePad from "@zag-js/signature-pad"
```

The signature pad 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:

```tsx
import { normalizeProps, useMachine } from "@zag-js/react"
import * as signaturePad from "@zag-js/signature-pad"
import { useId } from "react"

export function SignaturePad() {
  const service = useMachine(signaturePad.machine, {
    id: useId(),
  })

  const api = signaturePad.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <label {...api.getLabelProps()}>Signature Pad</label>

      <div {...api.getControlProps()}>
        <svg {...api.getSegmentProps()}>
          {api.paths.map((path, i) => (
            <path key={i} {...api.getSegmentPathProps({ path })} />
          ))}
          {api.currentPath && (
            <path {...api.getSegmentPathProps({ path: api.currentPath })} />
          )}
        </svg>

        <button {...api.getClearTriggerProps()}>X</button>

        <div {...api.getGuideProps()} />
      </div>
    </div>
  )
}
```

### Listening to drawing events

The signature pad component emits the following events:

- `onDraw`: Emitted when the user is drawing the signature.
- `onDrawEnd`: Emitted when the user stops drawing the signature.

```tsx
const service = useMachine(signaturePad.machine, {
  onDraw(details) {
    // details => { paths: string[] }
    console.log("Drawing signature", details)
  },
  onDrawEnd(details) {
    // details => { paths: string[], getDataUrl: (type, quality?) => Promise<string> }
    console.log("Signature drawn", details)
  },
})
```

### Clearing the signature

To clear the signature, use the `api.clear()`, or render the clear trigger
button.

```tsx
<button onClick={() => api.clear()}>Clear</button>
```

### Rendering an image preview

Use the `api.getDataUrl()` method to get the signature as a data URL and render
it as an image.

> You can also leverage the `onDrawEnd` event to get the signature data URL.

```tsx
const service = useMachine(signaturePad.machine, {
  onDrawEnd(details) {
    details.getDataUrl("image/png").then((url) => {
      // set the image URL in local state
      setImageURL(url)
    })
  },
})
```

Next, render the image preview using the URL.

```tsx
<img src={imageURL} alt="Signature" />
```

### Controlled signature paths

Use `paths` and `onDraw` for controlled usage.

```tsx
const service = useMachine(signaturePad.machine, {
  paths,
  onDraw(details) {
    setPaths(details.paths)
  },
})
```

### Changing the stroke color

To change the stroke color, set the `drawing.fill` option to a valid CSS color.

> Note: You can't use a css variable as the stroke color.

```tsx
const service = useMachine(signaturePad.machine, {
  drawing: {
    fill: "red",
  },
})
```

### Changing the stroke width

To change the stroke width, set the `drawing.size` option to a number.

```tsx
const service = useMachine(signaturePad.machine, {
  drawing: {
    size: 5,
  },
})
```

### Controlling pressure simulation

Pressure simulation is enabled by default. Set `drawing.simulatePressure` to
`false` to use raw pointer pressure values.

```tsx
const service = useMachine(signaturePad.machine, {
  drawing: {
    simulatePressure: false,
  },
})
```

### Usage in forms

To use the signature pad in a form, set the `name` context property.

```tsx
const service = useMachine(signaturePad.machine, {
  name: "signature",
})
```

Then, render the hidden input element using `api.getHiddenInputProps()`.

```tsx
<input {...api.getHiddenInputProps({ value: imageURL })} />
```

### Customizing screen reader text

Use `translations` to customize accessible text for the drawing control and
clear trigger.

```tsx
const service = useMachine(signaturePad.machine, {
  translations: {
    control: "Signature drawing area",
    clearTrigger: "Clear signature",
  },
})
```

## Methods and Properties

The signature pad `api` exposes the following methods and properties:

### Machine Context

The signature pad machine exposes the following context properties:

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the signature pad elements. Useful for composition.

**`translations`**
Type: `IntlTranslations | undefined`
Description: The translations of the signature pad. Useful for internationalization.

**`onDraw`**
Type: `((details: DrawDetails) => void) | undefined`
Description: Callback when the signature pad is drawing.

**`onDrawEnd`**
Type: `((details: DrawEndDetails) => void) | undefined`
Description: Callback when the signature pad is done drawing.

**`drawing`**
Type: `DrawingOptions | undefined`
Description: The drawing options.

**`disabled`**
Type: `boolean | undefined`
Description: Whether the signature pad is disabled.

**`required`**
Type: `boolean | undefined`
Description: Whether the signature pad is required.

**`readOnly`**
Type: `boolean | undefined`
Description: Whether the signature pad is read-only.

**`name`**
Type: `string | undefined`
Description: The name of the signature pad. Useful for form submission.

**`defaultPaths`**
Type: `string[] | undefined`
Description: The default paths of the signature pad.
Use when you don't need to control the paths of the signature pad.

**`paths`**
Type: `string[] | undefined`
Description: The controlled paths of the signature pad.

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

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

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

### Machine API

The signature pad `api` exposes the following methods:

**`empty`**
Type: `boolean`
Description: Whether the signature pad is empty.

**`drawing`**
Type: `boolean`
Description: Whether the user is currently drawing.

**`currentPath`**
Type: `string | null`
Description: The current path being drawn.

**`paths`**
Type: `string[]`
Description: The paths of the signature pad.

**`getDataUrl`**
Type: `(type: DataUrlType, quality?: number) => Promise<string>`
Description: Returns the data URL of the signature pad.

**`clear`**
Type: `VoidFunction`
Description: Clears the signature pad.

### Data Attributes

**`Label`**

**`data-signature-pad-label`**: <uid>
**`data-disabled`**: Present when disabled
**`data-required`**: Present when required

**`Root`**

**`data-signature-pad-root`**: <uid>
**`data-disabled`**: Present when disabled

**`Control`**

**`data-signature-pad-control`**: <uid>
**`data-disabled`**: Present when disabled

**`Guide`**

**`data-signature-pad-guide`**: <uid>
**`data-disabled`**: Present when disabled

A slider allows users to make selections from a range of values. Think of it as
a custom `<input type='range'/>` with the ability to achieve custom styling and
accessibility.

## Resources


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



**Features**

- Supports centered origin (slider starting at center, instead of start
  position)
- Fully managed keyboard navigation
- Supports touch or click on track to update value
- Supports Right-to-Left directionality
- Supports horizontal and vertical orientations
- Prevents text selection while dragging

## Installation

Install the slider package:

```bash
npm install @zag-js/slider @zag-js/react
# or
yarn add @zag-js/slider @zag-js/react
```

## Anatomy

Check the slider anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the slider package:

```tsx
import * as slider from "@zag-js/slider"
```

The slider package exports two key functions:

- `machine` - State machine logic.
- `connect` - Maps machine state to JSX props and event handlers.

> Pass a unique `id` to `useMachine` so generated element ids stay predictable.

Then use the framework integration helpers:

```tsx
import * as slider from "@zag-js/slider"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useId } from "react"

export function Slider() {
  const service = useMachine(slider.machine, { id: useId(), value: [0] })

  const api = slider.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <div>
        <label {...api.getLabelProps()}>Slider Label</label>
        <output {...api.getValueTextProps()}>{api.value.at(0)}</output>
      </div>
      <div {...api.getControlProps()}>
        <div {...api.getTrackProps()}>
          <div {...api.getRangeProps()} />
        </div>
        {api.value.map((_, index) => (
          <div key={index} {...api.getThumbProps({ index })}>
            <input {...api.getHiddenInputProps({ index })} />
          </div>
        ))}
      </div>
    </div>
  )
}
```

### Changing the orientation

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

In this mode, the slider will use the arrow up and down keys to
increment/decrement its value.

> Don't forget to change the styles of the vertical slider by specifying its
> height

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

### Setting the initial value

Pass the `defaultValue` property to the machine's context to set the initial
value.

```tsx {2}
const service = useMachine(slider.machine, {
  defaultValue: [30],
})
```

### Controlled slider

To control the slider's value programmatically, pass the `value` and
`onValueChange` properties.

```tsx
import { useState } from "react"

export function ControlledSlider() {
  const [value, setValue] = useState([30])

  const service = useMachine(slider.machine, {
    value,
    onValueChange(details) {
      setValue(details.value)
    },
  })

  return (
    // ...
  )
}

```

### Specifying the minimum and maximum

By default, the minimum is `0` and the maximum is `100`. If that's not what you
want, you can easily specify different bounds by changing the values of the min
and/or max attributes.

For example, to ask the user for a value between `-10` and `10`, you can use:

```tsx {2-3}
const service = useMachine(slider.machine, {
  min: -10,
  max: 10,
})
```

### Setting the value's granularity

By default, the granularity, is `1`, meaning that the value is always an
integer. You can change the step attribute to control the granularity.

For example, If you need a value between `5` and `10`, accurate to two decimal
places, you should set the value of step to `0.01`:

```tsx {4}
const service = useMachine(slider.machine, {
  min: 5,
  max: 10,
  step: 0.01,
})
```

### Listening for changes

When the slider value changes, the `onValueChange` and `onValueChangeEnd`
callbacks are invoked. You can use this to setup custom behaviors in your app.

```tsx {2-7}
const service = useMachine(slider.machine, {
  onValueChange(details) {
    // details => { value: number[] }
    console.log("value is changing to:", details.value)
  },
  onValueChangeEnd(details) {
    // details => { value: number[] }
    console.log("value has changed to:", details.value)
  },
})
```

### Listening for thumb focus changes

Use `onFocusChange` to track which thumb is focused.

```tsx
const service = useMachine(slider.machine, {
  onFocusChange(details) {
    // details => { focusedIndex: number, value: number[] }
    console.log("focused thumb:", details.focusedIndex)
  },
})
```

### Changing the start position

By default, the slider's origin is at the `start` position (left in LTR and
right in RTL). Change it by setting the `origin` property to these values:

- `start`: the track will be filled from start to the thumb (default).
- `center`: the track will be filled from the center (50%) to the thumb.
- `end`: the track will be filled from the thumb to the end.

This applies to sliders with single values.

In scenarios where the value represents an offset (or relative value) on a
diverging scale, it might be useful to change the origin to center. To do this,
set the `origin` context property to `center`.

```tsx {2}
const service = useMachine(slider.machine, {
  origin: "center",
})
```

In scenarios where the slider value is used as a threshold to include values
above it, it might make more sense to set the `origin` to `end` to have the
track filled from the thumb to the end.

### Changing the thumb alignment

By default, the thumb is aligned to the start of the track. Set the
`thumbAlignment` context property to `contain` or `center`.

- `center`: the thumb will extend beyond the bounds of the slider track.
- `contain`: the thumb will be contained within the bounds of the track.

```tsx {2}
const service = useMachine(slider.machine, {
  thumbAlignment: "center",
})
```

If you use `contain` alignment, you might need to set the thumb size to prevent
any flickering.

```tsx {3}
const service = useMachine(slider.machine, {
  thumbAlignment: "contain",
  thumbSize: { width: 20, height: 20 },
})
```

### Thumb collision behavior

For multi-thumb sliders, use `thumbCollisionBehavior` to control what happens
when thumbs collide.

```tsx
const service = useMachine(slider.machine, {
  defaultValue: [20, 80],
  thumbCollisionBehavior: "swap", // "none" | "push" | "swap"
})
```

### Usage within forms

To use slider in forms, set `name` and render `api.getHiddenInputProps()`.

```tsx {2}
const service = useMachine(slider.machine, {
  name: "quantity",
})
```

### Customizing value text for screen readers

Use `getAriaValueText` to customize `aria-valuetext` per thumb.

```tsx
const service = useMachine(slider.machine, {
  getAriaValueText(details) {
    return `Value ${details.index + 1}: ${details.value}`
  },
})
```

### RTL Support

The slider has built-in support for RTL alignment and interaction. In the RTL
mode, operations are performed from right to left, meaning, the left arrow key
will increment and the right arrow key will decrement.

To enable RTL support, pass the `dir: rtl` context property

```tsx {2}
const service = useMachine(slider.machine, {
  dir: "rtl",
})
```

> While we take care of the interactions in RTL mode, you'll have to ensure you
> apply the correct CSS styles to flip the layout.

### Using slider marks

To show marks or ticks along the slider track, use the exposed
`api.getMarkerProps()` method to position the slider marks relative to the
track.

```tsx {11-15}
//...
<div>
  <div {...api.getControlProps()}>
    <div {...api.getTrackProps()}>
      <div {...api.getRangeProps()} />
    </div>
    {api.value.map((_, index) => (
      <div key={index} {...api.getThumbProps({ index })}>
        <input {...api.getHiddenInputProps({ index })} />
      </div>
    ))}
  </div>
  <div {...api.getMarkerGroupProps()}>
    <span {...api.getMarkerProps({ value: 10 })}>|</span>
    <span {...api.getMarkerProps({ value: 30 })}>|</span>
    <span {...api.getMarkerProps({ value: 90 })}>|</span>
  </div>
</div>
//...
```

## Styling guide

Each slider part includes a `data-part` attribute you can target in CSS.

### Focused State

When the slider thumb is focused, the `data-focus` attribute is added to the
root, control, thumb and label parts.

```css
[data-part="root"][data-focus] {
  /* styles for root focus state */
}

[data-part="thumb"]:focus {
  /* styles for thumb focus state */
}

[data-part="control"][data-focus] {
  /* styles for control focus state */
}

[data-part="track"][data-focus] {
  /* styles for track focus state */
}

[data-part="range"][data-focus] {
  /* styles for range focus state */
}
```

### Disabled State

When the slider is disabled, the `data-disabled` attribute is added to the root,
label, control and thumb.

```css
[data-part="root"][data-disabled] {
  /* styles for root disabled state */
}

[data-part="label"][data-disabled] {
  /* styles for label disabled state */
}

[data-part="control"][data-disabled] {
  /* styles for control disabled state */
}

[data-part="value-text"][data-disabled] {
  /* styles for output disabled state */
}

[data-part="thumb"][data-disabled] {
  /* styles for thumb disabled state */
}

[data-part="range"][data-disabled] {
  /* styles for thumb disabled state */
}
```

### Invalid State

When the slider is invalid, the `data-invalid` attribute is added to the root,
track, range, label, and thumb parts.

```css
[data-part="root"][data-invalid] {
  /* styles for root invalid state */
}

[data-part="label"][data-invalid] {
  /* styles for label invalid state */
}

[data-part="control"][data-invalid] {
  /* styles for control invalid state */
}

[data-part="valueText"][data-invalid] {
  /* styles for output invalid state */
}

[data-part="thumb"][data-invalid] {
  /* styles for thumb invalid state */
}

[data-part="range"][data-invalid] {
  /* styles for range invalid state */
}
```

### Orientation

```css
[data-part="root"][data-orientation="(horizontal|vertical)"] {
  /* styles for horizontal or vertical  */
}

[data-part="thumb"][data-orientation="(horizontal|vertical)"] {
  /* styles for horizontal or vertical  */
}

[data-part="track"][data-orientation="(horizontal|vertical)"] {
  /* styles for horizontal or vertical  */
}
```

### Styling the markers

```css
[data-part="marker"][data-state="(at|under|over)-value"] {
  /* styles for when the value exceeds the marker's value */
}
```

## Methods and Properties

### Machine Context

The slider machine exposes the following context properties:

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the slider. Useful for composition.

**`aria-label`**
Type: `string[] | undefined`
Description: The aria-label of each slider thumb. Useful for providing an accessible name to the slider

**`aria-labelledby`**
Type: `string[] | undefined`
Description: The `id` of the elements that labels each slider thumb. Useful for providing an accessible name to the slider

**`name`**
Type: `string | undefined`
Description: The name associated with each slider thumb (when used in a form)

**`form`**
Type: `string | undefined`
Description: The associate form of the underlying input element.

**`value`**
Type: `number[] | undefined`
Description: The controlled value of the slider

**`defaultValue`**
Type: `number[] | undefined`
Description: The initial value of the slider when rendered.
Use when you don't need to control the value of the slider.

**`disabled`**
Type: `boolean | undefined`
Description: Whether the slider is disabled

**`readOnly`**
Type: `boolean | undefined`
Description: Whether the slider is read-only

**`invalid`**
Type: `boolean | undefined`
Description: Whether the slider is invalid

**`onValueChange`**
Type: `((details: ValueChangeDetails) => void) | undefined`
Description: Function invoked when the value of the slider changes

**`onValueChangeEnd`**
Type: `((details: ValueChangeDetails) => void) | undefined`
Description: Function invoked when the slider value change is done

**`onFocusChange`**
Type: `((details: FocusChangeDetails) => void) | undefined`
Description: Function invoked when the slider's focused index changes

**`getAriaValueText`**
Type: `((details: ValueTextDetails) => string) | undefined`
Description: Function that returns a human readable value for the slider thumb

**`min`**
Type: `number | undefined`
Description: The minimum value of the slider

**`max`**
Type: `number | undefined`
Description: The maximum value of the slider

**`step`**
Type: `number | undefined`
Description: The step value of the slider

**`largeStep`**
Type: `number | undefined`
Description: The step value of the slider when the `Shift` key is held, or the
`PageUp`/`PageDown` keys are used.

**`minStepsBetweenThumbs`**
Type: `number | undefined`
Description: The minimum permitted steps between multiple thumbs.

`minStepsBetweenThumbs` * `step` should reflect the gap between the thumbs.

- `step: 1` and `minStepsBetweenThumbs: 10` => gap is `10`
- `step: 10` and `minStepsBetweenThumbs: 2` => gap is `20`

**`orientation`**
Type: `"vertical" | "horizontal" | undefined`
Description: The orientation of the slider

**`origin`**
Type: `SliderOrigin | undefined`
Description: The origin of the slider range. The track is filled from the origin to the thumb.
- `"start"` / `"end"`: fill from `min` / `max`
- `"center"`: fill from the midpoint of `min`/`max`
- a `number`: fill from that value instead, for when the neutral point isn't the midpoint

**`thumbAlignment`**
Type: `"contain" | "center" | undefined`
Description: The alignment of the slider thumb relative to the track
- `center`: the thumb will extend beyond the bounds of the slider track.
- `contain`: the thumb will be contained within the bounds of the track.

**`thumbSize`**
Type: `{ width: number; height: number } | undefined`
Description: The slider thumbs dimensions

**`thumbCollisionBehavior`**
Type: `"none" | "push" | "swap" | undefined`
Description: Controls how thumbs behave when they collide during pointer interactions.
- `none` (default): Thumbs cannot move past each other; excess movement is ignored.
- `push`: Thumbs push each other without restoring their previous positions when dragged back.
- `swap`: Thumbs swap places when dragged past each other.

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

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

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

### Machine API

The slider `api` exposes the following methods:

**`value`**
Type: `number[]`
Description: The value of the slider.

**`dragging`**
Type: `boolean`
Description: Whether the slider is being dragged.

**`focused`**
Type: `boolean`
Description: Whether the slider is focused.

**`setValue`**
Type: `(value: number[]) => void`
Description: Function to set the value of the slider.

**`getThumbValue`**
Type: `(index: number) => number`
Description: Returns the value of the thumb at the given index.

**`setThumbValue`**
Type: `(index: number, value: number) => void`
Description: Sets the value of the thumb at the given index.

**`getValuePercent`**
Type: `(value: number) => number`
Description: Returns the percent of the thumb at the given index.

**`getPercentValue`**
Type: `(percent: number) => number`
Description: Returns the value of the thumb at the given percent.

**`getThumbPercent`**
Type: `(index: number) => number`
Description: Returns the percent of the thumb at the given index.

**`setThumbPercent`**
Type: `(index: number, percent: number) => void`
Description: Sets the percent of the thumb at the given index.

**`getThumbMin`**
Type: `(index: number) => number`
Description: Returns the min value of the thumb at the given index.

**`getThumbMax`**
Type: `(index: number) => number`
Description: Returns the max value of the thumb at the given index.

**`increment`**
Type: `(index: number) => void`
Description: Function to increment the value of the slider at the given index.

**`decrement`**
Type: `(index: number) => void`
Description: Function to decrement the value of the slider at the given index.

**`focus`**
Type: `VoidFunction`
Description: Function to focus the slider. This focuses the first thumb.

### Data Attributes

**`Label`**

**`data-slider-label`**: <uid>
**`data-disabled`**: Present when disabled
**`data-orientation`**: The orientation of the label
**`data-invalid`**: Present when invalid
**`data-dragging`**: Present when in the dragging state
**`data-focus`**: Present when focused

**`Root`**

**`data-slider-root`**: <uid>
**`data-disabled`**: Present when disabled
**`data-orientation`**: The orientation of the slider
**`data-dragging`**: Present when in the dragging state
**`data-invalid`**: Present when invalid
**`data-focus`**: Present when focused

**`ValueText`**

**`data-slider-value-text`**: <uid>
**`data-disabled`**: Present when disabled
**`data-orientation`**: The orientation of the valuetext
**`data-invalid`**: Present when invalid
**`data-focus`**: Present when focused

**`Track`**

**`data-slider-track`**: <uid>
**`data-disabled`**: Present when disabled
**`data-invalid`**: Present when invalid
**`data-dragging`**: Present when in the dragging state
**`data-orientation`**: The orientation of the track
**`data-focus`**: Present when focused

**`Thumb`**

**`data-slider-thumb`**: <uid>
**`data-index`**: The index of the item
**`data-name`**: 
**`data-disabled`**: Present when disabled
**`data-orientation`**: The orientation of the thumb
**`data-focus`**: Present when focused
**`data-dragging`**: Present when in the dragging state

**`Range`**

**`data-slider-range`**: <uid>
**`data-dragging`**: Present when in the dragging state
**`data-focus`**: Present when focused
**`data-invalid`**: Present when invalid
**`data-disabled`**: Present when disabled
**`data-orientation`**: The orientation of the range

**`Control`**

**`data-slider-control`**: <uid>
**`data-dragging`**: Present when in the dragging state
**`data-disabled`**: Present when disabled
**`data-orientation`**: The orientation of the control
**`data-invalid`**: Present when invalid
**`data-focus`**: Present when focused

**`MarkerGroup`**

**`data-slider-marker-group`**: <uid>
**`data-orientation`**: The orientation of the markergroup

**`Marker`**

**`data-slider-marker`**: <uid>
**`data-orientation`**: The orientation of the marker
**`data-value`**: The value of the item
**`data-disabled`**: Present when disabled
**`data-state`**: 

**`DraggingIndicator`**

**`data-slider-dragging-indicator`**: <uid>
**`data-orientation`**: The orientation of the draggingindicator
**`data-state`**: "open" | "closed"

### CSS Variables

<CssVarTable name="slider" />

## Accessibility

Adheres to the
[Slider WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/slider).

### Keyboard Interactions

**`ArrowRight`**
Description: <span>Increments the slider based on defined step</span>

**`ArrowLeft`**
Description: <span>Decrements the slider based on defined step</span>

**`ArrowUp`**
Description: <span>Increases the value by the step amount.</span>

**`ArrowDown`**
Description: <span>Decreases the value by the step amount.</span>

**`PageUp`**
Description: <span>Increases the value by the <code>largeStep</code> amount.</span>

**`PageDown`**
Description: <span>Decreases the value by the <code>largeStep</code> amount.</span>

**`Shift + ArrowUp`**
Description: <span>Increases the value by the <code>largeStep</code> amount.</span>

**`Shift + ArrowDown`**
Description: <span>Decreases the value by the <code>largeStep</code> amount.</span>

**`Home`**
Description: Sets the value to its minimum.

**`End`**
Description: Sets the value to its maximum.

A range slider is a multi-thumb slider used to select a range between two
numbers.

## Resources


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



**Features**

- Fully managed keyboard navigation
- Supports touch or click on track to update value
- Supports Right-to-Left directionality
- Supports horizontal and vertical orientations
- Prevents text selection while dragging

## Installation

Install the range slider package:

```bash
npm install @zag-js/slider @zag-js/react
# or
yarn add @zag-js/slider @zag-js/react
```

## Anatomy

Check the slider anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the range slider package:

```tsx
import * as rangeSlider from "@zag-js/slider"
```

The range slider package exports two key functions:

- `machine` - State machine logic.
- `connect` - Maps machine state to JSX props and event handlers.

> Pass a unique `id` to `useMachine` so generated element ids stay predictable.

Then use the framework integration helpers:

```tsx
import * as slider from "@zag-js/slider"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useId } from "react"

export function RangeSlider() {
  const service = useMachine(slider.machine, {
    id: useId(),
    name: "quantity",
    defaultValue: [10, 60],
  })

  const api = slider.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <div {...api.getControlProps()}>
        <div {...api.getTrackProps()}>
          <div {...api.getRangeProps()} />
        </div>
        {api.value.map((_, index) => (
          <div key={index} {...api.getThumbProps({ index })}>
            <input {...api.getHiddenInputProps({ index })} />
          </div>
        ))}
      </div>
    </div>
  )
}
```

### Changing the orientation

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

In this mode, the slider will use the arrow up and down keys to
increment/decrement its value.

> Don't forget to change the styles of the vertical slider by specifying its
> height

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

### Setting the initial value

```tsx {2}
const service = useMachine(rangeSlider.machine, {
  defaultValue: [30, 60],
})
```

### Controlled range value

Use `value` and `onValueChange` to control both thumb values externally.

```tsx
const service = useMachine(rangeSlider.machine, {
  value,
  onValueChange(details) {
    setValue(details.value)
  },
})
```

### Specifying the minimum and maximum

By default, the minimum is `0` and the maximum is `100`. If that's not what you
want, you can easily specify different bounds by changing the values of the min
and/or max attributes.

For example, to ask the user for a value between `-10` and `10`, you can use:

```tsx {2-3}
const service = useMachine(rangeSlider.machine, {
  min: -10,
  max: 10,
})
```

### Setting the value's granularity

By default, the granularity, is `1`, meaning that the value is always an
integer. You can change the step attribute to control the granularity.

For example, If you need a value between `5` and `10`, accurate to two decimal
places, you should set the value of step to `0.01`:

```tsx {4}
const service = useMachine(rangeSlider.machine, {
  min: 5,
  max: 10,
  step: 0.01,
})
```

### Listening for changes

When the slider value changes, the `onValueChange` and `onValueChangeEnd`
callbacks are invoked. You can use this to setup custom behaviors in your app.

```tsx {2-7}
const service = useMachine(rangeSlider.machine, {
  onValueChange(details) {
    // details => { value: number[] }
    console.log("value changing to:", details.value)
  },
  onValueChangeEnd(details) {
    // details => { value: number[] }
    console.log("value has changed to:", details.value)
  },
})
```

### Listening for thumb focus changes

Use `onFocusChange` to track which thumb is currently focused.

```tsx
const service = useMachine(rangeSlider.machine, {
  onFocusChange(details) {
    // details => { focusedIndex: number, value: number[] }
    console.log("focused thumb:", details.focusedIndex)
  },
})
```

### Preventing thumb overlap

By default, the range slider thumbs are allowed to overlap when their values are
equal. To prevent this, use the `minStepsBetweenThumbs` to avoid thumbs with
equal values.

```tsx {2}
const service = useMachine(rangeSlider.machine, {
  minStepsBetweenThumbs: 1,
})
```

### Thumb collision behavior

Use `thumbCollisionBehavior` to control how thumbs behave on collision.

```tsx
const service = useMachine(rangeSlider.machine, {
  defaultValue: [20, 80],
  thumbCollisionBehavior: "push", // "none" | "push" | "swap"
})
```

### Usage within forms

To use range slider in forms, set `name` and render
`api.getHiddenInputProps({ index })` for each thumb.

```tsx {2}
const service = useMachine(rangeSlider.machine, {
  name: "quantity",
})
```

### RTL Support

The slider has built-in support for RTL alignment and interaction. In the RTL
mode, operations are performed from right to left, meaning, the left arrow key
will increment and the right arrow key will decrement.

To enable RTL support, pass the `dir: rtl` context property

```tsx {2}
const service = useMachine(rangeSlider.machine, {
  dir: "rtl",
})
```

> While we take care of the interactions in RTL mode, you'll have to ensure you
> apply the correct CSS styles to flip the layout.

## Styling guide

Each slider part includes a `data-part` attribute you can target in CSS.

### Focused State

When the slider thumb is focused, the `data-focus` attribute is added to the
root, control, thumb and label parts.

```css
[data-part="root"][data-focus] {
  /* styles for root focus state */
}

[data-part="thumb"]:focus {
  /* styles for thumb focus state */
}

[data-part="control"][data-focus] {
  /* styles for control focus state */
}

[data-part="track"][data-focus] {
  /* styles for track focus state */
}

[data-part="range"][data-focus] {
  /* styles for range focus state */
}
```

### Disabled State

When the slider is disabled, the `data-disabled` attribute is added to the root,
label, control and thumb.

```css
[data-part="root"][data-disabled] {
  /* styles for root disabled state */
}

[data-part="label"][data-disabled] {
  /* styles for label disabled state */
}

[data-part="control"][data-disabled] {
  /* styles for control disabled state */
}

[data-part="value-text"][data-disabled] {
  /* styles for output disabled state */
}

[data-part="thumb"][data-disabled] {
  /* styles for thumb disabled state */
}

[data-part="range"][data-disabled] {
  /* styles for range disabled state */
}
```

### Orientation

```css
[data-part="root"][data-orientation="(horizontal|vertical)"] {
  /* styles for horizontal or vertical  */
}

[data-part="thumb"][data-orientation="(horizontal|vertical)"] {
  /* styles for horizontal or vertical  */
}

[data-part="track"][data-orientation="(horizontal|vertical)"] {
  /* styles for horizontal or vertical  */
}
```

## Methods and Properties

### Machine Context

The slider machine exposes the following context properties:

<ContextTable name="slider" />

### Machine API

The slider `api` exposes the following methods:

<ApiTable name="slider" />

### Data Attributes

<DataAttrTable name="slider" />

## Accessibility

Adheres to the
[Slider WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/slidertwothumb).

### Keyboard Interactions

**`ArrowRight`**
Description: <span>Increments the focused thumb based on defined step</span>

**`ArrowLeft`**
Description: <span>Decrements the focused thumb based on defined step</span>

**`ArrowUp`**
Description: <span>Increases the focused thumb by the step amount.</span>

**`ArrowDown`**
Description: <span>Decreases the focused thumb by the step amount.</span>

**`PageUp`**
Description: <span>Increases the focused thumb value by a larger step</span>

**`PageDown`**
Description: <span>Decreases the focused thumb value by a larger step</span>

**`Shift + ArrowUp`**
Description: <span>Increases the focused thumb value by a larger step</span>

**`Shift + ArrowDown`**
Description: <span>Decreases the focused thumb value by a larger step</span>

**`Home`**
Description: Sets the focused thumb value to its minimum.

**`End`**
Description: Sets the focused thumb value to its maximum.

A splitter creates resizable layouts with horizontal or vertical panels.

## Resources


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



**Features**

- Built with flexbox for flexible layout and SSR
- Supports horizontal and vertical panels
- Supports multiple panels and resize handles
- Supports collapsible panels
- Supports panel constraints like min and max sizes
- Programmatic control of panel sizes
- Implements the
  [Window Splitter pattern](https://www.w3.org/WAI/ARIA/apg/patterns/windowsplitter/)
  for accessibility and keyboard controls
- Supports multi-drag at handle intersections via a shared registry

## Installation

Install the splitter package:

```bash
npm install @zag-js/splitter @zag-js/react
# or
yarn add @zag-js/splitter @zag-js/react
```

## Anatomy

Check the splitter anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the splitter package:

```tsx
import * as splitter from "@zag-js/splitter"
```

The splitter 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:

```tsx
import * as splitter from "@zag-js/splitter"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useId } from "react"

export function Splitter() {
  const service = useMachine(splitter.machine, {
    id: useId(),
    defaultSize: [80, 20],
    panels: [
      { id: "a", minSize: 10 },
      { id: "b", minSize: 10 },
    ],
  })

  const api = splitter.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <div {...api.getPanelProps({ id: "a" })}>
        <p>A</p>
      </div>
      <div {...api.getResizeTriggerProps({ id: "a:b" })} />
      <div {...api.getPanelProps({ id: "b" })}>
        <p>B</p>
      </div>
    </div>
  )
}
```

### Setting the initial size

To set the initial size of the splitter panels, use the `defaultSize` property.
Ensure the `defaultSize` totals to `100`.

> Note: The splitter only supports setting percentage values.

```tsx {3}
const service = useMachine(splitter.machine, {
  // ...
  defaultSize: [40, 60],
})
```

### Controlled panel sizes

Use `size` and `onResize` for controlled layouts.

```tsx
const service = useMachine(splitter.machine, {
  panels,
  size,
  onResize(details) {
    setSize(details.size)
  },
})
```

### Listening for resize events

When the resize trigger is dragged, the `onResize`, `onResizeStart` and
`onResizeEnd` callbacks are invoked.

```tsx {3-10}
const service = useMachine(splitter.machine, {
  // ...
  onResize(detail) {
    console.log("resize", detail)
  },
  onResizeStart() {
    console.log("resize start")
  },
  onResizeEnd(detail) {
    console.log("change end", detail)
  },
})
```

### Changing the orientation

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

```tsx {3}
const service = useMachine(splitter.machine, {
  // ...
  orientation: "vertical",
})
```

### Specifying constraints

Use the `panels` property to specify constraints like `minSize` and `maxSize`
for the splitter panels.

```tsx {3-6}
const service = useMachine(splitter.machine, {
  // ...
  panels: [
    { id: "a", minSize: 20, maxSize: 80 },
    { id: "b", minSize: 20, maxSize: 80 },
  ],
})
```

### Configuring keyboard resize step

Use `keyboardResizeBy` to control how many pixels arrow keys resize by.

```tsx
const service = useMachine(splitter.machine, {
  panels,
  keyboardResizeBy: 16,
})
```

### Setting the collapsed size

Set the `collapsedSize` and `collapsible` of a panel to specify the collapsed
size of the panel.

> For best results, ensure you also set the `minSize` of the panel

```tsx {4}
const service = useMachine(splitter.machine, {
  // ...
  panels: [
    { id: "a", collapsible: true, collapsedSize: 5, minSize: 10, maxSize: 20 },
    { id: "b", minSize: 50 },
  ],
})
```

This allows the user to drag the splitter to collapse the panel to the
`collapsedSize`.

### Listening for collapse events

When the splitter panel is collapsed, the `onCollapse` callback is invoked.
Alternatively, the `onExpand` callback is invoked when the panel is expanded.

```tsx {3-8}
const service = useMachine(splitter.machine, {
  // ...
  onCollapse(detail) {
    console.log("collapse", detail)
  },
  onExpand(detail) {
    console.log("expand", detail)
  },
})
```

### Programmatic panel control

Use the connected API to resize, collapse, or expand panels from code.

```tsx
api.setSizes([30, 70])
api.resizePanel("a", 40)
api.collapsePanel("a")
api.expandPanel("a")
api.resetSizes()
```

### Multi-drag with registry

When you have nested splitters (e.g. horizontal and vertical), users can drag at
handle intersections to resize both directions simultaneously. Use
`splitter.registry()` to coordinate multiple splitter instances.

```tsx
import * as splitter from "@zag-js/splitter"

// Create a shared registry (once, at the layout level)
const registry = splitter.registry()
```

Pass the `registry` to each splitter machine that should participate in
multi-drag:

```tsx
const horizontalService = useMachine(splitter.machine, {
  panels: [{ id: "left" }, { id: "right" }],
  registry,
})

const verticalService = useMachine(splitter.machine, {
  orientation: "vertical",
  panels: [{ id: "top" }, { id: "bottom" }],
  registry,
})
```

When a user drags near the intersection of two resize handles, the registry
detects both handles and resizes them together. The registry also manages the
cursor globally during intersection dragging.

### Registry options

The `splitter.registry()` function accepts optional configuration:

```tsx
const registry = splitter.registry({
  // Nonce for injected cursor stylesheet (CSP compliance)
  nonce: "abc123",
  // Hit area margins for intersection detection
  hitAreaMargins: {
    coarse: 20, // touch devices (default: 15)
    fine: 10, // pointer devices (default: 5)
  },
})
```

## Styling guide

Each part includes a `data-part` attribute you can target in CSS.

### Resize trigger

When a resize trigger is horizontal or vertical, a `data-orientation` attribute
is set on the trigger element.

```css
[data-scope="splitter"][data-part="resize-trigger"] {
  /* styles for the item */
}

[data-scope="splitter"][data-part="resize-trigger"][data-orientation="horizontal"] {
  /* styles for the item is horizontal state */
}

[data-scope="splitter"][data-part="resize-trigger"][data-orientation="vertical"] {
  /* styles for the item is horizontal state */
}

[data-scope="splitter"][data-part="resize-trigger"][data-focus] {
  /* styles for the item is focus state */
}

[data-scope="splitter"][data-part="resize-trigger"]:active {
  /* styles for the item is active state */
}

[data-scope="splitter"][data-part="resize-trigger"][data-disabled] {
  /* styles for the item is disabled state */
}
```

## Methods and Properties

The splitter's `api` exposes the following methods and properties:

### Machine Context

The splitter machine exposes the following context properties:

**`orientation`**
Type: `"horizontal" | "vertical" | undefined`
Description: The orientation of the splitter. Can be `horizontal` or `vertical`

**`size`**
Type: `PanelSize[] | undefined`
Description: The controlled size data of the panels

**`defaultSize`**
Type: `PanelSize[] | undefined`
Description: The initial size of the panels when rendered.
Use when you don't need to control the size of the panels.

**`panels`**
Type: `PanelData[]`
Description: The size constraints of the panels.

**`onResize`**
Type: `((details: ResizeDetails) => void) | undefined`
Description: Function called when the splitter is resized.

**`onResizeStart`**
Type: `(() => void) | undefined`
Description: Function called when the splitter resize starts.

**`onResizeEnd`**
Type: `((details: ResizeEndDetails) => void) | undefined`
Description: Function called when the splitter resize ends.

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the splitter. Useful for composition.

**`keyboardResizeBy`**
Type: `number | null | undefined`
Description: The number of pixels to resize the panel by when the keyboard is used.

**`nonce`**
Type: `string | undefined`
Description: The nonce for the injected splitter cursor stylesheet.

**`onCollapse`**
Type: `((details: ExpandCollapseDetails) => void) | undefined`
Description: Function called when a panel is collapsed.

**`onExpand`**
Type: `((details: ExpandCollapseDetails) => void) | undefined`
Description: Function called when a panel is expanded.

**`registry`**
Type: `SplitterRegistry | undefined`
Description: The splitter registry to use for multi-drag support.
When provided, enables dragging at the intersection of multiple splitters.

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

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

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

### Machine API

The splitter `api` exposes the following methods:

**`dragging`**
Type: `boolean`
Description: Whether the splitter is currently being resized.

**`orientation`**
Type: `"horizontal" | "vertical"`
Description: The orientation of the splitter.

**`getSizes`**
Type: `() => number[]`
Description: Returns the current sizes of the panels.

**`setSizes`**
Type: `(size: PanelSize[]) => void`
Description: Sets the sizes of the panels.

**`getItems`**
Type: `() => SplitterItem[]`
Description: Returns the items of the splitter.

**`getPanels`**
Type: `() => PanelData[]`
Description: Returns the panels of the splitter.

**`getPanelById`**
Type: `(id: PanelId) => PanelData`
Description: Returns the panel with the specified id.

**`getPanelSize`**
Type: `(id: PanelId) => number`
Description: Returns the size of the specified panel.

**`isPanelCollapsed`**
Type: `(id: PanelId) => boolean`
Description: Returns whether the specified panel is collapsed.

**`isPanelExpanded`**
Type: `(id: PanelId) => boolean`
Description: Returns whether the specified panel is expanded.

**`collapsePanel`**
Type: `(id: PanelId) => void`
Description: Collapses the specified panel.

**`expandPanel`**
Type: `(id: PanelId, minSize?: number) => void`
Description: Expands the specified panel.

**`resizePanel`**
Type: `(id: PanelId, unsafePanelSize: number) => void`
Description: Resizes the specified panel.

**`getLayout`**
Type: `() => string`
Description: Returns the layout of the splitter.

**`resetSizes`**
Type: `VoidFunction`
Description: Resets the splitter to its initial state.

**`getResizeTriggerState`**
Type: `(props: ResizeTriggerProps) => ResizeTriggerState`
Description: Returns the state of the resize trigger.

### Data Attributes

**`Root`**

**`data-splitter-root`**: <uid>
**`data-orientation`**: The orientation of the splitter
**`data-dragging`**: Present when in the dragging state

**`Panel`**

**`data-splitter-panel`**: <uid>
**`data-orientation`**: The orientation of the panel
**`data-dragging`**: Present when in the dragging state
**`data-id`**: 
**`data-index`**: The index of the item

**`ResizeTrigger`**

**`data-splitter-resize-trigger`**: <uid>
**`data-id`**: 
**`data-orientation`**: The orientation of the resizetrigger
**`data-focus`**: Present when focused
**`data-dragging`**: Present when in the dragging state
**`data-disabled`**: Present when disabled

Steps guide users through a multi-step process.

## Resources


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



**Features**

- Supports horizontal and vertical orientations
- Supports changing the active step with the keyboard and pointer
- Supports linear and non-linear steps

## Installation

Install the steps package:

```bash
npm install @zag-js/steps @zag-js/react
# or
yarn add @zag-js/steps @zag-js/react
```

## Anatomy

Check the steps anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the steps package:

```tsx
import * as steps from "@zag-js/steps"
```

The steps 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:

```tsx
import * as steps from "@zag-js/steps"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useId } from "react"

const stepsData = [
  { title: "Step 1" },
  { title: "Step 2" },
  { title: "Step 3" },
]

function Steps() {
  const service = useMachine(steps.machine, {
    id: useId(),
    count: stepsData.length,
  })

  const api = steps.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <div {...api.getListProps()}>
        {stepsData.map((step, index) => (
          <div key={index} {...api.getItemProps({ index })}>
            <button {...api.getTriggerProps({ index })}>
              <div {...api.getIndicatorProps({ index })}>{index + 1}</div>
              <span>{step.title}</span>
            </button>
            <div {...api.getSeparatorProps({ index })} />
          </div>
        ))}
      </div>

      {stepsData.map((step, index) => (
        <div key={index} {...api.getContentProps({ index })}>
          {step.title}
        </div>
      ))}

      <div {...api.getContentProps({ index: stepsData.length })}>
        Steps Complete - Thank you for filling out the form!
      </div>

      <div>
        <button {...api.getPrevTriggerProps()}>Back</button>
        <button {...api.getNextTriggerProps()}>Next</button>
      </div>
    </div>
  )
}
```

### Setting the initial step

Set the initial step by passing `defaultStep` to the machine context.

> The value of the `step` property is zero-based index.

```tsx {2}
const service = useMachine(steps.machine, {
  defaultStep: 1,
})
```

### Controlled current step

Use `step` and `onStepChange` for controlled usage.

```tsx
const service = useMachine(steps.machine, {
  step,
  onStepChange(details) {
    setStep(details.step)
  },
})
```

### Listening for step change

When the active step changes, the machine will invoke the `onStepChange` event

```tsx {2-4}
const service = useMachine(steps.machine, {
  onStepChange(details) {
    // details => { step: number }
    console.log(`Step changed to ${details.step}`)
  },
})
```

### Listening for steps completion

When all steps are completed, the machine will invoke the `onStepComplete` event

```tsx {2-4}
const service = useMachine(steps.machine, {
  onStepComplete() {
    console.log("All steps are complete")
  },
})
```

### Enforcing linear steps

To enforce linear steps, you can set the `linear` prop to `true` when creating
the steps machine. This will prevent users from skipping steps.

```tsx {2}
const service = useMachine(steps.machine, {
  linear: true,
})
```

### Validating steps in linear mode

Use `isStepValid` to block forward navigation when a step is incomplete.

```tsx
const service = useMachine(steps.machine, {
  linear: true,
  isStepValid(index) {
    return completedSteps.has(index)
  },
  onStepInvalid(details) {
    // details => { step: number, action: "next" | "set", targetStep?: number }
    console.log("blocked at step", details.step)
  },
})
```

### Skipping optional steps

Use `isStepSkippable` when some steps should be bypassed by next/prev
navigation.

```tsx
const service = useMachine(steps.machine, {
  isStepSkippable(index) {
    return index === 2
  },
})
```

### Changing the orientation

The steps machine supports both horizontal and vertical orientations. You can
set the `orientation` prop to `horizontal` or `vertical` to change the
orientation of the steps.

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

### Programmatic navigation

Use the API methods to move through the flow in code.

```tsx
api.setStep(2)
api.goToNextStep()
api.goToPrevStep()
api.resetStep()
```

## Styling guide

Each part includes a `data-part` attribute you can target in CSS.

```css
[data-scope="steps"][data-part="root"] {
  /* styles for the root part */
}

[data-scope="steps"][data-part="root"][data-orientation="horizontal|vertical"] {
  /* styles for the root part based on orientation */
}

[data-scope="steps"][data-part="list"] {
  /* styles for the list part */
}

[data-scope="steps"][data-part="list"][data-orientation="horizontal|vertical"] {
  /* styles for the list part based on orientation */
}

[data-scope="steps"][data-part="separator"] {
  /* styles for the separator part */
}

[data-scope="steps"][data-part="separator"][data-orientation="horizontal|vertical"] {
  /* styles for the separator part based on orientation */
}
```

### Current step

To style the current step, you can use the `data-current` attribute.

```css
[data-scope="steps"][data-part="item"][data-current] {
  /* item styles for the current step */
}

[data-scope="steps"][data-part="separator"][data-current] {
  /* separator styles for the current step */
}
```

### Completed step

To style the completed step, you can use the `data-complete` attribute.

```css
[data-scope="steps"][data-part="item"][data-complete] {
  /* item styles for the completed step */
}

[data-scope="steps"][data-part="separator"][data-complete] {
  /* separator styles for the completed step */
}
```

### Incomplete step

To style the incomplete step, you can use the `data-incomplete` attribute.

```css
[data-scope="steps"][data-part="item"][data-incomplete] {
  /* item styles for the incomplete step */
}

[data-scope="steps"][data-part="separator"][data-incomplete] {
  /* separator styles for the incomplete step */
}
```

## Methods and Properties

### Machine Context

The steps machine exposes the following context properties:

**`ids`**
Type: `ElementIds | undefined`
Description: The custom ids for the stepper elements

**`step`**
Type: `number | undefined`
Description: The controlled value of the stepper

**`defaultStep`**
Type: `number | undefined`
Description: The initial value of the stepper when rendered.
Use when you don't need to control the value of the stepper.

**`onStepChange`**
Type: `((details: StepChangeDetails) => void) | undefined`
Description: Callback to be called when the value changes

**`onStepComplete`**
Type: `VoidFunction | undefined`
Description: Callback to be called when a step is completed

**`linear`**
Type: `boolean | undefined`
Description: If `true`, the stepper requires the user to complete the steps in order

**`orientation`**
Type: `"horizontal" | "vertical" | undefined`
Description: The orientation of the stepper

**`count`**
Type: `number | undefined`
Description: The total number of steps

**`isStepValid`**
Type: `((index: number) => boolean) | undefined`
Description: Whether a step is valid. Invalid steps block forward navigation in linear mode.

**`isStepSkippable`**
Type: `((index: number) => boolean) | undefined`
Description: Whether a step can be skipped during navigation.
Skippable steps are bypassed when using next/prev.

**`onStepInvalid`**
Type: `((details: StepInvalidDetails) => void) | undefined`
Description: Called when navigation is blocked due to an invalid step.

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

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

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

### Machine API

The steps `api` exposes the following methods:

**`value`**
Type: `number`
Description: The value of the stepper.

**`percent`**
Type: `number`
Description: The percentage of the stepper.

**`count`**
Type: `number`
Description: The total number of steps.

**`hasNextStep`**
Type: `boolean`
Description: Whether the stepper has a next step.

**`hasPrevStep`**
Type: `boolean`
Description: Whether the stepper has a previous step.

**`isCompleted`**
Type: `boolean`
Description: Whether the stepper is completed.

**`isStepValid`**
Type: `(index: number) => boolean`
Description: Check if a specific step is valid (lazy evaluation)

**`isStepSkippable`**
Type: `(index: number) => boolean`
Description: Check if a specific step can be skipped

**`setStep`**
Type: `(step: number) => void`
Description: Function to set the value of the stepper.

**`goToNextStep`**
Type: `VoidFunction`
Description: Function to go to the next step.

**`goToPrevStep`**
Type: `VoidFunction`
Description: Function to go to the previous step.

**`resetStep`**
Type: `VoidFunction`
Description: Function to go to reset the stepper.

**`getItemState`**
Type: `(props: ItemProps) => ItemState`
Description: Returns the state of the item at the given index.

### Data Attributes

**`Root`**

**`data-steps-root`**: <uid>
**`data-orientation`**: The orientation of the steps

**`List`**

**`data-steps-list`**: <uid>
**`data-orientation`**: The orientation of the list

**`Item`**

**`data-steps-item`**: <uid>
**`data-orientation`**: The orientation of the item
**`data-skippable`**: 

**`Trigger`**

**`data-steps-trigger`**: <uid>
**`data-state`**: "open" | "closed"
**`data-orientation`**: The orientation of the trigger
**`data-complete`**: Present when the trigger value is complete
**`data-current`**: Present when current
**`data-incomplete`**: 

**`Content`**

**`data-steps-content`**: <uid>
**`data-state`**: "open" | "closed"
**`data-orientation`**: The orientation of the content

**`Indicator`**

**`data-steps-indicator`**: <uid>
**`data-complete`**: Present when the indicator value is complete
**`data-current`**: Present when current
**`data-incomplete`**: 

**`Separator`**

**`data-steps-separator`**: <uid>
**`data-orientation`**: The orientation of the separator
**`data-complete`**: Present when the separator value is complete
**`data-current`**: Present when current
**`data-incomplete`**: 

**`Progress`**

**`data-steps-progress`**: <uid>
**`data-complete`**: Present when the progress value is complete

### CSS Variables

<CssVarTable name="steps" />

A switch allows users to turn an individual option on or off.

## Resources


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



**Features**

- Sync with `disabled` state of fieldset
- Sync with form `reset` events
- Can be toggled programmatically

## Installation

Install the switch package:

```bash
npm install @zag-js/switch @zag-js/react
# or
yarn add @zag-js/switch @zag-js/react
```

## Anatomy

Check the switch anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the switch package:

```tsx
import * as zagSwitch from "@zag-js/switch"
```

The switch 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:

```tsx
import * as zagSwitch from "@zag-js/switch"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useId } from "react"

function Switch() {
  const service = useMachine(zagSwitch.machine, { id: useId() })

  const api = zagSwitch.connect(service, normalizeProps)

  return (
    <label {...api.getRootProps()}>
      <input {...api.getHiddenInputProps()} />
      <span {...api.getControlProps()}>
        <span {...api.getThumbProps()} />
      </span>
      <span {...api.getLabelProps()}>{api.checked ? "On" : "Off"}</span>
    </label>
  )
}
```

### Making it checked by default

Use the `defaultChecked` property to make a switch checked by default.

```tsx {3}
const service = useMachine(zagSwitch.machine, {
  defaultChecked: true,
})
```

### Controlled checked state

Use `checked` and `onCheckedChange` for controlled usage.

```tsx
const service = useMachine(zagSwitch.machine, {
  checked,
  onCheckedChange(details) {
    setChecked(details.checked)
  },
})
```

### Listening for changes

When the switch value changes, the `onCheckedChange` callback is invoked.

```tsx {3-5}
const service = useMachine(zagSwitch.machine, {
  onCheckedChange(details) {
    // details => { checked: boolean }
    console.log("switch is:", details.checked ? "On" : "Off")
  },
})
```

### Programmatic toggle

Use the connected API when you need imperative control.

```tsx
api.setChecked(true)
api.toggleChecked()
```

### Usage within forms

To use switch in forms, set `name` and render `api.getHiddenInputProps()`.

```tsx {3}
const service = useMachine(zagSwitch.machine, {
  name: "feature",
})
```

### Custom form value

Set `value` to customize the submitted form value when checked.

```tsx
const service = useMachine(zagSwitch.machine, {
  name: "notifications",
  value: "enabled",
})
```

## Styling guide

Each switch part includes a `data-part` attribute you can target in CSS.

### Focused State

When the switch input is focused, the `data-focus` attribute is added to the
root, control and label parts.

```css
[data-part="root"][data-focus] {
  /* styles for root focus state */
}

[data-part="control"][data-focus] {
  /* styles for control focus state */
}

[data-part="label"][data-focus] {
  /* styles for label focus state */
}
```

### Disabled State

When the switch is disabled, the `data-disabled` attribute is added to the root,
control and label parts.

```css
[data-part="root"][data-disabled] {
  /* styles for root disabled state */
}

[data-part="control"][data-disabled] {
  /* styles for control disabled state */
}

[data-part="label"][data-disabled] {
  /* styles for label disabled state */
}
```

### Invalid State

When the switch is invalid, the `data-invalid` attribute is added to the root,
control and label parts.

```css
[data-part="root"][data-invalid] {
  /* styles for root invalid state */
}

[data-part="control"][data-invalid] {
  /* styles for control invalid state */
}

[data-part="label"][data-invalid] {
  /* styles for label invalid state */
}
```

## Methods and Properties

### Machine Context

The switch machine exposes the following context properties:

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the switch. Useful for composition.

**`label`**
Type: `string | undefined`
Description: Specifies the localized strings that identifies the accessibility elements and their states

**`disabled`**
Type: `boolean | undefined`
Description: Whether the switch is disabled.

**`invalid`**
Type: `boolean | undefined`
Description: If `true`, the switch is marked as invalid.

**`required`**
Type: `boolean | undefined`
Description: If `true`, the switch input is marked as required,

**`readOnly`**
Type: `boolean | undefined`
Description: Whether the switch is read-only

**`onCheckedChange`**
Type: `((details: CheckedChangeDetails) => void) | undefined`
Description: Function to call when the switch is clicked.

**`checked`**
Type: `boolean | undefined`
Description: The controlled checked state of the switch

**`defaultChecked`**
Type: `boolean | undefined`
Description: The initial checked state of the switch when rendered.
Use when you don't need to control the checked state of the switch.

**`name`**
Type: `string | undefined`
Description: The name of the input field in a switch
(Useful for form submission).

**`form`**
Type: `string | undefined`
Description: The id of the form that the switch belongs to

**`value`**
Type: `string | number | undefined`
Description: The value of switch input. Useful for form submission.

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

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

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

### Machine API

The switch `api` exposes the following methods:

**`checked`**
Type: `boolean`
Description: Whether the switch is checked

**`disabled`**
Type: `boolean | undefined`
Description: Whether the switch is disabled

**`focused`**
Type: `boolean | undefined`
Description: Whether the switch is focused

**`setChecked`**
Type: `(checked: boolean) => void`
Description: Sets the checked state of the switch.

**`toggleChecked`**
Type: `VoidFunction`
Description: Toggles the checked state of the switch.

### Data Attributes

**`Root`**

**`data-switch-root`**: <uid>
**`data-active`**: Present when active or pressed
**`data-focus`**: Present when focused
**`data-focus-visible`**: Present when focused with keyboard
**`data-readonly`**: Present when read-only
**`data-hover`**: Present when hovered
**`data-disabled`**: Present when disabled
**`data-state`**: "checked" | "unchecked"
**`data-invalid`**: Present when invalid
**`data-required`**: Present when required

**`Label`**

**`data-switch-label`**: <uid>
**`data-active`**: Present when active or pressed
**`data-focus`**: Present when focused
**`data-focus-visible`**: Present when focused with keyboard
**`data-readonly`**: Present when read-only
**`data-hover`**: Present when hovered
**`data-disabled`**: Present when disabled
**`data-state`**: "checked" | "unchecked"
**`data-invalid`**: Present when invalid
**`data-required`**: Present when required

**`Thumb`**

**`data-switch-thumb`**: <uid>
**`data-active`**: Present when active or pressed
**`data-focus`**: Present when focused
**`data-focus-visible`**: Present when focused with keyboard
**`data-readonly`**: Present when read-only
**`data-hover`**: Present when hovered
**`data-disabled`**: Present when disabled
**`data-state`**: "checked" | "unchecked"
**`data-invalid`**: Present when invalid
**`data-required`**: Present when required

**`Control`**

**`data-switch-control`**: <uid>
**`data-active`**: Present when active or pressed
**`data-focus`**: Present when focused
**`data-focus-visible`**: Present when focused with keyboard
**`data-readonly`**: Present when read-only
**`data-hover`**: Present when hovered
**`data-disabled`**: Present when disabled
**`data-state`**: "checked" | "unchecked"
**`data-invalid`**: Present when invalid
**`data-required`**: Present when required

## Accessibility

Adheres to the
[Switch WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/)

### Keyboard Interactions

**`Space + Enter`**
Description: Toggle the switch

Tabs organize related content into selectable panels.

## Resources


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



**Features**

- Supports mouse, touch, and keyboard interactions on tabs
- Supports LTR and RTL keyboard navigation
- Follows the tabs ARIA pattern, semantically linking tabs and their associated
  tab panels
- Focus management for tab panels without any focusable children

## Installation

Install the tabs package:

```bash
npm install @zag-js/tabs @zag-js/react
# or
yarn add @zag-js/tabs @zag-js/react
```

## Anatomy

Check the tabs anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the tabs package:

```tsx
import * as tabs from "@zag-js/tabs"
```

The tabs 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:

```tsx
import * as tabs from "@zag-js/tabs"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useId } from "react"

const data = [
  { value: "item-1", label: "Item one", content: "Item one content" },
  { value: "item-2", label: "Item two", content: "Item two content" },
  { value: "item-3", label: "Item three", content: "Item three content" },
]

export function Tabs() {
  const service = useMachine(tabs.machine, { id: useId(), defaultValue: "item-1" })

  const api = tabs.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <div {...api.getListProps()}>
        {data.map((item) => (
          <button
            {...api.getTriggerProps({ value: item.value })}
            key={item.value}
          >
            {item.label}
          </button>
        ))}
      </div>
      {data.map((item) => (
        <div {...api.getContentProps({ value: item.value })} key={item.value}>
          <p>{item.content}</p>
        </div>
      ))}
    </div>
  )
}
```

### Setting the initially selected tab

To set the initially selected tab, pass the `defaultValue` property to the
machine's context.

```tsx {2}
const service = useMachine(tabs.machine, {
  defaultValue: "tab-1",
})
```

Subsequently, you can use the `api.setValue` function to programmatically set
the selected tab.

```tsx
api.setValue("tab-2")
```

To clear selection (when `deselectable` is enabled), use:

```tsx
api.clearValue()
```

### Controlled tabs

To control the selected tab programmatically, pass the `value` and
`onValueChange` properties to the machine function.

```tsx
import { useState } from "react"

export function ControlledTabs() {
  const [value, setValue] = useState("tab-1")

  const service = useMachine(tabs.machine, {
    value,
    onValueChange(details) {
      setValue(details.value)
    },
  })

  return (
    // ...
  )
}
```

### Changing the orientation

The default orientation of the tabs is horizontal. To change the orientation,
set the `orientation` property in the machine's context to `"vertical"`.

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

### Showing an indicator

To show an active indicator when a tab is selected, you add the
`tabIndicatorProps` object provided by the `connect` function.

```tsx {13}
// ...
return (
  <div {...api.getRootProps()}>
    <div {...api.getListProps()}>
      {data.map((item) => (
        <button
          {...api.getTriggerProps({ value: item.value })}
          key={item.value}
        >
          {item.label}
        </button>
      ))}
      <div {...api.getIndicatorProps()} />
    </div>
    {data.map((item) => (
      <div {...api.getContentProps({ value: item.value })} key={item.value}>
        <p>{item.content}</p>
      </div>
    ))}
  </div>
)
```

### Disabling a tab

To disable a tab, set the `disabled` property in the `getTriggerProps` to
`true`.

When a Tab is `disabled`, it is skipped during keyboard navigation and it is not
clickable.

```tsx
//...
<button {...api.getTriggerProps({ disabled: true })}></button>
//...
```

### Listening for events

- `onValueChange` — Callback invoked when the selected tab changes.
- `onFocusChange` — Callback invoked when the focused tab changes.

```tsx {2-7}
const service = useMachine(tabs.machine, {
  onFocusChange(details) {
    // details => { focusedValue: string }
    console.log("focused tab:", details.focusedValue)
  },
  onValueChange(details) {
    // details => { value: string }
    console.log("selected tab:", details.value)
  },
})
```

### Allowing deselection

Set `deselectable` to allow clicking the active tab to clear the current value.

```tsx
const service = useMachine(tabs.machine, {
  deselectable: true,
})
```

### Custom navigation for link tabs

Use `navigate` when your tab triggers are rendered as links.

```tsx
const service = useMachine(tabs.machine, {
  navigate(details) {
    // details => { value: string, node: HTMLAnchorElement, href: string }
    router.push(details.href)
  },
})
```

### Manual tab activation

By default, a tab is selected when it receives focus from either keyboard or
pointer interaction. This is called "automatic tab activation".

The other approach is "manual tab activation" which means the tab is selected
with the Enter key or by clicking on the tab.

```tsx {2}
const service = useMachine(tabs.machine, {
  activationMode: "manual",
})
```

### Looping keyboard navigation

Set `loopFocus` to control whether arrow-key navigation wraps at the ends.

```tsx
const service = useMachine(tabs.machine, {
  loopFocus: false,
})
```

### RTL Support

The tabs machine provides support right to left writing directions. In this
mode, the layout and keyboard interaction is flipped.

To enable RTL support, set the `dir` property in the machine's context to `rtl`.

```tsx {2}
const service = useMachine(tabs.machine, {
  dir: "rtl",
})
```

### Programmatic tab control

Use the connected API for imperative navigation and focus.

```tsx
api.setValue("tab-2")
api.selectNext()
api.selectPrev()
api.focus()
```

## Styling guide

### Selected state

When a tab is selected, a `data-selected` attribute is added to the trigger and
content elements.

```css
[data-part="trigger"][data-state="active"] {
  /* Styles for selected tab */
}

[data-part="content"][data-state="active"] {
  /* Styles for selected tab */
}
```

### Disabled state

When a tab is disabled, a `data-disabled` attribute is added to the trigger
element.

```css
[data-part="trigger"][data-disabled] {
  /* Styles for disabled tab */
}
```

### Focused state

When a tab is focused, you the `:focus` or `:focus-visible` pseudo-class to
style it.

```css
[data-part="trigger"]:focus {
  /* Styles for focused tab */
}
```

When any tab is focused, the list is given a `data-focus` attribute.

```css
[data-part="list"][data-focus] {
  /* Styles for when any tab is focused */
}
```

### Orientation styles

All parts of the tabs component have the `data-orientation` attribute. You can
use this to set the style for the horizontal or vertical tabs.

```css
[data-part="trigger"][data-orientation="(horizontal|vertical)"] {
  /* Styles for horizontal/vertical tabs */
}

[data-part="root"][data-orientation="(horizontal|vertical)"] {
  /* Styles for horizontal/vertical root */
}

[data-part="indicator"][data-orientation="(horizontal|vertical)"] {
  /* Styles for horizontal/vertical tab-indicator */
}

[data-part="list"][data-orientation="(horizontal|vertical)"] {
  /* Styles for horizontal/vertical list */
}
```

### The tab indicator

The tab indicator styles have CSS variables for the `transitionDuration` and
`transitionTimingFunction` defined in it.

The transition definition is applied when the selected tab changes to allow the
indicator move smoothly to the new selected tab.

```css
[data-part="indicator"] {
  --transition-duration: 0.2s;
  --transition-timing-function: ease-in-out;
}
```

## Methods and Properties

### Machine Context

The tabs machine exposes the following context properties:

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the tabs. Useful for composition.

**`translations`**
Type: `IntlTranslations | undefined`
Description: Specifies the localized strings that identifies the accessibility elements and their states

**`loopFocus`**
Type: `boolean | undefined`
Description: Whether the keyboard navigation will loop from last tab to first, and vice versa.

**`value`**
Type: `string | null | undefined`
Description: The controlled selected tab value

**`defaultValue`**
Type: `string | null | undefined`
Description: The initial selected tab value when rendered.
Use when you don't need to control the selected tab value.

**`orientation`**
Type: `"horizontal" | "vertical" | undefined`
Description: The orientation of the tabs. Can be `horizontal` or `vertical`
- `horizontal`: only left and right arrow key navigation will work.
- `vertical`: only up and down arrow key navigation will work.

**`activationMode`**
Type: `"manual" | "automatic" | undefined`
Description: The activation mode of the tabs. Can be `manual` or `automatic`
- `manual`: Tabs are activated when clicked or press `enter` key.
- `automatic`: Tabs are activated when receiving focus

**`onValueChange`**
Type: `((details: ValueChangeDetails) => void) | undefined`
Description: Callback to be called when the selected/active tab changes

**`onFocusChange`**
Type: `((details: FocusChangeDetails) => void) | undefined`
Description: Callback to be called when the focused tab changes

**`virtualFocus`**
Type: `boolean | undefined`
Description: Whether the tabs use virtual focus instead of roving tabindex.

When `true`, triggers receive no DOM focus — arrow keys update `focusedValue`
and all triggers remain `tabIndex: -1`. Useful when tabs live inside another
widget that manages focus (e.g. a combobox).

**`deselectable`**
Type: `boolean | undefined`
Description: Whether the active tab can be deselected when clicking on it.

**`navigate`**
Type: `((details: NavigateDetails) => void) | null | undefined`
Description: Function to navigate to the selected tab when clicking on it.
Useful if tab triggers are anchor elements.

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

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

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

### Machine API

The tabs `api` exposes the following methods:

**`value`**
Type: `string | null`
Description: The current value of the tabs.

**`focusedValue`**
Type: `string | null`
Description: The value of the tab that is currently focused.

**`setValue`**
Type: `(value: string) => void`
Description: Sets the value of the tabs.

**`clearValue`**
Type: `VoidFunction`
Description: Clears the value of the tabs.

**`setIndicatorRect`**
Type: `(value: string) => void`
Description: Sets the indicator rect to the tab with the given value

**`syncTabIndex`**
Type: `VoidFunction`
Description: Synchronizes the tab index of the content element.
Useful when rendering tabs within a select or combobox

**`focus`**
Type: `VoidFunction`
Description: Set focus on the selected tab trigger

**`selectNext`**
Type: `(fromValue?: string) => void`
Description: Selects the next tab

**`selectPrev`**
Type: `(fromValue?: string) => void`
Description: Selects the previous tab

**`getTriggerState`**
Type: `(props: TriggerProps) => TriggerState`
Description: Returns the state of the trigger with the given props

### Data Attributes

**`Root`**

**`data-tabs-root`**: <uid>
**`data-orientation`**: The orientation of the tabs
**`data-focus`**: Present when focused

**`List`**

**`data-tabs-list`**: <uid>
**`data-focus`**: Present when focused
**`data-orientation`**: The orientation of the list

**`Trigger`**

**`data-tabs-trigger`**: <uid>
**`data-orientation`**: The orientation of the trigger
**`data-disabled`**: Present when disabled
**`data-value`**: The value of the item
**`data-selected`**: Present when selected
**`data-focus`**: Present when focused
**`data-ssr`**: Present when not rendered in the browser. Useful for ssr styling

**`Content`**

**`data-tabs-content`**: <uid>
**`data-selected`**: Present when selected
**`data-orientation`**: The orientation of the content

**`Indicator`**

**`data-tabs-indicator`**: <uid>
**`data-orientation`**: The orientation of the indicator

### CSS Variables

<CssVarTable name="tabs" />

## Accessibility

### Keyboard Interactions

**`Tab`**
Description: When focus moves onto the tabs, focuses the active trigger. When a trigger is focused, moves focus to the active content.

**`ArrowDown`**
Description: Moves focus to the next trigger in vertical orientation and activates its associated content.

**`ArrowRight`**
Description: Moves focus to the next trigger in horizontal orientation and activates its associated content.

**`ArrowUp`**
Description: Moves focus to the previous trigger in vertical orientation and activates its associated content.

**`ArrowLeft`**
Description: Moves focus to the previous trigger in horizontal orientation and activates its associated content.

**`Home`**
Description: Moves focus to the first trigger and activates its associated content.

**`End`**
Description: Moves focus to the last trigger and activates its associated content.

**`Enter + Space`**
Description: In manual mode, when a trigger is focused, moves focus to its associated content.

Tags input renders tags inside a control, followed by an actual text input. By
default, tags are added when text is typed in the input field and the `Enter` or
`Comma` key is pressed. Throughout the interaction, DOM focus remains on the
input element.

## Resources


[Latest version: v2.0.0-next.1](https://www.npmjs.com/package/@zag-js/tags-input)
[Logic Visualizer](https://zag-visualizer.vercel.app/tags-input)
[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/tags-input)



**Features**

- Typing in the input and pressing Enter adds new tags
- Clear trigger to remove all tags
- Add tags by pasting into the input
- Delete tags on backspace
- Edit tags after creation
- Limit the number of tags
- Navigate tags with keyboard
- Custom validation to accept/reject tags

## Installation

Install the tags input package:

```bash
npm install @zag-js/tags-input @zag-js/react
# or
yarn add @zag-js/tags-input @zag-js/react
```

## Anatomy

To set up the tags input 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 tags input package:

```tsx
import * as tagsInput from "@zag-js/tags-input"
```

The tags input 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:

```tsx
import * as tagsInput from "@zag-js/tags-input"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useId } from "react"

export function TagsInput() {
  const service = useMachine(tagsInput.machine, {
    id: useId(),
    value: ["React", "Vue"],
  })

  const api = tagsInput.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      {api.value.map((value, index) => (
        <span key={index} {...api.getItemProps({ index, value })}>
          <div {...api.getItemPreviewProps({ index, value })}>
            <span>{value} </span>
            <button {...api.getItemDeleteTriggerProps({ index, value })}>
              &#x2715;
            </button>
          </div>
          <input {...api.getItemInputProps({ index, value })} />
        </span>
      ))}
      <input placeholder="Add tag..." {...api.getInputProps()} />
    </div>
  )
}
```

### Navigating and editing tags

When the input has an empty value or the caret is at the start position, the
tags can be selected with the left and right arrow keys. When a tag has visual
focus:

- Press `Enter` or double-click the tag to edit it, then press `Enter` to commit
  the change.
- Pressing `Delete` or `Backspace` will delete the tag that has "visual" focus.

### Setting the initial tags

To set the initial tag values, pass the `defaultValue` property in the machine's
context.

```tsx {2}
const service = useMachine(tagsInput.machine, {
  defaultValue: ["React", "Redux", "TypeScript"],
})
```

### Controlled tags input

To control the tags input programmatically, pass the `value` and `onValueChange`
properties to the machine function.

```tsx
import { useState } from "react"

export function ControlledTagsInput() {
  const [value, setValue] = useState(["React", "Vue"])

  const service = useMachine(tagsInput.machine, {
    value,
    onValueChange(details) {
      setValue(details.value)
    },
  })

  return ( // ... )
}
```

### Controlled input value

Use `inputValue` and `onInputValueChange` when you need to control the typing
state separately.

```tsx
const service = useMachine(tagsInput.machine, {
  inputValue,
  onInputValueChange(details) {
    setInputValue(details.inputValue)
  },
})
```

### Removing all tags

The tags input will remove all tags when the clear button is clicked. To remove
all tags, use the provided `clearTriggerProps` function from the `api`.

```tsx {4}
//...
<div {...api.getControlProps()}>
  <input {...api.getInputProps()} />
  <button {...api.getClearTriggerProps()} />
</div>
//...
```

To programmatically remove all tags, use `api.clearValue()`.

### Usage within forms

The tags input works when placed within a form and the form is submitted. We
achieve this by:

- ensuring we emit the input event as the value changes.
- adding a `name` and `value` attribute to a hidden input so the tags can be
  accessed in the `FormData`.

To get this feature working you need to pass a `name` option to the context and
render the hidden input with `api.getHiddenInputProps()`.

```tsx {2}
const service = useMachine(tagsInput.machine, {
  name: "tags",
  defaultValue: ["React", "Redux", "TypeScript"],
})
```

### Limiting the number of tags

To limit the number of tags within the component, you can set the `max` property
to the limit you want. The default value is `Infinity`.

When the tag reaches the limit, new tags cannot be added except the
`allowOverflow` option is passed to the context.

```tsx {2-3}
const service = useMachine(tagsInput.machine, {
  max: 10,
  allowOverflow: true,
})
```

### Validating Tags

Before a tag is added, the machine provides a `validate` function you can use to
determine whether to accept or reject a tag.

> **Note:** Duplicate tags are prevented by default. Set `allowDuplicates: true`
> to allow repeatable tags (e.g. sentence builders). Use `validate` for custom
> rules like format or length.

Common use-cases for validating tags include enforcing format, length, or
content rules.

```tsx {2-4}
const service = useMachine(tagsInput.machine, {
  validate(details) {
    // Example: only allow lowercase alphabetic tags
    return /^[a-z]+$/.test(details.inputValue)
  },
})
```

### Allow Duplicates

By default, duplicate tags are prevented. For use cases like sentence builders
or repeatable tokens, set `allowDuplicates: true`:

```tsx {2}
const service = useMachine(tagsInput.machine, {
  allowDuplicates: true,
})
```

### Blur behavior

When the tags input is blurred, you can configure the action the machine should
take by passing the `blurBehavior` option to the context.

- `"add"` — Adds the tag to the list of tags.
- `"clear"` — Clears the tags input value.

```tsx {2}
const service = useMachine(tagsInput.machine, {
  blurBehavior: "add",
})
```

### Paste behavior

To add a tag when a arbitrary value is pasted in the input element, pass the
`addOnPaste` option.

When a value is pasted, the machine will:

- check if the value is a valid tag based on the `validate` option
- split the value by the `delimiter` option passed

```tsx {2}
const service = useMachine(tagsInput.machine, {
  addOnPaste: true,
})
```

### Enable tag editing

By default, tags are add/remove only. To allow inline editing — double-clicking
a tag or focusing it and pressing `Enter` — set `editable: true`.

```tsx {2}
const service = useMachine(tagsInput.machine, {
  editable: true,
})
```

### Custom tag delimiter

Use `delimiter` to control how tags are created from key presses and paste.

```tsx
const service = useMachine(tagsInput.machine, {
  delimiter: ";",
})
```

### Listening for events

During the lifetime of the tags input interaction, here's a list of events we
emit:

- `onValueChange` — invoked when the tag value changes.
- `onHighlightChange` — invoked when a tag has visual focus.
- `onValueInvalid` — invoked when the max tag count is reached or the `validate`
  function returns `false`.

```tsx
const service = useMachine(tagsInput.machine, {
  onValueChange(details) {
    // details => { value: string[] }
    console.log("tags changed to:", details.value)
  },
  onHighlightChange(details) {
    // details => { highlightedValue: string | null }
    console.log("highlighted tag:", details.highlightedValue)
  },
  onValueInvalid(details) {
    console.log("Invalid!", details.reason)
  },
})
```

### Programmatic tag operations

Use the API for imperative updates.

```tsx
api.addValue("React")
api.setValue(["React", "TypeScript"])
api.clearValue() // clear all
api.clearValue("React") // clear one
api.setValueAtIndex(0, "Vue")
api.focus()
```

## Styling guide

Each part includes a `data-part` attribute you can target in CSS.

### Focused state

The input is focused when the user clicks on it. In this focused state, the root
and label receive `data-focus`.

```css
[data-part="root"][data-focus] {
  /* styles for root focus state */
}

[data-part="label"][data-focus] {
  /* styles for label focus state */
}

[data-part="input"]:focus {
  /* styles for input focus state */
}
```

### Invalid state

When the tags input is invalid by setting the `invalid: true` in the machine's
context, the `data-invalid` attribute is set on the root, input, control, and
label.

```css
[data-part="root"][data-invalid] {
  /* styles for invalid state for root */
}

[data-part="label"][data-invalid] {
  /*  styles for invalid state for label */
}

[data-part="input"][data-invalid] {
  /*  styles for invalid state for input */
}
```

### Disabled state

When the tags input is disabled by setting the `disabled: true` in the machine's
context, the `data-disabled` attribute is set on the root, input, control and
label.

```css
[data-part="root"][data-disabled] {
  /* styles for disabled state for root */
}

[data-part="label"][data-disabled] {
  /* styles for disabled state for label */
}

[data-part="input"][data-disabled] {
  /* styles for disabled state for input */
}

[data-part="control"][data-disabled] {
  /* styles for disabled state for control */
}
```

When a tag is disabled, the `data-disabled` attribute is set on the tag.

```css
[data-part="item-preview"][data-disabled] {
  /* styles for disabled tag  */
}
```

### Highlighted state

When a tag is highlighted via the keyboard navigation or pointer hover, a
`data-highlighted` attribute is set on the tag.

```css
[data-part="item-preview"][data-highlighted] {
  /* styles for visual focus */
}
```

### Readonly state

When the tags input is in its readonly state, the `data-readonly` attribute is
set on the root, label, input and control.

```css
[data-part="root"][data-readonly] {
  /* styles for readonly for root */
}

[data-part="control"][data-readonly] {
  /* styles for readonly for control */
}

[data-part="input"][data-readonly] {
  /* styles for readonly for input  */
}

[data-part="label"][data-readonly] {
  /* styles for readonly for label */
}
```

## Methods and Properties

### Machine Context

The tags input machine exposes the following context properties:

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the tags input. Useful for composition.

**`translations`**
Type: `IntlTranslations | undefined`
Description: Specifies the localized strings that identifies the accessibility elements and their states

**`maxLength`**
Type: `number | undefined`
Description: The max length of the input.

**`delimiter`**
Type: `string | RegExp | undefined`
Description: The character that serves has:
- event key to trigger the addition of a new tag
- character used to split tags when pasting into the input

**`autoFocus`**
Type: `boolean | undefined`
Description: Whether the input should be auto-focused

**`disabled`**
Type: `boolean | undefined`
Description: Whether the tags input should be disabled

**`readOnly`**
Type: `boolean | undefined`
Description: Whether the tags input should be read-only

**`invalid`**
Type: `boolean | undefined`
Description: Whether the tags input is invalid

**`required`**
Type: `boolean | undefined`
Description: Whether the tags input is required

**`editable`**
Type: `boolean | undefined`
Description: Whether a tag can be edited after creation, by pressing `Enter` or double clicking.

**`inputValue`**
Type: `string | undefined`
Description: The controlled tag input's value

**`defaultInputValue`**
Type: `string | undefined`
Description: The initial tag input value when rendered.
Use when you don't need to control the tag input value.

**`value`**
Type: `string[] | undefined`
Description: The controlled tag value

**`defaultValue`**
Type: `string[] | undefined`
Description: The initial tag value when rendered.
Use when you don't need to control the tag value.

**`onValueChange`**
Type: `((details: ValueChangeDetails) => void) | undefined`
Description: Callback fired when the tag values is updated

**`onInputValueChange`**
Type: `((details: InputValueChangeDetails) => void) | undefined`
Description: Callback fired when the input value is updated

**`onHighlightChange`**
Type: `((details: HighlightChangeDetails) => void) | undefined`
Description: Callback fired when a tag is highlighted by pointer or keyboard navigation

**`onValueInvalid`**
Type: `((details: ValidityChangeDetails) => void) | undefined`
Description: Callback fired when the max tag count is reached or the `validateTag` function returns `false`

**`validate`**
Type: `((details: ValidateArgs) => boolean) | undefined`
Description: Returns a boolean that determines whether a tag can be added.
Useful for preventing duplicates or invalid tag values.

**`allowDuplicates`**
Type: `boolean | undefined`
Description: Whether to allow duplicate tags.

**`blurBehavior`**
Type: `"clear" | "add" | undefined`
Description: The behavior of the tags input when the input is blurred
- `"add"`: add the input value as a new tag
- `"clear"`: clear the input value

**`addOnPaste`**
Type: `boolean | undefined`
Description: Whether to add a tag when you paste values into the tag input

**`max`**
Type: `number | undefined`
Description: The max number of tags

**`allowOverflow`**
Type: `boolean | undefined`
Description: Whether to allow tags to exceed max. In this case,
we'll attach `data-invalid` to the root

**`sanitizeValue`**
Type: `((value: string) => string) | undefined`
Description: Function to sanitize the tag value before adding.
Useful for trimming whitespace, normalizing case, or stripping special characters.

**`name`**
Type: `string | undefined`
Description: The name attribute for the input. Useful for form submissions

**`form`**
Type: `string | undefined`
Description: The associate form of the underlying input element.

**`placeholder`**
Type: `string | undefined`
Description: The placeholder text for the input

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

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

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

**`onPointerDownOutside`**
Type: `((event: PointerDownOutsideEvent) => void) | undefined`
Description: Function called when the pointer is pressed down outside the component

**`onFocusOutside`**
Type: `((event: FocusOutsideEvent) => void) | undefined`
Description: Function called when the focus is moved outside the component

**`onInteractOutside`**
Type: `((event: InteractOutsideEvent) => void) | undefined`
Description: Function called when an interaction happens outside the component

### Machine API

The tags input `api` exposes the following methods:

**`empty`**
Type: `boolean`
Description: Whether the tags are empty

**`inputValue`**
Type: `string`
Description: The value of the tags entry input.

**`value`**
Type: `string[]`
Description: The value of the tags as an array of strings.

**`valueAsString`**
Type: `string`
Description: The value of the tags as a string.

**`count`**
Type: `number`
Description: The number of the tags.

**`atMax`**
Type: `boolean`
Description: Whether the tags have reached the max limit.

**`setValue`**
Type: `(value: string[]) => void`
Description: Function to set the value of the tags.

**`clearValue`**
Type: `(id?: string) => void`
Description: Function to clear the value of the tags.

**`addValue`**
Type: `(value: string) => void`
Description: Function to add a tag to the tags.

**`setValueAtIndex`**
Type: `(index: number, value: string) => void`
Description: Function to set the value of a tag at the given index.

**`setInputValue`**
Type: `(value: string) => void`
Description: Function to set the value of the tags entry input.

**`clearInputValue`**
Type: `VoidFunction`
Description: Function to clear the value of the tags entry input.

**`focus`**
Type: `VoidFunction`
Description: Function to focus the tags entry input.

**`getItemState`**
Type: `(props: ItemProps) => ItemState`
Description: Returns the state of a tag

### Data Attributes

**`Root`**

**`data-tags-input-root`**: <uid>
**`data-invalid`**: Present when invalid
**`data-readonly`**: Present when read-only
**`data-disabled`**: Present when disabled
**`data-focus`**: Present when focused
**`data-empty`**: Present when the content is empty

**`Label`**

**`data-tags-input-label`**: <uid>
**`data-disabled`**: Present when disabled
**`data-invalid`**: Present when invalid
**`data-readonly`**: Present when read-only
**`data-required`**: Present when required

**`Control`**

**`data-tags-input-control`**: <uid>
**`data-disabled`**: Present when disabled
**`data-readonly`**: Present when read-only
**`data-invalid`**: Present when invalid
**`data-focus`**: Present when focused

**`Input`**

**`data-tags-input-input`**: <uid>
**`data-invalid`**: Present when invalid
**`data-readonly`**: Present when read-only
**`data-empty`**: Present when the content is empty

**`Item`**

**`data-tags-input-item`**: <uid>
**`data-value`**: The value of the item
**`data-disabled`**: Present when disabled

**`ItemPreview`**

**`data-tags-input-item-preview`**: <uid>
**`data-value`**: The value of the item
**`data-disabled`**: Present when disabled
**`data-highlighted`**: Present when highlighted

**`ItemText`**

**`data-tags-input-item-text`**: <uid>
**`data-disabled`**: Present when disabled
**`data-highlighted`**: Present when highlighted

**`ItemDeleteTrigger`**

**`data-tags-input-item-delete-trigger`**: <uid>
**`data-disabled`**: Present when disabled
**`data-highlighted`**: Present when highlighted

**`ClearTrigger`**

**`data-tags-input-clear-trigger`**: <uid>
**`data-readonly`**: Present when read-only

## Accessibility

### Keyboard Interactions

**`ArrowLeft`**
Description: Moves focus to the previous tag item

**`ArrowRight`**
Description: Moves focus to the next tag item

**`Backspace`**
Description: Deletes the tag item that has visual focus or the last tag item

**`Enter`**
Description: <span>When a tag item has visual focus, it puts the tag in edit mode.<br />When the input has focus, it adds the value to the list of tags</span>

**`Delete`**
Description: Deletes the tag item that has visual focus

**`Control + V`**
Description: When `addOnPaste` is set. Adds the pasted value as a tags

The timer machine tracks elapsed or remaining time.

## Resources


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



**Features**

- Countdown from a specified time
- Use as stopwatch to record the time elapsed
- Control the timer with start, pause, resume, reset, and restart actions
- Set the tick interval for the timer

## Installation

Install the timer package:

```bash
npm install @zag-js/timer @zag-js/react
# or
yarn add @zag-js/timer @zag-js/react
```

## Anatomy

Check the timer anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the timer package:

```tsx
import * as timer from "@zag-js/timer"
```

These are the key exports:

- `machine` - State machine logic.
- `connect` - Maps machine state to JSX props and event handlers.
- `parse` - Parses a date-time string or object into milliseconds.

Then use the framework integration helpers:

```tsx
import { normalizeProps, useMachine } from "@zag-js/react"
import * as timer from "@zag-js/timer"
import { useId } from "react"

export function Countdown() {
  const service = useMachine(timer.machine, {
    id: useId(),
    countdown: true,
    autoStart: true,
    startMs: timer.parse({ days: 2, seconds: 10 }),
  })

  const api = timer.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <div {...api.getAreaProps()}>
        <div {...api.getItemProps({ type: "days" })}>
          {api.formattedTime.days}
        </div>
        <div {...api.getSeparatorProps()}>:</div>
        <div {...api.getItemProps({ type: "hours" })}>
          {api.formattedTime.hours}
        </div>
        <div {...api.getSeparatorProps()}>:</div>
        <div {...api.getItemProps({ type: "minutes" })}>
          {api.formattedTime.minutes}
        </div>
        <div {...api.getSeparatorProps()}>:</div>
        <div {...api.getItemProps({ type: "seconds" })}>
          {api.formattedTime.seconds}
        </div>
      </div>
      <div {...api.getControlProps()}>
        <button {...api.getActionTriggerProps({ action: "start" })}>
          START
        </button>
        <button {...api.getActionTriggerProps({ action: "pause" })}>
          PAUSE
        </button>
        <button {...api.getActionTriggerProps({ action: "resume" })}>
          RESUME
        </button>
        <button {...api.getActionTriggerProps({ action: "reset" })}>
          RESET
        </button>
      </div>
    </div>
  )
}
```

### Setting the start value

Set the `startMs` property to the timer machine's context to set the start time
in milliseconds.

```tsx
const service = useMachine(timer.machine, {
  startMs: 1000 * 60 * 60, // 1 hour
})
```

Alternatively, you can also use the `timer.parse` function to convert a date
time string or object into milliseconds

```tsx
const service = useMachine(timer.machine, {
  startMs: timer.parse("2021-01-01T12:00:00Z"),
  // startMs: timer.parse({ hours: 12, minutes: 0, seconds: 0 }),
})
```

### Auto starting the timer

Set the `autoStart` property to `true` in the timer machine's context to start
the timer automatically when the component mounts.

```tsx
const service = useMachine(timer.machine, {
  autoStart: true,
})
```

### Usage as countdown timer

To use the timer as a countdown timer, set the `countdown` property to `true` in
the timer machine's context.

```tsx
const service = useMachine(timer.machine, {
  countdown: true,
})
```

### Setting the target value

To set the target value of the countdown timer, pass the `targetMs` property in
the timer machine's context. The timer stops automatically when the `targetMs`
is reached.

When `targetMs` is set and `countdown=true`, the timer ticks down to zero from
the specified target time.

```tsx
const service = useMachine(timer.machine, {
  countdown: true,
  targetMs: 1000 * 60 * 60, // 1 hour
})
```

When `targetMs` is set and `countdown=false|undefined`, the timer ticks up to
the specified target time.

```tsx
const service = useMachine(timer.machine, {
  targetMs: 1000 * 60 * 60, // 1 hour
})
```

### Setting the tick interval

Set the `interval` property to the timer machine's context to set the tick
interval in milliseconds.

```tsx
const service = useMachine(timer.machine, {
  interval: 1000, // 1 second
})
```

### Listening to tick events

When the timer ticks, the `onTick` callback is invoked. You can listen to this
event and update your UI accordingly.

```tsx
const service = useMachine(timer.machine, {
  onTick(details) {
    // details => { value: number, time, formattedTime }
    console.log(details.formattedTime)
  },
})
```

### Listening for completion events

When the timer reaches the target time, the `onComplete` callback is invoked.

```tsx
const service = useMachine(timer.machine, {
  countdown: true,
  targetMs: 1000 * 60 * 60, // 1 hour
  onComplete() {
    console.log("Timer completed")
  },
})
```

### Programmatic timer controls

Use the connected API for timer actions.

```tsx
api.start()
api.pause()
api.resume()
api.reset()
api.restart()
```

## Methods and Properties

### Machine Context

The timer machine exposes the following context properties:

**`translations`**
Type: `IntlTranslations | undefined`
Description: Specifies the localized strings that identifies the accessibility elements and their states

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the timer parts

**`countdown`**
Type: `boolean | undefined`
Description: Whether the timer should countdown, decrementing the timer on each tick.

**`startMs`**
Type: `number | undefined`
Description: The total duration of the timer in milliseconds.

**`targetMs`**
Type: `number | undefined`
Description: The minimum count of the timer in milliseconds.

**`autoStart`**
Type: `boolean | undefined`
Description: Whether the timer should start automatically

**`interval`**
Type: `number | undefined`
Description: The interval in milliseconds to update the timer count.

**`onTick`**
Type: `((details: TickDetails) => void) | undefined`
Description: Function invoked when the timer ticks

**`onComplete`**
Type: `(() => void) | undefined`
Description: Function invoked when the timer is completed

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

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

### Machine API

The timer `api` exposes the following methods:

**`running`**
Type: `boolean`
Description: Whether the timer is running.

**`paused`**
Type: `boolean`
Description: Whether the timer is paused.

**`time`**
Type: `Time`
Description: The formatted timer count value.

**`formattedTime`**
Type: `Time<string>`
Description: The formatted time parts of the timer count.

**`start`**
Type: `VoidFunction`
Description: Function to start the timer.

**`pause`**
Type: `VoidFunction`
Description: Function to pause the timer.

**`resume`**
Type: `VoidFunction`
Description: Function to resume the timer.

**`reset`**
Type: `VoidFunction`
Description: Function to reset the timer.

**`restart`**
Type: `VoidFunction`
Description: Function to restart the timer.

**`progressPercent`**
Type: `number`
Description: The progress percentage of the timer.

Toast provides brief feedback after an action.

## Resources


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



**Features**

- Supports screen readers
- Limits the number of visible toasts
- Handles promise lifecycles
- Pauses on hover, focus, or page idle
- Supports programmatic update/remove
- Priority-based queue system for ordering queued toasts

## Installation

Install the toast package:

```bash
npm install @zag-js/toast @zag-js/react
# or
yarn add @zag-js/toast @zag-js/react
```

## Anatomy

Check the toast anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the toast package:

```tsx
import * as toast from "@zag-js/toast"
```

Then use the framework integration helpers:

```tsx
import { useMachine, normalizeProps } from "@zag-js/react"
import * as toast from "@zag-js/toast"
import { useId } from "react"

// 1. Create the toast store
const toaster = toast.createStore({
  overlap: true,
  placement: "top-end",
})

// 2. Design the toast component
function Toast(props) {
  const machineProps = {
    ...props.toast,
    parent: props.parent,
    index: props.index,
  }
  const service = useMachine(toast.machine, machineProps)
  const api = toast.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <h3 {...api.getTitleProps()}>{api.title}</h3>
      <p {...api.getDescriptionProps()}>{api.description}</p>
      <button onClick={api.dismiss}>Close</button>
    </div>
  )
}

// 3. Design the toaster
export function Toaster() {
  const service = useMachine(toast.group.machine, {
    id: useId(),
    store: toaster,
  })
  const api = toast.group.connect(service, normalizeProps)
  return (
    <div {...api.getGroupProps()}>
      {api.getToasts().map((toast, index) => (
        <Toast key={toast.id} toast={toast} parent={service} index={index} />
      ))}
    </div>
  )
}

// 4. Render the toaster in your app
export function App() {
  return (
    <>
      <Toaster />
      <ExampleComponent />
    </>
  )
}

// 5. Within your app
function Demo() {
  return (
    <div>
      <button
        onClick={() => {
          toaster.create({ title: "Hello" })
        }}
      >
        Info toast
      </button>
      <button
        onClick={() => {
          toaster.create({ title: "Data submitted!", type: "success" })
        }}
      >
        Success toast
      </button>
    </div>
  )
}
```

To use toast effectively, understand these key parts:

### Toast Group

- `toast.group.machine` - State machine logic for the toast region.
- `toast.group.connect` - Maps group state to JSX props and subscriptions.

  > We recommend setting up the toast group machine once at the root of your
  > project.

### Toast Item

- `toast.machine` - State machine logic for a single toast.
- `toast.connect` - Maps toast state to JSX props and controls.

### Creating a toast

Common toast types are `info`, `success`, `warning`, `loading`, and `error`. You
can also pass a custom type string.

Helper methods are also available: `toaster.info(...)`, `toaster.success(...)`,
`toaster.warning(...)`, `toaster.error(...)`, and `toaster.loading(...)`.

To create a toast, use the `toaster.create(...)` method.

```tsx
toaster.create({
  title: "Hello World",
  description: "This is a toast",
  type: "info",
})
```

The options you can pass in are:

- `title` — The title of the toast.
- `description` — The description of the toast.
- `type` — The type of the toast. Can be either `error`, `success` , `info`,
  `warning`, `loading`, or any custom string.
- `duration` — The duration of the toast. The default duration is computed based
  on the specified `type`.
- `onStatusChange` — A callback that listens for the status changes across the
  toast lifecycle.
- `removeDelay` — The delay before unmounting the toast from the DOM. Useful for
  transition.
- `action` — Optional action button with `label` and `onClick`.
- `closable` — Whether to render a close trigger.
- `priority` — Queue priority (1–8, lower is higher). Auto-assigned based on
  `type` and `action` when omitted.

### Changing the placement

Placement is configured on the toast store and applies to the whole toast group.

```tsx
const toaster = toast.createStore({
  placement: "top-start",
})
```

### Overlapping toasts

When multiple toasts are created, they are rendered in a stack. To make the
toasts overlap, set the `overlap` property to `true`.

```tsx
const toaster = toast.createStore({
  overlap: true,
})
```

> Be sure to set up the [required styles](#requirement) to make overlap work
> correctly.

### Changing the duration

Every toast has a default visible duration depending on the `type` set. Here's
the following toast types and matching default durations:

<PropValueTable
  items={{
    headings: ["type", "duration"],
    data: [
      ["info", "5000"],
      ["error", "5000"],
      ["success", "2000"],
      ["loading", "Infinity"],
    ],
  }}
/>

You can override the duration of the toast by passing the `duration` property to
the `toaster.create(...)` function.

```tsx {5}
toaster.create({
  title: "Hello World",
  description: "This is a toast",
  type: "info",
  duration: 6000,
})
```

Use `toaster.create(...)` for new toasts and `toaster.update(id, ...)` to modify
an existing one.

### Using portals

Using a portal is helpful to ensure that the toast is rendered outside the DOM
hierarchy of the parent component. To render the toast in a portal, wrap the
rendered toasts in the `ToastProvider` within your framework-specific portal.

```tsx {1,12,14}
import { useMachine, normalizeProps, Portal } from "@zag-js/react"
import * as toast from "@zag-js/toast"

// ...

// 3. Create the toast group provider, wrap your app with it
export function Toaster() {
  const service = useMachine(toast.group.machine, { id: "1", store: toaster })
  const api = toast.group.connect(service, normalizeProps)

  return (
    <Portal>
      {api.getToasts().map((toast, index) => (
        <Toast key={toast.id} actor={toast} parent={service} index={index} />
      ))}
    </Portal>
  )
}
```

### Programmatic control

To update a toast programmatically, you need access to the unique identifier of
the toast.

This identifier can be either:

- the `id` passed into `toaster.create(...)` or,
- the returned random `id` when the `toaster.create(...)` is called.

You can use any of the following methods to control a toast:

- `toaster.update(...)` — Updates a toast.
- `toaster.remove(...)` — Removes a toast instantly without delay.
- `toaster.dismiss(...)` — Removes a toast with delay.
- `toaster.pause(...)` — Pauses a toast.
- `toaster.resume(...)` — Resumes a toast.
- `toaster.isVisible(...)` — Checks if a toast is currently visible.
- `toaster.isDismissed(...)` — Checks if a toast has been dismissed.

```tsx {2,11-15}
// grab the id from the created toast
const id = toaster.create({
  title: "Hello World",
  description: "This is a toast",
  type: "info",
  duration: 6000,
})

// update the toast
toaster.update(id, {
  title: "Hello World",
  description: "This is a toast",
  type: "success",
})

// remove the toast
toaster.remove(id)

// dismiss the toast
toaster.dismiss(id)
```

#### Pause and resume all toasts

Call `pause()`/`resume()` without an `id` to affect all active toasts.

```tsx
toaster.pause()
toaster.resume()
```

### Handling promises

The toast group API exposes a `toaster.promise()` function to allow you update
the toast when it resolves or rejects.

> With the promise API, you can pass the toast options for each promise
> lifecycle. **The `loading` option is required**

```tsx
toaster.promise(promise, {
  loading: {
    title: "Loading",
    description: "Please wait...",
  },
  success: (data) => ({
    title: "Success",
    description: "Your request has been completed",
  }),
  error: (err) => ({
    title: "Error",
    description: "An error has occurred",
  }),
})
```

`toaster.promise(...)` returns `{ id, unwrap }`, so you can await the original
result:

```tsx
const result = toaster.promise(fetchData(), {
  loading: { title: "Loading..." },
})
await result?.unwrap()
```

### Pausing the toasts

There are three scenarios that pause toast timeout:

- When a user hovers or focuses the toast region.
- When the document loses focus or the page is idle (e.g. switching to a new
  browser tab), controlled via the `pauseOnPageIdle` store option.
- When the `toaster.pause(id)` is called.

```tsx
// Global pause options
const toaster = toast.createStore({
  pauseOnPageIdle: true,
})

// Programmatically pause a toast (by `id`)
// `id` is the return value of `toaster.create(...)`
toaster.pause(id)
```

### Limiting the number of toasts

Toasts are great but displaying too many of them can sometimes hamper the user
experience. To limit visible toasts, set `max` on the store.

```tsx {3}
const toaster = toast.createStore({
  max: 10,
})
```

### Toast priority

When the max number of visible toasts is reached, queued toasts are sorted by
priority before being displayed. Priority ranges from `1` (highest) to `8`
(lowest).

Default priorities are assigned automatically based on toast type and whether it
has an action:

| Type      | With action | Without action |
| --------- | ----------- | -------------- |
| `error`   | 1           | 2              |
| `warning` | 3           | 6              |
| `loading` | 4           | 5              |
| `success` | 5           | 7              |
| `info`    | 6           | 8              |

You can override the priority by passing the `priority` option:

```tsx
toaster.create({
  title: "Critical update",
  type: "info",
  priority: 1, // treat as highest priority
})
```

### Focus Hotkey for toasts

When a toast is created, you can focus the toast region by pressing the
`alt + T`. This is useful for screen readers and keyboard navigation.

Set the `hotkey` store option to change the underlying hotkey.

```tsx
const service = useMachine(toast.group.machine, {
  store: toast.createStore({ hotkey: ["F6"] }),
})
```

### Listening for toast lifecycle

When a toast is created, you can listen for the status changes across its
lifecycle using the `onStatusChange` callback when you call
`toaster.create(...)`.

The status values are:

- `visible` - The toast is mounted and rendered
- `dismissing` - The toast is closing but still mounted
- `unmounted` - The toast has been completely unmounted and no longer exists

```tsx {3-7}
toaster.info({
  title: "Hello World",
  description: "This is a toast",
  type: "info",
  onStatusChange: (details) => {
    // details => { status: "visible" | "dismissing" | "unmounted" }
    console.log("Toast status:", details)
  },
})
```

### Changing the gap between toasts

When multiple toasts are rendered, a gap of `16px` is applied between each
toast. To change this value, set `gap` on the store.

```tsx
const toaster = toast.createStore({
  gap: 24,
})
```

### Changing the offset

The toast region has a default `1rem` offset from the viewport. Use the
`offsets` store option to change this offset.

```tsx
const toaster = toast.createStore({
  offsets: "24px",
})
```

## Styling guide

### Requirement

The toast machine injects a bunch of css variables that are required for it to
work. You need to connect these variables in your styles.

```css
[data-part="root"] {
  translate: var(--x) var(--y);
  scale: var(--scale);
  z-index: var(--z-index);
  height: var(--height);
  opacity: var(--opacity);
  will-change: translate, opacity, scale;
}
```

To make transitions smooth, include `transition` properties.

```css
[data-part="root"] {
  transition:
    translate 400ms,
    scale 400ms,
    opacity 400ms;
  transition-timing-function: cubic-bezier(0.21, 1.02, 0.73, 1);
}

[data-part="root"][data-state="closed"] {
  transition:
    translate 400ms,
    scale 400ms,
    opacity 200ms;
  transition-timing-function: cubic-bezier(0.06, 0.71, 0.55, 1);
}
```

### Toast styling

When a toast is created and the `api.getRootProps()` from the `toast.connect` is
used, the toast will have a `data-type` that matches the specified `type` at its
creation.

You can use this property to style the toast.

```css
[data-part="root"][data-type="info"] {
  /* Styles for the specific toast type */
}

[data-part="root"][data-type="error"] {
  /* Styles for the error toast type */
}

[data-part="root"][data-type="success"] {
  /* Styles for the success toast type */
}

[data-part="root"][data-type="loading"] {
  /* Styles for the loading toast type */
}
```

## Methods and Properties

### Machine API

The toast's `api` exposes the following methods:

**`getCount`**
Type: `() => number`
Description: The total number of toasts

**`getToasts`**
Type: `() => ToastProps[]`
Description: The toasts

**`subscribe`**
Type: `(callback: (toasts: Options<O>[]) => void) => VoidFunction`
Description: Subscribe to the toast group

### Data Attributes

**`Root`**

**`data-toast-root`**: <uid>
**`data-state`**: "open" | "closed"
**`data-type`**: The type of the item
**`data-placement`**: The placement of the toast
**`data-align`**: 
**`data-side`**: The side of the trigger that the toast is positioned on
**`data-mounted`**: Present when mounted
**`data-paused`**: Present when paused
**`data-first`**: 
**`data-sibling`**: 
**`data-stack`**: 
**`data-overlap`**: Present when overlapping

**`GhostBefore`**

**`data-toast-ghost-before`**: <uid>
**`data-ghost`**: 

**`GhostAfter`**

**`data-toast-ghost-after`**: <uid>
**`data-ghost`**: 

### CSS Variables

<CssVarTable name="toast" />

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)).

## Resources


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



**Features**

- Controlled and uncontrolled pressed state
- Optional indicator part for icons or labels
- `aria-pressed` for assistive technology

## Installation

Install the toggle package:

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

## Anatomy

To set up the toggle correctly, you'll need to understand its anatomy and how we name its parts.

> Each part includes a component-specific data attribute to help identify it 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:

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

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

  return (
    <button {...api.getRootProps()}>
      <span {...api.getIndicatorProps()} />
      Bold
    </button>
  )
}
```

### 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
<button {...api.getRootProps()}>
  <span {...api.getIndicatorProps()}>
    <BoldIcon />
  </span>
</button>
```

## Styling guide

Each part includes a component-specific data attribute you can target in CSS.

### Pressed state

When pressed, `data-pressed` is applied to the root and indicator.

```css
[data-toggle-root][data-pressed] {
  /* pressed */
}

[data-toggle-indicator][data-pressed] {
  /* pressed indicator */
}
```

### Disabled state

When disabled, `data-disabled` is set on the root and indicator.

```css
[data-toggle-root][data-disabled] {
  /* disabled */
}
```

## Methods and Properties

### Machine Context

The toggle machine exposes the following context properties:

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

**`defaultPressed`**
Type: `boolean | undefined`
Description: The default pressed state of the toggle.

**`pressed`**
Type: `boolean | undefined`
Description: The pressed state of the toggle.

**`onPressedChange`**
Type: `((pressed: boolean) => void) | undefined`
Description: Event handler called when the pressed state of the toggle changes.

### Machine API

The toggle `api` exposes the following methods:

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

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

**`setPressed`**
Type: `(pressed: boolean) => void`
Description: Sets the pressed state of the toggle.

**`getRootProps`**
Type: `() => T["element"]`
Description: Props for the root `button` element.

**`getIndicatorProps`**
Type: `() => T["element"]`
Description: Props for the optional visual indicator (e.g. icon) element.

### Data Attributes

**`Root`**

**`data-toggle-root`**: <uid>
**`data-pressed`**: Present when pressed
**`data-disabled`**: Present when disabled

**`Indicator`**

**`data-toggle-indicator`**: <uid>
**`data-disabled`**: Present when disabled
**`data-pressed`**: Present when pressed

## Accessibility

Implements a [button](https://www.w3.org/WAI/ARIA/apg/patterns/button/) with `aria-pressed` reflecting the pressed
state.

### Keyboard Interactions

**`Space + Enter`**
Description: Toggle the pressed state

A toggle group lets users toggle one or more related options.

## Resources


[Latest version: v2.0.0-next.1](https://www.npmjs.com/package/@zag-js/toggle-group)
[Logic Visualizer](https://zag-visualizer.vercel.app/toggle-group)
[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/toggle-group)



**Features**

- Fully managed keyboard navigation
- Supports horizontal and vertical orientation
- Supports multiple selection

## Installation

Install the toggle group package:

```bash
npm install @zag-js/toggle-group @zag-js/react
# 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 component-specific data attribute to help identify it in the DOM.



## Usage

Import the toggle group package:

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

The toggle group 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:

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

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

### Listening for value changes

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

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

### Controlled toggle group

Use `value` and `onValueChange` for controlled usage.

```tsx
const service = useMachine(toggle.machine, {
  value,
  onValueChange(details) {
    setValue(details.value)
  },
})
```

### Allowing multiple selection

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

```tsx {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.

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

### Disabling a toggle

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

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

### Disabling focus loop

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

```tsx {2}
const service = useMachine(toggle.machine, {
  loopFocus: 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`.

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

### Allowing or preventing deselection

Use `deselectable` to control whether the active item can be toggled off in
single-select mode.

```tsx
const service = useMachine(toggle.machine, {
  deselectable: false,
})
```

### Programmatic value control

Use the API for imperative updates.

```tsx
api.setValue(["bold", "italic"])
```

## Styling guide

Each part includes a component-specific data attribute you can target in CSS.

### Pressed State

When pressed, `data-pressed` is applied to the toggle button.

```css
[data-toggle-group-item][data-pressed] {
  /* styles for toggle button */
}
```

### Focused State

Use native focus selectors to style the focused toggle button. Use
`:focus-visible` for keyboard focus rings and `:focus-within` if the root should
be styled while a toggle button is focused.

```css
[data-toggle-group-root]:focus-within {
  /* styles for the focused root */
}

[data-toggle-group-item]:focus-visible {
  /* styles for the focused toggle */
}
```

### Disabled State

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

```css
[data-toggle-group-root][data-disabled] {
  /* styles for the root */
}

[data-toggle-group-item][data-disabled] {
  /* styles for the toggle */
}
```

## Methods and Properties

### Machine Context

The toggle group machine exposes the following context properties:

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the toggle. Useful for composition.

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

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

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

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

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

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

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

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

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

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

**`getRootNode`**
Type: `(() => ShadowRoot | Document | Node) | undefined`
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-toggle-group-root`**: <uid>
**`data-disabled`**: Present when disabled
**`data-multiple`**: 
**`data-orientation`**: The orientation of the toggle-group

**`Item`**

**`data-toggle-group-item`**: <uid>
**`data-pressed`**: Present when pressed
**`data-disabled`**: Present when disabled
**`data-orientation`**: The orientation of the item

## Accessibility

Uses roving tabindex to manage focus movement among toggle buttons. Items are
rendered as buttons with `aria-pressed` in both single and multiple selection
modes.

### 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: v2.0.0-next.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, click, pointer down, or scroll
- 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
- Supports multiple triggers sharing a single tooltip instance

## Installation

Install the tooltip package:

```bash
npm install @zag-js/tooltip @zag-js/react
# or
yarn add @zag-js/tooltip @zag-js/react
```

## Anatomy

Check the tooltip anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the tooltip package:

```tsx
import * as tooltip from "@zag-js/tooltip"
```

The tooltip package exports two key functions:

- `machine` - State machine logic.
- `connect` - Maps machine state to JSX props and event handlers.

To get tooltip working, you'll need to:

- Set up the tooltip portal (shared container for tooltips)
- Add `triggerProps` and `tooltipProps` to the right elements

Then use the framework integration helpers:

```tsx
import * as tooltip from "@zag-js/tooltip"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useId } from "react"

export function Tooltip() {
  const service = useMachine(tooltip.machine, { id: useId() })

  const api = tooltip.connect(service, normalizeProps)

  return (
    <>
      <button {...api.getTriggerProps()}>Hover me</button>
      {api.open && (
        <div {...api.getPositionerProps()}>
          <div {...api.getContentProps()}>Tooltip</div>
        </div>
      )}
    </>
  )
}
```

### Customizing the timings

By default, the tooltip opens after `400ms` and closes after `150ms`. You can
customize this by passing the `openDelay` and `closeDelay` context properties.

```tsx {2-3}
const service = useMachine(tooltip.machine, {
  openDelay: 500,
  closeDelay: 200,
})
```

### Changing the placement

The tooltip uses [floating-ui](https://floating-ui.com/) for dynamic
positioning. You can change the placement of the tooltip by passing the
`positioning.placement` context property to the machine.

```tsx {2-4}
const service = useMachine(tooltip.machine, {
  positioning: {
    placement: "bottom-start",
  },
})
```

### Adding an arrow

To render an arrow within the tooltip, use the `api.getArrowProps()` and
`api.getArrowTipProps()`.

```tsx {6-8}
//...
const api = tooltip.connect(service, normalizeProps)
//...
return (
  <div {...api.getPositionerProps()}>
    <div {...api.getArrowProps()}>
      <div {...api.getArrowTipProps()} />
    </div>
    <div {...api.getContentProps()}>{/* ... */}</div>
  </div>
)
//...
```

### Dismiss behavior

Tooltips close on Escape, click, pointer down, and scroll by default. Configure
these with `closeOnEscape`, `closeOnClick`, `closeOnPointerDown`, and
`closeOnScroll`.

```tsx {2-5}
const service = useMachine(tooltip.machine, {
  closeOnEscape: false,
  closeOnClick: false,
  closeOnPointerDown: false,
  closeOnScroll: false,
})
```

### Making the tooltip interactive

Set the `interactive` context property to `true` to make the tooltip
interactive.

When a tooltip is interactive, it remains open as the pointer moves from the
trigger into the content.

```tsx {2}
const service = useMachine(tooltip.machine, {
  interactive: true,
})
```

### Listening for open state changes

When the tooltip is opened or closed, the `onOpenChange` callback is invoked.

```tsx {2-7}
const service = useMachine(tooltip.machine, {
  onOpenChange(details) {
    // details => { open: boolean }
    console.log(details.open)
  },
})
```

### Multiple triggers

A single tooltip instance can be shared across multiple trigger elements. Pass a
`value` to `getTriggerProps` to identify each trigger.

```tsx
const service = useMachine(tooltip.machine, {
  onTriggerValueChange({ value }) {
    console.log("active trigger:", value)
  },
})

const api = tooltip.connect(service, normalizeProps)

return (
  <>
    <button {...api.getTriggerProps({ value: "bold" })}>B</button>
    <button {...api.getTriggerProps({ value: "italic" })}>I</button>
    <div {...api.getPositionerProps()}>
      <div {...api.getContentProps()}>
        {api.triggerValue === "bold" ? "Bold" : "Italic"}
      </div>
    </div>
  </>
)
```

When hovering a different trigger while the tooltip is open, it repositions
without closing. `aria-describedby` is scoped to the active trigger.

### Controlled tooltip

Use `open` and `onOpenChange` for controlled usage.

```tsx
const service = useMachine(tooltip.machine, {
  open,
  onOpenChange(details) {
    setOpen(details.open)
  },
})
```

### Programmatic open

Use the connected API for imperative control.

```tsx
api.setOpen(true)
```

## Styling guide

Each part includes a `data-part` attribute you can target in CSS.

```css
[data-part="trigger"] {
  /* styles for the content */
}

[data-part="content"] {
  /* styles for the content */
}
```

### Open and close states

When the tooltip is open, the `data-state` attribute is added to the trigger

```css
[data-part="trigger"][data-state="open|closed"] {
  /* styles for the trigger's expanded state */
}

[data-part="content"][data-state="open|closed"] {
  /* styles for the trigger's expanded state */
}
```

### Styling the arrow

When using arrows within the menu, you can style it using css variables.

```css
[data-part="arrow"] {
  --arrow-size: 20px;
  --arrow-background: red;
}
```

## Methods and Properties

### Machine Context

The tooltip machine exposes the following context properties:

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the tooltip. Useful for composition.

**`openDelay`**
Type: `number | undefined`
Description: The open delay of the tooltip.

**`closeDelay`**
Type: `number | undefined`
Description: The close delay of the tooltip.

**`closeOnPointerDown`**
Type: `boolean | undefined`
Description: Whether to close the tooltip on pointerdown.

**`closeOnEscape`**
Type: `boolean | undefined`
Description: Whether to close the tooltip when the Escape key is pressed.

**`closeOnScroll`**
Type: `boolean | undefined`
Description: Whether the tooltip should close on scroll

**`closeOnClick`**
Type: `boolean | undefined`
Description: Whether the tooltip should close on click

**`interactive`**
Type: `boolean | undefined`
Description: Whether the tooltip's content is interactive.
In this mode, the tooltip will remain open when user hovers over the content.

**`onOpenChange`**
Type: `((details: OpenChangeDetails) => void) | undefined`
Description: Function called when the tooltip is opened.

**`aria-label`**
Type: `string | undefined`
Description: Custom label for the tooltip.

**`positioning`**
Type: `PositioningOptions | undefined`
Description: The user provided options used to position the popover content

**`disabled`**
Type: `boolean | undefined`
Description: Whether the tooltip is disabled

**`open`**
Type: `boolean | undefined`
Description: The controlled open state of the tooltip

**`defaultOpen`**
Type: `boolean | undefined`
Description: The initial open state of the tooltip when rendered.
Use when you don't need to control the open state of the tooltip.

**`triggerValue`**
Type: `string | null | undefined`
Description: The controlled trigger value

**`defaultTriggerValue`**
Type: `string | null | undefined`
Description: The initial trigger value when rendered.
Use when you don't need to control the trigger value.

**`onTriggerValueChange`**
Type: `((details: TriggerValueChangeDetails) => void) | undefined`
Description: Function called when the trigger value changes.

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

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

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

### Machine API

The tooltip `api` exposes the following methods:

**`open`**
Type: `boolean`
Description: Whether the tooltip is open.

**`setOpen`**
Type: `(open: boolean) => void`
Description: Function to open the tooltip.

**`triggerValue`**
Type: `string | null`
Description: The trigger value

**`setTriggerValue`**
Type: `(value: string | null) => void`
Description: Function to set the trigger value

**`reposition`**
Type: `(options?: Partial<PositioningOptions>) => void`
Description: Function to reposition the popover

### Data Attributes

**`Trigger`**

**`data-tooltip-trigger`**: <uid>
**`data-value`**: The value of the item
**`data-current`**: Present when current
**`data-expanded`**: Present when expanded
**`data-state`**: "open" | "closed"

**`Content`**

**`data-tooltip-content`**: <uid>
**`data-state`**: "open" | "closed"
**`data-instant`**: 
**`data-placement`**: The placement of the content
**`data-side`**: The side of the trigger that the content is positioned on

### CSS Variables

<CssVarTable name="tooltip" />

## Accessibility

### Keyboard Interactions

**`Tab`**
Description: Opens/closes the tooltip without delay.

**`Escape`**
Description: If open, closes the tooltip without delay.

A tour guides users through product features with step-by-step overlays.

## Resources


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



**Features**

- Supports different step types such as "dialog", "floating", "tooltip" or
  "wait".
- Supports customizable content per step.
- Wait steps for waiting for a specific selector to appear on the page before
  showing the next step.
- Flexible positioning of the tour dialog per step.
- Progress tracking shows users their progress through the tour.

## Installation

Install the tour package:

```bash
npm install @zag-js/tour @zag-js/react
# or
yarn add @zag-js/tour @zag-js/react
```

## Anatomy

Check the tour anatomy and part names.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

Import the tour package:

```tsx
import * as tour from "@zag-js/tour"
```

These are the key exports:

- `machine` - State machine logic.
- `connect` - Maps machine state to JSX props and event handlers.

Then use the framework integration helpers:

```tsx
import * as tour from "@zag-js/tour"
import { useMachine, normalizeProps, Portal } from "@zag-js/react"
import { useId } from "react"

function Tour() {
  const service = useMachine(tour.machine, { id: useId(), steps })
  const api = tour.connect(service, normalizeProps)
  return (
    <div>
      <div>
        <button onClick={() => api.start()}>Start Tour</button>
        <div id="step-1">Step 1</div>
      </div>
      {api.step && api.open && (
        <Portal>
          {api.step.backdrop && <div {...api.getBackdropProps()} />}
          <div {...api.getSpotlightProps()} />
          <div {...api.getPositionerProps()}>
            <div {...api.getContentProps()}>
              {api.step.arrow && (
                <div {...api.getArrowProps()}>
                  <div {...api.getArrowTipProps()} />
                </div>
              )}

              <p {...api.getTitleProps()}>{api.step.title}</p>
              <div {...api.getDescriptionProps()}>{api.step.description}</div>
              <div {...api.getProgressTextProps()}>{api.getProgressText()}</div>

              {api.step.actions && (
                <div>
                  {api.step.actions.map((action) => (
                    <button
                      key={action.label}
                      {...api.getActionTriggerProps({ action })}
                    >
                      {action.label}
                    </button>
                  ))}
                </div>
              )}

              <button {...api.getCloseTriggerProps()}>X</button>
            </div>
          </div>
        </Portal>
      )}
    </div>
  )
}

const steps: tour.StepDetails[] = [
  {
    type: "dialog",
    id: "start",
    title: "Ready to go for a ride",
    description: "Let's take the tour component for a ride and have some fun!",
    actions: [{ label: "Let's go!", action: "next" }],
  },
  {
    id: "logic",
    title: "Step 1",
    description: "This is the first step",
    target: () => document.querySelector("#step-1"),
    placement: "bottom",
    actions: [
      { label: "Prev", action: "prev" },
      { label: "Next", action: "next" },
    ],
  },
  {
    type: "dialog",
    id: "end",
    title: "Amazing! You got to the end",
    description: "Like what you see? Now go ahead and use it in your project.",
    actions: [{ label: "Finish", action: "dismiss" }],
  },
]
```

### Using step types

The tour machine supports different types of steps, allowing you to create a
diverse and interactive tour experience. The available step types are defined in
the `StepType` type:

- `"tooltip"`: Displays the step content as a tooltip, typically positioned near
  the target element.

- `"dialog"`: Shows the step content in a modal dialog centered on screen,
  useful for starting or ending the tour. This usually doesn't have a `target`
  defined.

- `"floating"`: Presents the step content as a floating element, which can be
  positioned flexibly on the screen. This usually doesn't have a `target`
  defined.

- `"wait"`: A special type that waits for a specific condition before proceeding
  to the next step.

```tsx
const steps: tour.StepDetails[] = [
  // Tooltip step
  {
    id: "step-1",
    type: "tooltip",
    placement: "top-start",
    target: () => document.querySelector("#target-1"),
    title: "Tooltip Step",
    description: "This is a tooltip step",
  },

  // Dialog step
  {
    id: "step-2",
    type: "dialog",
    title: "Dialog Step",
    description: "This is a dialog step",
  },

  // Floating step
  {
    id: "step-3",
    type: "floating",
    placement: "top-start",
    title: "Floating Step",
    description: "This is a floating step",
  },

  // Wait step
  {
    id: "step-4",
    type: "wait",
    title: "Wait Step",
    description: "This is a wait step",
    effect({ next }) {
      // do something and go next
      // you can also return a cleanup
    },
  },
]
```

### Configuring actions

Every step supports a list of actions that are rendered in the step footer. Use
the `actions` property to define each action.

```tsx
const steps: tour.StepDetails[] = [
  {
    id: "step-1",
    type: "dialog",
    title: "Dialog Step",
    description: "This is a dialog step",
    actions: [{ label: "Show me a tour!", action: "next" }],
  },
]
```

### Changing tooltip placement

Use the `placement` property to define the placement of the tooltip.

```tsx {5}
const steps: tour.StepDetails[] = [
  {
    id: "step-1",
    type: "tooltip",
    placement: "top-start",
    // ...
  },
]
```

### Hiding the arrow

Set `arrow: false` in the step property to hide the tooltip arrow. This is only
useful for tooltip steps.

```tsx {5}
const steps: tour.StepDetails[] = [
  {
    id: "step-1",
    type: "tooltip",
    arrow: false,
  },
]
```

### Hiding the backdrop

Set `backdrop: false` in the step property to hide the backdrop. This applies to
all step types except the `wait` step.

```tsx {5}
const steps: tour.StepDetails[] = [
  {
    id: "step-1",
    type: "dialog",
    backdrop: false,
  },
]
```

### Step Effects

Step effects are functions that are called before a step is opened. They are
useful for adding custom logic to a step.

This function provides the following methods:

- `next()`: Call this method to move to the next step.
- `goto(id)`: Jump to a specific step by id.
- `dismiss()`: Dismiss the tour immediately.
- `show()`: Call this method to show the current step.
- `update(details: Partial<StepBaseDetails>)`: Call this method to update the
  current step details (for example, after data is fetched).

```tsx
const steps: tour.StepDetails[] = [
  {
    id: "step-1",
    type: "tooltip",
    effect({ next, show, update }) {
      fetchData().then((res) => {
        // update the step details
        update({ title: res.title })
        // then show show the step
        show()
      })

      return () => {
        // cleanup fetch data
      }
    },
  },
]
```

### Wait Steps

Wait steps are useful when you need to wait for a specific condition before
proceeding to the next step.

Use the step `effect` function to perform an action and then call `next()` to
move to the next step.

> **Note:** You cannot call `show()` in a wait step.

```tsx
const steps: tour.StepDetails[] = [
  {
    id: "step-1",
    type: "wait",
    effect({ next }) {
      const button = document.querySelector("#button")
      const listener = () => next()
      button.addEventListener("click", listener)
      return () => button.removeEventListener("click", listener)
    },
  },
]
```

### Showing progress dots

Use the `api.getProgressPercent()` to show the progress dots.

```tsx
const ProgressBar = () => {
  const service = useMachine(tour.machine, { steps: [] })
  const api = tour.connect(service, normalizeProps)
  return <div>{api.getProgressPercent()}</div>
}
```

### Tracking the lifecycle

As the tour is progressed, events are fired and you can track the lifecycle of
the tour. Here's are the events you can listen to:

- `onStepChange`: Fires when the current step changes.
- `onStepsChange`: Fires when the steps array is updated.
- `onStatusChange`: Fires when the status of the tour changes.

```tsx
const Lifecycle = () => {
  const service = useMachine(tour.machine, {
    steps: [],
    onStepChange(details) {
      // => { stepId: "step-1", stepIndex: 0, totalSteps: 3, complete: false, progress: 0 }
      console.log(details)
    },
    onStepsChange(details) {
      // => { steps: StepDetails[] }
      console.log(details.steps)
    },
    onStatusChange(details) {
      // => { status: "started" | "skipped" | "completed" | "dismissed" | "not-found" }
      console.log(details.status)
    },
  })

  const api = tour.connect(service, normalizeProps)
  // ...
}
```

### Controlled current step

Use `stepId` and `onStepChange` for controlled navigation.

```tsx
const service = useMachine(tour.machine, {
  steps,
  stepId,
  onStepChange(details) {
    setStepId(details.stepId)
  },
})
```

### Programmatic tour control

Use the connected API to drive tour flow from code.

```tsx
api.start()
api.setStep("step-2")
api.next()
api.prev()
api.updateStep("step-2", { title: "Updated title" })
```

### Dismiss and interaction behavior

Configure dismissal and page interaction behavior with machine props.

```tsx
const service = useMachine(tour.machine, {
  closeOnEscape: false,
  closeOnInteractOutside: false,
  preventInteraction: true,
})
```

### Customizing progress text

Use `translations.progressText` to customize the progress message.

```tsx
const service = useMachine(tour.machine, {
  translations: {
    progressText: ({ current, total }) => `Step ${current} of ${total}`,
  },
})
```

## Styling guide

### Prerequisites

Ensure the `box-sizing` is set to `border-box` for the means of measuring the
tour target.

```css
* {
  box-sizing: border-box;
}
```

Ensure the `body` has a `position` of `relative`.

```css
body {
  position: relative;
}
```

### Overview

Each tour part has a `data-part` attribute that can be used to style them in the
DOM.

```css
[data-scope="tour"][data-part="content"] {
  /* styles for the content part */
}

[data-scope="tour"][data-part="positioner"] {
  /* styles for the positioner part */
}

[data-scope="tour"][data-part="arrow"] {
  /* styles for the arrow part */
}

[data-scope="tour"][data-part="title"] {
  /* styles for the title part */
}

[data-scope="tour"][data-part="description"] {
  /* styles for the description part */
}

[data-scope="tour"][data-part="progress-text"] {
  /* styles for the progress text part */
}

[data-scope="tour"][data-part="action-trigger"] {
  /* styles for the action trigger part */
}

[data-scope="tour"][data-part="backdrop"] {
  /* styles for the backdrop part */
}
```

### Step types

The tour component can render `tooltip`, `dialog`, or `floating` content. You
can apply specific styles based on the rendered type:

```css
[data-scope="tour"][data-part="content"][data-type="dialog"] {
  /* styles for content when step is dialog type */
}

[data-scope="tour"][data-part="content"][data-type="floating"] {
  /* styles for content when step is floating type */
}

[data-scope="tour"][data-part="content"][data-type="tooltip"] {
  /* styles for content when step is tooltip type */
}

[data-scope="tour"][data-part="positioner"][data-type="dialog"] {
  /* styles for positioner when step is dialog type */
}

[data-scope="tour"][data-part="positioner"][data-type="floating"] {
  /* styles for positioner when step is floating type */
}
```

### Placement Styles

For floating type tours, you can style based on the placement using the
`data-placement` attribute:

```css
[data-scope="tour"][data-part="positioner"][data-type="floating"][data-placement*="bottom"] {
  /* styles for bottom placement */
}

[data-scope="tour"][data-part="positioner"][data-type="floating"][data-placement*="top"] {
  /* styles for top placement */
}

[data-scope="tour"][data-part="positioner"][data-type="floating"][data-placement*="start"] {
  /* styles for start placement */
}

[data-scope="tour"][data-part="positioner"][data-type="floating"][data-placement*="end"] {
  /* styles for end placement */
}
```

## Methods and Properties

### Machine Context

The tour machine exposes the following context properties:

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the elements in the tour. Useful for composition.

**`steps`**
Type: `StepDetails[] | undefined`
Description: The steps of the tour

**`stepId`**
Type: `string | null | undefined`
Description: The id of the currently highlighted step

**`onStepChange`**
Type: `((details: StepChangeDetails) => void) | undefined`
Description: Callback when the highlighted step changes

**`onStepsChange`**
Type: `((details: StepsChangeDetails) => void) | undefined`
Description: Callback when the steps change

**`onStatusChange`**
Type: `((details: StatusChangeDetails) => void) | undefined`
Description: Callback when the tour is opened or closed

**`closeOnInteractOutside`**
Type: `boolean | undefined`
Description: Whether to close the tour when the user clicks outside the tour

**`closeOnEscape`**
Type: `boolean | undefined`
Description: Whether to close the tour when the user presses the escape key

**`keyboardNavigation`**
Type: `boolean | undefined`
Description: Whether to allow keyboard navigation (right/left arrow keys to navigate between steps)

**`preventInteraction`**
Type: `boolean | undefined`
Description: Prevents interaction with the rest of the page while the tour is open

**`spotlightOffset`**
Type: `Point | undefined`
Description: The offsets to apply to the spotlight

**`spotlightRadius`**
Type: `number | undefined`
Description: The radius of the spotlight clip path

**`translations`**
Type: `IntlTranslations | undefined`
Description: The translations for the tour

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

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

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

**`onPointerDownOutside`**
Type: `((event: PointerDownOutsideEvent) => void) | undefined`
Description: Function called when the pointer is pressed down outside the component

**`onFocusOutside`**
Type: `((event: FocusOutsideEvent) => void) | undefined`
Description: Function called when the focus is moved outside the component

**`onInteractOutside`**
Type: `((event: InteractOutsideEvent) => void) | undefined`
Description: Function called when an interaction happens outside the component

### Machine API

The tour `api` exposes the following methods:

**`open`**
Type: `boolean`
Description: Whether the tour is open

**`totalSteps`**
Type: `number`
Description: The total number of steps

**`stepIndex`**
Type: `number`
Description: The index of the current step

**`step`**
Type: `StepDetails | null`
Description: The current step details

**`hasNextStep`**
Type: `boolean`
Description: Whether there is a next step

**`hasPrevStep`**
Type: `boolean`
Description: Whether there is a previous step

**`firstStep`**
Type: `boolean`
Description: Whether the current step is the first step

**`lastStep`**
Type: `boolean`
Description: Whether the current step is the last step

**`addStep`**
Type: `(step: StepDetails) => void`
Description: Add a new step to the tour

**`removeStep`**
Type: `(id: string) => void`
Description: Remove a step from the tour

**`updateStep`**
Type: `(id: string, stepOverrides: Partial<StepDetails>) => void`
Description: Update a step in the tour with partial details

**`setSteps`**
Type: `(steps: StepDetails[]) => void`
Description: Set the steps of the tour

**`setStep`**
Type: `(id: string) => void`
Description: Set the current step of the tour

**`start`**
Type: `(id?: string) => void`
Description: Start the tour at a specific step (or the first step if not provided)

**`isValidStep`**
Type: `(id: string) => boolean`
Description: Check if a step is valid

**`isCurrentStep`**
Type: `(id: string) => boolean`
Description: Check if a step is visible

**`next`**
Type: `VoidFunction`
Description: Move to the next step

**`prev`**
Type: `VoidFunction`
Description: Move to the previous step

**`getProgressText`**
Type: `() => string`
Description: Returns the progress text

**`getProgressPercent`**
Type: `() => number`
Description: Returns the progress percent

The TreeView component provides a hierarchical view of data, similar to a file
system explorer. It allows users to expand and collapse branches, select
individual or multiple nodes, and traverse the hierarchy using keyboard
navigation.

## Resources


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



**Features**

- Display hierarchical data in a tree structure
- Expand or collapse nodes
- Supports keyboard navigation
- Select single or multiple nodes (depending on the selection mode)
- Perform actions on the nodes, such as deleting them or performing some other
  operation

## Installation

Install the tree view package:

```bash
npm install @zag-js/tree-view @zag-js/react
# or
yarn add @zag-js/tree-view @zag-js/react
```

## Anatomy

Check the tree view anatomy and part names.



## Usage

Import the tree view package:

```tsx
import * as tree from "@zag-js/tree-view"
```

The tree view 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:

### Create the tree collection

Use the `collection` function to create a tree collection. This creates a tree
factory that the component uses for traversal.

```ts
import * as tree from "@zag-js/tree-view"

interface Node {
  id: string
  name: string
  children?: Node[]
}

const collection = tree.collection<Node>({
  nodeToValue: (node) => node.id,
  nodeToString: (node) => node.name,
  rootNode: {
    id: "ROOT",
    name: "",
    children: [
      {
        id: "node_modules",
        name: "node_modules",
        children: [
          { id: "node_modules/zag-js", name: "zag-js" },
          { id: "node_modules/pandacss", name: "panda" },
          {
            id: "node_modules/@types",
            name: "@types",
            children: [
              { id: "node_modules/@types/react", name: "react" },
              { id: "node_modules/@types/react-dom", name: "react-dom" },
            ],
          },
        ],
      },
    ],
  },
})
```

### Create the tree view

Pass the tree collection to the machine to create the tree view.

```tsx
import { normalizeProps, useMachine } from "@zag-js/react"
import * as tree from "@zag-js/tree-view"
import { FileIcon, FolderIcon, ChevronRightIcon } from "lucide-react"
import { useId } from "react"

// 1. Create the tree collection

interface Node {
  id: string
  name: string
  children?: Node[]
}

const collection = tree.collection<Node>({
  // ...
})

// 2. Create the recursive tree node

interface TreeNodeProps {
  node: Node
  indexPath: number[]
  api: tree.Api
}

const TreeNode = (props: TreeNodeProps): JSX.Element => {
  const { node, indexPath, api } = props

  const nodeProps = { indexPath, node }
  const nodeState = api.getNodeState(nodeProps)

  if (nodeState.isBranch) {
    return (
      <div {...api.getBranchProps(nodeProps)}>
        <div {...api.getBranchControlProps(nodeProps)}>
          <FolderIcon />
          <span {...api.getBranchTextProps(nodeProps)}>{node.name}</span>
          <span {...api.getBranchIndicatorProps(nodeProps)}>
            <ChevronRightIcon />
          </span>
        </div>
        <div {...api.getBranchContentProps(nodeProps)}>
          <div {...api.getBranchIndentGuideProps(nodeProps)} />
          {node.children?.map((childNode, index) => (
            <TreeNode
              key={childNode.id}
              node={childNode}
              indexPath={[...indexPath, index]}
              api={api}
            />
          ))}
        </div>
      </div>
    )
  }

  return (
    <div {...api.getItemProps(nodeProps)}>
      <FileIcon /> {node.name}
    </div>
  )
}

// 3. Create the tree view

export function TreeView() {
  const service = useMachine(tree.machine, { id: useId(), collection })
  const api = tree.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <h3 {...api.getLabelProps()}>My Documents</h3>
      <div {...api.getTreeProps()}>
        {collection.rootNode.children?.map((node, index) => (
          <TreeNode key={node.id} node={node} indexPath={[index]} api={api} />
        ))}
      </div>
    </div>
  )
}
```

### Expanding and Collapsing Nodes

By default, the tree view will expand or collapse when clicking the branch
control. To control the expanded state of the tree view, use the `api.expand`
and `api.collapse` methods.

> **Note:** The array parameter contains individual node values/IDs, not paths.
> All nodes specified in the array will be collapsed or expanded.

```tsx
api.expand(["node_modules/zag-js"]) // expand a single node by its value/ID
api.expand(["node_modules/zag-js", "node_modules/pandacss"]) // expand multiple nodes by their values/IDs
api.expand() // expand all nodes

api.collapse(["node_modules/@types"]) // collapse a single node by its value/ID
api.collapse(["node_modules/@types", "node_modules/pandacss"]) // collapse multiple nodes by their values/IDs
api.collapse() // collapse all nodes
```

### Multiple selection

The tree view supports multiple selection. To enable this, set the
`selectionMode` to `multiple`.

```tsx {2}
const service = useMachine(tree.machine, {
  selectionMode: "multiple",
})
```

### Setting the default expanded nodes

To set the default expanded nodes, use `defaultExpandedValue`.

```tsx {2}
const service = useMachine(tree.machine, {
  defaultExpandedValue: ["node_modules/pandacss"],
})
```

### Setting the default selected nodes

To set the default selected nodes, use `defaultSelectedValue`.

```tsx {2}
const service = useMachine(tree.machine, {
  defaultSelectedValue: ["node_modules/pandacss"],
})
```

### Controlled expanded and selected values

Use controlled props when expansion or selection is managed externally.

```tsx
const service = useMachine(tree.machine, {
  collection,
  expandedValue,
  selectedValue,
  onExpandedChange(details) {
    setExpandedValue(details.expandedValue)
  },
  onSelectionChange(details) {
    setSelectedValue(details.selectedValue)
  },
})
```

### Indentation Guide

When rendering a branch node in the tree view, you can render the `indentGuide`
element by using the `api.getBranchIndentGuideProps()` function.

```tsx {9}
<div {...api.getBranchProps(nodeProps)}>
  <div {...api.getBranchControlProps(nodeProps)}>
    <FolderIcon />
    {node.name}
    <span {...api.getBranchIndicatorProps(nodeProps)}>
      <ChevronRightIcon />
    </span>
  </div>
  <div {...api.getBranchContentProps(nodeProps)}>
    <div {...api.getBranchIndentGuideProps(nodeProps)} />
    {node.children.map((childNode, index) => (
      <TreeNode
        key={childNode.id}
        node={childNode}
        indexPath={[...indexPath, index]}
        api={api}
      />
    ))}
  </div>
</div>
```

### Listening for selection

When a node is selected, the `onSelectionChange` callback is invoked with the
selected nodes.

```tsx {2-5}
const service = useMachine(tree.machine, {
  onSelectionChange(details) {
    // details => { focusedValue, selectedValue, selectedNodes }
    console.log("selected nodes:", details.selectedNodes)
  },
})
```

### Listening for expanding and collapsing

When a node is expanded or collapsed, the `onExpandedChange` callback is invoked
with the expanded nodes.

```tsx {2-5}
const service = useMachine(tree.machine, {
  onExpandedChange(details) {
    // details => { focusedValue, expandedValue, expandedNodes }
    console.log("expanded nodes:", details.expandedNodes)
  },
})
```

### Listening for focus and checked changes

Use `onFocusChange` and `onCheckedChange` when you need focus/checkbox state.

```tsx
const service = useMachine(tree.machine, {
  onFocusChange(details) {
    // details => { focusedValue, focusedNode }
    console.log(details.focusedValue)
  },
  onCheckedChange(details) {
    // details => { checkedValue: string[] }
    console.log(details.checkedValue)
  },
})
```

### Programmatic tree control

Use the connected API for imperative interactions.

```tsx
api.expand(["node_modules"])
api.collapse(["node_modules/@types"])
api.select(["node_modules/pandacss"])
api.deselect(["node_modules/pandacss"])
api.focus("node_modules")
api.toggleChecked("node_modules", true)
```

### Controlling branch click behavior

Set `expandOnClick` to control whether clicking a branch toggles expansion.

```tsx
const service = useMachine(tree.machine, {
  collection,
  expandOnClick: false,
})
```

### Controlling typeahead

Set `typeahead` to disable keyboard typeahead matching.

```tsx
const service = useMachine(tree.machine, {
  collection,
  typeahead: false,
})
```

### Lazy Loading

> **Added in v1.15.0**

Lazy loading is a feature that allows the tree view to load children of a node
on demand. This helps to improve the initial load time and memory usage.

To use this, you need to provide the following:

- `loadChildren` — A function that is used to load the children of a node.
- `onLoadChildrenComplete` — A callback that is called when the children of a
  node are loaded. Used to update the tree collection.
- `onLoadChildrenError` — A callback that is called when loading fails.
- `childrenCount` — A number that indicates the number of children of a branch
  node.

```tsx
function TreeAsync() {
  const [collection, setCollection] = useState(
    tree.collection({
      nodeToValue: (node) => node.id,
      nodeToString: (node) => node.name,
      rootNode: {
        id: "ROOT",
        name: "",
        children: [
          { id: "node_modules", name: "node_modules", childrenCount: 3 },
          { id: "src", name: "src", childrenCount: 2 },
        ],
      },
    }),
  )

  const service = useMachine(tree.machine, {
    id: useId(),
    collection,
    async loadChildren({ valuePath, signal }) {
      const url = `/api/file-system/${valuePath.join("/")}`
      const response = await fetch(url, { signal })
      const data = await response.json()
      return data.children
    },
    onLoadChildrenComplete({ collection }) {
      setCollection(collection)
    },
    onLoadChildrenError({ nodes }) {
      console.error("Failed to load:", nodes)
    },
  })

  // ...
}
```

### Renaming Nodes

The tree view supports renaming node labels inline, perfect for file explorers,
content management systems, and other applications where users need to edit item
names.

To enable renaming:

1. Add the rename input to your tree node component
2. Handle the `onRenameComplete` callback to update your collection

```tsx
import { normalizeProps, useMachine } from "@zag-js/react"
import * as tree from "@zag-js/tree-view"
import { FileIcon, FolderIcon, ChevronRightIcon } from "lucide-react"
import { useId, useState } from "react"

// 1. Create the tree collection with state

interface Node {
  id: string
  name: string
  children?: Node[]
}

const initialCollection = tree.collection<Node>({
  nodeToValue: (node) => node.id,
  nodeToString: (node) => node.name,
  rootNode: {
    id: "ROOT",
    name: "",
    children: [
      { id: "README.md", name: "README.md" },
      { id: "package.json", name: "package.json" },
    ],
  },
})

// 2. Create the tree node with rename input

interface TreeNodeProps {
  node: Node
  indexPath: number[]
  api: tree.Api
}

const TreeNode = (props: TreeNodeProps): JSX.Element => {
  const { node, indexPath, api } = props

  const nodeProps = { indexPath, node }
  const nodeState = api.getNodeState(nodeProps)

  if (nodeState.isBranch) {
    return (
      <div {...api.getBranchProps(nodeProps)}>
        <div {...api.getBranchControlProps(nodeProps)}>
          <FolderIcon />
          <span
            {...api.getBranchTextProps(nodeProps)}
            style={{ display: nodeState.renaming ? "none" : "inline" }}
          >
            {node.name}
          </span>
          <input {...api.getNodeRenameInputProps(nodeProps)} />
          <span {...api.getBranchIndicatorProps(nodeProps)}>
            <ChevronRightIcon />
          </span>
        </div>
        <div {...api.getBranchContentProps(nodeProps)}>
          <div {...api.getBranchIndentGuideProps(nodeProps)} />
          {node.children?.map((childNode, index) => (
            <TreeNode
              key={childNode.id}
              node={childNode}
              indexPath={[...indexPath, index]}
              api={api}
            />
          ))}
        </div>
      </div>
    )
  }

  return (
    <div {...api.getItemProps(nodeProps)}>
      <FileIcon />
      <span
        {...api.getItemTextProps(nodeProps)}
        style={{ display: nodeState.renaming ? "none" : "inline" }}
      >
        {node.name}
      </span>
      <input {...api.getNodeRenameInputProps(nodeProps)} />
    </div>
  )
}

// 3. Setup rename handlers

export function TreeView() {
  const [collection, setCollection] = useState(initialCollection)

  const service = useMachine(tree.machine, {
    id: useId(),
    collection,
    onRenameComplete: (details) => {
      // Update the collection with the new label
      const node = collection.at(details.indexPath)
      const updatedCollection = collection.replace(details.indexPath, {
        ...node,
        name: details.label,
      })
      setCollection(updatedCollection)
    },
  })

  const api = tree.connect(service, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <h3 {...api.getLabelProps()}>My Documents</h3>
      <p>Press F2 to rename any file or folder</p>
      <div {...api.getTreeProps()}>
        {collection.rootNode.children?.map((node, index) => (
          <TreeNode key={node.id} node={node} indexPath={[index]} api={api} />
        ))}
      </div>
    </div>
  )
}
```

### Controlling which nodes can be renamed

Use the `canRename` callback to control which nodes are renameable based on node
type or custom logic.

```tsx {3-6}
const service = useMachine(tree.machine, {
  collection,
  canRename(node, indexPath) {
    // Only allow renaming leaf nodes (files), not branches (folders)
    return !node.children
  },
})
```

### Validating rename input

Use the `onBeforeRename` callback to validate the new name before accepting the
change. Return `false` to reject the rename.

```tsx {3-14}
const service = useMachine(tree.machine, {
  collection,
  onBeforeRename(details) {
    // Prevent empty names (label is already trimmed)
    if (!details.label) return false

    // Prevent duplicate names
    const parent = getParentNode(details.indexPath)
    const hasDuplicate = parent.children.some(
      (child) => child.name === details.label && child.id !== details.value,
    )
    return !hasDuplicate
  },
})
```

### Tracking rename events

Use the `onRenameStart` callback to track when users start renaming, useful for
analytics or showing contextual hints.

```tsx {3-6}
const service = useMachine(tree.machine, {
  collection,
  onRenameStart(details) {
    console.log("Started renaming:", details.node.name)
    trackEvent("tree_rename_started")
  },
})
```

**Features:**

- Press `F2` to enter rename mode
- Press `Enter` to submit or `Escape` to cancel
- Blur automatically submits changes
- Empty or whitespace-only names are automatically rejected
- Labels are automatically trimmed before callbacks
- IME composition events are properly handled
- `data-renaming` attribute added for styling

## Styling guide

### Checked state

When using checkbox selection (`onCheckedChange`), item and branch control
elements expose `data-checked` and `data-indeterminate` attributes for styling.

```css
[data-part="item"][data-checked] {
  /* styles for fully checked items */
}

[data-part="item"][data-indeterminate] {
  /* styles for partially checked items (some children selected) */
}

[data-part="branch-control"][data-checked] {
  /* styles for fully checked branches */
}

[data-part="branch-control"][data-indeterminate] {
  /* styles for partially checked branches */
}
```

## Methods and Properties

### Machine Context

The tree view machine exposes the following context properties:

**`translations`**
Type: `IntlTranslations | undefined`
Description: Specifies the localized strings that identifies the accessibility elements and their states

**`collection`**
Type: `TreeCollection<T> | undefined`
Description: The tree collection data

**`ids`**
Type: `ElementIds | undefined`
Description: The ids of the tree elements. Useful for composition.

**`expandedValue`**
Type: `string[] | undefined`
Description: The controlled expanded node ids

**`defaultExpandedValue`**
Type: `string[] | undefined`
Description: The initial expanded node ids when rendered.
Use when you don't need to control the expanded node value.

**`selectedValue`**
Type: `string[] | undefined`
Description: The controlled selected node value

**`defaultSelectedValue`**
Type: `string[] | undefined`
Description: The initial selected node value when rendered.
Use when you don't need to control the selected node value.

**`defaultCheckedValue`**
Type: `string[] | undefined`
Description: The initial checked node value when rendered.
Use when you don't need to control the checked node value.

**`checkedValue`**
Type: `string[] | undefined`
Description: The controlled checked node value

**`defaultFocusedValue`**
Type: `string | null | undefined`
Description: The initial focused node value when rendered.
Use when you don't need to control the focused node value.

**`focusedValue`**
Type: `string | null | undefined`
Description: The value of the focused node

**`selectionMode`**
Type: `"single" | "multiple" | undefined`
Description: Whether the tree supports multiple selection
- "single": only one node can be selected
- "multiple": multiple nodes can be selected

**`onExpandedChange`**
Type: `((details: ExpandedChangeDetails<T>) => void) | undefined`
Description: Called when the tree is opened or closed

**`onSelectionChange`**
Type: `((details: SelectionChangeDetails<T>) => void) | undefined`
Description: Called when the selection changes

**`onFocusChange`**
Type: `((details: FocusChangeDetails<T>) => void) | undefined`
Description: Called when the focused node changes

**`onCheckedChange`**
Type: `((details: CheckedChangeDetails) => void) | undefined`
Description: Called when the checked value changes

**`canRename`**
Type: `((node: T, indexPath: IndexPath) => boolean) | undefined`
Description: Function to determine if a node can be renamed

**`onRenameStart`**
Type: `((details: RenameStartDetails<T>) => void) | undefined`
Description: Called when a node starts being renamed

**`onBeforeRename`**
Type: `((details: RenameCompleteDetails) => boolean) | undefined`
Description: Called before a rename is completed. Return false to prevent the rename.

**`onRenameComplete`**
Type: `((details: RenameCompleteDetails) => void) | undefined`
Description: Called when a node label rename is completed

**`onLoadChildrenComplete`**
Type: `((details: LoadChildrenCompleteDetails<T>) => void) | undefined`
Description: Called when a node finishes loading children

**`onLoadChildrenError`**
Type: `((details: LoadChildrenErrorDetails<T>) => void) | undefined`
Description: Called when loading children fails for one or more nodes

**`expandOnClick`**
Type: `boolean | undefined`
Description: Whether clicking on a branch should open it or not

**`typeahead`**
Type: `boolean | undefined`
Description: Whether the tree supports typeahead search

**`loadChildren`**
Type: `((details: LoadChildrenDetails<T>) => Promise<T[]>) | undefined`
Description: Function to load children for a node asynchronously.
When provided, branches will wait for this promise to resolve before expanding.

**`scrollToIndexFn`**
Type: `((details: ScrollToIndexDetails<T>) => void) | undefined`
Description: Function to scroll to a specific index.
Useful for virtualized tree views.

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

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

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

### Machine API

The tree view `api` exposes the following methods:

**`collection`**
Type: `TreeCollection<V>`
Description: The tree collection data

**`expandedValue`**
Type: `string[]`
Description: The value of the expanded nodes.

**`setExpandedValue`**
Type: `(value: string[]) => void`
Description: Sets the expanded value

**`selectedValue`**
Type: `string[]`
Description: The value of the selected nodes.

**`setSelectedValue`**
Type: `(value: string[]) => void`
Description: Sets the selected value

**`checkedValue`**
Type: `string[]`
Description: The value of the checked nodes

**`toggleChecked`**
Type: `(value: string, isBranch: boolean) => void`
Description: Toggles the checked value of a node

**`setChecked`**
Type: `(value: string[]) => void`
Description: Sets the checked value of a node

**`clearChecked`**
Type: `VoidFunction`
Description: Clears the checked value of a node

**`getCheckedMap`**
Type: `() => CheckedValueMap`
Description: Returns the checked details of branch and leaf nodes

**`getVisibleNodes`**
Type: `() => VisibleNode<V>[]`
Description: Returns the visible nodes as a flat array of nodes and their index path.
Useful for rendering virtualized tree views.

**`expand`**
Type: `(value?: string[]) => void`
Description: Function to expand nodes.
If no value is provided, all nodes will be expanded

**`collapse`**
Type: `(value?: string[]) => void`
Description: Function to collapse nodes
If no value is provided, all nodes will be collapsed

**`select`**
Type: `(value?: string[]) => void`
Description: Function to select nodes
If no value is provided, all nodes will be selected

**`deselect`**
Type: `(value?: string[]) => void`
Description: Function to deselect nodes
If no value is provided, all nodes will be deselected

**`focus`**
Type: `(value: string) => void`
Description: Function to focus a node by value

**`selectParent`**
Type: `(value: string) => void`
Description: Function to select the parent node of the focused node

**`expandParent`**
Type: `(value: string) => void`
Description: Function to expand the parent node of the focused node

**`startRenaming`**
Type: `(value: string) => void`
Description: Function to start renaming a node by value

**`submitRenaming`**
Type: `(value: string, label: string) => void`
Description: Function to submit the rename and update the node label

**`cancelRenaming`**
Type: `() => void`
Description: Function to cancel renaming without changes

**`getNodeState`**
Type: `(props: NodeProps) => NodeState`
Description: Returns the state of a node including whether it's selected, expanded,
focused, disabled, checked, loading, renaming, and its depth/path info.

### Data Attributes

**`Tree`**

**`data-tree-view-tree`**: <uid>
**`data-branch`**: 

**`NodeGroup`**

**`data-tree-view-node-group`**: <uid>
**`data-depth`**: The depth of the item
**`data-value`**: The value of the item
**`data-path`**: The path of the item
**`data-state`**: "open" | "closed"
**`data-disabled`**: Present when disabled
**`data-loading`**: Present when loading

**`Node`**

**`data-tree-view-node`**: <uid>
**`data-path`**: The path of the item
**`data-value`**: The value of the item
**`data-focus`**: Present when focused
**`data-selected`**: Present when selected
**`data-state`**: "open" | "closed"
**`data-disabled`**: Present when disabled
**`data-renaming`**: 
**`data-checked`**: Present when checked
**`data-indeterminate`**: 
**`data-depth`**: The depth of the item
**`data-loading`**: Present when loading
**`data-branch`**: 

**`NodeExpandTrigger`**

**`data-tree-view-node-expand-trigger`**: <uid>
**`data-disabled`**: Present when disabled
**`data-state`**: "open" | "closed"
**`data-value`**: The value of the item
**`data-loading`**: Present when loading

**`NodeText`**

**`data-tree-view-node-text`**: <uid>
**`data-disabled`**: Present when disabled
**`data-selected`**: Present when selected
**`data-focus`**: Present when focused
**`data-state`**: "open" | "closed"
**`data-loading`**: Present when loading

**`NodeIndicator`**

**`data-tree-view-node-indicator`**: <uid>
**`data-type`**: The type of the item
**`data-state`**: "expanded" | "open" | "closed"
**`data-disabled`**: Present when disabled
**`data-selected`**: Present when selected
**`data-focus`**: Present when focused
**`data-loading`**: Present when loading

**`NodeGroupContent`**

**`data-tree-view-node-group-content`**: <uid>
**`data-state`**: "open" | "closed"
**`data-depth`**: The depth of the item
**`data-path`**: The path of the item
**`data-value`**: The value of the item

**`IndentGuide`**

**`data-tree-view-indent-guide`**: <uid>
**`data-depth`**: The depth of the item

**`NodeCheckbox`**

**`data-tree-view-node-checkbox`**: <uid>
**`data-state`**: "checked" | "unchecked" | "indeterminate"
**`data-disabled`**: Present when disabled

**`NodeCell`**

**`data-tree-view-node-cell`**: <uid>
**`data-value`**: The value of the item

### CSS Variables

<CssVarTable name="tree-view" />

## Accessibility

Adheres to the
[Tree View WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/treeview).

### Keyboard Interactions

**`Tab`**
Description: Moves focus to the tree view, placing the first tree view item in focus.

**`Enter + Space`**
Description: Selects the item or branch node

**`ArrowDown`**
Description: Moves focus to the next node

**`ArrowUp`**
Description: Moves focus to the previous node

**`ArrowRight`**
Description: When focus is on a closed branch node, opens the branch.<br> When focus is on an open branch node, moves focus to the first item node.

**`ArrowLeft`**
Description: When focus is on an open branch node, closes the node.<br> When focus is on an item or branch node, moves focus to its parent branch node.

**`Home`**
Description: Moves focus to first node without opening or closing a node.

**`End`**
Description: Moves focus to the last node that can be focused without expanding any nodes that are closed.

**`a-z + A-Z`**
Description: Focus moves to the next node with a name that starts with the typed character. The search logic ignores nodes that are descendants of closed branch.

**`*`**
Description: Expands all sibling nodes that are at the same depth as the focused node.

**`Shift + ArrowDown`**
Description: Moves focus to and toggles the selection state of the next node.

**`Shift + ArrowUp`**
Description: Moves focus to and toggles the selection state of the previous node.

**`Ctrl + A`**
Description: Selects all nodes in the tree. If all nodes are selected, unselects all nodes.