Combobox

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

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:

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

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

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

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

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.
• Control: The element that contains the input and trigger.
• Input: The element that receives user input.
• Item: The combobox item or option element.
• ItemIndicator: The element that indicates the selected item.
• ItemGroup: The element used to group related items.

Usage

First, import the combobox package into your project

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 from an array of items.

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 collection = combobox.collection({
    items: comboboxData,
    itemToValue: (item) => item.code,
    itemToString: (item) => item.label,
  })

  const [state, send] = useMachine(
    combobox.machine({
      id: useId(),
      collection,
      onOpenChange(details) {
        if (!details.open) return
        setOptions(comboboxData)
      },
      onInputValueChange({ value }) {
        const filtered = comboboxData.filter((item) =>
          item.label.toLowerCase().includes(value.toLowerCase()),
        )
        setOptions(filtered.length > 0 ? filtered : comboboxData)
      },
    }),
    {
      context: { collection },
    },
  )

  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) => (
              <li key={item.code} {...api.getItemProps({ item })}>
                {item.label}
              </li>
            ))}
          </ul>
        )}
      </div>
    </div>
  )
}

import * as combobox from "@zag-js/combobox"
import { normalizeProps, useMachine } from "@zag-js/vue"
import { computed, defineComponent, ref } from "vue"

const comboboxData = [
  { label: "Zambia", code: "ZA" },
  { label: "Benin", code: "BN" },
  //...
]

export default defineComponent({
  name: "Combobox",
  setup() {
    const options = ref(comboboxData)

    const collectionRef = computed(() =>
      combobox.collection({
        items: options.value,
        itemToString: (item) => item.label,
        itemToValue: (item) => item.code,
      }),
    )

    const [state, send] = useMachine(
      combobox.machine({
        id: "v1",
        collection: collectionRef.value,
        onOpenChange(details) {
          if (!details.open) return
          options.value = comboboxData
        },
        onInputValueChange({ value }) {
          const filtered = comboboxData.filter((item) =>
            item.label.toLowerCase().includes(value.toLowerCase()),
          )
          options.value = filtered.length > 0 ? filtered : comboboxData
        },
      }),
      {
        context: computed(() => ({
          collection: collectionRef.value,
        })),
      },
    )

    const apiRef = computed(() =>
      combobox.connect(state.value, send, normalizeProps),
    )

    return () => {
      const api = apiRef.value

      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.value.length > 0 && (
              <ul {...api.contentProps}>
                {options.value.map((item) => (
                  <li key={item.code} {...api.getItemProps({ item })}>
                    {item.label}
                  </li>
                ))}
              </ul>
            )}
          </div>
        </div>
      )
    }
  },
})

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

  const comboboxData = [
    { label: "Zambia", code: "ZA" },
    { label: "Benin", code: "BN" },
    //...
  ]

  const options = ref(comboboxData)

  const collectionRef = computed(() =>
    select.collection({
      items: options.value,
      itemToValue: (item) => item.code,
      itemToString: (item) => item.label,
    }),
  )

  const [state, send] = useMachine(
    combobox.machine({
      id: "1",
      collection: collectionRef.value,
      onOpenChange(details) {
        if (!details.open) return
        options.value = comboboxData
      },
      onInputValueChange({ value }) {
        const filtered = comboboxData.filter((item) =>
          item.label.toLowerCase().includes(value.toLowerCase()),
        )
        options.value = filtered.length > 0 ? filtered : comboboxData
      },
    }),
    {
      context: computed(() => ({
        collection: collectionRef.value,
      })),
    },
  )

  const api = computed(() =>
    combobox.connect(state.value, send, normalizeProps),
  )
</script>

<template>
  <div v-bind="api.rootProps">
    <label v-bind="api.labelProps">Select country</label>

    <div v-bind="api.controlProps">
      <input v-bind="api.inputProps" />
      <button v-bind="api.triggerProps">▼</button>
    </div>
  </div>
  <div v-bind="api.positionerProps">
    <ul v-if="options.length > 0" v-bind="api.contentProps">
      <li
        v-for="item in options"
        :key="item.code"
        v-bind="api.getItemProps({ item })"
      >
        {{ item.label }}
      </li>
    </ul>
  </div>
</template>

import * as combobox from "@zag-js/combobox"
import { normalizeProps, useMachine } from "@zag-js/solid"
import { createMemo, createSignal, createUniqueId, For, Show } from "solid-js"

const comboboxData = [
  { label: "Zambia", code: "ZA" },
  { label: "Benin", code: "BN" },
  //...
]

