Listbox

Use a Listbox to present a persistent, keyboard-navigable set of options where users choose one or more items.

import {Listbox} from "@qualcomm-ui/react/listbox"

Overview

Each listbox uses the listCollection helper to manage the list of items. This ListCollection instance is documented below.

Examples

Filtering

Filter a single-select collection before rendering the Listbox items.

Filter regions

Deployment region


<Listbox.Root collection={collection} selectionMode="single">
  <Listbox.Input
    className="mb-4"
    label="Filter regions"
    onValueChange={filter}
    placeholder="Search regions"
    startIcon={Search}
  />
  <Listbox.Label>Deployment region</Listbox.Label>
  <Listbox.Content>
    {collection.items.map((region) => (
      <Listbox.Item key={region.value} item={region}>
        <Listbox.ItemControl />
        <Listbox.ItemLabel>{region.label}</Listbox.ItemLabel>
        <Listbox.ItemDescription>
          {region.description}
        </Listbox.ItemDescription>
      </Listbox.Item>
    ))}
  </Listbox.Content>
</Listbox.Root>

Multiple selection

Set selectionMode to multiple when users can choose more than one option.

Assign reviewers

<Listbox.Root collection={collection} selectionMode="multiple">
  <Listbox.Label>Assign reviewers</Listbox.Label>
  <Listbox.Content>
    {collection.items.map((reviewer) => (
      <Listbox.Item key={reviewer.value} item={reviewer}>
        <Listbox.ItemControl />
        <Listbox.ItemLabel>{reviewer.label}</Listbox.ItemLabel>
        <Listbox.ItemDescription>
          {reviewer.description}
        </Listbox.ItemDescription>
      </Listbox.Item>
    ))}
  </Listbox.Content>
</Listbox.Root>

Scrollable

Set a maximum height and vertical overflow on Listbox.Content when the collection exceeds the available space.

<Listbox.Label>Device</Listbox.Label>
<Listbox.Content className="max-h-64 overflow-y-auto">
  {collection.items.map((device) => (
    <Listbox.Item key={device} item={device}>
      <Listbox.ItemControl />
      <Listbox.ItemLabel>{device}</Listbox.ItemLabel>
    </Listbox.Item>
  ))}
</Listbox.Content>

Controlled state

Pass value and update it in onValueChange when the selected items change.

Appearance

Selected: Auto

<Listbox.Root
  collection={collection}
  onValueChange={({value}) => setValue(value)}
  value={value}
>
  <Listbox.Label>Appearance</Listbox.Label>
  <Listbox.Content>
    {collection.items.map((item) => (
      <Listbox.Item key={item} item={item}>
        <Listbox.ItemControl />
        <Listbox.ItemLabel>{item}</Listbox.ItemLabel>
      </Listbox.Item>
    ))}
  </Listbox.Content>
</Listbox.Root>
<p className="mt-2">Selected: {value.join(", ") || "None"}</p>

Item customization

Customize each item using the List.Item subcomponents.

Projects

<Listbox.Label>Projects</Listbox.Label>
<Listbox.Content>
  {collection.items.map((project) => (
    <Listbox.Item key={project.value} item={project}>
      <Listbox.ItemStartIcon icon={project.icon} />
      <Listbox.ItemLabel>{project.label}</Listbox.ItemLabel>
      <Listbox.ItemDescription>
        {project.description}
      </Listbox.ItemDescription>
      <Listbox.ItemSecondaryText>
        {project.technologyArea}
      </Listbox.ItemSecondaryText>
    </Listbox.Item>
  ))}
</Listbox.Content>

Prop	Type	Default
collection ^* The item collection	ListCollection
defaultHighlightedValue The initial value of the highlighted item when opened. Use when you don't need to control the highlighted value of the listbox.	string
defaultValue The initial default value of the listbox when rendered. Use when you don't need to control the value of the listbox.	string[]	[]
deselectable Whether to disallow empty selection	boolean
dir The document's text/writing direction.	'ltr' \| 'rtl'	'ltr'
disabled Whether the listbox is disabled	boolean
disallowSelectAll Whether to disallow selecting all items when `meta+a` is pressed	boolean
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
id id attribute. If omitted, a unique identifier will be automatically generated for accessibility.	string
loopFocus Whether to loop the keyboard navigation through the options	boolean	false
onHighlightChange The callback fired when the highlighted item changes.	(details: { highlightedIndex: number highlightedItem: T highlightedValue: string }) => void
onSelect Function called when an item is selected	(details: { value: string }) => void
onValueChange The callback fired when the selected item changes.	(details: { items: Array<T> value: string[] }) => void
orientation The orientation of the listbox.	\| 'horizontal' \| 'vertical'	"vertical"
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)
scrollToIndexFn Function to scroll to a specific index	(details: { getElement: () => HTMLElement immediate?: boolean index: number }) => void
selectionMode How multiple selection should behave in the listbox. - `single`: The user can select a single item. - `multiple`: The user can select multiple items without using modifier keys. - `extended`: The user can select multiple items by using modifier keys.	\| 'single' \| 'multiple' \| 'none' \| 'extended'	"single"
selectOnHighlight Whether to select the item when it is highlighted	boolean
size	\| 'sm' \| 'md' \| 'lg'	"sm"
typeahead Whether to enable typeahead on the listbox	boolean
value The controlled keys of the selected items	string[]

