Select

A dropdown picker built on a custom button + listbox UI. Sizes, color and visual variants, validation states, slot-overridable label/helper/prefix/suffix, and a clearable trigger. Toggle Vue / CSS to switch the live demo and source together.

Basic

Default select with label, placeholder and helper text.

Vue SFC

Keyboard

Opening highlights the first option, so ↑ / ↓ start from a known place and Enter picks without needing an arrow press first. This works whether or not the select is searchable — the trigger drives the list when there's no search field to hold focus.

Keys	Does
Enter / Space / ↓ (closed)	open the panel
↑ / ↓	move the highlight, scrolling it into view
Enter	select the highlighted option
Esc	close

The highlight is drawn as a leading bar on the option's left edge, distinct from the background that marks the selected option — an option is often both at once. Tune it with --mono-select-cursor-width (default 3px) and --mono-select-cursor-color.

Sizes

Small, medium and large.

Vue SFC

Variants

outlined, filled and underlined.

underlined focuses with a soft glow under the line rather than a ring around the field — tune it with --mono-select-underline-glow (default 0 5px 6px -6px).

Vue SFC

Colors

All built-in color variants.

Vue SFC

States

Disabled, readonly and required.

Vue SFC

Validation

valid, invalid and warning states with messages.

Vue SFC

Clearable

Clear button shown when a value is selected.

Vue SFC

Slots

Custom label, helper and prefix/suffix content via slots.

Vue SFC

Event: change

Listen to mno-change to react to selection.

Vue SFC

Event log

Live log of mno-change and mno-clear events.

Vue SFC

Customized

Override per-element styling with cssClass (Vue) or utility classes (CSS).

Vue SFC

Custom keys

Use key-value and display-value to feed natural-shape items (for example { id, name }) without pre-mapping. key-value names the property stored in modelValue; omit it to store the whole item object. display-value is either a property name (string) or a (item) => string function — when unset it falls back to item.label.

Without key-value the whole item is the value, and it is matched by identity — the object in modelValue has to be one of the objects in items. A reactive wrapper around it is fine (the select compares raw targets), but an item rebuilt between renders — a refetch, a structuredClone, a JSON round trip — is a different object and stops resolving. Pass key-value whenever items are re-created.

Vue SFC

DataSource (devextreme)

Bind a live devextreme DataSource with :data-source.prop. The select reads its items and stays reactive to the source's events — so an external ds.filter(...) + ds.load() updates the list with no re-binding. With load-more="scroll" it pages the source one chunk at a time (here pageSize: 5). This example builds the source with mono-utils' monoCreateFetcher against a public OData endpoint (baseUrl, no configBaseUrl). Bind with .prop and use key-value / display-value to map the server fields.

Search

Add searchable and the trigger becomes a text box you type into — with a bound DataSource it queries the server (debounced, search-value names the fields), otherwise it filters the items array client-side. search-operation picks the comparison (default contains), search-debounce the delay (default 300 ms) and search-placeholder the hint shown while open.

Search expressions

search-value is not limited to top-level field names. It takes the same grammar the data grid uses, as an array or as a comma-separated string — the two are equivalent, so plain HTML loses nothing:

search-value="Company.Name,Transaction.[*].Price,*.[*].*"

:search-value.prop="['Company.Name', 'Transaction.[1].Name', 'Transaction.[*].Price', '*']"

An entry can be:

Entry	Matches
Nama	a top-level field
Company.Name	a nested field
Transaction.[1].Name	one array element
Transaction.[*].Name	any element of the array
*	every top-level field
Company.*	every field of Company
*.*	every field of every nested object
*.[*].*	every field of every array element

Patterns read literally, segment by segment — '*' covers the top level only, so pair it with '*.*' / '*.[*].*' to reach deeper. A field named explicitly always wins over a pattern, in either order, and is searched exactly once.

In the array form an entry may also be a { field, custom } clause builder, for a column contains can't search — a boolean, or a code the user never types. Return null to opt the column out of a given term:

:search-value.prop="[
  '*',
  { field: 'Active', custom: ({ field, value }) => `${field} eq ${value === 'yes'}` },
]"

Setting search-value explicitly means it alone decides what is searched.

