Combobox

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

import {ComboboxModule} from "@qualcomm-ui/angular/combobox"

Overview

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

Examples

Simple

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

Country

<div class="flex flex-col gap-4">
  <q-combobox
    class="w-56"
    label="Country"
    placeholder="Select a country"
    [collection]="listCollection.collection()"
    (inputValueChanged)="onInputChange($event)"
  />
</div>

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.

<div
  class="w-56"
  placeholder="Select a country"
  q-combobox-root
  [collection]="listCollection.collection()"
  (inputValueChanged)="onInputChange($event)"
>
  <label q-combobox-label>Search</label>
  <div q-combobox-control>
    <input q-combobox-input />
    <button q-combobox-clear-trigger></button>
    <div q-combobox-trigger></div>
  </div>

  <ng-template qPortal>
    <div q-combobox-positioner>
      <div q-combobox-content>
        <div q-combobox-empty>No results found</div>
        <q-combobox-items />
      </div>
    </div>
  </ng-template>
</div>

Open on Click

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

Country

<q-combobox
  class="w-56"
  label="Country"
  openOnClick
  placeholder="Select a country"
  [collection]="listCollection.collection()"
  (inputValueChanged)="onInputChange($event)"
/>

Input Behavior

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

Country

<q-combobox
  class="w-56"
  inputBehavior="autohighlight"
  label="Country"
  placeholder="Select a country"
  [collection]="listCollection.collection()"
  (inputValueChanged)="onInputChange($event)"
/>

Multiple Selection

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

Country

import {Component, signal} from "@angular/core"
import {FormsModule} from "@angular/forms"

import {useListCollection} from "@qualcomm-ui/angular-core/collection"
import {ComboboxModule} from "@qualcomm-ui/angular/combobox"
import {TagDirective} from "@qualcomm-ui/angular/tag"
import type {ComboboxInputValueChangeDetails} from "@qualcomm-ui/core/combobox"

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

@Component({
  imports: [ComboboxModule, TagDirective, FormsModule],
  selector: "combobox-multiple-demo",
  template: `
    <div class="flex w-72 flex-col gap-4">
      <div class="flex flex-wrap gap-2">
        @for (item of value(); track item) {
          <button
            emphasis="neutral"
            q-tag
            variant="dismissable"
            (click)="handleValueDismissed(item)"
          >
            {{ item }}
          </button>
        }
      </div>
      <q-combobox
        class="w-full"
        label="Country"
        multiple
        placeholder="Select a country"
        [collection]="listCollection.collection()"
        [(ngModel)]="value"
        (inputValueChanged)="onInputChange($event)"
      />
    </div>
  `,
})
export class ComboboxMultipleDemo {
  readonly value = signal<string[]>([])

  readonly listCollection = useListCollection<string>({
    filter: "contains",
    items: countries,
  })

  onInputChange(event: ComboboxInputValueChangeDetails) {
    this.listCollection.filterText.set(event.inputValue)
  }

  handleValueDismissed(item: string) {
    this.value.set(this.value().filter((v) => v !== item))
  }
}

Highlight Matching Text

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

Country

<q-combobox
  class="w-56"
  highlightMatchingText
  label="Country"
  name="combobox-highlight"
  placeholder="Search countries..."
  [collection]="listCollection.collection()"
  (inputValueChanged)="onInputChange($event)"
/>

ARIA Label

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

<q-combobox
  aria-label="Country"
  class="w-48"
  placeholder="Select a country"
  [collection]="listCollection.collection()"
  (inputValueChanged)="onInputChange($event)"
/>

NOTE

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

Content Width

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

<q-combobox
  aria-label="Country"
  class="w-48"
  placeholder="Select a country"
  [collection]="listCollection.collection()"
  [positioning]="{sameWidth: false}"
  (inputValueChanged)="onInputChange($event)"
/>

Input Icon

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