export function Combobox() {
  const [options, setOptions] = createSignal(comboboxData)

  const collection = createMemo(() =>
    combobox.collection({
      items: options(),
      itemToValue: (item) => item.code,
      itemToString: (item) => item.label,
    }),
  )

  const [state, send] = useMachine(
    combobox.machine({
      id: createUniqueId(),
      collection: collection(),
      onOpenChange(details) {
        if (!details.open) return
        setOptions(comboboxData)
      },
      onInputValueChange({ value }) {
        const filtered = comboboxData.filter((item) =>
          item.label.toLowerCase().includes(value.toLowerCase()),
        )
        setOptions(filtered.length > 0 ? filtered : comboboxData)
      },
    }),
  )

  const api = createMemo(() => 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}>
        <Show when={options().length > 0}>
          <ul {...api().contentProps}>
            <For each={options()}>
              {(item) => (
                <li {...api().getItemProps({ item })}>{item.label}</li>
              )}
            </For>
          </ul>
        </Show>
      </div>
    </div>
  )
}

Setting the initial value

To set the initial value of the combobox, pass the value property to the machine's context.

The value property must be an array of strings. If selecting a single value, pass an array with a single string.

const collection = combobox.collection({
  items: [
    { label: "Nigeria", value: "ng" },
    { label: "Ghana", value: "gh" },
    { label: "Kenya", value: "ke" },
    //...
  ],
})

const [state, send] = useMachine(
  combobox.machine({
    id: useId(),
    collection,
    value: ["ng"],
  }),
)

Selecting multiple values

To allow selecting multiple values, set the multiple property in the machine's context to true.

const [state, send] = useMachine(
  combobox.machine({
    id: useId(),
    collection,
    multiple: true,
  }),
)

Rendering the selected values outside the combobox

By default, the selected values of a combobox is displayed in the input element, when selecting multiple items, it is a better UX to render the selected value outside the combobox.

To achieve this you need to:

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

const [state, send] = useMachine(
  combobox.machine({
    id: useId(),
    collection,
    selectionBehavior: "clear",
    multiple: true,
  }),
)

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, pass the isItemDisabled property to the collection function.

const [state, send] = useMachine(
  combobox.machine({
    id: useId(),
    collection: combobox.collection({
      items: countries,
      isItemDisabled(item) {
        return item.disabled
      },
    }),
  }),
)

Close on select

This behaviour ensures that the menu is closed when an option is selected and is true by default. It's only concerned with when an option is selected with pointer or enter key. To disable the behaviour, set the closeOnSelect property in the machine's context to false.

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

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, use the onHighlightChange property to listen for this change and do something with it.

const [state, send] = useMachine(
  combobox.machine({
    id: useId(),
    onHighlightChange(details) {
      // details => { value: string | null; item: CollectionItem | null }
      console.log(details)
    },
  }),
)

Listening for value changes

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

const [state, send] = useMachine(
  combobox.machine({
    onValueChange(details) {
      // details => { value: string[]; items: CollectionItem[] }
      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",
  }),
)

Allowing custom values

By default, the combobox only allows selecting values from the collection. To allow custom values, set the allowCustomValue property in the machine's context to true.

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

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.

Open and closed state

When the combobox is open or closed, the data-state attribute is added to the content,control, input and control parts.

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

[data-part="input"][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 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="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.

[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-selected attribute is added to the item part.

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

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

Methods and Properties

The combobox's api exposes the following methods:

• isFocusedbooleanWhether the combobox is focused
• isOpenbooleanWhether the combobox is open
• isInputValueEmptybooleanWhether the combobox input value is empty
• inputValuestringThe value of the combobox input
• highlightedValuestringThe value of the highlighted item
• highlightedItemVThe highlighted item
• highlightValue(value: string) => voidThe value of the combobox input
• selectedItemsV[]The selected items
• hasSelectedItemsbooleanWhether there's a selected item
• valuestring[]The selected item keys
• valueAsStringstringThe string representation of the selected items
• selectValue(value: string) => voidFunction to select a value
• setValue(value: string[]) => voidFunction to set the value of the combobox
• clearValue(value?: string) => voidFunction to clear the value of the combobox
• focus() => voidFunction to focus on the combobox input
• setInputValue(value: string) => voidFunction to set the input value of the combobox
• getItemState(props: ItemProps) => ItemStateReturns the state of a combobox item
• open() => voidFunction to open the combobox
• close() => voidFunction to close the combobox
• setCollection(collection: Collection<V>) => voidFunction to set the collection of items
• setPositioning(options: Partial<PositioningOptions>) => voidFunction to set the positioning options