How multiple selection should behave in the listbox.

- single: The user can select a single item.
- multiple: The user can select multiple items without using modifier keys.
- extended: The user can select multiple items by using modifier keys.

selectOnHighlight

Type

boolean

Description

Whether to select the item when it is highlighted

size

Type

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

Description

typeahead

Type

boolean

Description

Whether to enable typeahead on the listbox

value

Type

string[]

Description

The controlled keys of the selected items

<Listbox.Label>

Accessible label for the listbox. 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

<Listbox.Content>

Container for the listbox 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

<Listbox.Input>

The Listbox.Input extends the TextInput component with listbox accessibility like keyboard navigation.

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
children The simple TextInput doesn't support children.	never
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	{ render?: \| Element \| (( props: Props, ) => Element) }
defaultValue The initial value of the input when rendered. Use when you don't need to control the value of the input.	string
dir The document's text/writing direction.	'ltr' \| 'rtl'	'ltr'
disabled Whether the input is disabled. When true, prevents user interaction and applies visual styling to indicate the disabled state.	boolean
endIcon lucide-react icon, positioned after the input. Can be supplied as a `ReactElement` for additional customization.	\| LucideIcon \| ReactNode
errorIndicatorProps Props applied to the error indicator element.	{ icon?: \| LucideIcon \| ReactNode render?: \| Element \| (( props: Props, ) => Element) }
errorText Optional error that describes the element when invalid is true.	string
errorTextProps Props applied to the error text element.	{ icon?: \| LucideIcon \| ReactNode render?: \| Element \| (( props: Props, ) => Element) }
form The id of the form that the input belongs to.	string
getRootNode A root node to correctly resolve document in custom environments. i.e., Iframes, Electron.	() => \| Node \| ShadowRoot \| Document
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.	{ children?: ReactNode render?: \| Element \| (( props: Props, ) => Element) }
ids The ids of the elements that are associated with the input. These will be automatically generated if omitted.	{ errorText: string hint: string input: string label: string }
inputGroupProps Props applied to the input group element.	TextInputInputGroupProps
inputProps Props applied to the input element.	any
invalid Controls the visual error state of the input. When true, applies semantic error styling to indicate validation failure.	boolean
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.	{ children?: ReactNode render?: \| Element \| (( props: Props, ) => Element) }
name The name of the input field. Useful for form submission.	string
onFocusChange The callback invoked when the field is focused or blurred.	( focused: boolean, ) => void
onValueChange The callback invoked when the value changes.	( value: string, ) => void
placeholder HTML placeholder attribute, passed to the underlying input element.	string
readOnly Whether the input is read-only. When true, prevents user interaction while keeping the input focusable and visible.	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 input is required. When true, the input must have a value for form validation to pass.	boolean
size The size of the input field and its elements. Governs properties like font size, item padding, and icon sizes.	\| 'sm' \| 'md' \| 'lg'	'md'
startIcon lucide-react icon, positioned before the input. Can be supplied as a `ReactElement` for additional customization.	\| LucideIcon \| ReactNode
value The controlled value of the input	string

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.

children

Type

never

Description

The simple TextInput doesn't support children.

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

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

defaultValue

Type

string

Description

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

dir

Type

'ltr' | 'rtl'

Description

The document's text/writing direction.

disabled

Type

boolean

Description

Whether the input is disabled. When true, prevents user interaction and applies visual styling to indicate the disabled state.

endIcon

Type

| LucideIcon
| ReactNode

Description

lucide-react icon, positioned after the input. Can be supplied as a ReactElement for additional customization.

errorIndicatorProps

Type

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

Description

Props applied to the error indicator element.

errorText

Type

string

Description

Optional error that describes the element when invalid is true.

errorTextProps

Type

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

Description

Props applied to the error text element.

form

Type

string

Description

The id of the form that the input belongs to.

getRootNode

Type

() =>
| Node
| ShadowRoot
| Document

Description

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

hint

Type

ReactNode

Description

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

hintProps

Type

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

Description

Props applied to the label element.

ids

Type

{
  errorText: string
  hint: string
  input: string
  label: string
}

Description

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

inputGroupProps

Type

TextInputInputGroupProps

Description

Props applied to the input group element.

inputProps

Type

any

Description

Props applied to the input element.

invalid

Type

boolean

Description

Controls the visual error state of the input. When true, applies semantic error styling to indicate validation failure.

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

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

Description

Props applied to the label element.