<q-combobox
  aria-label="Country"
  class="w-48"
  icon="MapPin"
  placeholder="Select a country"
  [collection]="listCollection.collection()"
  (inputValueChanged)="onInputChange($event)"
/>

Icon Customization

Provide a custom element using the q-combobox-icon directive to override the default icon. This example features a loading indicator:

<q-combobox
  aria-label="Country"
  class="w-48"
  placeholder="Select a country"
  [collection]="listCollection.collection()"
  (inputValueChanged)="onInputChange($event)"
>
  @if (loading()) {
    <div q-combobox-icon q-progress-ring size="xs"></div>
  }
</q-combobox>

Items as Objects

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

City

<q-combobox
  class="w-48"
  label="City"
  placeholder="Select a city"
  [collection]="cityCollection.collection()"
  (inputValueChanged)="onInputChange($event)"
/>

Item Customization

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

Country

<q-combobox
  class="w-56"
  label="Country"
  placeholder="Select a country"
  [collection]="listCollection.collection()"
  [icon]="valueIcon()"
  [(ngModel)]="value"
  (inputValueChanged)="onInputChange($event)"
>
  <div q-combobox-content>
    <div q-combobox-empty>No results found</div>
    @for (
      item of listCollection.collection().items;
      track listCollection.collection().getItemValue(item)
    ) {
      <div q-combobox-item [item]="item">
        <svg [qIcon]="item.icon"></svg>
        <span q-combobox-item-text>
          {{ listCollection.collection().stringifyItem(item) }}
        </span>
        <span q-combobox-item-indicator></span>
      </div>
    }
  </div>
</q-combobox>

TIP

When you override the default item renderer, certain props like highlightMatchingText and emptyText won't have any effect. Refer to the source code to learn more about the built-in item renderer.

Async Loading

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

Country

<q-combobox
  class="w-56"
  label="Country"
  placeholder="Select a country"
  [collection]="listCollection.collection()"
  (inputValueChanged)="onInputChange($event)"
>
  @if (query.isFetching()) {
    <div q-combobox-icon q-progress-ring size="xs"></div>
  }
</q-combobox>

Virtualized

For large lists, use the virtual prop to improve performance. This virtualizes the visible list items for performant scrolling and searching.

Users

<q-combobox
  class="w-56"
  label="Users"
  placeholder="Search for a username"
  virtual
  [collection]="listCollection.collection()"
  (inputValueChanged)="onInputChange($event)"
/>

Virtual Item Customization

Use the q-combobox-virtual-content and q-combobox-virtual-item directives to customize virtual item rendering.

Starship

<q-combobox
  class="w-56"
  label="Starship"
  placeholder="Search for a Starship"
  [collection]="listCollection.collection()"
  (inputValueChanged)="onInputChange($event)"
>
  @if (query.isFetching()) {
    <div q-combobox-icon q-progress-ring size="xs"></div>
  }

  <div q-combobox-virtual-content [virtualOptions]="virtualOptions">
    <div q-combobox-empty>No results found</div>

    <ng-container *comboboxVirtualizer="let virtualizer">
      @for (
        virtualItem of virtualizer.getVirtualItems();
        track virtualItem.key
      ) {
        @let item = listCollection.collection().items.at(virtualItem.index);
        <div
          q-combobox-virtual-item
          style="height: 52px"
          [virtualItem]="virtualItem"
        >
          <div class="flex flex-col gap-0.5" q-combobox-item-text>
            <div class="font-body-xs-bold">{{ item!.name }}</div>
            <div class="font-body-xs overflow-x-hidden text-ellipsis">
              {{ item!.url }}
            </div>
          </div>
          <span q-combobox-item-indicator></span>
        </div>
      }
    </ng-container>
  </div>
</q-combobox>

Sizes

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

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

import {Component} from "@angular/core"

import {useListCollection} from "@qualcomm-ui/angular-core/collection"
import {ComboboxModule} from "@qualcomm-ui/angular/combobox"
import type {ComboboxInputValueChangeDetails} from "@qualcomm-ui/core/combobox"

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

