Select

WHEN TO USE

• The value comes from a set the product knows in advance: a country, a status, an assignee, a plan.
• The list is long enough that showing every option at once would dominate the form, but short enough that the user recognises the option rather than recalling it.
• The list is long enough to need filtering — set hasSearch and a search field is rendered in the panel header.

WHEN NOT TO USE

• The user may need to enter a value that is not in the list. The field is isReadonly by default, so typing an unlisted value is not possible.USE COMBOBOX →
• There are only two or three options and the form has room. Showing them all costs one click less and makes the choice visible while filling the rest of the form.USE RADIO-GROUP →
• The choice is a binary on/off for a single setting.USE TOGGLE →
• What is being opened is a list of actions or destinations rather than a value the form will submit.USE MENU →

DO

• Give the panel a search field with hasSearch once the list passes roughly ten options — scanning a long unfiltered list is where this control gets slow.
• Use align="top" when the field sits near the bottom of the viewport, so the panel opens into space rather than off-screen.
• Set isError alongside errorNote, exactly as with al-input — the field treatment is inherited, and so is that requirement.
• Keep isReadonly at its default true unless you have deliberately built a type-ahead. It is what stops the user typing a value the list cannot honour.

DON’T

• Don't expect the options to exist in the DOM while the select is closed. The dropdown panel is only rendered when the panel is open, so anything that walks the light DOM for options — a test, a form serializer, an autofill heuristic — will find nothing until it is opened.
• Don't stamp role="option" onto the slotted items. They are al-list-items that render their own <button>, and an interactive role wrapping an interactive control is exactly the pattern the component avoided on purpose.
• Don't use this for multi-select without checking what the composed panel actually renders — the component registers al-checkbox for that case, but the behaviour is not a documented public prop.
• Don't reach for a select when the answer is a date. There is a dedicated picker with the calendar semantics that come with it.