Select

The select component provides a streamlined way for users to pick a single option from a collapsible list of choices. It conserves screen space while offering clear visual feedback and maintaining accessibility standards.

import {SelectModule} from "@qualcomm-ui/angular/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.

City

<q-select
  class="w-48"
  label="City"
  placeholder="Select a city"
  [collection]="cityCollection"
/>

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.

City

<div
  class="w-48"
  placeholder="Select a city"
  q-select-root
  [collection]="cityCollection"
>
  <div q-select-label>City</div>

  <div q-select-control>
    <span q-select-value-text></span>
    <button q-select-clear-trigger></button>
    <button q-select-indicator></button>
    <div q-select-error-indicator></div>
  </div>

  <select q-select-hidden-select></select>

  <ng-template qPortal>
    <div q-select-positioner>
      <div q-select-content>
        @for (item of cityCollection.items; track item) {
          <div q-select-item [item]="item">
            <span q-select-item-text>
              {{ cityCollection.stringifyItem(item) }}
            </span>
            <span q-select-item-indicator></span>
          </div>
        }
      </div>
    </div>
  </ng-template>
</div>

ARIA Label

The Select's label is automatically associated with the control for accessibility. If you omit the label, give the control an accessible name with aria-label or aria-labelledby.

<q-select
  aria-label="City"
  class="w-48"
  placeholder="Select a city"
  [collection]="cityCollection"
/>

NOTE

Use aria-label or aria-labelledby on the simple <q-select> to forward an accessible name to the internal control. The q-select host removes those attributes after forwarding them. If you use the composite API, provide aria-label or aria-labelledby on the q-select-control element. For dynamic label references, use [aria-labelledby] instead of [attr.aria-labelledby] so the control can treat the value as a consumer-provided override.

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.

City

<q-select
  class="w-48"
  label="City"
  placeholder="Select a city"
  [collection]="cityCollection"
  [positioning]="{sameWidth: false}"
/>

Trigger Icon

Use the icon prop to add an icon to the start of the trigger element. View our Icon documentation to learn more about using icons in QUI.

City

<q-select
  class="w-48"
  icon="MapPin"
  label="City"
  placeholder="Select a city"
  [collection]="cityCollection"
/>

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.

City

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.

<q-select
  aria-label="City"
  class="w-40"
  placeholder="sm"
  size="sm"
  [collection]="cityCollection"
/>
<q-select
  aria-label="City"
  class="w-48"
  placeholder="md"
  size="md"
  [collection]="cityCollection"
/>
<q-select
  aria-label="City"
  class="w-56"
  placeholder="lg"
  size="lg"
  [collection]="cityCollection"
/>

Content Height

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

City

<q-select
  class="w-48"
  label="City"
  placeholder="Select a city"
  [collection]="cityCollection"
>
  <div q-select-content style="max-height: 240px">
    <q-select-items />
  </div>
</q-select>

Multiple Selection

Use the multiple prop to allow multiple selections.

The selectionIndicator prop controls how selected items are displayed:

"checkmark" — Uses a checkmark after the selected options only (default)
"checkbox" — Uses a checkbox before each option

City

<q-select
  class="w-72"
  label="City"
  multiple
  placeholder="Select cities"
  selectionIndicator="checkbox"
  [collection]="cityCollection"
/>

Set the initial visibility using the defaultOpen prop, or use open and openChanged to control the dropdown visibility manually. These props follow our controlled state pattern.

City

<q-select
  class="w-48"
  label="City"
  placeholder="Select a city"
  [collection]="cityCollection"
  [open]="isOpen()"
  (openChanged)="isOpen.set($event)"
/>

Error Text and Indicator

Error messages are displayed using two props:

invalid
errorText (or the q-select-error-text component when using the composite API)

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

City

Invalid

<q-select
  class="w-48"
  errorText="Invalid"
  invalid
  label="City"
  [collection]="cityCollection"
/>

Item Customization

When using the simple API, provide the q-select-content directive as a child of the <q-select> component to override the default item renderer. The following example demonstrates how to add a custom icon to each item:

Food

<q-select
  class="w-48"
  label="Food"
  [collection]="cityCollection"
  [icon]="valueIcon()"
  (valueChanged)="value.set($event.items)"
>
  <div q-select-content>
    @for (
      item of cityCollection.items;
      track cityCollection.getItemValue(item)
    ) {
      <div q-select-item [item]="item">
        <svg [qIcon]="item.icon"></svg>
        <span q-select-item-text>
          {{ cityCollection.stringifyItem(item) }}
        </span>
        <span q-select-item-indicator></span>
      </div>
    }
  </div>
</q-select>

