Combobox

The Combobox consists of a label, a text-input field, and a chevron icon that indicates the control can expand. The input field contains the current value or placeholder text and is enclosed by a container that provides focus and hover states. Activating the control reveals the dropdown menu, which presents a list of options.

import {Combobox} from "@qualcomm-ui/react/combobox"

Overview

Each combobox uses the comboboxCollection helper to manage the list of options. This creates a ListCollection instance, documented below.

Examples

Simple

The simple API provides a standalone component with bundled subcomponents.

Country

<Combobox
  collection={collection}
  label="Country"
  onInputValueChange={handleInputChange}
  placeholder="Select a country"
/>

Composite

Build with the composite API for granular control. This API requires you to provide each subcomponent, but gives you full control over the structure and layout.

<Combobox.Root
  className="w-56"
  collection={collection}
  icon={Search}
  name="combobox-composite"
  onInputValueChange={handleInputChange}
  placeholder="Search..."
>
  <Combobox.Label>Search</Combobox.Label>
  <Combobox.Control>
    <Combobox.Input />
    <Combobox.ClearTrigger />
    <Combobox.Trigger />
  </Combobox.Control>
  <Portal>
    <Combobox.Positioner>
      <Combobox.Content>
        <Combobox.Empty>No results found</Combobox.Empty>
        {collection.items.map((item) => (
          <Combobox.Item key={item} item={item}>
            <Combobox.ItemText>{item}</Combobox.ItemText>
            <Combobox.ItemIndicator>✓</Combobox.ItemIndicator>
          </Combobox.Item>
        ))}
      </Combobox.Content>
    </Combobox.Positioner>
  </Portal>
</Combobox.Root>

Open on Click

Use the openOnClick prop to open the combobox when the user clicks on the input.

Country

<Combobox
  collection={collection}
  label="Country"
  onInputValueChange={handleInputChange}
  openOnClick
  placeholder="Select a country"
/>

Input Behavior

Adjust the auto-completion behavior of the combobox with the inputBehavior prop.

Country

<Combobox
  collection={collection}
  inputBehavior="autohighlight"
  label="Country"
  onInputValueChange={handleInputChange}
  placeholder="Select a country"
/>

Multiple Selection

Use the multiple prop to enable multiple selection. When this is set, the combobox will always clear the input value when the user selects an option.

Country

import {useState} from "react"

import type {ComboboxInputValueChangeDetails} from "@qualcomm-ui/core/combobox"
import {useListCollection} from "@qualcomm-ui/react-core/collection"
import {useFilter} from "@qualcomm-ui/react-core/locale"
import {Combobox} from "@qualcomm-ui/react/combobox"
import {Tag} from "@qualcomm-ui/react/tag"

import {countries} from "./country-list"

export function ComboboxMultipleDemo() {
  const {contains} = useFilter({sensitivity: "base"})
  const [value, setValue] = useState<string[]>([])

  const {collection, filter} = useListCollection({
    filter: contains,
    initialItems: countries,
  })

  function handleInputChange(details: ComboboxInputValueChangeDetails) {
    filter(details.inputValue)
  }

  function handleValueDismissed(item: string) {
    setValue(value.filter((v) => v !== item))
  }

  return (
    <div className="flex w-72 flex-col gap-4">
      <div className="flex flex-wrap gap-2">
        {value.map((item) => (
          <Tag
            key={item}
            emphasis="neutral"
            onClick={() => handleValueDismissed(item)}
            variant="dismissable"
          >
            {item}
          </Tag>
        ))}
      </div>
      <Combobox
        className="w-full"
        collection={collection}
        label="Country"
        multiple
        onInputValueChange={handleInputChange}
        onValueChange={(details) => setValue(details.value)}
        placeholder="Select a country"
        value={value}
      />
    </div>
  )
}

Highlight Matching Text

Use the highlightMatchingText prop to highlight the portion of each option that matches the user's input. This provides visual feedback during filtering.

Country

<Combobox
  className="w-56"
  collection={collection}
  highlightMatchingText
  label="Country"
  name="combobox-highlight"
  onInputValueChange={handleInputChange}
  placeholder="Search countries..."
/>

ARIA Label

The Combobox's label is automatically associated with the input element for accessibility. If you omit the label, you should provide an aria-label to the input to give your combobox an accessible name.

<Combobox
  aria-label="Country"
  className="w-48"
  collection={collection}
  onInputValueChange={handleInputChange}
  placeholder="Select a country"
/>

Content Width

The positioning.sameWidth property controls whether the width of the combobox content matches the width of the input element. The default is true.

<Combobox
  aria-label="Country"
  className="w-48"
  collection={collection}
  onInputValueChange={handleInputChange}
  placeholder="Select a country"
  positioning={{sameWidth: false}}
/>

Input Icon

Use the icon prop to add an icon to the start of the input element.

<Combobox
  aria-label="Country"
  className="w-48"
  collection={collection}
  icon={MapPin}
  onInputValueChange={handleInputChange}
  placeholder="Select a country"
/>

Icon Customization

Supply a ReactNode to the icon prop to customize the icon. This example features a loading indicator:

<Combobox
  aria-label="Country"
  className="w-48"
  collection={collection}
  icon={<ProgressRing size="xs" />}
  onInputValueChange={handleInputChange}
  placeholder="Select a country"
/>

Items as Objects

The items prop can be an array of objects. Use the itemLabel and itemValue properties on the comboboxCollection to specify the label and value of each item.

City

{name: "San Diego", value: "SD"},
{name: "Nashville", value: "NV"},
{name: "Denver", value: "DV"},
{name: "Miami", value: "MI"},
{name: "Las Vegas", value: "LV"},
{name: "New York City", value: "NYC"},
{name: "San Francisco", value: "SF"},

Custom Item Rendering

When using the simple API, use the renderItem prop to customize the rendering of each item.

Select team member

<Combobox
  className="w-72"
  collection={collection}
  label="Select team member"
  onInputValueChange={handleInputChange}
  placeholder="Search by name, role, or email"
  renderItem={({item, ...itemProps}) => {
    const person = item
    return (
      <Combobox.Item className="min-h-[48px]" item={item} {...itemProps}>
        <div className="flex flex-1 flex-col gap-0.5">
          <Combobox.ItemText>
            <span className="font-body-sm">{person.name}</span>
          </Combobox.ItemText>
          <div className="font-body-xs flex items-center gap-1">
            <span>{person.role}</span>
            <span>—</span>
            <span>{person.email}</span>
          </div>
        </div>
        <Combobox.ItemIndicator />
      </Combobox.Item>
    )
  }}
/>

WARNING

When rendering custom items with virtual set to true, you must forward the data-virtual and style props to the rendered item:

<Combobox
  renderItem={({item, ...itemProps}) => {
    return (
      <Combobox.Item item={item} {...itemProps}>
        {/* ... */}
      </Combobox.Item>
    )
  }}
/>

Sizes

This component supports three size options to accommodate different layout densities and design requirements.

The available sizes are sm, md, and lg. The default size is md.

import type {ComboboxInputValueChangeDetails} from "@qualcomm-ui/core/combobox"
import {useListCollection} from "@qualcomm-ui/react-core/collection"
import {useFilter} from "@qualcomm-ui/react-core/locale"
import {Combobox} from "@qualcomm-ui/react/combobox"