@Component({
  imports: [ComboboxModule],
  selector: "combobox-sizes-demo",
  template: `
    <div class="flex flex-col items-center gap-4">
      <q-combobox
        aria-label="City"
        class="w-40"
        placeholder="sm"
        size="sm"
        [collection]="listCollection.collection()"
        (inputValueChanged)="onInputChange($event)"
      />
      <q-combobox
        aria-label="City"
        class="w-48"
        placeholder="md"
        size="md"
        [collection]="listCollection.collection()"
        (inputValueChanged)="onInputChange($event)"
      />
      <q-combobox
        aria-label="City"
        class="w-56"
        placeholder="lg"
        size="lg"
        [collection]="listCollection.collection()"
        (inputValueChanged)="onInputChange($event)"
      />
    </div>
  `,
})
export class ComboboxSizesDemo {
  readonly listCollection = useListCollection<string>({
    filter: "contains",
    items: cityList,
  })

  onInputChange(event: ComboboxInputValueChangeDetails) {
    this.listCollection.filterText.set(event.inputValue)
  }
}

Content Height

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

Country

import {Component} from "@angular/core"

import {useListCollection} from "@qualcomm-ui/angular-core/collection"
import {PortalDirective} from "@qualcomm-ui/angular-core/portal"
import {ComboboxModule} from "@qualcomm-ui/angular/combobox"
import type {ComboboxInputValueChangeDetails} from "@qualcomm-ui/core/combobox"

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

@Component({
  imports: [ComboboxModule, PortalDirective],
  selector: "combobox-max-height-demo",
  template: `
    <div
      class="w-56"
      placeholder="Select a country"
      q-combobox-root
      [collection]="listCollection.collection()"
      (inputValueChanged)="onInputChange($event)"
    >
      <label q-combobox-label>Country</label>
      <div q-combobox-control>
        <input q-combobox-input />
        <button q-combobox-clear-trigger></button>
        <div q-combobox-trigger></div>
      </div>

      <ng-template qPortal>
        <div q-combobox-positioner>
          <div q-combobox-content style="max-height: 200px">
            <div q-combobox-empty>No results found</div>
            <q-combobox-items />
          </div>
        </div>
      </ng-template>
    </div>
  `,
})
export class ComboboxMaxHeightDemo {
  readonly listCollection = useListCollection<string>({
    filter: "contains",
    items: countries,
  })

  onInputChange(event: ComboboxInputValueChangeDetails) {
    this.listCollection.filterText.set(event.inputValue)
  }
}

Controlled State

Set the initial value using the defaultValue prop. Use valueChanged to listen to value changes. For fine-grained control, refer to the Forms section below.

<q-combobox
  aria-label="Country"
  class="w-48"
  placeholder="Select a country"
  [collection]="listCollection.collection()"
  [(ngModel)]="value"
  (inputValueChanged)="onInputChange($event)"
/>

States

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

Disabled

Read Only

Invalid

import {Component} from "@angular/core"

import {useListCollection} from "@qualcomm-ui/angular-core/collection"
import {ComboboxModule} from "@qualcomm-ui/angular/combobox"

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

@Component({
  imports: [ComboboxModule],
  selector: "combobox-states-demo",
  template: `
    <div class="flex flex-col items-start gap-4">
      <q-combobox
        class="w-48"
        disabled
        label="Disabled"
        placeholder="Select a country"
        [collection]="listCollection.collection()"
      />
      <q-combobox
        class="w-48"
        label="Read Only"
        placeholder="Select a country"
        readOnly
        [collection]="listCollection.collection()"
      />
      <q-combobox
        class="w-48"
        invalid
        label="Invalid"
        placeholder="Select a country"
        [collection]="listCollection.collection()"
      />
    </div>
  `,
})
export class ComboboxStatesDemo {
  readonly listCollection = useListCollection<string>({
    filter: "contains",
    items: countries,
  })
}

Error Text and Indicator

