Select

import {Select} from "@qualcomm-ui/react/select"

Overview

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

Examples

Simple

The simple API provides a standalone component with built-in layout.

Brand

<Select
  className="w-48"
  collection={cityCollection}
  controlProps={{"aria-label": "City"}}
  placeholder="Select a city"
/>

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.

Brand

City

<Select.Root
  className="w-48"
  collection={cityCollection}
  placeholder="Select a city"
>
  <Select.Label>City</Select.Label>

  <Select.Control>
    <Select.ValueText />
    <Select.ClearTrigger />
    <Select.Indicator />
    <Select.ErrorIndicator />
  </Select.Control>

  <Select.HiddenSelect />

  <Portal>
    <Select.Positioner>
      <Select.Content>
        {cityCollection.items.map((item) => {
          const label = cityCollection.stringifyItem(item)
          const value = cityCollection.getItemValue(item)
          return (
            <Select.Item key={value} item={item}>
              <Select.ItemText>{label}</Select.ItemText>
              <Select.ItemIndicator />
            </Select.Item>
          )
        })}
      </Select.Content>
    </Select.Positioner>
  </Portal>
</Select.Root>

ARIA Label

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

Brand

<Select
  className="w-48"
  collection={cityCollection}
  controlProps={{"aria-label": "City"}}
  placeholder="Select a city"
/>

Content Width

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

Brand

<Select
  className="w-48"
  collection={cityCollection}
  controlProps={{"aria-label": "City"}}
  placeholder="Select a city"
  positioning={{sameWidth: false}}
/>

Trigger Icon

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

Brand

<Select
  className="w-48"
  collection={cityCollection}
  controlProps={{"aria-label": "City"}}
  icon={MapPin}
  placeholder="Select a city"
/>

Items as Objects

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

Brand