const cityList = ["San Diego", "Dallas", "Denver"]

export function ComboboxSizesDemo() {
  const {contains} = useFilter({sensitivity: "base"})

  const {collection, filter} = useListCollection({
    filter: contains,
    initialItems: cityList,
  })

  function handleInputChange(details: ComboboxInputValueChangeDetails) {
    filter(details.inputValue)
  }

  return (
    <div className="flex flex-col items-center gap-4">
      <Combobox
        aria-label="City"
        className="w-40"
        collection={collection}
        onInputValueChange={handleInputChange}
        placeholder="sm"
        positioning={{sameWidth: true}}
        size="sm"
      />
      <Combobox
        aria-label="City"
        className="w-48"
        collection={collection}
        onInputValueChange={handleInputChange}
        placeholder="md"
        positioning={{sameWidth: true}}
        size="md"
      />
      <Combobox
        aria-label="City"
        className="w-56"
        collection={collection}
        onInputValueChange={handleInputChange}
        placeholder="lg"
        positioning={{sameWidth: true}}
        size="lg"
      />
    </div>
  )
}

Content Height

Change the height of the item container by adjusting the style of the Content element.

<Combobox
  aria-label="Country"
  className="w-48"
  collection={collection}
  contentProps={{style: {maxHeight: 240}}}
  onInputValueChange={handleInputChange}
  placeholder="Select a country"
  positioning={{sameWidth: true}}
/>

Controlled State

Set the initial value using the defaultValue prop, or use value and onValueChange to control the value manually. These props follow our controlled state pattern.

<Combobox
  aria-label="Country"
  className="w-48"
  collection={collection}
  onInputValueChange={handleInputChange}
  onValueChange={(details) => setValue(details.value)}
  placeholder="Select a country"
  value={value}
/>

States

The following shows how the Combobox component appears in each interactive state.

Disabled

Read only

Invalid

<Combobox
  className="w-48"
  collection={collection}
  defaultValue={[countries[0]]}
  disabled
  label="Disabled"
  onInputValueChange={handleInputChange}
/>
<Combobox
  className="w-48"
  collection={collection}
  defaultValue={[countries[0]]}
  label="Read only"
  onInputValueChange={handleInputChange}
  readOnly
/>
<Combobox
  className="w-48"
  collection={collection}
  defaultValue={[countries[0]]}
  errorText="Invalid"
  invalid
  label="Invalid"
  onInputValueChange={handleInputChange}
/>

Error Text and Indicator

Error messages are displayed using two props:

invalid
errorText (or the Combobox.ErrorText component when using the composite API)

The error text and indicator will only render when invalid is true.

You must select a country

<Combobox
  aria-label="Country"
  className="w-48"
  collection={collection}
  errorText="You must select a country"
  invalid={!value.length}
  onInputValueChange={handleInputChange}
  onValueChange={(details) => setValue(details.value)}
  placeholder="Select a country"
  value={value}
/>

Hint Text

Use the hint prop to provide additional context or instructions below the combobox.

Optional hint

<Combobox
  aria-label="Country"
  className="w-48"
  collection={collection}
  hint="Optional hint"
  onInputValueChange={handleInputChange}
  placeholder="Select a country"
/>

Within Dialog

To use the Combobox within a Dialog, you need to avoid portalling the Combobox.Positioner to the document's body. To do this using the simple API, set portalProps.disabled to true:

import type {ReactElement} from "react"

import type {ComboboxInputValueChangeDetails} from "@qualcomm-ui/core/combobox"
import {useListCollection} from "@qualcomm-ui/react-core/collection"
import {useFilter} from "@qualcomm-ui/react-core/locale"
import {Button} from "@qualcomm-ui/react/button"
import {Combobox} from "@qualcomm-ui/react/combobox"
import {Dialog} from "@qualcomm-ui/react/dialog"

import {countries} from "./country-list"

export function ComboboxWithinDialogDemo(): ReactElement {
  const {contains} = useFilter({sensitivity: "base"})

  const {collection, filter} = useListCollection({
    filter: contains,
    initialItems: countries,
  })

  function handleInputChange(details: ComboboxInputValueChangeDetails) {
    filter(details.inputValue)
  }

  return (
    <Dialog.Root>
      <Dialog.Trigger>
        <Button emphasis="primary" variant="fill">
          Open Dialog
        </Button>
      </Dialog.Trigger>
      <Dialog.FloatingPortal>
        <Dialog.Body>
          <Dialog.Heading>Dialog Title</Dialog.Heading>
          <Dialog.CloseButton />
          <Combobox
            aria-label="Country"
            className="w-48"
            collection={collection}
            onInputValueChange={handleInputChange}
            placeholder="Select a country"
            portalProps={{disabled: true}}
          />
        </Dialog.Body>

        <Dialog.Footer>
          <Dialog.CloseTrigger>
            <Button emphasis="primary" size="sm" variant="fill">
              Confirm
            </Button>
          </Dialog.CloseTrigger>
        </Dialog.Footer>
      </Dialog.FloatingPortal>
    </Dialog.Root>
  )
}

Like with the Dialog, you need to avoid portalling the Combobox.Positioner to the document's body:

import type {ReactElement} from "react"

import type {ComboboxInputValueChangeDetails} from "@qualcomm-ui/core/combobox"
import {useListCollection} from "@qualcomm-ui/react-core/collection"
import {useFilter} from "@qualcomm-ui/react-core/locale"
import {Button} from "@qualcomm-ui/react/button"
import {Combobox} from "@qualcomm-ui/react/combobox"
import {Popover} from "@qualcomm-ui/react/popover"

import {countries} from "./country-list"

export function ComboboxWithinPopoverDemo(): ReactElement {
  const {contains} = useFilter({sensitivity: "base"})

  const {collection, filter} = useListCollection({
    filter: contains,
    initialItems: countries,
  })

  function handleInputChange(details: ComboboxInputValueChangeDetails) {
    filter(details.inputValue)
  }

  return (
    <Popover
      label="Combobox Example"
      trigger={<Button emphasis="primary">Show Popover</Button>}
    >
      <Combobox
        className="w-48"
        collection={collection}
        label="Country"
        onInputValueChange={handleInputChange}
        placeholder="Select a country"
        portalProps={{disabled: true}}
      />
    </Popover>
  )
}

Async Loading

This example shows how to load items asynchronously and display a loading indicator.

Starship

<Combobox
  className="w-56"
  collection={collection}
  icon={isFetching ? <ProgressRing size="xs" /> : undefined}
  inputValue={inputValue}
  label="Starship"
  onInputValueChange={(details) => setInputValue(details.inputValue)}
  placeholder="Search for a starship"
/>

Virtualized

For large lists, use the virtual prop to improve performance. This virtualizes the visible list items for performant scrolling and searching. The following example features a list of 5000 mock usernames.

Users

import {useState} from "react"

import {useAsyncListCollection} from "@qualcomm-ui/react-core/collection"
import {useFilter} from "@qualcomm-ui/react-core/locale"
import {Combobox} from "@qualcomm-ui/react/combobox"
import {ProgressRing} from "@qualcomm-ui/react/progress-ring"