Error messages are displayed using two props:

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

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

You must select a country

<q-combobox
  aria-label="Country"
  class="w-48"
  errorText="You must select a country"
  invalid
  placeholder="Select a country"
  [collection]="listCollection.collection()"
  (inputValueChanged)="onInputChange($event)"
/>

Hint Text

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

Country

Choose your country of residence

<q-combobox
  class="w-56"
  hint="Choose your country of residence"
  label="Country"
  placeholder="Select a country"
  [collection]="listCollection.collection()"
  (inputValueChanged)="onInputChange($event)"
/>

Within Dialog

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

<q-combobox
  aria-label="Country"
  class="w-48"
  disablePortal
  placeholder="Select a country"
  [collection]="listCollection.collection()"
  (inputValueChanged)="onInputChange($event)"
/>

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

<div q-popover>
  <div q-popover-anchor>
    <button q-button q-popover-trigger variant="outline">Click Me</button>
  </div>
  <q-combobox
    disablePortal
    label="Country"
    placeholder="Search for a country"
    [collection]="listCollection.collection()"
    (inputValueChanged)="onInputChange($event)"
  />
</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 combobox collection.

Template Forms

Strings

[ "Andorra" ]

Country

readonly value = signal<string[]>([countries[0]])

Objects

[ { "id": "US", "name": "United States" } ]

Country

readonly value = signal<Country[]>([{id: "US", name: "United States"}])

States

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

Disabled

Read only

Invalid

<q-combobox
  disabled
  label="Disabled"
  placeholder="Disabled"
  [collection]="listCollection.collection()"
  (inputValueChanged)="onInputChange($event)"
/>
<q-combobox
  label="Read only"
  placeholder="Read only"
  readOnly
  [collection]="listCollection.collection()"
  (inputValueChanged)="onInputChange($event)"
/>
<q-combobox
  errorText="Invalid"
  invalid
  label="Invalid"
  placeholder="Invalid"
  [collection]="listCollection.collection()"
  (inputValueChanged)="onInputChange($event)"
/>

Required

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

Country

<q-combobox
  class="w-48"
  errorText="Please select a country"
  label="Country"
  placeholder="Select a country"
  required
  [collection]="listCollection.collection()"
  [(ngModel)]="value"
  (inputValueChanged)="onInputChange($event)"
/>

Reactive Forms

Strings

[ "Andorra" ]

Country

readonly formControl = new FormControl<string[]>([countries[0]])

Objects

[ { "id": "US", "name": "United States" } ]

Country

readonly formControl = new FormControl<Country[]>([
  {id: "US", name: "United States"},
])

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 input clear-trigger trigger content item item-text item-indicator hint

API

<q-combobox>

The simple combobox extends the q-combobox-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 input 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 combobox dropdown content.	boolean
emptyText Text to display when no items match the filter.	string	'No results found'
errorText Optional error that describes the element when invalid is true.	string

highlightMatchingText Set to `true` to highlight option text matches during filtering.	boolean
hint Optional hint describing the element. This element is automatically associated with the component's input element for accessibility.	string

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

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

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 input 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 combobox dropdown content.

emptyText

Type

string

Description

Text to display when no items match the filter.

errorText

Type

string

Description

Optional error that describes the element when invalid is true.

highlightMatchingText

Type

boolean

Description

Set to true to highlight option text matches during filtering.

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.

virtual

Type

boolean

Description

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

Composite API

q-combobox-root

