Forms

Select

@xui/select

A filterable single-select. The trigger opens a popover with a search field and a keyboard-navigable list (Arrow keys + Enter, Escape closes). Items render with a custom [xuiSelectOption] template. [(value)] two-way binding.

Install

pnpm add @xui/select

Add the barrel to a standalone component's imports:

import { XuiSelectImports } from '@xui/select';

@Component({
  imports: [XuiSelectImports],
  // …
})

Examples

Default

Loading preview…

<div class="w-64">
  <xui-select [items]="users" [itemText]="itemText" [(value)]="selected" placeholder="Select a user" />
  <p class="text-foreground-muted mt-3 text-sm">Selected: {{ selected?.name ?? '—' }}</p>
</div>

Custom items

Source only — this one needs a component of its own to run, so there is nothing to render here.

<div class="w-72">
  <xui-select [items]="users" [itemText]="itemText" [itemDisabled]="itemDisabled" placeholder="Assign to…">
    <ng-template xuiSelectOption let-user let-active="active">
      <div class="flex flex-1 items-center justify-between">
        <span>{{ user.name }}</span>
        <span class="text-foreground-muted text-xs">{{ user.role }}</span>
      </div>
    </ng-template>
  </xui-select>
</div>

Non filterable

Loading preview…

<div class="w-64"><xui-select [items]="users" [itemText]="itemText" [filterable]="false" placeholder="Pick one" /></div>

API

XuiSelectOption

directive

ng-template[xuiSelectOption]

Marks an <ng-template> as a xui-select item renderer.

XuiSelect

component

xui-select

A filterable single-select dropdown: a trigger button opens a popover with a search field and a keyboard-navigable list. Items can be rendered with a custom [xuiSelectOption] template. [(value)] two-way binding.

Inputs

Name

Type

Default

class

ClassValueExtra classes, merged into the component's own rather than replacing them.

''

items

readonly T[]The options to choose from.

[]

itemText

(item: T) => stringHow an item is labelled, in both the list and the trigger. Also what the default filter matches against.

(item: T) => (item == null ? '' : String(item))

itemPredicate

(query: string, item: T) => booleanCustom filter for one item against the query. Defaults to a case-insensitive substring match on itemText.

—

itemListPredicate

(query: string, items: readonly T[]) => T[]Filter the whole list at once, for ranking or fuzzy matching that cannot be decided item by item. Takes precedence over itemPredicate.

—

itemDisabled

(item: T) => booleanWhich items cannot be selected. They stay in the list, greyed out.

() => false

filterable

booleanShow the query field above the list. Turn it off for a short, fixed set of options.

true

disabled

booleanBlock interaction and dim the trigger. The list cannot be opened.

false

matchTargetWidth

booleanMake the dropdown exactly as wide as the trigger. On by default.

true

resetOnClose

booleanClear the query (and thus the filter) each time the popover closes.

true

placeholder

stringTrigger text shown while nothing is selected. Doubles as the accessible name when neither aria-label nor aria-labelledby is given.

'Select…'

ariaLabel

string | nullNames the control. A combobox takes its *value* from its content, so the name has to come from a label — without one axe reports button-name and a screen reader announces the current value with no idea what it is for. Falls back to the placeholder, which is at least descriptive.

null

ariaLabelledby

string | nullId of an element naming the select. Use it instead of aria-label when that text is already on screen.

null

searchPlaceholder

stringText shown in the empty query field.

'Filter…'

noResultsText

stringShown in place of the list when the query matches nothing.

'No results.'

value

two-way

T | nullThe chosen item. Two-way bindable with [(value)], or via formControl/ngModel.

null

Source

libs/ui/select/xui