import {useMockUsers} from "./use-mock-users"

export function ComboboxVirtualDemo() {
  const {data, isFetching} = useMockUsers(5000)
  const {contains} = useFilter({sensitivity: "base"})

  const [inputValue, setInputValue] = useState<string>("")

  const {collection} = useAsyncListCollection<string>({
    filter: contains,
    filterText: inputValue,
    items: data ?? [],
  })

  return (
    <Combobox
      className="w-56"
      collection={collection}
      icon={isFetching ? <ProgressRing size="xs" /> : undefined}
      inputBehavior="autohighlight"
      inputValue={inputValue}
      label="Users"
      onInputValueChange={(details) => setInputValue(details.inputValue)}
      placeholder="Search for a username"
      virtual
    />
  )
}

Forms

Choose the form library that fits your needs—we've built examples with React Hook Form and Tanstack Form to get you started.

React Hook Form

Use React Hook Form to handle the input state and validation. ArkType works great for schema validation if you need it.

import type {ReactElement} from "react"

import {type} from "arktype"
import {Controller, type SubmitHandler, useForm} from "react-hook-form"

import type {ComboboxInputValueChangeDetails} from "@qualcomm-ui/core/combobox"
import {useListCollection} from "@qualcomm-ui/react-core/collection"
import {useFilter} from "@qualcomm-ui/react-core/locale"
import {Button} from "@qualcomm-ui/react/button"
import {Combobox} from "@qualcomm-ui/react/combobox"
import {createToaster, Toaster} from "@qualcomm-ui/react/toast"

import {countries} from "./country-list"

const valueSchema = type({
  country: type("string[] > 0").configure({
    message: "At least one country must be selected",
  }),
})

type ValueSchema = typeof valueSchema.infer

const toaster = createToaster({
  overlap: true,
  placement: "bottom-end",
})

export function ComboboxHookFormDemo(): ReactElement {
  const {contains} = useFilter({sensitivity: "base"})

  const {collection, filter} = useListCollection({
    filter: contains,
    initialItems: countries,
  })

  function handleInputChange(details: ComboboxInputValueChangeDetails) {
    filter(details.inputValue)
  }

  const {
    control,
    formState: {isSubmitting},
    handleSubmit,
    setError,
  } = useForm<ValueSchema>({
    defaultValues: {
      country: [],
    },
  })

  const handleFormSubmit: SubmitHandler<ValueSchema> = (data) => {
    const validation = valueSchema(data)

    if (validation instanceof type.errors) {
      for (const error of validation) {
        const field = error.path?.[0] as keyof ValueSchema
        if (field) {
          setError(field, {
            message: error.message,
          })
        }
      }
      return
    }

    toaster.create({
      label: "Form submitted",
      type: "success",
    })
  }

  return (
    <>
      <Toaster toaster={toaster} />
      <form
        className="w-48"
        noValidate
        onSubmit={(event) => void handleSubmit(handleFormSubmit)(event)}
      >
        <Controller
          control={control}
          name="country"
          render={({field: {onChange, ...fieldProps}, fieldState: {error}}) => (
            <Combobox
              className="w-full"
              collection={collection}
              errorText={error?.message}
              invalid={!!error}
              label="Country"
              onInputValueChange={handleInputChange}
              onValueChange={(details) => onChange(details.value)}
              placeholder="Select a country"
              required
              {...fieldProps}
            />
          )}
        />
        <div className="mt-2 flex w-full justify-end">
          <Button
            disabled={isSubmitting}
            emphasis="primary"
            type="submit"
            variant="fill"
          >
            Submit
          </Button>
        </div>
      </form>
    </>
  )
}

Tanstack Form

Tanstack Form handles validation with its built-in validators.

import type {ReactElement} from "react"

import {useForm} from "@tanstack/react-form"

import type {ComboboxInputValueChangeDetails} from "@qualcomm-ui/core/combobox"
import {useListCollection} from "@qualcomm-ui/react-core/collection"
import {useFilter} from "@qualcomm-ui/react-core/locale"
import {Button} from "@qualcomm-ui/react/button"
import {Combobox} from "@qualcomm-ui/react/combobox"
import {createToaster, Toaster} from "@qualcomm-ui/react/toast"

import {countries} from "./country-list"

const toaster = createToaster({
  overlap: true,
  placement: "bottom-end",
})

export function ComboboxTanstackFormDemo(): ReactElement {
  const {contains} = useFilter({sensitivity: "base"})

  const {collection, filter} = useListCollection({
    filter: contains,
    initialItems: countries,
  })

  function handleInputChange(details: ComboboxInputValueChangeDetails) {
    filter(details.inputValue)
  }

  const form = useForm({
    defaultValues: {
      country: [] as string[],
    },
    onSubmit: () => {
      toaster.create({
        label: "Form submitted",
        type: "success",
      })
    },
  })

  return (
    <>
      <Toaster toaster={toaster} />
      <form
        className="w-48"
        noValidate
        onSubmit={(e) => {
          e.preventDefault()
          e.stopPropagation()
          form.handleSubmit()
        }}
      >
        <form.Field
          name="country"
          validators={{
            onChange: ({value}) =>
              value.length === 0
                ? "At least one country must be selected"
                : undefined,
          }}
        >
          {(field) => (
            <Combobox
              className="w-full"
              collection={collection}
              errorText={field.state.meta.errors[0]}
              invalid={field.state.meta.errors.length > 0}
              label="Country"
              onInputValueChange={handleInputChange}
              onValueChange={(details) => field.handleChange(details.value)}
              placeholder="Select a country"
              required
              value={field.state.value}
            />
          )}
        </form.Field>
        <div className="mt-2 flex w-full justify-end">
          <Button
            disabled={form.state.isSubmitting}
            emphasis="primary"
            type="submit"
            variant="fill"
          >
            Submit
          </Button>
        </div>
      </form>
    </>
  )
}

Tanstack form also supports ArkType.

Explorer

Framework

Choose a framework

Component Anatomy

Hover to highlight, click to view API

root label control input clear-trigger trigger content item item-text item-indicator hint

API

<Combobox>

The simple combobox extends the Combobox.Root component with the following props:

Prop	Type	Default
aria-label aria-label attribute, forwarded to the input element.	string
aria-labelledby aria-labelledby attribute, forwarded to the input element. If you provide a label, omit this prop.	string
clearTriggerProps Props applied to the clear trigger element. To prevent this element from rendering, pass `{hidden: true}`	ComboboxClearTriggerProps
contentProps Props applied to the content element.	ComboboxContentProps
controlProps Props applied to the control element.	ComboboxControlProps
emptyMessage Label to render when the list is empty.	ReactNode	"No results found"
emptyProps Props applied to the component that renders the empty message.	{ render?: \| Element \| (( props: Props, ) => Element) }
errorIndicatorProps Props applied to the error indicator element.	ComboboxErrorIndicatorProps
errorText Optional error that describes the element when invalid is true.	string
errorTextProps Props applied to the error text element.	ComboboxErrorTextProps
highlightMatchingText Set to `true` to highlight option text matches during filtering.	boolean
hint Optional hint describing the element. This element is automatically associated with the component's input element for accessibility.	ReactNode
hintProps Props applied to the label element.	ComboboxHintProps
inputProps Props applied to the select element.	ComboboxInputProps
label Optional label describing the element. Recommended. This element is automatically associated with the component's input element for accessibility.	ReactNode
labelProps Props applied to the label element.	ComboboxLabelProps
portalProps Props applied to the portal element.	PortalProps
positionerProps Props applied to the positioner element.	ComboboxPositionerProps
renderItem Customize the rendering of the combobox list items.	( props: Props, ) => Element
triggerProps Props applied to the trigger element.	ComboboxTriggerProps
virtual When `true`, the list items will be virtually rendered. Useful for large lists.	boolean

