# Select A dropdown selector supporting single/multiple selection, groups, clearable, remote search, and custom creation, with size/status variants, controlled open, and selection limits, fully operable by keyboard. ## Single Select ## Accessible Name (label) The `label` attribute provides the trigger's accessible name (`aria-label`): when set, screen readers announce it and it takes priority over the placeholder; when unset, it falls back to `placeholder`. The visible field-label position is handled by `oas-form-item`, and native `label for` association (click-to-focus) goes through the form-associated channel. ## Preset Value ## Multiple Select In multiple mode `value` is a JSON array; selected items are shown as tags that can be removed individually. Tags wrap to new lines by default and the trigger grows with the content (no collapsing unless `max-tag-count` is set). ## Hide Selected (hide-selected) `hide-selected` (multiple mode only) removes selected options from the dropdown β€” the list only shows "what is still selectable", useful for multi-select over large option sets; clearing (clearable) or removing a tag puts the option back into the list automatically. Selecting everything shows the empty state. ## Disabled ## Size `size` supports `small` / `medium` (default) / `large`; control height and font size follow the global size tokens. When not set explicitly, the nearest `oas-config-provider` `size` injection applies (global density sync). Use `small` inside tables or `large` on filter bars directly. ## Variants `variant` mirrors the `oas-input` three-value variants: `outlined` (default border) / `filled` (tinted background, border appears on focus/open) / `borderless` (no border, no background β€” for plain-text embedding or low-chrome filter bars); invalid values silently fall back to the default. The `status` semantic color takes precedence over the variant background. ## Status `status` supports `success` / `warning` / `error`, tinting the trigger border and focus ring. `error` also mirrors `aria-invalid="true"` onto the host (recognizable by screen readers); setting `aria-invalid` directly produces the same visual. Pairs well with form validation. ## Readonly `readonly` and `disabled` carry different form semantics: readonly is focusable, copyable, never opens the dropdown, and the value still submits (clear and tag-remove affordances are hidden); disabled is not focusable and its value does not submit. Use readonly to display values decided elsewhere, disabled to block interaction. ## Empty State When options are empty, the dropdown shows "No data". ## Custom Empty `template[slot="empty"]` overrides both the "no data" and "no match" default texts (which come from the locale registry); the content is cloned into the dropdown empty area. ## Searchable Once opened, you can type directly to filter; when nothing matches, "No matching options" is shown. ## Custom Filtering By default options are matched by `label` inclusion; assigning `el.filterMethod = (query, option) => boolean` (a JS property channel β€” attributes cannot carry functions) takes over local filtering, where `query` is the raw input and `option` the full option object. This example (see the page script at the bottom) matches both `value` and `label` (pinyin-initial matching and other custom rules work the same way); in `remote` mode the host owns data-side filtering and `filterMethod` does not apply. ## Controlled Search Input (input-value) `input-value` makes the search text controllable: when the attribute is present it is the source of truth for the search box (presets/external updates sync into the box and re-filter); user typing writes the attribute back and dispatches `oas-input-value-change` (`detail: { value }`) β€” the host can listen or simply read the attribute. ## Reserve Keyword (reserve-keyword) In multiple + searchable mode, the keyword is cleared by default after selecting an option (the list resets so you can pick unrelated items); with `reserve-keyword` the keyword is kept, ideal for picking multiple items among similar results. ## Highlight First Option (default-active-first-option) When set, opening the dropdown highlights the first visible option (Enter picks it); by default the currently selected option is highlighted. ## Groups Options carrying a `group` field are rendered under a group title (not selectable), with items indented; keyboard `↑`/`↓` navigates continuously across groups. ## Clearable When a value is selected, a clear button appears; clicking clears the value and dispatches `oas-clear` and `oas-change`. ## Trigger Affixes & Custom Icons `template[slot="prefix"]` / `template[slot="suffix"]` render into the trigger affixes (icons, unit text, etc.); `template[slot="suffix-icon"]` replaces the default dropdown arrow (rotating with the container when expanded); `template[slot="clear-icon"]` replaces the default Γ— icon of the clear button. `show-arrow="false"` hides the default arrow (arrow-less search-trigger scenarios). ## Remote Search In `remote` mode the component does no local filtering: typing dispatches `oas-input` for the host to request data, and the host sets `loading` during the request to show a loading placeholder. This example simulates an 800ms delayed filter: ## Loading Text (loading-text) `loading-text` overrides the default loading placeholder copy (built-in locale copy by default); pair it with `remote` / `loading`. ## Remote Debounce `debounce` (milliseconds, default `0` β€” dispatch immediately, leaving existing behavior untouched) applies only to `oas-input` dispatching in `remote` mode: rapid inputs within the window collapse into a single last-value dispatch, sparing the host a `setTimeout` boilerplate; local filtering is always instant. ## Tag Collapse Multiple-select tags wrap by default and do not collapse; only when `max-tag-count` is explicitly set do they collapse into `+N` (hover to see the remaining items). ## Hint & Auto Width `hint` renders one line of hint copy below the trigger (wired via `aria-describedby`, screen-reader reachable); `auto-width` lets the trigger width shrink to fit the selected item/content (fixed `220px` by default). ## Reserve Widest Option (reserve-width)
`reserve-width` (opt-in) measures the max text width of all option labels plus the placeholder and locks the trigger min-width: the trigger never jitters when switching values. It pairs well with `auto-width` β€” after shrinking to content, the reserved value acts as the floor (the first select above is locked to the widest option, the second is the control; open the dropdowns and switch values to see the difference). Both the `options` attribute and the declarative child channel participate; content changes re-measure automatically; removing the attribute releases the lock. The text width is an approximation (trigger chrome margin tunable via the `--oas-select-reserve-pad` variable, default 46px). ## Max Count Limit hint With `multiple` and `max-count` set, once the selection reaches the limit, unselected options become disabled and grayed out (selected ones can still be deselected, which re-enables the rest); attempts to exceed the limit β€” click or keyboard β€” dispatch `oas-exceed-limit` (`detail: { value, max }`), which this example uses to update the hint tag. `max-count` has no effect in single-select mode. Voting and tag-cap scenarios work out of the box. ## Allow Create When search yields no match, a "Create {label}" item is shown; clicking or pressing Enter creates a new option from the input value and selects it. Creation dispatches `oas-create` (`detail: { value, label }` carrying the created text). ## Custom Option Rendering Listen to `oas-option-render` (each option row) and `oas-tag-render` (multi-select tags); `detail.element` is the corresponding text container that the host can rewrite into any content (icons, rich text). You can also put `