Leave it off and the default is '*' — every top-level field of an option — so searching works without naming anything. display-value (when it's a string) and key-value stay in the list beside it, and the rendered display text is matched too, which is the only way to search a display-value function.

Two caveats on a bound DataSource: a * pattern is resolved against the rows already loaded, so it can only see fields present in that sample; and it only emits clauses for string columns, because contains(Price,'x') is not valid OData. That is exactly why display-value / key-value remain alongside '*' — they are explicit entries, so they still work before the first page arrives and a numeric key-value stays searchable. Give any other non-text column an explicit entry or a custom builder.

To offer no search at all, drop searchable rather than emptying search-value.

Vue SFC

Grouped options

display-group is an array with one accessor per level (string field or function), used as the group key and header. Add the boolean group to bucket a paginated source client-side, or feed pre-grouped { key, items } data directly; group-sticky pins headers.

Two levels over a 1,200-row static array, load-more="scroll" revealing a chunk at a time.

Pre-grouped data with custom group-key / group-items field names.

Width & height

Set width, height, min-width, max-width, min-height or max-height — each takes a CSS string ("260px", "80%") or a number (px). This sizes the field (distinct from dropdownHeight/dropdownMaxHeight, which size the popup).

Vue SFC

Placement

The dropdown keeps itself inside the viewport, so a select near the bottom of the page is never clipped:

• flip (default true) opens the list upward when there isn't room below.
• shift (default true) slides it horizontally so it doesn't overflow a screen edge.
• When neither side fits the full list, it opens on the roomier side and shrinks to fit, scrolling internally. This caps dropdownHeight / dropdownMaxHeight — those stay the requested size whenever there is room for them.

Set :flip="false" / :shift="false" to pin the list below the field.

CSS Variables

Vue SFC

Themed through --mono-select-* custom properties (they inherit and pierce the shadow boundary); an explicit --mono-select-focus-color override wins over the color prop. Re-skin globally via the --theme-* tokens.

Variable	Default	Controls
--mono-select-focus-color	--theme-primary	Focus / hover border (set by color)
--mono-select-focus-rgb	primary rgb	Focus ring color (as r, g, b)
--mono-select-underline-glow	0 5px 6px -6px	Underlined focus glow geometry
--mono-select-cursor-width	3px	Keyboard-cursor bar on the highlighted option
--mono-select-cursor-color	--mono-select-focus-color	Colour of that bar
--mono-select-text	--theme-text	Trigger + label text color
--mono-select-border	--theme-border	Trigger border color
--mono-select-surface	--theme-surface	Dropdown / option surface
--mono-select-background	--theme-background	Trigger background base
--mono-select-shadow	0 1px 2px …	Trigger shadow
--mono-select-dropdown-shadow	elevation preset	Dropdown popup shadow
--mono-select-success	--theme-success	Valid-state color
--mono-select-danger	--theme-danger	Invalid / required color
--mono-select-warning	--theme-warning	Warning-state color

Types

Importimport { SelectProps } from 'mono-helper'

Prop	Value	Default	Description
modelValue	unknown	—	The currently selected value.
value	unknown	—	Alias for the selected value, kept in sync with modelValue.
items	string | SelectItem[]	—	List of selectable items, as an array or JSON string.
dataSource	SelectDataSource<SelectItem>	—	DataSource used to drive the item list, taking precedence over items.
immediate	boolean	—	Auto-load the DataSource on attach when it has no items yet.
loadMore	'' | 'button' | 'scroll' | boolean	—	Incremental loading mode: scroll, button, or off.
pageSize	number	—	Chunk size used when paging a plain items array.
keyValue	string	—	Item property name used as the model value.
displayValue	string | (item: SelectItem) => string	—	Item property name or function used to derive display text.
displayGroup	SelectDisplayGroup	—	Per-level accessors for grouped options (header label per group level).
groupKey	string	—	Field holding a group node's key (default 'key').
groupItems	string	—	Field holding a group node's child array (default 'items').
searchable	boolean	—	Turn the field itself into a search input (combobox); server query when a DataSource is bound.
searchValue	string | MonoSearchExprEntry[]	—	Field(s) the search matches (server query + client filter target). A comma string or an array; entries may be plain columns, paths (`Company.Name`, `Transaction.[*].Price`), `*` patterns (`'*'`, `'*.[*].*'`) or, in array form, `{ field, custom }` clause builders.
searchOperation	string	—	devextreme search operation for server search (default 'contains').
searchDebounce	number	—	Debounce (ms) before a server search fires (default 300).
searchPlaceholder	string	—	Placeholder shown in the field while it is open/searching (falls back to `placeholder`).
group	boolean	—	Group a plain, paginated DataSource client-side (keeps scroll/load-more).
groupSticky	boolean	—	Keep group headers pinned to the top while their rows scroll.
dropdownHeight	string | number	—	Fixed height of the scrollable dropdown list.
dropdownMaxHeight	string | number	—	Maximum height of the scrollable dropdown list.
stayOpen	boolean	—	Exempt this select from every automatic close — clicking or focusing anything outside it, which includes opening another select. Not a lock: its own trigger, Escape and picking an item still close it. Set it on every select to allow several dropdowns open at once.
size	'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl'	—	Visual size of the select.
color	'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info'	—	Color theme applied to the select.
variant	'underlined' | 'outlined' | 'filled'	—	Visual style variant of the select.
label	string	—	Text label shown above the select.
placeholder	string	—	Placeholder text shown when no value is selected.
helperText	string	—	Helper text shown below the select.
validationState	'warning' | 'default' | 'valid' | 'invalid'	—	Validation state controlling the select's appearance.
validationMessage	string	—	Validation message shown below the select.
errorMessage	string	—	Error message shown below the select.
successMessage	string	—	Success message shown below the select.
name	string	—	Form field name submitted with the value.
disabled	boolean	—	Disables the select, preventing interaction.
readonly	boolean	—	Makes the select read-only, blocking value changes.
required	boolean	—	Marks the select as required and shows a required indicator.
clearable	boolean	—	Shows a clear button to reset the selected value.
ariaLabelText	string	—	Accessible label used when no visible label is present.
ariaLabel	string	—	—
width	string | number	—	Explicit sizing of the field. Each accepts a CSS length string (`"320px"`, `"80%"`) or a number (interpreted as px). Use `width="100%"` for full width. (Distinct from `dropdownHeight`/`dropdownMaxHeight`, which size the popup.)
height	string | number	—	—
minWidth	string | number	—	—
maxWidth	string | number	—	—
minHeight	string | number	—	—
maxHeight	string | number	—	—
cssClass	SelectCssClass	—	Custom CSS classes applied to internal select parts.
visible	boolean	—	Whether the control is shown. Defaults to `true`.
visibleType	'invisible' | 'none'	—	How it hides when `visible` is `false`. Defaults to `'none'`.