aria-label

Type

string

Description

aria-label attribute, forwarded to the input element.

aria-labelledby

Type

string

Description

aria-labelledby attribute, forwarded to the input element. If you provide a label, omit this prop.

clearTriggerProps

Type

ComboboxClearTriggerProps

Description

Props applied to the clear trigger element. To prevent this element from rendering, pass {hidden: true}

contentProps

Type

ComboboxContentProps

Description

Props applied to the content element.

controlProps

Type

ComboboxControlProps

Description

Props applied to the control element.

emptyMessage

Type

ReactNode

Description

Label to render when the list is empty.

emptyProps

Type

{
  render?:
    | Element
    | ((
        props: Props,
      ) => Element)
}

Description

Props applied to the component that renders the empty message.

errorIndicatorProps

Type

ComboboxErrorIndicatorProps

Description

Props applied to the error indicator element.

errorText

Type

string

Description

Optional error that describes the element when invalid is true.

errorTextProps

Type

ComboboxErrorTextProps

Description

Props applied to the error text element.

highlightMatchingText

Type

boolean

Description

Set to true to highlight option text matches during filtering.

hint

Type

ReactNode

Description

Optional hint describing the element. This element is automatically associated with the component's input element for accessibility.

hintProps

Type

ComboboxHintProps

Description

Props applied to the label element.

inputProps

Type

ComboboxInputProps

Description

Props applied to the select element.

label

Type

ReactNode

Description

Optional label describing the element. Recommended. This element is automatically associated with the component's input element for accessibility.

labelProps

Type

ComboboxLabelProps

Description

Props applied to the label element.

portalProps

Type

PortalProps

Description

Props applied to the portal element.

positionerProps

Type

ComboboxPositionerProps

Description

Props applied to the positioner element.

renderItem

Type

(
  props: Props,
) => Element

Description

Customize the rendering of the combobox list items.

triggerProps

Type

ComboboxTriggerProps

Description

Props applied to the trigger element.

virtual

Type

boolean

Description

When true, the list items will be virtually rendered. Useful for large lists.

Composite API

This section describes the elements of the Combobox's composite API.

<Combobox.Root>

Groups all parts of the combobox. Renders a <div> element by default.

Prop	Type	Default
allowCustomValue Whether to allow typing custom values in the input	boolean
alwaysSubmitOnEnter 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.	boolean	false
autoFocus Whether to autofocus the input on mount	boolean
closeOnSelect Whether to close the combobox when an item is selected.	boolean
collection The collection of items	ListCollection
composite Whether the combobox is a composed with other composite widgets like tabs	boolean	true
defaultHighlightedValue The initial highlighted value of the combobox when rendered. Use when you don't need to control the highlighted value of the combobox.	string
defaultInputValue 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.	string	""
defaultOpen The initial open state of the combobox when rendered. Use when you don't need to control the open state of the combobox.	boolean
defaultValue 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.	string[]	[]
dir The document's text/writing direction.	'ltr' \| 'rtl'	'ltr'
disabled Whether the combobox is disabled	boolean
disableLayer Whether to disable registering this as a dismissable layer	boolean
form The associate form of the combobox.	string
getRootNode A root node to correctly resolve document in custom environments. i.e., Iframes, Electron.	() => \| Node \| ShadowRoot \| Document
highlightedValue The controlled highlighted value of the combobox	string
icon lucide icon, positioned at the start of the input field.	\| LucideIcon \| ReactNode
id id attribute. If omitted, a unique identifier will be automatically generated for accessibility.	string
ids The ids of the combobox's elements. If omitted, these will be generated automatically.	Partial<{ clearTrigger: string content: string control: string errorText: string hint: string input: string label: string positioner: string root: string trigger: string }>
immediate Whether to synchronize the present change immediately or defer it to the next frame	boolean
inputBehavior 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	\| 'none' \| 'autohighlight' \| 'autocomplete'	"none"
inputValue The controlled value of the combobox's input	string
invalid Whether the combobox is invalid	boolean
lazyMount When true, the component will not be rendered in the DOM until it becomes visible or active.	boolean	false
loopFocus Whether to loop the keyboard navigation through the items	boolean	true
multiple Whether to allow multiple selection. When `multiple` is `true`, the `selectionBehavior` is automatically set to `clear`. It's recommended to render the selected items in a separate container.	boolean
name The `name` attribute of the combobox's input. Useful for form submission	string
onExitComplete Function called when the animation ends in the closed state	VoidFunction
onFocusOutside Function called when the focus is moved outside the component	( event: FocusOutsideEvent, ) => void
onHighlightChange Function called when an item is highlighted using the pointer or keyboard navigation.	(details: { highlightedItem: T highlightedValue: string }) => void
onInputValueChange Function called when the input's value changes	(details: { inputValue: string reason?: \| 'input-change' \| 'item-select' \| 'clear-trigger' \| 'script' \| 'interact-outside' }) => void
onInteractOutside Function called when an interaction happens outside the component	( event: InteractOutsideEvent, ) => void
onOpenChange Function called when the popup is opened	(details: { open: boolean reason?: \| 'input-click' \| 'trigger-click' \| 'script' \| 'arrow-key' \| 'input-change' \| 'interact-outside' \| 'escape-key' \| 'item-select' \| 'clear-trigger' \| 'input-focus' }) => void
onPointerDownOutside Function called when the pointer is pressed down outside the component	( event: PointerDownOutsideEvent, ) => void
onSelect Function called when an item is selected	(details: { itemValue: string value: string[] }) => void
onValueChange Function called when a new item is selected	(details: { items: Array<T> value: string[] }) => void
open The controlled open state of the combobox	boolean
openOnChange Whether to show the combobox when the input value changes	\| boolean \| ((details: { inputValue: string reason?: \| 'input-change' \| 'item-select' \| 'clear-trigger' \| 'script' \| 'interact-outside' }) => boolean)	true
openOnClick Whether to open the combobox popup on initial click on the input	boolean	false
openOnKeyPress Whether to open the combobox on arrow key press	boolean	true
placeholder The placeholder text of the combobox's input	string
positioning The positioning options to dynamically position the popup menu	ComboboxPositioningOptions
present Whether the node is present (controlled by the user)	boolean
readOnly Whether the combobox is readonly. This puts the combobox in a "non-editable" mode but the user can still interact with it	boolean
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)
required Whether the combobox is a required input field	boolean
scrollToIndexFn Function to scroll to a specific index	(details: { getElement: () => HTMLElement immediate?: boolean index: number }) => void
selectionBehavior 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	\| 'replace' \| 'clear' \| 'preserve'	"replace"
selectionIndicator Visual indicator style for selected items. Use "checkbox" for multi-select with always-visible checkboxes on the left, or "checkmark" for a checkmark icon on the right that only appears when selected.	\| 'checkmark' \| 'checkbox'	'checkmark'
size The size of the select and its elements. Governs properties like font size, item padding, and icon sizes.	\| 'sm' \| 'md' \| 'lg'	'md'
skipAnimationOnMount Whether to allow the initial presence animation.	boolean	false
translations Specifies the localized strings that identifies the accessibility elements and their states	{ listLabel?: string }
unmountOnExit When true, the component will be completely removed from the DOM when it becomes inactive or hidden, rather than just being hidden with CSS.	boolean	false
value The controlled value of the combobox's selected items	string[]

