Dialog Title
Dialog Description
{data.map((item, index) => (
))}
)
}
export default function App() {
return (
{item.content}
ZagJs in Iframe
{data.map((item) => (
))}
)
}
```
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 accordions at once
To allow multiple items to be expanded at once, set `multiple` to `true`. This
mode implicitly sets `collapsible` to `true` and ensures that each accordion can
be expanded.
```jsx {2}
const service = useMachine(accordion.machine, {
multiple: true,
})
```
## Opening specific accordions
To set the value of the accordion(s) that should be opened initially, pass the
`value` property to the machine function.
```jsx {3,4,9}
// for multiple accordions
const service = useMachine(accordion.machine, {
multiple: true,
defaultValue: ["home"],
})
// for single accordions
const service = useMachine(accordion.machine, {
defaultValue: ["home"],
})
```
## Toggle each accordion item
To collapse an already expanded accordion item by clicking on it, set the
context's `collapsible` property to `true`.
> Note: If `multiple` is `true`, we internally set `collapsible` to be `true`.
```jsx {2}
const service = useMachine(accordion.machine, {
collapsible: true,
})
```
## Listening for changes
When the accordion value changes, the `onValueChange` callback is invoked.
```jsx {2-5}
const service = useMachine(accordion.machine, {
onValueChange(details) {
// details => { value: string[] }
console.log("selected accordion:", details.value)
},
})
```
## 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.
```jsx
//...
{item.content}
Content
{localProps.items.map((item) => (
))}
)
}
```
## 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: `Partial<{ root: string; item(value: string): string; itemContent(value: string): string; itemTrigger(value: string): string; }>`
Description: The ids of the elements in the accordion. Useful for composition.
**`multiple`**
Type: `boolean`
Description: Whether multiple accordion items can be expanded at the same time.
**`collapsible`**
Type: `boolean`
Description: Whether an accordion item can be closed after it has been expanded.
**`value`**
Type: `string[]`
Description: The controlled value of the expanded accordion items.
**`defaultValue`**
Type: `string[]`
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`
Description: Whether the accordion items are disabled
**`onValueChange`**
Type: `(details: ValueChangeDetails) => void`
Description: The callback fired when the state of expanded/collapsed accordion items changes.
**`onFocusChange`**
Type: `(details: FocusChangeDetails) => void`
Description: The callback fired when the focused accordion item changes.
**`orientation`**
Type: `"horizontal" | "vertical"`
Description: The orientation of the accordion items.
**`dir`**
Type: `"ltr" | "rtl"`
Description: The document's text/writing direction.
**`id`**
Type: `string`
Description: The unique identifier of the machine.
**`getRootNode`**
Type: `() => ShadowRoot | Node | Document`
Description: A root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.
### Machine API
The accordion `api` exposes the following methods:
**`focusedValue`**
Type: `string`
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: Gets the state of an accordion item.
### Data Attributes
**`Root`**
**`data-scope`**: accordion
**`data-part`**: root
**`data-orientation`**: The orientation of the accordion
**`Item`**
**`data-scope`**: accordion
**`data-part`**: item
**`data-state`**: "open" | "closed"
**`data-focus`**: Present when focused
**`data-disabled`**: Present when disabled
**`data-orientation`**: The orientation of the item
**`ItemContent`**
**`data-scope`**: accordion
**`data-part`**: item-content
**`data-state`**: "open" | "closed"
**`data-disabled`**: Present when disabled
**`data-focus`**: Present when focused
**`data-orientation`**: The orientation of the item
**`ItemIndicator`**
**`data-scope`**: accordion
**`data-part`**: item-indicator
**`data-state`**: "open" | "closed"
**`data-disabled`**: Present when disabled
**`data-focus`**: Present when focused
**`data-orientation`**: The orientation of the item
**`ItemTrigger`**
**`data-scope`**: accordion
**`data-part`**: item-trigger
**`data-orientation`**: The orientation of the item
**`data-state`**: "open" | "closed"
## 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.
# Angle Slider
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: v1.7.0](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 track to update value.
- Supports Right-to-Left directionality.
## Installation
To use the angle slider machine in your project, run the following command in
your command line:
```bash
npm install @zag-js/angle-slider @zag-js/react
# or
yarn add @zag-js/angle-slider @zag-js/react
```
This command will install the framework agnostic angle slider logic and the
reactive utilities for your framework of choice.
## 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
First, import the angle-slider package into your project
```jsx
import * as angleSlider from "@zag-js/angle-slider"
```
The angle slider package exports two key functions:
- `machine` — The state machine logic for the angle slider widget as described
in the WAI-ARIA spec.
- `connect` — The function that translates the machine's state to JSX attributes
and event handlers.
> You'll need to provide a unique `id` to the `useMachine` hook. This is used to
> ensure that every part has a unique identifier.
Next, import the required hooks and functions for your framework and use the
angle slider machine in your project 🔥
```jsx
import * as angleSlider from "@zag-js/angle-slider"
import { normalizeProps, useMachine } from "@zag-js/react"
export function AngleSlider() {
const service = useMachine(angleSlider.machine, { id: "1" })
const api = angleSlider.connect(service, normalizeProps)
return (
{item.content}
{[0, 45, 90, 135, 180, 225, 270, 315].map((value) => (
))}
{api.value} degrees
{[0, 45, 90, 135, 180, 225, 270, 315].map((value) => (
))}
{api.value} degrees
PA
)
}
```
## Listening for loading status changes
When the image has loaded or failed to load, the `onStatusChange` callback is
invoked.
```jsx {2}
const service = useMachine(avatar.machine, {
onStatusChange(details) {
// details => { status: "error" | "loaded" }
},
})
```
## Styling guide
Earlier, we mentioned that each avatar part has a `data-part` attribute added to
them to select and style them in the DOM.
```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 Component
Create your avatar component by abstracting the machine into your own component.
### Usage
```tsx
import { Avatar } from "./your-avatar"
function Demo() {
return (
{getInitials(localProps.name)}
)
}
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`
Description: Functional called when the image loading status changes.
**`ids`**
Type: `Partial<{ root: string; image: string; fallback: string; }>`
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 | Node | Document`
Description: A root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.
**`dir`**
Type: `"ltr" | "rtl"`
Description: The document's text/writing direction.
### Machine API
The avatar `api` exposes the following methods:
**`loaded`**
Type: `boolean`
Description: Whether the image is loaded.
**`setSrc`**
Type: `(src: string) => void`
Description: Function to set new src.
**`setLoaded`**
Type: `() => void`
Description: Function to set loaded state.
**`setError`**
Type: `() => void`
Description: Function to set error state.
### Data Attributes
**`Image`**
**`data-scope`**: avatar
**`data-part`**: image
**`data-state`**: "visible" | "hidden"
**`Fallback`**
**`data-scope`**: avatar
**`data-part`**: fallback
**`data-state`**: "hidden" | "visible"
# Carousel
an accessible carousel component that leverages native CSS Scroll Snap for
smooth, performant scrolling between slides.
## Resources
[Latest version: v1.7.0](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 alignment of slides (start, center or end alignment).
- Show multiple slides at a time.
- Supports looping and auto-playing.
- Supports custom spacing between slides.
## Installation
To use the carousel machine in your project, run the following command in your
command line:
```bash
npm install @zag-js/carousel @zag-js/react
# or
yarn add @zag-js/carousel @zag-js/react
```
This command will install the framework agnostic carousel logic and the reactive
utilities for your framework of choice.
## Anatomy
To set up the carousel correctly, you'll need to understand its anatomy and how
we name its parts.
> Each part includes a `data-part` attribute to help identify them in the DOM.
## Usage
First, import the carousel package into your project
```jsx
import * as carousel from "@zag-js/carousel"
```
The carousel package exports two key functions:
- `machine` — The state machine logic for the carousel widget.
- `connect` — The function that translates the machine's state to JSX attributes
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.
Next, import the required hooks and functions for your framework and use the
carousel machine in your project 🔥
> **Note:** The carousel requires that you provide a `slideCount` property in
> the machine's context. This is the number of slides in the carousel.
```jsx
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",
slideCount: items.length,
})
const api = carousel.connect(service, normalizeProps)
return (
{items.map((image, index) => (
))}
{api.pageSnapPoints.map((_, index) => (
))}
Collape Content
{/* ... */}
)
}
```
## Disabling the color picker
To disable user interactions with the color picker, set the `disabled` context
property to `true`.
```jsx
const [current, send] = useMachine(colorPicker.machine, {
disabled: true,
})
```
## Controlling the open and closed state
To control the open and closed state of the color picker, use the `open` and
`onOpenChange` context properties.
```jsx
const [current, send] = useMachine(colorPicker.machine, {
open: true,
onOpenChange: (details) => {
// details => { open: boolean }
},
})
```
You can also leverage the `api.setOpen(...)` method to control the open and
closed state of the color picker.
## 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 (
{presets.map((preset) => (
))}
{/* ... */}
)
}
```
## 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 the `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 (
{api.format === "rgba" && (
)}
R
G
B
A
{/* ... */}
)
}
```
## Usage within forms
To use the color picker within a form, add the `name` context property to the
machine and render the visually hidden input using the `hiddenInputProps`.
```jsx {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: `Partial<{ root: string; control: string; trigger: string; label: string; input: string; hiddenInput: string; content: string; area: string; areaGradient: string; positioner: string; formatSelect: string; areaThumb: string; channelInput(id: string): string; channelSliderTrack(id: ColorChannel): string; }>`
Description: The ids of the elements in the color picker. Useful for composition.
**`value`**
Type: `Color`
Description: The controlled color value of the color picker
**`defaultValue`**
Type: `Color`
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`
Description: Whether the color picker is disabled
**`readOnly`**
Type: `boolean`
Description: Whether the color picker is read-only
**`required`**
Type: `boolean`
Description: Whether the color picker is required
**`invalid`**
Type: `boolean`
Description: Whether the color picker is invalid
**`onValueChange`**
Type: `(details: ValueChangeDetails) => void`
Description: Handler that is called when the value changes, as the user drags.
**`onValueChangeEnd`**
Type: `(details: ValueChangeDetails) => void`
Description: Handler that is called when the user stops dragging.
**`onOpenChange`**
Type: `(details: OpenChangeDetails) => void`
Description: Handler that is called when the user opens or closes the color picker.
**`name`**
Type: `string`
Description: The name for the form input
**`positioning`**
Type: `PositioningOptions`
Description: The positioning options for the color picker
**`initialFocusEl`**
Type: `() => HTMLElement`
Description: The initial focus element when the color picker is opened.
**`open`**
Type: `boolean`
Description: The controlled open state of the color picker
**`defaultOpen`**
Type: `boolean`
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`
Description: The controlled color format to use
**`defaultFormat`**
Type: `ColorFormat`
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`
Description: Function called when the color format changes
**`closeOnSelect`**
Type: `boolean`
Description: Whether to close the color picker when a swatch is selected
**`openAutoFocus`**
Type: `boolean`
Description: Whether to auto focus the color picker when it is opened
**`id`**
Type: `string`
Description: The unique identifier of the machine.
**`getRootNode`**
Type: `() => Node | ShadowRoot | Document`
Description: A root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.
**`dir`**
Type: `"ltr" | "rtl"`
Description: The document's text/writing direction.
**`onPointerDownOutside`**
Type: `(event: PointerDownOutsideEvent) => void`
Description: Function called when the pointer is pressed down outside the component
**`onFocusOutside`**
Type: `(event: FocusOutsideEvent) => void`
Description: Function called when the focus is moved outside the component
**`onInteractOutside`**
Type: `(event: InteractOutsideEvent) => void`
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
**`value`**
Type: `Color`
Description: The current color value (as a string)
**`valueAsString`**
Type: `string`
Description: The current color value (as a Color object)
**`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
### Data Attributes
**`Root`**
**`data-scope`**: color-picker
**`data-part`**: root
**`data-disabled`**: Present when disabled
**`data-readonly`**: Present when read-only
**`data-invalid`**: Present when invalid
**`Label`**
**`data-scope`**: color-picker
**`data-part`**: label
**`data-disabled`**: Present when disabled
**`data-readonly`**: Present when read-only
**`data-invalid`**: Present when invalid
**`data-focus`**: Present when focused
**`Control`**
**`data-scope`**: color-picker
**`data-part`**: control
**`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-scope`**: color-picker
**`data-part`**: trigger
**`data-disabled`**: Present when disabled
**`data-readonly`**: Present when read-only
**`data-invalid`**: Present when invalid
**`data-placement`**: The placement of the trigger
**`data-state`**: "open" | "closed"
**`data-focus`**: Present when focused
**`Content`**
**`data-scope`**: color-picker
**`data-part`**: content
**`data-placement`**: The placement of the content
**`data-state`**: "open" | "closed"
**`ValueText`**
**`data-scope`**: color-picker
**`data-part`**: value-text
**`data-disabled`**: Present when disabled
**`data-focus`**: Present when focused
**`Area`**
**`data-scope`**: color-picker
**`data-part`**: area
**`data-invalid`**: Present when invalid
**`data-disabled`**: Present when disabled
**`data-readonly`**: Present when read-only
**`AreaBackground`**
**`data-scope`**: color-picker
**`data-part`**: area-background
**`data-invalid`**: Present when invalid
**`data-disabled`**: Present when disabled
**`data-readonly`**: Present when read-only
**`AreaThumb`**
**`data-scope`**: color-picker
**`data-part`**: area-thumb
**`data-disabled`**: Present when disabled
**`data-invalid`**: Present when invalid
**`data-readonly`**: Present when read-only
**`ChannelSlider`**
**`data-scope`**: color-picker
**`data-part`**: channel-slider
**`data-channel`**: The color channel of the channelslider
**`data-orientation`**: The orientation of the channelslider
**`ChannelSliderTrack`**
**`data-scope`**: color-picker
**`data-part`**: channel-slider-track
**`data-channel`**: The color channel of the channelslidertrack
**`data-orientation`**: The orientation of the channelslidertrack
**`ChannelSliderLabel`**
**`data-scope`**: color-picker
**`data-part`**: channel-slider-label
**`data-channel`**: The color channel of the channelsliderlabel
**`ChannelSliderValueText`**
**`data-scope`**: color-picker
**`data-part`**: channel-slider-value-text
**`data-channel`**: The color channel of the channelslidervaluetext
**`ChannelSliderThumb`**
**`data-scope`**: color-picker
**`data-part`**: channel-slider-thumb
**`data-channel`**: The color channel of the channelsliderthumb
**`data-disabled`**: Present when disabled
**`data-orientation`**: The orientation of the channelsliderthumb
**`ChannelInput`**
**`data-scope`**: color-picker
**`data-part`**: channel-input
**`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-scope`**: color-picker
**`data-part`**: eye-dropper-trigger
**`data-disabled`**: Present when disabled
**`data-invalid`**: Present when invalid
**`data-readonly`**: Present when read-only
**`SwatchTrigger`**
**`data-scope`**: color-picker
**`data-part`**: swatch-trigger
**`data-state`**: "checked" | "unchecked"
**`data-value`**: The value of the item
**`data-disabled`**: Present when disabled
**`Swatch`**
**`data-scope`**: color-picker
**`data-part`**: swatch
**`data-state`**: "checked" | "unchecked"
**`data-value`**: The value of the item
## Accessibility
### Keyboard Interactions
**`Enter`**
Description: When focus is on the trigger, opens the color pickerWhen focus is on a trigger of a swatch, selects the color (and closes the color picker)
When focus is on the input or channel inputs, selects the color **`ArrowLeft`** Description: When focus is on the color area, decreases the hue value of the color
When focus is on the channel sliders, decreases the value of the channel **`ArrowRight`** Description: When focus is on the color area, increases the hue value of the color
When focus is on the channel sliders, increases the value of the channel **`ArrowUp`** Description: When focus is on the color area, increases the saturation value of the color
When focus is on the channel sliders, increases the value of the channel **`ArrowDown`** Description: When focus is on the color area, decreases the saturation value of the color
When focus is on the channel sliders, decreases the value of the channel **`Esc`** Description: Closes the color picker and moves focus to the trigger # Combobox A combobox is an input widget with an associated popup that enables users to select a value from a collection of possible values. ## Resources [Latest version: v1.7.0](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** - Support for selecting multiple values - Support for disabled options - Support for custom user input values - Support for mouse, touch, and keyboard interactions - Keyboard support for opening the combo box list box using the arrow keys, including automatically focusing the first or last item accordingly ## Installation To use the combobox machine in your project, run the following command in your command line: ```bash npm install @zag-js/combobox @zag-js/react # or yarn add @zag-js/combobox @zag-js/react ``` This command will install the framework agnostic combobox logic and the reactive utilities for your framework of choice. ## Anatomy To set up the combobox correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Usage First, import the combobox package into your project ```jsx import * as combobox from "@zag-js/combobox" ``` The combobox package exports these functions: - `machine` — The state machine logic for the combobox widget. - `connect` — The function that translates the machine's state to JSX attributes and event handlers. - `collection` - The function that creates a [collection interface](/overview/collection) from an array of items. Next, import the required hooks and functions for your framework and use the combobox machine in your project 🔥 ```jsx 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 (
{options.length > 0 && (
-
{options.map((item) => (
- {item.label} ))}
{/* Day View */}
{/* Month View */}
{api
.getMonthsGrid({ columns: 4, format: "short" })
.map((months, row) => (
{/* Year View */}
{api.getYearsGrid({ columns: 4 }).map((years, row) => (
| {day.narrow} | ))}
|---|
|
{value.day}
|
))}
|
{month.label}
|
))}
{api.getDecade().start} - {api.getDecade().end}
|
{year.label}
|
))}
Edit profile
Make changes to your profile here. Click save when you are done.
{!api.editing && }
{api.editing && (
)}