Prop	Type	Default
collection ^* The item collection	ListCollection
allowCustomValue Whether to allow custom values that are not in the collection	boolean	false
alwaysSubmitOnEnter Whether to always submit on Enter key press, even if popup is open	boolean	false
autoFocus Whether to autofocus the input on mount	boolean
closeOnSelect Whether the combobox should close after an item is selected	boolean	false
composite Whether the combobox is a composed with other composite widgets	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 combobox.	string
defaultInputValue The initial value of the input when opened.	string
defaultOpen Whether the combobox'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
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
disableLayer Whether to disable registering this as a dismissable layer	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 control element.	\| LucideIconData \| string
id id attribute. If omitted, a unique identifier will be generated for accessibility.)	string
immediate Whether to synchronize the present change immediately or defer it to the next frame.	boolean	false
inputBehavior Defines the auto-completion behavior of the combobox	\| 'none' \| 'autohighlight' \| 'autocomplete'	"none"
inputValue The value of the input	string
invalid Controls the visual error state of the input. When true, applies semantic error styling to indicate validation failure.	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 of the input field. Useful for form submission.	string
open Whether the combobox menu is open	boolean
openOnChange Whether to show the combobox when the input value changes	boolean	true
openOnClick Whether to open the combobox popup on click	boolean	true
openOnKeyPress Whether to open the combobox on arrow key press	boolean	true
placeholder Placeholder text to display when no value is selected.	string	"Select option"
positioning The positioning options of the menu.	PositioningOptions
present The controlled presence of the node.	boolean
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: { getElement: () => HTMLElement immediate?: boolean index: number }) => void
selectionBehavior The behavior of the combobox input when an item is selected - `replace`: The selected item string is set as the input value - `clear`: The input value is cleared - `preserve`: The input value is preserved	\| 'replace' \| 'clear' \| 'preserve'	"replace"
selectionIndicator Visual indicator style for selected items. Use "checkbox" for multi-select with always-visible checkboxes on the left, or "checkmark" for a checkmark icon on the right that only appears when selected.	\| 'checkmark' \| 'checkbox'	'checkmark'
size The size of the combobox and its elements. Governs properties like font size, item padding, and icon sizes.	\| 'sm' \| 'md' \| 'lg'	'md'
skipAnimationOnMount Whether to allow the initial presence animation.	boolean	false
translations Specifies the localized strings	{ clearTriggerLabel?: string triggerLabel?: string }
unmountOnExit When true, the component will be completely removed from the DOM when it becomes inactive or hidden, rather than just being hidden with CSS.	boolean	false
(exitCompleted) Function called when the animation ends in the closed state	void
(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 } & { highlightedItem: T highlightedValue: string }
(inputValueChanged) The callback fired when the input value changes	{ inputValue: string reason?: \| 'input-change' \| 'item-select' \| 'clear-trigger' \| 'script' \| 'interact-outside' }
(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	{ open: boolean reason?: \| 'input-click' \| 'trigger-click' \| 'script' \| 'arrow-key' \| 'input-change' \| 'interact-outside' \| 'escape-key' \| 'item-select' \| 'clear-trigger' \| 'input-focus' }
(pointerDownOutside) Function called when the pointer is pressed down outside the component	CustomEvent<{ event?: E }>
(valueChanged) The callback fired when the selected item changes.	{ items: Array<T> value: string[] }

collection

Type

ListCollection

Description

The item collection

allowCustomValue

Type

boolean

Description

Whether to allow custom values that are not in the collection

alwaysSubmitOnEnter

Type

boolean

Description

Whether to always submit on Enter key press, even if popup is open

autoFocus

Type

boolean

Description

Whether to autofocus the input on mount

closeOnSelect

Type

boolean

Description

Whether the combobox should close after an item is selected

composite

Type

boolean

Description

Whether the combobox is a composed with other composite widgets

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

defaultInputValue

Type

string

Description

The initial value of the input when opened.

defaultOpen

Type

boolean

Description

Whether the combobox'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.

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.

disableLayer

Type

boolean

Description

Whether to disable registering this as a dismissable layer

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 control element.

Type

string

Description

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

immediate

Type

boolean

Description

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

inputBehavior

Type

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

Description

Defines the auto-completion behavior of the combobox

inputValue

Type

string

Description

The value of the input

invalid

Type

boolean

Description

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

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

open

Type

boolean

Description

Whether the combobox menu is open

openOnChange

Type

boolean

Description

Whether to show the combobox when the input value changes

openOnClick

Type

boolean

Description

Whether to open the combobox popup on click

openOnKeyPress

Type

boolean

Description

Whether to open the combobox on arrow key press

placeholder

Type

string

Description

Placeholder text to display when no value is selected.

positioning

Type

PositioningOptions

Description

The positioning options of the menu.

present

Type

boolean

Description

The controlled presence of the node.

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: {
  getElement: () => HTMLElement
  immediate?: boolean
  index: number
}) => void