name

Type

string

Description

The name of the input field. Useful for form submission.

onFocusChange

Type

(
  focused: boolean,
) => void

Description

The callback invoked when the field is focused or blurred.

onValueChange

Type

(
  value: string,
) => void

Description

The callback invoked when the value changes.

placeholder

Type

string

Description

HTML placeholder attribute, passed to the underlying input element.

readOnly

Type

boolean

Description

Whether the input is read-only. When true, prevents user interaction while keeping the input focusable and 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

required

Type

boolean

Description

Whether the input is required. When true, the input must have a value for form validation to pass.

size

Type

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

Description

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

startIcon

Type

| LucideIcon
| ReactNode

Description

lucide-react icon, positioned before the input. Can be supplied as a ReactElement for additional customization.

value

Type

string

Description

The controlled value of the input

<Listbox.Item>

An interactive option in the listbox. Renders a <li> element by default.

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

render

Type

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

Description

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

<Listbox.ItemStartIcon>

An icon displayed before the text of a list item. Renders a <span> element by default when the icon is a React element.

Prop	Type
icon ^* The icon displayed before the item's 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

The icon displayed before the item's 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

<Listbox.ItemControl>

A selection indicator for a listbox item. 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

<Listbox.ItemLabel>

The primary text of a listbox option. 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

<Listbox.ItemDescription>

Supplementary text for a list item. 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

<Listbox.ItemSecondaryText>

Secondary text displayed after a list item's label and description. 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

<Listbox.ItemAccessory>

Content displayed at the end of a list item. 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

Data Structures

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

interface ExampleItem {
  label: string
  value: string
}

const items: ExampleItem[] = [
  // ...
]

function Component() {
  const {fuzzyContains} = useFilter({sensitivity: "base"})
  const {collection, filter} = useListCollection({
    filter: fuzzyContains,
    initialItems: items,
    // the itemLabel is what the filter will use to compare items
    itemLabel: (item) => item.label,
    itemValue: (item) => item.value,
  })
  return <Listbox.Root collection={collection}>{/*...*/}</Listbox.Root>
}

useListCollection

Prop	Type
filter The filter function to use to filter the items.	( itemText: string, filterText: string, item: T, ) => boolean
groupBy Function to group items	( item: T, index: number, ) => string
groupSort Function to sort items	\| string[] \| 'desc' \| 'asc' \| (( a: string, b: string, ) => number)
initialItems The initial items to display in the collection (this is the initial state of the collection before filtering)	Array<T>
itemDisabled Function to determine if a node is disabled.	( item: T, ) => boolean
itemLabel Function to get the item's label. This is the string used for filtering.	( item: T, ) => string
itemValue Function to get the item's unique value.	( item: T, ) => string
limit The maximum number of items to display in the collection. Useful for performance when you have a large number of items.	number

filter

Type

(
  itemText: string,
  filterText: string,
  item: T,
) => boolean

Description

The filter function to use to filter the items.

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

initialItems

Type

Array<T>

Description

The initial items to display in the collection (this is the initial state of the collection before filtering)

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. This is the string used for filtering.

itemValue

Type

(
  item: T,
) => string

Description

Function to get the item's unique value.

limit

Type

number

Description

The maximum number of items to display in the collection. Useful for performance when you have a large number of items.

The following predefined filters are available:

Prop	Type
contains Checks if string contains substring using locale-aware exact matching	( string: string, substring: string, ) => boolean
endsWith Checks if string ends with substring using locale-aware exact matching	( string: string, substring: string, ) => boolean
fuzzyContains Checks if string starts with substring or contains substring within Levenshtein distance threshold	( string: string, substring: string, ) => boolean
startsWith Checks if string starts with substring using locale-aware exact matching	( string: string, substring: string, ) => boolean

contains

Type

(
  string: string,
  substring: string,
) => boolean

Description

Checks if string contains substring using locale-aware exact matching

endsWith

Type

(
  string: string,
  substring: string,
) => boolean

Description

Checks if string ends with substring using locale-aware exact matching

fuzzyContains

Type

(
  string: string,
  substring: string,
) => boolean

Description

Checks if string starts with substring or contains substring within Levenshtein distance threshold

startsWith

Type

(
  string: string,
  substring: string,
) => boolean

Description

Checks if string starts with substring using locale-aware exact matching

ListCollection

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

Last updated on Aug 19, 2026 by Ryan Bower

Link

Listbox

Overview

Examples

Filtering

Multiple selection

Scrollable

Controlled state

Item customization

API

<Listbox.Root>

<Listbox.Label>

<Listbox.Content>

<Listbox.Input>

<Listbox.Item>

<Listbox.ItemStartIcon>

<Listbox.ItemControl>

<Listbox.ItemLabel>

<Listbox.ItemDescription>

<Listbox.ItemSecondaryText>

<Listbox.ItemAccessory>

Data Structures

useListCollection

ListCollection