Usage

Selector opens a list when the trigger is clicked. Choosing one option closes the list. It can filter the list, clear the current value, and disable individual options.

Pass the options and bind the value:

<script setup lang="ts">
import { Selector } from '@astryx-vue/core/Selector'
import { ref } from 'vue'

const selected = ref(null)
const options = [
  { value: 'apple', label: 'Apple' },
  { value: 'banana', label: 'Banana' },
  { value: 'cherry', label: 'Cherry' },
]
</script>

<template>
  <Selector v-model="selected" :options="options" placeholder="Select a fruit" />
</template>

Each option has a value and a label. Set disabled to skip an option, or description to add a second line of text.

searchable shows a search field that filters the list. hasClear adds a clear button next to the current value; clearable is the older name. The menu is at least as wide as the trigger, and grows when an option label is longer.

A read-only field keeps the current value, stays focusable, and still submits with the form. It does not open, and it has no clear button or chevron. It does not dim. Disabled wins when both are set. While loading, the trigger shows a spinner and the menu does not claim that nothing was found. An empty catalog and a search with no matches use different sentences. The check mark sits at the end of a selected row by default, and can move to the start. An unselected row does not reserve space for it. disabledMessage explains a disabled field: a tooltip follows hover and keyboard focus, the trigger stays focusable through aria-disabled, and the list still does not open.

Arrow keys move the highlight. Home and End jump to the ends. Enter selects the highlighted option, and Escape closes the list. Once the search field is open, the arrow keys and Enter apply there, and Space still types a character.

Built-in strings such as the placeholder and the empty state are English. Call provideAstryxLocale('zh-CN') to use the Chinese strings.

Best Practices

Guideline	Practice
Do	Enable search when options exceed 10 items to help users find items quickly.
Do	Provide a clear button for non-required fields so users can deselect.
Do	Use concise, clear option labels and avoid overly long text.
Don't	Put more than 100 options in a selector; consider pagination or async loading.
Don't	Use selector for multi-select; use a dedicated multi-select component instead.

Anatomy

Element	Description
Field	Standalone Field shell that provides the label and optional supporting content; omitted inside InputGroup.
Trigger	Painted control that displays the current selection or placeholder and opens the selection surface when editable.
Icon-rendered start icon	Optional leading semantic icon or icon component rendered through Icon.
Caller-rendered start content	Optional arbitrary slot content rendered directly at the start of the trigger.
Trigger clear button	Shared clear action that removes the selected value when clearable is set.
Status icon	Status glyph shown in place of the disclosure indicator for attached or tooltip status.
Indicator icon	Trailing chevron shown when status presentation does not replace it; reflects collapsed or expanded state.
Search row	Panel header with a borderless search input and optional clear action.
Search icon	Leading magnifier rendered through Icon inside the search row.
Search clear button	Shared clear action shown in the search row while a query is present.
Option row	Selectable row for one supplied option.
Default option content	Label, description, and icon drawn from the option data when the option slot is not provided.
Option slot content	Content supplied through the option slot, in place of the default label and description.
Option selection indicator	Resolved selection mark rendered for each option in its checked or unchecked state. Its layout space collapses when the resolved indicator draws nothing.
Option divider	Divider supplied in the public options data to separate adjacent option groups.
Section heading	Visible heading for a labeled group of option rows.
Empty state	Message shown when the shared panel content has no options or no search matches.
Pointer popup	Anchored painted surface that hosts the shared panel content for popover presentation.
Touch sheet heading	Heading above the shared panel content in bottom-sheet presentation.
Touch sheet	BottomSheet surface that hosts the same panel content for bottom-sheet presentation.

Examples

Bottom sheet

Team

Team

Presents a single-selection list in a bottom sheet for compact touch interfaces.

Clearable

Department

A clear button resets the selected value.

Ghost toolbar

Calendar view

Density

This setting affects all users

A borderless selector sits with ghost buttons in a toolbar.

Secondary

Priority

The secondary trigger rests like a secondary button: no border, and a neutral fill.

Option actions

City

An option can carry an action. Activating it does not change the selection. Once any option has an action, the menu becomes two columns.

Grouped sections

Office

Options are grouped into labeled sections.

Option descriptions

Visibility

Default trigger: one line at the size token.

Visibility

A stacked value: the description gets its own line, and the trigger grows by exactly one line.

Visibility

Visibility

Options carry a description, so the menu draws a two-line row. A one-line value stays at the size token. A two-line value grows by one line. Inside an input group the value stays on one line.

Validation states

Role

Please select a role

Role

Viewer has limited access

Role

Error, warning, and success validation states.

Read-only, disabled, loading, and search

Saved fruit

Read only

Catalog

Required fruit ∙ Required

Locked fruit

Only the owner of this list can change it

Search fruit

Read-only keeps the current value. Loading does not claim the catalog is empty. Required is marked beside the label. A disabled field explains itself in a tooltip on hover or keyboard focus and stays focusable. A search with no matches uses its own sentence, and the check mark can sit at the start of the row.