Skip to main content
BETA
View Zag.js on Github
Join the Discord server

Combobox

A combobox is an input widget with an associated popup that enables users to select a value from a collection of possible values.

Properties

Features

  • Support for filtering a list of options by typing.
  • 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:

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.

On a high level, the combobox consists of:

  • Root: The root container for the combobox
  • Label: The label that gives the user information on the combobox
  • Positioner: The element that positions the combobox dynamically.
  • Content: The element that contains the options.
  • Trigger: The element that toggles the combobox menu.

Usage

First, import the combobox package into your project

import * as combobox from "@zag-js/combobox"

The combobox package exports two key 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.

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

import * as combobox from "@zag-js/combobox" import { useMachine, normalizeProps } from "@zag-js/react" const comboboxData = [ { label: "Zambia", code: "ZA" }, { label: "Benin", code: "BN" }, //... ] export function Combobox() { const [options, setOptions] = useState(comboboxData) const [state, send] = useMachine( combobox.machine({ id: useId(), onOpen() { setOptions(comboboxData) }, onInputChange({ value }) { const filtered = comboboxData.filter((item) => item.label.toLowerCase().includes(value.toLowerCase()), ) setOptions(filtered.length > 0 ? filtered : comboboxData) }, }), ) const api = combobox.connect(state, send, normalizeProps) return ( <div> <div {...api.rootProps}> <label {...api.labelProps}>Select country</label> <div {...api.controlProps}> <input {...api.inputProps} /> <button {...api.triggerProps}></button> </div> </div> <div {...api.positionerProps}> {options.length > 0 && ( <ul {...api.contentProps}> {options.map((item, index) => ( <li key={`${item.code}:${index}`} {...api.getOptionProps({ label: item.label, value: item.code, index, disabled: item.disabled, })} > {item.label} </li> ))} </ul> )} </div> </div> ) }

Disabling the combobox

To make a combobox disabled, set the context's disabled property to true

const [state, send] = useMachine( combobox.machine({ disabled: true, }), )

Disabling an option

To make a combobox option disabled, set the disabled property of getOptionProps to true

const [state, send] = useMachine(combobox.machine()) return { <li {...api.getOptionProps({ label: item.label, value: item.code, index:index, disabled: item.disabled, })} /> }

Making the combobox readonly

To make a combobox readonly, set the context's readOnly property to true

const [state, send] = useMachine( combobox.machine({ readOnly: true, }), )

Listening for highlight changes

When an option is highlighted with the pointer or keyboard, the highlightedOption property in the machine's context is updated. You can listen for this change and do something with it.

const [state, send] = useMachine( combobox.machine({ id: useId(), onHighlight(details) { // details => { label: string, value: string, relatedTarget: HTMLElement | null } console.log(details) }, }), )

Listening for selection changes

When an option is selected, the selectedOption property in the machine's context is updated. You can listen for this change and do something with it.

const [state, send] = useMachine( combobox.machine({ onSelect(details) { // details => { label: string, value: string, relatedTarget: HTMLElement | null } console.log(details) }, }), )

Usage within forms

The combobox 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 attribute to the input so the value can be accessed in the FormData.

To get this feature working you need to pass a name option to the context.

const [state, send] = useMachine( combobox.machine({ name: "countries", }), )

Methods and Properties

The combobox's api exposes the following methods:

  • isFocused — Whether the comboboxis focused.
  • isOpen — Whether the combobox content is open.
  • isInputValueEmpty — Whether the combobox input has no value.
  • inputValue — The value of the combobox input element.
  • activeOption — The active option in the combobox.
  • selectedValue — The selected option in the combobox.
  • setValue(...) — Function to set combobox value.
  • setInputValue(...) — Function to set combobox input's value.
  • clearValue(...) — Function to clear combobox value.
  • focus(...) — Function to focus combobox.

Styling guide

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

Focused State

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

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

[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="option"][data-disabled] { /* styles for option disabled state */ }

Invalid State

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

[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 */ }

Edit this page on GitHub

On this page