allowCustomValue

Type

boolean

Description

Whether to allow typing custom values in the input

alwaysSubmitOnEnter

Type

boolean

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.

autoFocus

Type

boolean

Description

Whether to autofocus the input on mount

closeOnSelect

Type

boolean

Description

Whether to close the combobox when an item is selected.

collection

Type

ListCollection

Description

The collection of items

composite

Type

boolean

Description

Whether the combobox is a composed with other composite widgets like tabs

defaultHighlightedValue

Type

string

Description

The initial highlighted value of the combobox when rendered. Use when you don't need to control the highlighted value of the combobox.

defaultInputValue

Type

string

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.

defaultOpen

Type

boolean

Description

The initial open state of the combobox when rendered. Use when you don't need to control the open state of the combobox.

defaultValue

Type

string[]

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.

dir

Type

'ltr' | 'rtl'

Description

The document's text/writing direction.

disabled

Type

boolean

Description

Whether the combobox is disabled

disableLayer

Type

boolean

Description

Whether to disable registering this as a dismissable layer

form

Type

string

Description

The associate form of the combobox.

getRootNode

Type

() =>
| Node
| ShadowRoot
| Document

Description

A root node to correctly resolve document in custom environments. i.e., Iframes, Electron.

highlightedValue

Type

string

Description

The controlled highlighted value of the combobox

icon

Type

| LucideIcon
| ReactNode

Description

lucide icon, positioned at the start of the input field.

Type

string

Description

id attribute. If omitted, a unique identifier will be automatically generated for accessibility.

ids

Type

Partial<{
  clearTrigger: string
  content: string
  control: string
  errorText: string
  hint: string
  input: string
  label: string
  positioner: string
  root: string
  trigger: string
}>

Description

The ids of the combobox's elements. If omitted, these will be generated automatically.

immediate

Type

boolean

Description

Whether to synchronize the present change immediately or defer it to the next frame

inputBehavior

Type

| 'none'
| 'autohighlight'
| 'autocomplete'

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

inputValue

Type

string

Description

The controlled value of the combobox's input

invalid

Type

boolean

Description

Whether the combobox is invalid

lazyMount

Type

boolean

Description

When true, the component will not be rendered in the DOM until it becomes visible or active.

loopFocus

Type

boolean

Description

Whether to loop the keyboard navigation through the items

multiple

Type

boolean

Description

Whether to allow multiple selection.

When multiple is true, the selectionBehavior is automatically set to clear. It's recommended to render the selected items in a separate container.

name

Type

string

Description

The name attribute of the combobox's input. Useful for form submission

onExitComplete

Type

VoidFunction

Description

Function called when the animation ends in the closed state

onFocusOutside

Type

(
  event: FocusOutsideEvent,
) => void

Description

Function called when the focus is moved outside the component

onHighlightChange

Type

(details: {
  highlightedItem: T
  highlightedValue: string
}) => void

Description

Function called when an item is highlighted using the pointer or keyboard navigation.

onInputValueChange

Type

(details: {
  inputValue: string
  reason?:
    | 'input-change'
    | 'item-select'
    | 'clear-trigger'
    | 'script'
    | 'interact-outside'
}) => void

Description

Function called when the input's value changes

onInteractOutside

Type

(
  event: InteractOutsideEvent,
) => void

Description

Function called when an interaction happens outside the component

onOpenChange

Type

(details: {
  open: boolean
  reason?:
    | 'input-click'
    | 'trigger-click'
    | 'script'
    | 'arrow-key'
    | 'input-change'
    | 'interact-outside'
    | 'escape-key'
    | 'item-select'
    | 'clear-trigger'
    | 'input-focus'
}) => void

Description

Function called when the popup is opened

onPointerDownOutside

Type

(
  event: PointerDownOutsideEvent,
) => void

Description

Function called when the pointer is pressed down outside the component

onSelect

Type

(details: {
  itemValue: string
  value: string[]
}) => void

Description

Function called when an item is selected

onValueChange

Type

(details: {
  items: Array<T>
  value: string[]
}) => void

Description

Function called when a new item is selected

open

Type

boolean

Description

The controlled open state of the combobox

openOnChange

Type

| boolean
| ((details: {
    inputValue: string
    reason?:
      | 'input-change'
      | 'item-select'
      | 'clear-trigger'
      | 'script'
      | 'interact-outside'
  }) => boolean)

Description

Whether to show the combobox when the input value changes

openOnClick

Type

boolean

Description

Whether to open the combobox popup on initial click on the input

openOnKeyPress

Type

boolean

Description

Whether to open the combobox on arrow key press

placeholder

Type

string

Description

The placeholder text of the combobox's input

positioning

Type

ComboboxPositioningOptions

Description

The positioning options to dynamically position the popup menu

present

Type

boolean

Description

Whether the node is present (controlled by the user)

readOnly

Type

boolean

Description

Whether the combobox is readonly. This puts the combobox in a "non-editable" mode but the user can still interact with it

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

required

Type

boolean

Description

Whether the combobox is a required input field

scrollToIndexFn

Type

(details: {
  getElement: () => HTMLElement
  immediate?: boolean
  index: number
}) => void

Description

Function to scroll to a specific index

selectionBehavior

Type

| 'replace'
| 'clear'
| 'preserve'

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

selectionIndicator

Type

| 'checkmark'
| 'checkbox'

Description

Visual indicator style for selected items. Use "checkbox" for multi-select with always-visible checkboxes on the left, or "checkmark" for a checkmark icon on the right that only appears when selected.

size

Type

| 'sm'
| 'md'
| 'lg'

Description

The size of the select and its elements. Governs properties like font size, item padding, and icon sizes.

skipAnimationOnMount

Type

boolean

Description

Whether to allow the initial presence animation.

translations

Type

{
  listLabel?: string
}

Description

Specifies the localized strings that identifies the accessibility elements and their states

unmountOnExit

Type

boolean

Description

When true, the component will be completely removed from the DOM when it becomes inactive or hidden, rather than just being hidden with CSS.

value

Type

string[]

Description

The controlled value of the combobox's selected items

<Combobox.Label>

Label text associated with the combobox. Renders a <label> element by default.

Prop	Type
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-select__label'
`data-combobox-part`	'label'
`data-disabled`
`data-focus`
`data-invalid`
`data-readonly`
`data-required`

className

Value

'qui-select__label'

data-combobox-part

Value

'label'

data-disabled

Value

data-focus

Value

data-invalid

Value

data-readonly

Value

data-required

Value

<Combobox.Control>

