Form controls

Select

One value from a list of five or more. The kit draws the list itself, in the theme's colors and type, and never hands it to the browser. It takes the same border, focus ring and error treatment as Input. For two to four short choices use a SegmentedControl, and see Choosing a control for the whole rule. Reach for Autocomplete when typing is the main way in, and MultiSelect for several values at once.

Basic

Pass the rows as options and bind the value.

Never the browser's list

There is no native mode. A native select opens a list the operating system paints, in its own font and highlight color, and no stylesheet reaches it: on a dark page it opens white. So the trigger is a button and the panel is the kit's own, with the same keyboard model as a select. Arrow keys move, Enter picks, Escape closes, and typing a few letters jumps to a matching row.

In a form

name posts the value through a hidden input, exactly as a select would. onvaluechange fires once that input holds the new value, so a page that saves on change can submit the form from it and post the value just picked.

A hidden input is barred from constraint validation, so required is announced through aria-required and enforced by the page and the server.

Groups

group collects a run of neighboring rows under a heading. An array that interleaves two groups shows the heading twice, which is what the array says. placeholder shows while nothing is chosen.

Icons

A row can carry a lucide icon before its label, and the chosen row carries a tick.

Searching the panel

searchable adds a search box, and the letters typed become query text instead of a jump. Add it once a list passes about ten rows, as the thirteen tenants here do. keywords gives the matcher more than the label, so a row known by a machine name or a code can be found by typing it. Matching ignores case and accents. Try GBX here.

filter replaces the matcher, and filter={false} switches local filtering off for a list that arrived already narrowed by a server query.

Under the keyboard, the search box turns its border the focus color, with no ring inside or around it, as the field does.

A trigger of your own

trigger fills the button rather than replacing it. The button stays, because it carries the id, the label association and the ARIA, and a button nested in another button is not markup a browser will focus.

Error state

Described by text elsewhere

describedBy takes the ids of other elements that explain the control, separated by spaces. A screen reader reads them after the control's own hint or error. Use it when the explanation already sits on the page, such as a note above a form or the message a wrapping Field renders.

Under a touch screen

Every option in the open list is 44px tall, as a Dropdown menu item is. A mouse keeps the shorter rows.

A list that would run past the side of the screen, or of the dialog or scrolling box it opens in, slides back inside it. In a container too short for it above and below, such as a one-field Modal, it opens below its field at its own height, and the container grows to hold it or scrolls down to it. The list keeps at least four rows in view, or all of them when it has fewer.

API

SelectOption