Within Dialog

To use the Select within a Dialog, you need to avoid portalling the item dropdown. To do this using the simple API, set disablePortal property to true:

<q-select
  aria-label="City"
  class="w-48"
  disablePortal
  placeholder="Select a city"
  [collection]="cityCollection"
/>

Like with the Dialog, you need to avoid portalling the q-select-positioner:

<div q-popover>
  <div q-popover-anchor>
    <button q-button q-popover-trigger variant="outline">Click Me</button>
  </div>
  <q-select
    disablePortal
    label="City"
    placeholder="Select a city"
    [collection]="cityCollection"
  />
</div>

Forms

All form control values are arrays to support multiple selections.
The value of the form control is an array of type T, where T is the type of the items in your select collection.

Template Forms

Strings

[ "San Diego" ]

City

readonly value = signal<string[]>(["San Diego"])

Objects

[ { "id": "SD", "name": "San Diego" } ]

City

readonly value = signal<City[]>([{id: "SD", name: "San Diego"}])

States

When using template forms, the disabled, readOnly, and invalid properties govern the interactive state of the control.

Disabled

Read only

Invalid

<q-select
  disabled
  label="Disabled"
  placeholder="Disabled"
  [collection]="cityCollection"
/>
<q-select
  label="Read only"
  placeholder="Read only"
  readOnly
  [collection]="cityCollection"
/>
<q-select
  errorText="Invalid"
  invalid
  label="Invalid"
  placeholder="Invalid"
  [collection]="cityCollection"
/>

Required

When using template forms, pass the required property to the form control. This applies the RequiredValidator and MinLengthValidator to the form control.

City

<q-select
  class="w-48"
  errorText="Please select a city"
  label="City"
  placeholder="Select a city"
  required
  [collection]="cityCollection"
  [(ngModel)]="value"
/>

Reactive Forms

Strings

[ "San Diego" ]

City

readonly formControl = new FormControl<string[]>(["San Diego"])

Objects

[ { "id": "SD", "name": "San Diego" } ]

City

readonly formControl = new FormControl<City[]>([
  {id: "SD", name: "San Diego"},
])

State Guidelines

The disabled, invalid, and required properties have no effect when using Reactive Forms. Use the equivalent Reactive Form bindings instead:

Disabled

Required

Invalid

disabledField = new FormControl([])
invalidField = new FormControl([], {
  validators: [Validators.required, Validators.minLength(1)],
})
requiredField = new FormControl([], {
  validators: [Validators.required, Validators.minLength(1)],
})

ngOnInit() {
  this.disabledField.disable()
  this.invalidField.markAsDirty()
}

Explorer

Component Anatomy

Hover to highlight, click to view API

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

API

<q-select>

The simple select extends the q-select-root directive with the following properties:

Prop	Type	Default
aria-label v2.9.0 ARIA label applied to the control element. Use this if you omit the label	string
aria-labelledby v2.9.0 ID reference for an external label applied to the control element.	string
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
disablePortal Set to true to disable portalling behavior for the select dropdown content.	boolean
errorText Optional error that describes the element when invalid is true.	string

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

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

aria-label

v2.9.0

Type

string

Description

ARIA label applied to the control element. Use this if you omit the label

aria-labelledby

v2.9.0

Type

string

Description

ID reference for an external label applied to the control element.

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.

disablePortal

Type

boolean

Description

Set to true to disable portalling behavior for the select dropdown content.

errorText

Type

string

Description

Optional error that describes the element when invalid is true.

hint

Type

string

Description

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

label

Type

string

Description

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

Composite API