Container for the input element and associated controls. Renders a <div> element by default.

Prop	Type
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-select__control'
`data-combobox-part`	'control'
`data-disabled`
`data-focus`
`data-invalid`
`data-size`	\| 'sm' \| 'md' \| 'lg'
`data-state`	\| 'open' \| 'closed'

className

Value

'qui-select__control'

data-combobox-part

Value

'control'

data-disabled

Value

data-focus

Value

data-invalid

Value

data-size

Value

| 'sm'
| 'md'
| 'lg'

data-state

Value

| 'open'
| 'closed'

<Combobox.Input>

Text input element for filtering and selecting items. Renders an <input> element by default.

Attribute / Property	Value
`className`	'qui-input__input'
`data-autofocus`
`data-combobox-part`	'input'
`data-invalid`
`data-size`	\| 'sm' \| 'md' \| 'lg'
`data-state`	\| 'open' \| 'closed'

className

Value

'qui-input__input'

data-autofocus

Value

data-combobox-part

Value

'input'

data-invalid

Value

data-size

Value

| 'sm'
| 'md'
| 'lg'

data-state

Value

| 'open'
| 'closed'

<Combobox.Trigger>

Icon that indicates the open/close state of the combobox's associated panel. Renders a <button> element by default.

Prop	Type	Default
focusable Whether the trigger is focusable	boolean
icon Dropdown visibility indicator icon. This automatically rotates when the dropdown is visible.	\| ReactNode \| LucideIcon	ChevronDown
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

focusable

Type

boolean

Description

Whether the trigger is focusable

icon

Type

| ReactNode
| LucideIcon

Description

Dropdown visibility indicator icon. This automatically rotates when the dropdown is visible.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-select__indicator'
`data-combobox-part`	'trigger'
`data-disabled`
`data-focusable`
`data-invalid`
`data-readonly`
`data-size`	\| 'sm' \| 'md' \| 'lg'
`data-state`	\| 'open' \| 'closed'
`tabIndex`	-1

className

Value

'qui-select__indicator'

data-combobox-part

Value

'trigger'

data-disabled

Value

data-focusable

Value

data-invalid

Value

data-readonly

Value

data-size

Value

| 'sm'
| 'md'
| 'lg'

data-state

Value

| 'open'
| 'closed'

tabIndex

Value

-1

<Combobox.ClearTrigger>

Button that clears the input value. Renders a <button> element by default.

Prop	Type
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-select__clear-trigger'
`data-combobox-part`	'clear-trigger'
`data-invalid`
`data-size`	\| 'sm' \| 'md' \| 'lg'
`hidden`	boolean
`tabIndex`	-1

className

Value

'qui-select__clear-trigger'

data-combobox-part

Value

'clear-trigger'

data-invalid

Value

data-size

Value

| 'sm'
| 'md'
| 'lg'

hidden

Value

boolean

tabIndex

Value

-1

<Combobox.Positioner>

Positions the combobox menu relative to the control. Renders a <div> element by default.

Prop	Type
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-select__positioner'
`data-combobox-part`	'positioner'
`style`	CSSProperties

className

Value

'qui-select__positioner'

data-combobox-part

Value

'positioner'

style

Value

CSSProperties

<Combobox.Content>

Container for the combobox options. Renders a <div> element by default.

Prop	Type
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-select__content'
`data-combobox-part`	'content'
`data-disabled`
`data-empty`
`data-focus-visible`
`data-placement`	\| 'bottom' \| 'bottom-end' \| 'bottom-start' \| 'left' \| 'left-end' \| 'left-start' \| 'right' \| 'right-end' \| 'right-start' \| 'top' \| 'top-end' \| 'top-start'
`data-state`	\| 'open' \| 'closed'
`hidden`	boolean
`tabIndex`	-1

className

Value

'qui-select__content'

data-combobox-part

Value

'content'

data-disabled

Value

data-empty

Value

data-focus-visible

Value

data-placement

Value

| 'bottom'
| 'bottom-end'
| 'bottom-start'
| 'left'
| 'left-end'
| 'left-start'
| 'right'
| 'right-end'
| 'right-start'
| 'top'
| 'top-end'
| 'top-start'

data-state

Value

| 'open'
| 'closed'

hidden

Value

boolean

tabIndex

Value

-1

<Combobox.Item>

Individual option within the combobox menu. Renders a <div> element by default.

Prop	Type
item ^* The item to render	T
persistFocus Whether hovering outside should clear the highlighted state	boolean
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

item

Type

Description

The item to render

persistFocus

Type

boolean

Description

Whether hovering outside should clear the highlighted state

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-select__item'
`data-combobox-part`	'item'
`data-disabled`
`data-highlighted`
`data-selection-indicator`	\| 'checkmark' \| 'checkbox'
`data-size`	\| 'sm' \| 'md' \| 'lg'
`data-state`	\| 'checked' \| 'unchecked'
`data-value`	string
`tabIndex`	-1

className

Value

'qui-select__item'

data-combobox-part

Value

'item'

data-disabled

Value

data-highlighted

Value

data-selection-indicator

Value

| 'checkmark'
| 'checkbox'

data-size

Value

| 'sm'
| 'md'
| 'lg'

data-state

Value

| 'checked'
| 'unchecked'

data-value

Value

string

tabIndex

Value

-1

<Combobox.ItemIndicator>

Visual indicator showing the selected state of an item. Renders a <span> element by default.

Prop	Type	Default
children React children prop.	ReactNode	<Icon icon={Check}/>
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

children

Type

ReactNode

Description

React children prop.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`data-combobox-part`	'item-indicator'
`data-state`	\| 'checked' \| 'unchecked'
`hidden`	boolean

data-combobox-part

Value

'item-indicator'

data-state

Value

| 'checked'
| 'unchecked'

hidden

Value

boolean

<Combobox.ItemText>

Text content of a combobox item. Renders a <span> element by default.

Prop	Type
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-select__item-text'
`data-combobox-part`	'item-text'
`data-disabled`
`data-highlighted`
`data-state`	\| 'checked' \| 'unchecked'

className

Value

'qui-select__item-text'

data-combobox-part

Value

'item-text'

data-disabled

Value

data-highlighted

Value

data-state

Value

| 'checked'
| 'unchecked'

<Combobox.Hint>

Helper text displayed below the input. Renders a <div> element by default.

Prop	Type
children React children prop.	ReactNode
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

children

Type

ReactNode

Description

React children prop.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-input__hint'
`data-disabled`
`data-select-part`	'hint'
`hidden`	boolean

<Combobox.ErrorText>

Error message displayed when the input is invalid. Renders a <div> element by default.

Prop	Type
icon An icon to display next to the error text.	\| LucideIcon \| ReactNode
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

icon

Type

| LucideIcon
| ReactNode

Description

An icon to display next to the error text.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-input__error-text'
`data-select-part`	'error-text'
`hidden`	boolean

<Combobox.ErrorIndicator>

Visual indicator displayed when the input is invalid. Renders a <div> element by default.

Prop	Type	Default
icon lucide-react icon or ReactNode.	\| LucideIcon \| ReactNode	CircleAlert
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

icon

Type

| LucideIcon
| ReactNode

Description

lucide-react icon or ReactNode.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`data-combobox-part`	'error-indicator'
`hidden`	boolean