Description

Function to scroll to a specific index

selectionBehavior

Type

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

Description

The behavior of the combobox input when an item is selected
- replace: The selected item string is set as the input value
- clear: The input value is cleared
- preserve: The input value is preserved

selectionIndicator

Type

| 'checkmark'
| 'checkbox'

Description

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

size

Type

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

Description

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

skipAnimationOnMount

Type

boolean

Description

Whether to allow the initial presence animation.

translations

Type

{
  clearTriggerLabel?: string
  triggerLabel?: string
}

Description

Specifies the localized strings

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.

(exitCompleted)

Type

void

Description

Function called when the animation ends in the closed state

(focusOutside)

Type

CustomEvent<{
  event?: E
}>

Description

Function called when the focus is moved outside the component

(highlightChanged)

Type

{
  value: string
} & {
  highlightedItem: T
  highlightedValue: string
}

Description

The callback fired when the highlighted item changes.

(inputValueChanged)

Type

{
  inputValue: string
  reason?:
    | 'input-change'
    | 'item-select'
    | 'clear-trigger'
    | 'script'
    | 'interact-outside'
}

Description

The callback fired when the input value changes

(interactOutside)

Type

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

Description

Function called when an interaction happens outside the component

(openChanged)

Type

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

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

(valueChanged)

Type

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

Description

The callback fired when the selected item changes.

q-combobox-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-combobox-part`	'label'
`data-disabled`
`data-focus`
`data-invalid`
`data-readonly`
`data-required`

class

Value

'qui-select__label'

data-combobox-part

Value

'label'

data-disabled

Value

data-focus

Value

data-invalid

Value

data-readonly

Value

data-required

Value

q-combobox-control

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__control'
`data-combobox-part`	'control'
`data-disabled`
`data-focus`
`data-invalid`
`data-size`	\| 'sm' \| 'md' \| 'lg'
`data-state`	\| 'open' \| 'closed'

class

Value

'qui-select__control'

data-combobox-part

Value

'control'

data-disabled

Value

data-focus

Value

data-invalid

Value

data-size

Value

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

data-state

Value

| 'open'
| 'closed'

q-combobox-input

Prop	Type
aria-label v2.4.0 ARIA label applied to the input.	string
aria-labelledby v2.4.0 ID reference for an external label applied to the input.	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 input.

aria-labelledby

v2.4.0

Type

string

Description

ID reference for an external label applied to the input.

Type

string

Description

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

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

class

Value

'qui-input__input'

data-autofocus

Value

data-combobox-part

Value

'input'

data-invalid

Value

data-size

Value

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

data-state

Value

| 'open'
| 'closed'

q-combobox-trigger

Prop	Type
focusable Whether the trigger is focusable	boolean
id id attribute. If omitted, a unique identifier will be generated for accessibility.	string

focusable

Type

boolean

Description

Whether the trigger is focusable

Type

string

Description

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

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

class

Value

'qui-select__indicator'

data-combobox-part

Value

'trigger'

data-disabled

Value

data-focusable

Value

data-invalid

Value

data-readonly

Value

data-size

Value

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

data-state

Value

| 'open'
| 'closed'

tabIndex

Value

-1

q-combobox-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-combobox-part`	'clear-trigger'
`data-invalid`
`data-size`	\| 'sm' \| 'md' \| 'lg'
`hidden`	boolean
`tabIndex`	-1

class

Value

'qui-select__clear-trigger'

data-combobox-part

Value

'clear-trigger'

data-invalid

Value