q-select-root

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 value of the input when rendered. Use when you don't need to control the value of the input. This property will be ignored if you opt into controlled state via form control bindings.	InputSigna
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 Controls whether the input is disabled in template-driven forms. When true, prevents user interaction and applies visual styling to indicate the disabled state.	boolean
getRootNode A root node to correctly resolve the 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 trigger element.	\| LucideIconData \| string
id id attribute. If omitted, a unique identifier will be generated for accessibility.)	string
invalid Controls the visual error state of the input. When true, applies semantic error styling to indicate validation failure.	boolean
loopFocus Whether to loop the keyboard navigation through the options	boolean	false
multiple Whether to allow multiple selection	boolean	false
name The name of the input field. Useful for form submission.	string
open Whether the select menu is open	boolean
placeholder Placeholder text to display when no value is selected.	string	"Select option"
positioning The positioning options of the menu.	PositioningOptions
readOnly Whether the input is read-only. When true, prevents user interaction while keeping the input focusable and visible.	boolean
required Controls whether the input is required in template-driven forms. When true, the input must have a value for form validation to pass.	boolean
scrollToIndexFn Function to scroll to a specific index	(details: { immediate?: boolean index: number }) => void
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'
(focusOutside) Function called when the focus is moved outside the component	CustomEvent<{ event?: E }>
(highlightChanged) The callback fired when the highlighted item changes.	{ value: string } & { highlightedIndex: number highlightedItem: T }
(interactOutside) Function called when an interaction happens outside the component	\| CustomEvent<{event?: E}> \| CustomEvent<{event?: E}>
(openChanged) Function invoked when the popup opens or closes	boolean
(pointerDownOutside) Function called when the pointer is pressed down outside the component	CustomEvent<{ event?: E }>
(selected) Function called when an item is selected	{ value: string }
(valueChanged) The callback fired when the selected item changes.	{ items: Array<T> value: 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

InputSigna

Description

The initial value of the input when rendered. Use when you don't need to control the value of the input. This property will be ignored if you opt into controlled state via form control bindings.

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

Controls whether the input is disabled in template-driven forms. When true, prevents user interaction and applies visual styling to indicate the disabled state.

getRootNode

Type

() =>
| Node
| ShadowRoot
| Document

Description

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

highlightedValue

Type

string

Description

The controlled key of the highlighted item

icon

Type

| LucideIconData
| string

Description

lucide icon, positioned at the start of the trigger element.

Type

string

Description

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

invalid

Type

boolean

Description

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

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 of the input field. Useful for form submission.

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

PositioningOptions

Description

The positioning options of the menu.

readOnly

Type

boolean

Description

Whether the input is read-only. When true, prevents user interaction while keeping the input focusable and visible.

required

Type

boolean

Description

Controls whether the input is required in template-driven forms. When true, the input must have a value for form validation to pass.

scrollToIndexFn

Type

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

Description

Function to scroll to a specific index

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.

(focusOutside)

Type

CustomEvent<{
  event?: E
}>

Description

Function called when the focus is moved outside the component

(highlightChanged)

Type

{
  value: string
} & {
  highlightedIndex: number
  highlightedItem: T
}

Description

The callback fired when the highlighted item changes.

(interactOutside)

Type

| CustomEvent<{event?: E}>
| CustomEvent<{event?: E}>

Description

Function called when an interaction happens outside the component

(openChanged)

Type

boolean

Description

Function invoked when the popup opens or closes

(pointerDownOutside)

Type

CustomEvent<{
  event?: E
}>

Description

Function called when the pointer is pressed down outside the component

(selected)

Type

{
  value: string
}

Description

Function called when an item is selected

(valueChanged)

Type

{
  items: Array<T>
  value: string[]
}

Description

The callback fired when the selected item changes.

q-select-label

Prop	Type
id id attribute. If omitted, a unique identifier will be generated for accessibility.	string

Type

string

Description

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

Attribute / Property	Value
`class`	'qui-select__label'
`data-disabled`
`data-invalid`
`data-readonly`
`data-select-part`	'label'

class

Value

'qui-select__label'

data-disabled

Value

data-invalid

Value

data-readonly

Value

data-select-part

Value

'label'

q-select-control

Prop	Type
aria-label v2.4.0 ARIA label applied to the control. Use this instead of `[attr.aria-label]`	string
aria-labelledby v2.4.0 ID reference for an external label applied to the control.	string
id id attribute. If omitted, a unique identifier will be generated for accessibility.	string

aria-label

v2.4.0

Type

string

Description

ARIA label applied to the control. Use this instead of [attr.aria-label]

aria-labelledby

v2.4.0

Type

string

Description

ID reference for an external label applied to the control.

Type

string

Description

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

Attribute / Property	Value
`class`	'qui-select__control'
`data-disabled`
`data-invalid`
`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-select-part`	'control'
`data-size`	\| 'sm' \| 'md' \| 'lg'
`data-state`	\| 'open' \| 'closed'
`tabIndex`	number

class

Value

'qui-select__control'

data-disabled

Value

data-invalid

Value

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-select-part

Value

'control'

data-size

Value

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

data-state

Value

| 'open'
| 'closed'

tabIndex

Value

number

q-select-indicator

Prop	Type	Default
icon Indicator icon.	\| LucideIconData \| string	ChevronDown

icon

Type

| LucideIconData
| string

Description

Indicator icon.

Attribute / Property	Value
`class`	'qui-select__indicator'
`data-disabled`
`data-invalid`
`data-readonly`
`data-select-part`	'indicator'
`data-size`	\| 'sm' \| 'md' \| 'lg'
`data-state`	\| 'open' \| 'closed'
`tabIndex`	-1

class

Value

'qui-select__indicator'

data-disabled

Value

data-invalid

Value

data-readonly

Value

data-select-part

Value

'indicator'

data-size

Value

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

data-state

Value

| 'open'
| 'closed'

tabIndex

Value

-1

q-select-value-text

Attribute / Property	Value
`class`	'qui-select__value-text'
`data-disabled`
`data-focus`
`data-invalid`
`data-multiple`
`data-select-part`	'value-text'
`data-size`	\| 'sm' \| 'md' \| 'lg'

class

Value

'qui-select__value-text'

data-disabled

Value

data-focus

Value

data-invalid

Value

data-multiple

Value

data-select-part

Value

'value-text'

data-size

Value

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

q-select-clear-trigger

Prop	Type
id id attribute. If omitted, a unique identifier will be generated for accessibility.	string

Type

string

Description

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

Attribute / Property	Value
`class`	'qui-select__clear-trigger'
`data-invalid`
`data-select-part`	'clear-trigger'
`data-size`	\| 'sm' \| 'md' \| 'lg'
`hidden`	boolean

class

Value

'qui-select__clear-trigger'

data-invalid

Value

data-select-part

Value

'clear-trigger'

data-size

Value

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

hidden

Value

boolean

q-select-positioner

Prop	Type
id id attribute. If omitted, a unique identifier will be generated for accessibility.	string

Type

string

Description

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

Attribute / Property	Value
`class`	'qui-select__positioner'
`data-select-part`	'positioner'
`style`	CSSProperties

q-select-content

Prop	Type
id id attribute. If omitted, a unique identifier will be generated for accessibility.	string

Type

string

Description

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

Attribute / Property	Value
`class`	'qui-select__content'
`data-activedescendant`	string
`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-select-part`	'content'
`data-state`	\| 'open' \| 'closed'
`hidden`	boolean
`tabIndex`	0

class

Value

'qui-select__content'

data-activedescendant

Value

string

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-select-part

Value

'content'

data-state

Value

| 'open'
| 'closed'

hidden

Value

boolean

tabIndex

Value

q-select-item

Prop	Type
item The item to render, from the collection	any
persistFocus Whether hovering outside should clear the highlighted state	boolean

item

Type

any

Description

The item to render, from the collection

persistFocus

Type

boolean

Description

Whether hovering outside should clear the highlighted state

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

class

Value

'qui-select__item'

data-disabled

Value

data-highlighted

Value

data-select-part

Value

'item'

data-selection-indicator

Value

| 'checkmark'
| 'checkbox'

data-size

Value

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

data-state

Value

| 'checked'
| 'unchecked'

data-value

Value

string

q-select-item-checkbox

Checkbox-style indicator for select items. Use this instead of q-select-item-indicator when selectionIndicator="checkbox" is set on the root. The checkbox is always visible and fills when the item is selected.

Checkbox-style indicator for select items. Always visible, showing a checkbox that fills when selected. Use with selectionIndicator="checkbox" on the Select root.

q-select-item-indicator

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

q-select-item-text

Attribute / Property	Value
`data-disabled`
`data-highlighted`
`data-select-part`	'item-text'
`data-state`	\| 'checked' \| 'unchecked'

data-disabled

Value

data-highlighted

Value

data-select-part

Value

'item-text'

data-state

Value

| 'checked'
| 'unchecked'

q-select-hidden-select

Prop	Type
id id attribute. If omitted, a unique identifier will be generated for accessibility.	string

Type

string

Description

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

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

class

Value

'qui-select__hidden-select'

data-select-part

Value

'hidden-select'

style

Value

CSSProperties

tabIndex

Value

-1

q-select-hint

Prop	Type
id id attribute. If omitted, a unique identifier will be generated for accessibility.	string

Type

string

Description

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

q-select-error-text

Prop	Type
icon Optional error indicator icon.	\| string \| LucideIconData
id id attribute. If omitted, a unique identifier will be generated for accessibility.	string

icon

Type

| string
| LucideIconData

Description

Optional error indicator icon.

Type

string

Description

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

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

q-select-error-indicator

Prop	Type	Default
icon lucide-angular icon	\| LucideIconData \| string	CircleAlert

icon

Type

| LucideIconData
| string

Description

lucide-angular icon

Attribute / Property	Value
`data-select-part`	'error-indicator'
`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:

@Component({
  template: `
    <q-select [collection]="collection" />
  `,
})
export class MyComponent {
  collection = selectCollection({
    items: [
      // ...
    ],
  })
}

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.

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

SelectPositioningOptions

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 22, 2026 by Ryan Bower

Segmented Control

Side Nav