Data Structures

ListCollection

The following describes the member variables and methods of the ListCollection class. The Combobox component uses an instance of this class as input:

const collection = comboboxCollection({
  items: [
    // ...
  ],
})

return <Combobox collection={collection} />

Note that the ListCollection accepts a single generic type parameter, T, which is the type of each list item used in the collection. This can be a string or an object.

Constructor

Prop	Type
groupBy Function to group items	( item: T, index: number, ) => string
groupSort Function to sort items	\| string[] \| 'desc' \| 'asc' \| (( a: string, b: string, ) => number)
itemDisabled Function to determine if a node is disabled.	( item: T, ) => boolean
itemLabel Function to get the item's label.	( item: T, ) => string
items The options of the select	\| Iterable<T, any, any> \| Readonly< Iterable<T, any, any> >
itemValue Function to get the item's unique value.	( item: T, ) => string

groupBy

Type

(
  item: T,
  index: number,
) => string

Description

Function to group items

groupSort

Type

| string[]
| 'desc'
| 'asc'
| ((
    a: string,
    b: string,
  ) => number)

Description

Function to sort items

itemDisabled

Type

(
  item: T,
) => boolean

Description

Function to determine if a node is disabled.

itemLabel

Type

(
  item: T,
) => string

Description

Function to get the item's label.

items

Type

| Iterable<T, any, any>
| Readonly<
    Iterable<T, any, any>
  >

Description

The options of the select

itemValue

Type

(
  item: T,
) => string

Description

Function to get the item's unique value.

A collection of list items, commonly used in Select and Combobox components.

Prop	Type
append Append items to the collection	( items: Array<T>, ) => ListCollection<T>
at Get the item based on its index	( index: number, ) => T
compareValue Compare two values	( a: string, b: string, ) => -1 \| 0 \| 1
copy Copy the collection	(items Array<T>,) => ListCollection<T>
filter Filter the collection	( fn: ( itemString: string, index: number, item: T, ) => boolean, ) => ListCollection<T>
find Get the item based on its value	( value: string, ) => T
findMany Get the items based on its values	( values: string[], ) => Array<T>
firstValue Returns the first value in the collection	string
getItemDisabled Whether an item is disabled	( T, ) => boolean
getItemValue Convert an item to a value	( T, ) => string
getNextValue Returns the next value in the collection	( value: string, step: number, clamp: boolean, ) => string
getPreviousValue Returns the previous value in the collection	( value: string, step: number, clamp: boolean, ) => string
getValueRange Get the range of values between two values	( from: string, to: string, ) => string[]
getValues Returns all the values in the collection	( items: Array<T>, ) => string[]
group Group items by the groupBy function provided in options Returns an array of [groupKey, items] tuples	() => Array< [string, Array<T>] >
has Whether the collection has a value	( value: string, ) => boolean
hasItem Whether the collection has an item	( T, ) => boolean
indexOf Get the index of an item based on its key	( value: string, ) => number
insert Insert items at a specific index	( index: number, items: Array<T>, ) => ListCollection<T>
insertAfter Insert items after a specific value	( value: string, items: Array<T>, ) => ListCollection<T>
insertBefore Insert items before a specific value	( value: string, items: Array<T>, ) => ListCollection<T>
isEqual Check if the collection is equal to another collection	( any, ) => boolean
items The items in the collection	Array<T>
lastValue Returns the last value in the collection	string
move Move an item to a specific index	( value: string, toIndex: number, ) => ListCollection<T>
moveAfter Move items after a specific value	( value: string, values: string[], ) => ListCollection<T>
moveBefore Move items before a specific value	( value: string, values: string[], ) => ListCollection<T>
prepend Prepend items to the collection	( items: Array<T>, ) => ListCollection<T>
remove Remove items from the collection	( itemsOrValues: Array< string \| T >, ) => ListCollection<T>
reorder Reorder items	( fromIndex: number, toIndex: number, ) => ListCollection<T>
search Search for a value based on a query	( queryString: string, { currentValue: string state: { keysSoFar: string timer: number } timeout?: number }, ) => string
setItems Function to update the collection items	( items: Array<T>, ) => ListCollection<T>
size Returns the number of items in the collection	number
sort Sort the values based on their index	( values: string[], ) => string[]
stringify Convert a value to a string	( value: string, ) => string
stringifyItem Convert an item to a string	( T, ) => string
stringifyItems Convert an array of items to a string	( items: Array<T>, separator: string, ) => string
stringifyMany Convert an array of items to a string	(value: string[],separator string,) => string
toJSON Convert the collection to a JSON object	() => { first: string last: string size: number }
toString Convert the collection to a string	() => string
update Update an item in the collection	( value: string, T, ) => ListCollection<T>
upsert Update an item in the collection if it exists, otherwise append it	( value: string, T, mode: 'append' \| 'prepend', ) => ListCollection<T>

append

Type

(
  items: Array<T>,
) => ListCollection<T>

Description

Append items to the collection

Type

(
  index: number,
) => T

Description

Get the item based on its index

compareValue

Type

(
  a: string,
  b: string,
) => -1 | 0 | 1

Description

Compare two values

copy

Type

(items Array<T>,) => ListCollection<T>

Description

Copy the collection

filter

Type

(
  fn: (
    itemString: string,
    index: number,
    item: T,
  ) => boolean,
) => ListCollection<T>

Description

Filter the collection

find

Type

(
  value: string,
) => T

Description

Get the item based on its value

findMany

Type

(
  values: string[],
) => Array<T>

Description

Get the items based on its values

firstValue

Type

string

Description

Returns the first value in the collection

getItemDisabled

Type

(
  T,
) => boolean

Description

Whether an item is disabled

getItemValue

Type

(
  T,
) => string

Description

Convert an item to a value

getNextValue

Type

(
  value: string,
  step: number,
  clamp: boolean,
) => string

Description

Returns the next value in the collection

getPreviousValue

Type

(
  value: string,
  step: number,
  clamp: boolean,
) => string

Description

Returns the previous value in the collection

getValueRange

Type

(
  from: string,
  to: string,
) => string[]

Description

Get the range of values between two values

getValues

Type

(
  items: Array<T>,
) => string[]

Description

Returns all the values in the collection

group

Type

() => Array<
  [string, Array<T>]
>

Description

Group items by the groupBy function provided in options Returns an array of [groupKey, items] tuples

has

Type

(
  value: string,
) => boolean

Description

Whether the collection has a value

hasItem

Type

(
  T,
) => boolean

Description

Whether the collection has an item

indexOf

Type

(
  value: string,
) => number

Description

Get the index of an item based on its key

insert

Type

(
  index: number,
  items: Array<T>,
) => ListCollection<T>

Description

Insert items at a specific index

insertAfter

Type

(
  value: string,
  items: Array<T>,
) => ListCollection<T>

Description

Insert items after a specific value

insertBefore

Type

(
  value: string,
  items: Array<T>,
) => ListCollection<T>

Description

Insert items before a specific value

isEqual

Type

(
  any,
) => boolean

Description

Check if the collection is equal to another collection

items

Type

Array<T>

Description

The items in the collection

lastValue

Type

string

Description

Returns the last value in the collection

move

Type