data-size

Value

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

hidden

Value

boolean

tabIndex

Value

-1

q-combobox-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-combobox-part`	'positioner'
`style`	CSSProperties

q-combobox-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-combobox-part`	'content'
`data-disabled`
`data-empty`
`data-focus-visible`
`data-placement`	\| 'bottom' \| 'bottom-end' \| 'bottom-start' \| 'left' \| 'left-end' \| 'left-start' \| 'right' \| 'right-end' \| 'right-start' \| 'top' \| 'top-end' \| 'top-start'
`data-state`	\| 'open' \| 'closed'
`hidden`	boolean
`tabIndex`	-1

class

Value

'qui-select__content'

data-combobox-part

Value

'content'

data-disabled

Value

data-empty

Value

data-focus-visible

Value

data-placement

Value

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

data-state

Value

| 'open'
| 'closed'

hidden

Value

boolean

tabIndex

Value

-1

q-combobox-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-combobox-part`	'item'
`data-disabled`
`data-highlighted`
`data-selection-indicator`	\| 'checkmark' \| 'checkbox'
`data-size`	\| 'sm' \| 'md' \| 'lg'
`data-state`	\| 'checked' \| 'unchecked'
`data-value`	string
`tabIndex`	-1

class

Value

'qui-select__item'

data-combobox-part

Value

'item'

data-disabled

Value

data-highlighted

Value

data-selection-indicator

Value

| 'checkmark'
| 'checkbox'

data-size

Value

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

data-state

Value

| 'checked'
| 'unchecked'

data-value

Value

string

tabIndex

Value

-1

q-combobox-item-indicator

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

data-combobox-part

Value

'item-indicator'

data-state

Value

| 'checked'
| 'unchecked'

hidden

Value

boolean

q-combobox-item-text

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

class

Value

'qui-select__item-text'

data-combobox-part

Value

'item-text'

data-disabled

Value

data-highlighted

Value

data-state

Value

| 'checked'
| 'unchecked'

q-combobox-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.

Attribute / Property	Value
`class`	'qui-input__hint'
`data-combobox-part`	'hint'
`data-disabled`
`hidden`	boolean

q-combobox-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
`class`	'qui-input__error-text'
`data-combobox-part`	'error-text'
`hidden`	boolean

q-combobox-error-indicator

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

icon

Type

| LucideIconData
| string

Description

lucide-angular icon

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

Data Structures

ListCollection

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

@Component({
  template: `
    <q-combobox [collection]="collection" />
  `,
})
export class MyComponent {
  collection = comboboxCollection({
    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

ComboboxPositioningOptions

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

arrowPadding

Type

number

Description

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

arrowSelector

Type

string

Description

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

boundary

Type

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

Description

The overflow boundary of the reference element

fitViewport

Type

boolean

Description

Whether the popover should fit the viewport.

flip

Type

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

Description

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

getAnchorRect

Type

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

Description

Function that returns the anchor rect

gutter

Type

number

Description

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

hideWhenDetached

Type

boolean

Description

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

listeners

Type

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

Description

Options to activate auto-update listeners

offset

Type

{
  crossAxis?: number
  mainAxis?: number
}

Description

The offset of the floating element

onComplete

Type

(
  data: ComputePositionReturn,
) => void

Description

Function called when the placement is computed

onPositioned

Type

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

Description

Function called when the floating element is positioned or not

overflowPadding

Type

number

Description

The virtual padding around the viewport edges to check for overflow

overlap

Type

boolean

Description

Whether the floating element can overlap the reference element

placement

Type

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

Description

The initial placement of the floating element

sameWidth

Type

boolean

Description

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

shift

Type

number

Description

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

slide

Type

boolean

Description

Whether the popover should slide when it overflows.

strategy

Type

| 'absolute'
| 'fixed'

Description

The strategy to use for positioning

updatePosition

Type

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

Description

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

Last updated on May 22, 2026 by Ryan Bower

Collapsible

Data Grid / Table