Choice & selection
AppSelect
Pick one value from a known set of options — searchable once the list grows past a handful.
<app-select label="Client" name="client">…</app-select><app-select> lets a user pick one value from a known set of options. It collapses the choices into a single control until opened, and turns on a type-to-filter box once the list grows past a handful — so a four-item list and a forty-item list both stay usable.
Its look comes entirely from the shared @webority/theme, and the behaviour lives once in the shared <wui-select> element, so the Razor <app-select> and the React <AppSelect> render and behave identically on every Webority surface.
Playground
Every attribute, live. Each change re-renders the real tag helper on the server, so the markup underneath is the exact call that produced the select above it.
value only seeds the initial selectionThe value control picks what's selected when the page loads; picking a different option in the control itself does not round-trip back into this field — that's client-side state the tag helper does not read.
Basic
A labelled select with a placeholder. Give it the options and a value; it reports the chosen value back on change.
A single-choice select
Show code
<app-select label="Client" name="client" placeholder="Select a client…">
<app-option value="rpg">RPG Bhiwadi DC</app-option>
<app-option value="tata">Tata Power Mumbai</app-option>
<app-option value="adani">Adani Green Gujarat</app-option>
<app-option value="lt">L&T Construction</app-option>
</app-select>
Searchable
Set searchable to add a type-to-filter box inside the menu. Reach for it once the list runs past about ten options.
Type-to-filter
search-placeholder labels the filter box inside the open menu.
Show code
<app-select label="Client" name="client" searchable
search-placeholder="Search clients…" placeholder="Select a client…">
<app-option value="rpg">RPG Bhiwadi DC</app-option>
<app-option value="tata">Tata Power Mumbai</app-option>
<app-option value="adani">Adani Green Gujarat</app-option>
<app-option value="lt">L&T Construction</app-option>
</app-select>
Make it searchable past ~10 optionsUnder a handful of options, a plain select is quickest. Past about ten, add
searchable so the user can type-to-find instead of scrolling a long menu.Clearable
Set clearable to add a ✕ that resets the selection back to empty. It appears only once a value is chosen.
Reset the selection
Show code
<app-select label="Client" name="client" clearable placeholder="Select a client…">
<app-option value="tata" selected>Tata Power Mumbai</app-option>
<!-- … -->
</app-select>
Sizes
size takes sm or lg (md is the default), matching AppInput so a select lines up with the text fields beside it in a form row.
Small, medium, large
Show code
<app-select label="Small" name="c" size="sm">…</app-select> <app-select label="Medium (default)" name="c">…</app-select> <app-select label="Large" name="c" size="lg">…</app-select>
Leading icon
icon adds a leading Bootstrap Icons glyph inside the control — a quick visual cue for what the select picks (a client, a category, a status).
A select with a leading icon
Show code
<app-select label="Client" name="client" icon="building" placeholder="Select a client…">…</app-select>
Option icons
Give any option an icon (a Bootstrap Icons name) and it renders on that row in the menu — and on the selected value in the control. Great for statuses and categories.
An icon per option
Show code
<app-select label="Status" name="status">
<app-option value="active" icon="check-circle">Active</app-option>
<app-option value="pending" icon="clock" selected>Pending</app-option>
<!-- … -->
</app-select>
Floating label
Set floating-label to sit the label inside the control as a placeholder; it slides up and shrinks on focus or once a value is chosen.
Label slides up on select
Show code
<app-select label="Client" name="client" floating-label>
<app-option value="rpg">RPG Bhiwadi DC</app-option>
<!-- … -->
</app-select>
Custom class & width
The plain class attribute merges onto the field wrapper — reach for it to size the select with a width utility or your own class. No special attribute needed.
Size the select with class
Show code
<app-select label="Full width" name="c">…</app-select> <app-select label="Half width" name="c" class="w-50">…</app-select>
Validation
A select carries the same field treatment as the text inputs — a required mark on the label, a hint for guidance, and an error that turns the control red.
Required with an error
Client is required.
Show code
<app-select label="Client" name="client" required error="Client is required.">
<app-option value="rpg">RPG Bhiwadi DC</app-option>
<!-- … -->
</app-select>
When to use
Use it when
- The user picks one value from a known set of roughly 6 or more options.
- The options are a fixed list you can render up front — statuses, clients, categories.
- You want a compact control that keeps the choices collapsed until opened.
Reach for something else when
- There are only 2–5 options and they fit comfortably on screen. → AppRadio
- The user needs to pick several values at once. → AppMultiSelect
- The list is large or loaded from the server as the user types. → AppAutocomplete
- It is a compact single-purpose picker like page size. → AppSelectMini
Best practices
Do
Past ~10 options, searchable turns a long scroll into a quick type-to-find.
Don't
A long, unsearchable list forces the user to scroll and scan every time.
Do
A label names the field and the placeholder tells the user what to pick.
Don't
No label and a bare 'Select' leave the field's purpose unclear.
Do
Choose the client this project belongs to.
A specific error says which choice is missing and why it matters.
Don't
Required
'Required' just repeats the asterisk without helping.
Every option
The whole surface of the component, one cell per value — plus the shell states (disabled, required + error) and a long list that exercises the search-select menu's own scroll.
size — sm · (default) · lg
size="sm"
(default)
size="lg"
searchable / clearable
(default)
searchable
clearable (value set)
searchable + clearable
icon — leading control icon vs. per-option icon
icon="building" (control)
per-option icon
state — disabled · required + error · floating label
disabled
required + error
Client is required.
floating-label + value
floating-label + empty
long list — searchable menu scroll
30 options, searchable
Grouped options and a per-option disabled are not supportedThe shared
<wui-select> element reads only value, label and icon per option — there is no group header and no way to mark a single option unselectable. A caller wanting either has to fake it today (a label prefix for grouping, filtering the option out entirely instead of disabling it). Reported as a library gap, not fixed here.Attributes
| Attribute | Type | Default | Description |
|---|---|---|---|
| label | string | — | The field label. Rendered with the field shell. |
| name | string | — | Field name the select posts its value under. |
| placeholder | string | Select... | Shown in the control when nothing is selected. |
| search-placeholder | string | Search... | Placeholder for the in-menu search box. |
| searchable | bool | false | Adds a type-to-filter box inside the menu. |
| clearable | bool | false | Adds a ✕ that resets the selection; shown only when a value is set. |
| size | string | — | Control size: sm / lg. Omit for the default (md). |
| icon | string | — | Leading Bootstrap Icons glyph inside the control, e.g. building. |
| prefix | string | - | A bordered box before the select, e.g. +91. The same shell as <app-input prefix>. |
| suffix | string | - | A bordered box after the select, as <app-input suffix>. |
| floating-label | bool | false | Label sits inside as a placeholder and slides up on focus/selection. |
| class | string | — | Merges onto the field wrapper — e.g. a width utility to size the select. |
| disabled | bool | false | Disables the control. |
| required | bool | false | Appends a required mark to the label. |
| hint | string | — | Helper text below the control. Hidden while an error is shown. |
| error | string | — | Error message. Turns the control red and replaces the hint. |
| <app-option> value | string | — | The value of an option child. Its label is the inner content. |
| <app-option> icon | string | — | Leading Bootstrap Icons glyph for that option, e.g. check-circle. |
| <app-option> selected | bool | false | Marks that option as initially selected. |
| help | string | — | Info-tip content shown beside the label. |
| help-label | string | More information | aria-label for the info-tip button (React helpLabel). |
| value | string | — | The selected option value. With asp-for this comes from the model instead. |
| aria-label | string | — | Explicit accessible name for the control. Wins over the label-derived aria-label — needed for a label-less filter/toolbar select. |
| aria-labelled-by | string | — | Forwarded verbatim onto the control (React aria-labelledby). |
| aria-described-by | string | — | Forwarded verbatim onto the control (React aria-describedby). |
| input-class | string | — | Extra classes on the control itself (the wui-select) — the React className counterpart. The plain class attribute merges onto the .field wrapper instead. |