(
  value: string,
  toIndex: number,
) => ListCollection<T>

Description

Move an item to a specific index

moveAfter

Type

(
  value: string,
  values: string[],
) => ListCollection<T>

Description

Move items after a specific value

moveBefore

Type

(
  value: string,
  values: string[],
) => ListCollection<T>

Description

Move items before a specific value

prepend

Type

(
  items: Array<T>,
) => ListCollection<T>

Description

Prepend items to the collection

remove

Type

(
  itemsOrValues: Array<
    string | T
  >,
) => ListCollection<T>

Description

Remove items from the collection

reorder

Type

(
  fromIndex: number,
  toIndex: number,
) => ListCollection<T>

Description

Reorder items

Type

(
  queryString: string,
  {
    currentValue: string
    state: {
      keysSoFar: string
      timer: number
    }
    timeout?: number
  },
) => string

Description

Search for a value based on a query

setItems

Type

(
  items: Array<T>,
) => ListCollection<T>

Description

Function to update the collection items

size

Type

number

Description

Returns the number of items in the collection

sort

Type

(
  values: string[],
) => string[]

Description

Sort the values based on their index

stringify

Type

(
  value: string,
) => string

Description

Convert a value to a string

stringifyItem

Type

(
  T,
) => string

Description

Convert an item to a string

stringifyItems

Type

(
  items: Array<T>,
  separator: string,
) => string

Description

Convert an array of items to a string

stringifyMany

Type

(value: string[],separator string,) => string

Description

Convert an array of items to a string

toJSON

Type

() => {
  first: string
  last: string
  size: number
}

Description

Convert the collection to a JSON object

toString

Type

() => string

Description

Convert the collection to a string

update

Type

(
  value: string,
  T,
) => ListCollection<T>

Description

Update an item in the collection

upsert

Type

(
  value: string,
  T,
  mode: 'append' | 'prepend',
) => ListCollection<T>

Description

Update an item in the collection if it exists, otherwise append it

ComboboxPositioningOptions

Prop	Type	Default
arrowPadding The minimum padding between the arrow and the floating element's corner.	number	4
arrowSelector CSS selector used to locate the arrow element within the floating element. Components override this with their own anatomy-namespaced selector (e.g. `[data-menu-part=arrow]`).	string
boundary The overflow boundary of the reference element	() => \| 'clippingAncestors' \| Element \| Array<Element> \| { height: number width: number x: number y: number }
fitViewport Whether the popover should fit the viewport.	boolean
flip Whether to flip the placement when the floating element overflows the boundary.	\| boolean \| Array< \| 'bottom' \| 'bottom-end' \| 'bottom-start' \| 'left' \| 'left-end' \| 'left-start' \| 'right' \| 'right-end' \| 'right-start' \| 'top' \| 'top-end' \| 'top-start' >	true
getAnchorRect Function that returns the anchor rect	( element: \| HTMLElement \| VirtualElement, ) => { height?: number width?: number x?: number y?: number }
gutter The main axis offset or gap between the reference and floating element	number	2
hideWhenDetached Whether the popover should be hidden when the reference element is detached	boolean
listeners Options to activate auto-update listeners	\| boolean \| { ancestorResize?: boolean ancestorScroll?: boolean animationFrame?: boolean elementResize?: boolean layoutShift?: boolean }	true
offset The offset of the floating element	{ crossAxis?: number mainAxis?: number }
onComplete Function called when the placement is computed	( data: ComputePositionReturn, ) => void
onPositioned Function called when the floating element is positioned or not	(data: { placed: boolean }) => void
overflowPadding The virtual padding around the viewport edges to check for overflow	number
overlap Whether the floating element can overlap the reference element	boolean	false
placement The initial placement of the floating element	\| 'bottom' \| 'bottom-end' \| 'bottom-start' \| 'left' \| 'left-end' \| 'left-start' \| 'right' \| 'right-end' \| 'right-start' \| 'top' \| 'top-end' \| 'top-start'	'bottom-start'
sameWidth Whether to make the floating element same width as the reference element	boolean	true
shift The secondary axis offset or gap between the reference and floating elements	number
slide Whether the popover should slide when it overflows.	boolean
strategy The strategy to use for positioning	\| 'absolute' \| 'fixed'	'absolute'
updatePosition A callback that will be called when the popover needs to calculate its position.	(data: { updatePosition: () => Promise<void> }) => void \| Promise<void>

arrowPadding

Type

number

Description

The minimum padding between the arrow and the floating element's corner.

arrowSelector

Type

string

Description

CSS selector used to locate the arrow element within the floating element. Components override this with their own anatomy-namespaced selector (e.g. [data-menu-part=arrow]).

boundary

Type

() =>
| 'clippingAncestors'
| Element
| Array<Element>
| {
    height: number
    width: number
    x: number
    y: number
  }

Description

The overflow boundary of the reference element

fitViewport

Type

boolean

Description

Whether the popover should fit the viewport.

flip

Type

| boolean
| Array<
    | 'bottom'
    | 'bottom-end'
    | 'bottom-start'
    | 'left'
    | 'left-end'
    | 'left-start'
    | 'right'
    | 'right-end'
    | 'right-start'
    | 'top'
    | 'top-end'
    | 'top-start'
  >

Description

Whether to flip the placement when the floating element overflows the boundary.

getAnchorRect

Type

(
  element:
    | HTMLElement
    | VirtualElement,
) => {
  height?: number
  width?: number
  x?: number
  y?: number
}

Description

Function that returns the anchor rect

gutter

Type

number

Description

The main axis offset or gap between the reference and floating element

hideWhenDetached

Type

boolean

Description

Whether the popover should be hidden when the reference element is detached

listeners

Type

| boolean
| {
    ancestorResize?: boolean
    ancestorScroll?: boolean
    animationFrame?: boolean
    elementResize?: boolean
    layoutShift?: boolean
  }

Description

Options to activate auto-update listeners

offset

Type

{
  crossAxis?: number
  mainAxis?: number
}

Description

The offset of the floating element

onComplete

Type

(
  data: ComputePositionReturn,
) => void

Description

Function called when the placement is computed

onPositioned

Type

(data: {
  placed: boolean
}) => void

Description

Function called when the floating element is positioned or not

overflowPadding

Type

number

Description

The virtual padding around the viewport edges to check for overflow

overlap

Type

boolean

Description

Whether the floating element can overlap the reference element

placement

Type

| 'bottom'
| 'bottom-end'
| 'bottom-start'
| 'left'
| 'left-end'
| 'left-start'
| 'right'
| 'right-end'
| 'right-start'
| 'top'
| 'top-end'
| 'top-start'

Description

The initial placement of the floating element

sameWidth

Type

boolean

Description

Whether to make the floating element same width as the reference element

shift

Type

number

Description

The secondary axis offset or gap between the reference and floating elements

slide

Type

boolean

Description

Whether the popover should slide when it overflows.

strategy

Type

| 'absolute'
| 'fixed'

Description

The strategy to use for positioning

updatePosition

Type

(data: {
  updatePosition: () => Promise<void>
}) => void | Promise<void>

Description

A callback that will be called when the popover needs to calculate its position.

Last updated on May 23, 2026 by Ryan Bower

Collapsible

Dialog