const cityCollection = selectCollection({
  itemLabel: (item) => item.name,
  items: [
    {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"},
  ],
  itemValue: (item) => item.value,
})

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.

Brand

Content Height

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

Brand

<Select
  className="w-48"
  collection={cityCollection}
  contentProps={{style: {maxHeight: 240}}}
  controlProps={{"aria-label": "City"}}
  placeholder="Select a city"
  positioning={{sameWidth: true}}
/>

Multiple Selection

Use the multiple prop to allow multiple selections.

Brand

<Select
  className="w-72"
  collection={cityCollection}
  controlProps={{"aria-label": "City"}}
  multiple
  placeholder="Select a city"
/>

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.

Brand

<Select
  className="w-48"
  collection={cityCollection}
  controlProps={{"aria-label": "City"}}
  onValueChange={setValue}
  placeholder="Select a city"
  value={value}
/>

States

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

Brand

Disabled

Read only

Invalid

<Select
  className="w-48"
  collection={cityCollection}
  defaultValue={["San Diego"]}
  disabled
  label="Disabled"
/>
<Select
  className="w-48"
  collection={cityCollection}
  defaultValue={["San Diego"]}
  label="Read only"
  readOnly
/>
<Select
  className="w-48"
  collection={cityCollection}
  defaultValue={["San Diego"]}
  errorText="Invalid"
  invalid
  label="Invalid"
/>

Error Text and Indicator

Error messages are displayed using two props:

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

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

Brand

You must select a city

<Select
  className="w-48"
  collection={cityCollection}
  controlProps={{"aria-label": "City"}}
  errorText="You must select a city"
  invalid={!value.length}
  onValueChange={setValue}
  placeholder="Select a city"
  value={value}
/>

Within Dialog

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

Brand

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

Brand

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.

Brand

import type {ReactElement} from "react"

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

import {selectCollection} from "@qualcomm-ui/core/select"
import {Button} from "@qualcomm-ui/react/button"
import {Select} from "@qualcomm-ui/react/select"
import {createToaster, Toaster} from "@qualcomm-ui/react/toast"

const cityCollection = selectCollection({
  items: [
    "San Diego",
    "Nashville",
    "Denver",
    "Miami",
    "Las Vegas",
    "New York City",
    "San Francisco",
  ],
})

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

type ValueSchema = typeof valueSchema.infer

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

export default function Demo(): ReactElement {
  const {
    control,
    formState: {isSubmitting},
    handleSubmit,
    setError,
  } = useForm<ValueSchema>({
    defaultValues: {
      city: [],
    },
  })

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

    if (validation instanceof type.errors) {
      validation.forEach((error) => {
        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={handleSubmit(handleFormSubmit)}
      >
        <Controller
          control={control}
          name="city"
          render={({field: {onChange, ...fieldProps}, fieldState: {error}}) => (
            <Select
              className="w-full"
              collection={cityCollection}
              errorText={error?.message}
              invalid={!!error}
              label="City"
              onValueChange={(valueStrings) => onChange(valueStrings)}
              placeholder="Select a city"
              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.

Brand

import type {ReactElement} from "react"

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

import {selectCollection} from "@qualcomm-ui/core/select"
import {Button} from "@qualcomm-ui/react/button"
import {Select} from "@qualcomm-ui/react/select"
import {createToaster, Toaster} from "@qualcomm-ui/react/toast"

const cityCollection = selectCollection({
  items: [
    "San Diego",
    "Nashville",
    "Denver",
    "Miami",
    "Las Vegas",
    "New York City",
    "San Francisco",
  ],
})

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

export default function Demo(): ReactElement {
  const form = useForm({
    defaultValues: {
      city: [] as string[],
    },
    onSubmit: async () => {
      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="city"
          validators={{
            onChange: ({value}) =>
              value.length === 0
                ? "At least one city must be selected"
                : undefined,
          }}
        >
          {(field) => (
            <Select
              className="w-full"
              collection={cityCollection}
              errorText={field.state.meta.errors[0]}
              invalid={field.state.meta.errors.length > 0}
              label="City"
              onValueChange={field.handleChange}
              placeholder="Select a city"
              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.

API

<Select>

The simple select extends the Select.Root component with the following props:

Prop	Type	Default
clearable When `true`, renders a clear button that resets the input value on click. The button only appears when the input has a value.	boolean	true
clearTriggerProps Props applied to the clear trigger element.	SelectClearTriggerProps
contentProps Props applied to the content element.	SelectContentProps
controlProps Props applied to the trigger element.	SelectControlProps
errorIndicatorProps Props applied to the error indicator element.	SelectErrorIndicatorProps
errorText Optional error that describes the element when invalid is true.	ReactNode
errorTextProps Props applied to the error text element.	SelectErrorTextProps
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.	SelectHintProps
indicatorProps Props applied to the indicator element.	SelectIndicatorProps
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.	SelectLabelProps
portalProps Props applied to the portal element.	PortalProps
positionerProps Props applied to the positioner element.	SelectPositionerProps
selectProps Props applied to the select element.	SelectHiddenSelectProps
valueTextProps Props applied to the value text element.	SelectValueTextProps

clearable

Type

boolean

Description

When true, renders a clear button that resets the input value on click. The button only appears when the input has a value.

clearTriggerProps

Type

SelectClearTriggerProps

Description

Props applied to the clear trigger element.

contentProps

Type

SelectContentProps

Description

Props applied to the content element.

controlProps

Type

SelectControlProps

Description

Props applied to the trigger element.

errorIndicatorProps

Type

SelectErrorIndicatorProps

Description

Props applied to the error indicator element.

errorText

Type

ReactNode

Description

Optional error that describes the element when invalid is true.

errorTextProps

Type

SelectErrorTextProps

Description

Props applied to the error text element.

hint

Type

ReactNode

Description

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

hintProps

Type

SelectHintProps

Description

Props applied to the label element.

indicatorProps

Type

SelectIndicatorProps

Description

Props applied to the indicator 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

SelectLabelProps

Description

Props applied to the label element.

portalProps

Type

PortalProps

Description

Props applied to the portal element.

positionerProps

Type

SelectPositionerProps

Description

Props applied to the positioner element.

selectProps

Type

SelectHiddenSelectProps

Description

Props applied to the select element.

valueTextProps

Type

SelectValueTextProps

Description

Props applied to the value text element.

Composite API

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

<Select.Root>

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

Prop	Type	Default
collection ^* The item collection	ListCollection
closeOnSelect Whether the select should close after an item is selected	boolean	true
defaultHighlightedValue The initial value of the highlighted item when opened. Use when you don't need to control the highlighted value of the select.	string
defaultOpen Whether the select's open state is controlled by the user	boolean
defaultValue The initial default value of the select when rendered. Use when you don't need to control the value of the select.	string[]
deselectable Whether the value can be cleared by clicking the selected item. This is only applicable for single selection.	boolean
dir The document's text/writing direction.	'ltr' \| 'rtl'	'ltr'
disabled Whether the select is disabled	boolean
form The associate form of the underlying select.	string
getRootNode A root node to correctly resolve document in custom environments. i.e., Iframes, Electron.	() => \| Node \| ShadowRoot \| Document
highlightedValue The controlled key of the highlighted item	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 elements that are associated with the select. These will be automatically generated if omitted.	Partial< Omit< { clearTrigger: string content: string control: string errorText: string hiddenSelect: string hint: string label: string positioner: string root: string }, \| 'item' \| 'itemGroupLabel' \| 'itemGroup' > >
immediate Whether to synchronize the present change immediately or defer it to the next frame	boolean
invalid Whether the select 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 options	boolean	false
multiple Whether to allow multiple selection	boolean	false
name The `name` attribute of the underlying select.	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 The callback fired when the highlighted item changes.	( value: string, details: { highlightedIndex: number highlightedItem: T }, ) => void
onInteractOutside Function called when an interaction happens outside the component	( event: InteractOutsideEvent, ) => void
onOpenChange Function invoked when the popup opens or closes openThe next value of the open state.	( open: boolean, ) => void
onPointerDownOutside Function called when the pointer is pressed down outside the component	( event: PointerDownOutsideEvent, ) => void
onSelect Function called when an item is selected	( value: string, ) => void
onValueChange The callback fired when the selected item changes.	( valueStrings: string[], details: {items: Array<T>}, ) => void
open Whether the select menu is open	boolean
placeholder Placeholder text to display when no value is selected.	string	"Select an option"
positioning The positioning options of the menu.	SelectPositioningOptions
present Whether the node is present (controlled by the user)	boolean
readOnly Whether the select is read-only	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 select is required	boolean
scrollToIndexFn Function to scroll to a specific index	(details: { immediate?: boolean index: number }) => void
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
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 keys of the selected items	string[]

collection

Type

ListCollection

Description

The item collection

closeOnSelect

Type

boolean

Description

Whether the select should close after an item is selected

defaultHighlightedValue

Type

string

Description

The initial value of the highlighted item when opened. Use when you don't need to control the highlighted value of the select.

defaultOpen

Type

boolean

Description

Whether the select's open state is controlled by the user

defaultValue

Type

string[]

Description

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

deselectable

Type

boolean

Description

Whether the value can be cleared by clicking the selected item.

This is only applicable for single selection.

dir

Type

'ltr' | 'rtl'

Description

The document's text/writing direction.

disabled

Type

boolean

Description

Whether the select is disabled

form

Type

string

Description

The associate form of the underlying select.

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 key of the highlighted item

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<
  Omit<
    {
      clearTrigger: string
      content: string
      control: string
      errorText: string
      hiddenSelect: string
      hint: string
      label: string
      positioner: string
      root: string
    },
    | 'item'
    | 'itemGroupLabel'
    | 'itemGroup'
  >
>

Description

The ids of the elements that are associated with the select. These will be automatically generated if omitted.

immediate

Type

boolean

Description

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

invalid

Type

boolean

Description

Whether the select 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 options

multiple

Type

boolean

Description

Whether to allow multiple selection

name

Type

string

Description

The name attribute of the underlying select.

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

(
  value: string,
  details: {
    highlightedIndex: number
    highlightedItem: T
  },
) => void

Description

The callback fired when the highlighted item changes.

onInteractOutside

Type

(
  event: InteractOutsideEvent,
) => void

Description

Function called when an interaction happens outside the component

onOpenChange

Type

(
  open: boolean,
) => void

Description

Function invoked when the popup opens or closes

openThe next value of the open state.

onPointerDownOutside

Type

(
  event: PointerDownOutsideEvent,
) => void

Description

Function called when the pointer is pressed down outside the component

onSelect

Type

(
  value: string,
) => void

Description

Function called when an item is selected

onValueChange

Type

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

Description

The callback fired when the selected item changes.

open

Type

boolean

Description

Whether the select menu is open

placeholder

Type

string

Description

Placeholder text to display when no value is selected.

positioning

Type

SelectPositioningOptions

Description

The positioning options of the menu.

present

Type

boolean

Description

Whether the node is present (controlled by the user)

readOnly

Type

boolean

Description

Whether the select is read-only

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 select is required

scrollToIndexFn

Type

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

Description

Function to scroll to a specific index

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.

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 keys of the selected items

<Select.Label>

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

Prop	Type
children React children prop.	ReactNode
id id attribute. If omitted, a unique identifier will be automatically generated for accessibility.	string
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.

Type

string

Description

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

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-disabled`
`data-invalid`
`data-part`	'label'
`data-readonly`
`data-scope`	'select'

className

Value

'qui-select__label'

data-disabled

Value

data-invalid

Value

data-part

Value

'label'

data-readonly

Value

data-scope

Value

'select'

<Select.Control>

The trigger that opens and closes the select menu. 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-disabled`
`data-invalid`
`data-part`	'control'
`data-placeholder-shown`
`data-placement`	\| 'bottom' \| 'bottom-end' \| 'bottom-start' \| 'left' \| 'left-end' \| 'left-start' \| 'right' \| 'right-end' \| 'right-start' \| 'top' \| 'top-end' \| 'top-start'
`data-readonly`
`data-scope`	'select'
`data-size`	\| 'sm' \| 'md' \| 'lg'
`data-state`	\| 'open' \| 'closed'
`tabIndex`	number

className

Value

'qui-select__control'

data-disabled

Value

data-invalid

Value

data-part

Value

'control'

data-placeholder-shown

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-readonly

Value

data-scope

Value

'select'

data-size

Value

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

data-state

Value

| 'open'
| 'closed'

tabIndex

Value

number

<Select.Indicator>

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

Prop	Type	Default
icon Indicator icon.	\| 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)

icon

Type

| ReactNode
| LucideIcon

Description

Indicator icon.

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-disabled`
`data-invalid`
`data-part`	'indicator'
`data-readonly`
`data-scope`	'select'
`data-size`	\| 'sm' \| 'md' \| 'lg'
`data-state`	\| 'open' \| 'closed'

className

Value

'qui-select__indicator'

data-disabled

Value

data-invalid

Value

data-part

Value

'indicator'

data-readonly

Value

data-scope

Value

'select'

data-size

Value

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

data-state

Value

| 'open'
| 'closed'

<Select.ValueText>

Displays the currently selected value(s). 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__value-text'
`data-disabled`
`data-focus`
`data-invalid`
`data-multiple`
`data-part`	'value-text'
`data-scope`	'select'
`data-size`	\| 'sm' \| 'md' \| 'lg'

className

Value

'qui-select__value-text'

data-disabled

Value

data-focus

Value

data-invalid

Value

data-multiple

Value

data-part

Value

'value-text'

data-scope

Value

'select'

data-size

Value

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

<Select.ClearTrigger>

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

Prop	Type
id id attribute. If omitted, a unique identifier will be automatically generated for accessibility.	string
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

Type

string

Description

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

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-invalid`
`data-part`	'clear-trigger'
`data-scope`	'select'
`data-size`	\| 'sm' \| 'md' \| 'lg'
`hidden`	boolean

className

Value

'qui-select__clear-trigger'

data-invalid

Value

data-part

Value

'clear-trigger'

data-scope

Value

'select'

data-size

Value

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

hidden

Value

boolean

<Select.Positioner>

Positions the select menu relative to the trigger. Renders a <div> element by default.

Prop	Type
id id attribute. If omitted, a unique identifier will be automatically generated for accessibility.	string
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

Type

string

Description

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

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-part`	'positioner'
`data-scope`	'select'
`style`	CSSProperties

className

Value

'qui-select__positioner'

data-part

Value

'positioner'

data-scope

Value

'select'

style

Value

CSSProperties

<Select.Content>

Container for the select options. 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-select__content'
`data-activedescendant`	string
`data-focus-visible`
`data-part`	'content'
`data-placement`	\| 'bottom' \| 'bottom-end' \| 'bottom-start' \| 'left' \| 'left-end' \| 'left-start' \| 'right' \| 'right-end' \| 'right-start' \| 'top' \| 'top-end' \| 'top-start'
`data-scope`	'select'
`data-state`	\| 'open' \| 'closed'
`hidden`	boolean
`tabIndex`	0

className

Value

'qui-select__content'

data-activedescendant

Value

string

data-focus-visible

Value

data-part

Value

'content'

data-placement

Value

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

data-scope

Value

'select'

data-state

Value

| 'open'
| 'closed'

hidden

Value

boolean

tabIndex

Value

<Select.Item>

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

Prop	Type
item ^* The item to render	any
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

any

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-disabled`
`data-highlighted`
`data-part`	'item'
`data-scope`	'select'
`data-size`	\| 'sm' \| 'md' \| 'lg'
`data-state`	\| 'checked' \| 'unchecked'
`data-value`	string

className

Value

'qui-select__item'

data-disabled

Value

data-highlighted

Value

data-part

Value

'item'

data-scope

Value

'select'

data-size

Value

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

data-state

Value

| 'checked'
| 'unchecked'

data-value

Value

string

<Select.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-part`	'item-indicator'
`data-scope`	'select'
`data-state`	\| 'checked' \| 'unchecked'
`hidden`	boolean

data-part

Value

'item-indicator'

data-scope

Value

'select'

data-state

Value

| 'checked'
| 'unchecked'

hidden

Value

boolean

<Select.ItemText>

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-disabled`
`data-highlighted`
`data-part`	'item-text'
`data-scope`	'select'
`data-state`	\| 'checked' \| 'unchecked'

className

Value

'qui-select__item-text'

data-disabled

Value

data-highlighted

Value

data-part

Value

'item-text'

data-scope

Value

'select'

data-state

Value

| 'checked'
| 'unchecked'

<Select.HiddenSelect>

Hidden native select element for form submission. Renders a <select> element.

Attribute / Property	Value
`className`	'qui-select__hidden-select'
`data-part`	'hidden-select'
`data-scope`	'select'
`style`	CSSProperties
`tabIndex`	-1

className

Value

'qui-select__hidden-select'

data-part

Value

'hidden-select'

data-scope

Value

'select'

style

Value

CSSProperties

tabIndex

Value

-1

<Select.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-part`	'hint'
`data-scope`	'select'

<Select.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
id id attribute. If omitted, a unique identifier will be automatically generated for accessibility.	string
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.

Type

string

Description

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

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-part`	'error-text'
`data-scope`	'select'
`hidden`	boolean

className

Value

'qui-input__error-text'

data-part

Value

'error-text'

data-scope

Value

'select'

hidden

Value

boolean

<Select.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-part`	'error-indicator'
`data-scope`	'select'
`hidden`	boolean

Data Structures

ListCollection

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

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

return <Select 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 itemsThe items in the 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

itemsThe items in the 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

SelectPositioningOptions

Prop	Type	Default
arrowPadding The minimum padding between the arrow and the floating element's corner.	number	4
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.

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.

Radio

Slider