Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

Single choice

A labelled select with a placeholder picks one value from a list, and it can be cleared or marked required.

A single-choice select
RPG Bhiwadi DC Tata Power Mumbai Adani Green Gujarat L&T Construction
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" selected>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>
Reset the selection
RPG Bhiwadi DC Tata Power Mumbai Adani Green Gujarat L&T Construction
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>
Open on hover
open-on-hover opens the list when the mouse rests on the control and closes it when the mouse leaves; touch still taps, and a select with a search box ignores it.
RPG Bhiwadi DC Tata Power Mumbai Adani Green Gujarat L&T Construction
Show code
<app-select label="Client" name="client-hover" open-on-hover="true">
    <app-option value="rpg">RPG Bhiwadi DC</app-option>
    <!-- … -->
</app-select>
Required with an error
RPG Bhiwadi DC Tata Power Mumbai Adani Green Gujarat L&T Construction
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>

Searchable

Add a type-to-filter box once the list runs past about ten options, so the reader can type to find one.

Type to filter the list
search-placeholder labels the filter box inside the open menu.
RPG Bhiwadi DC Tata Power Mumbai Adani Green Gujarat L&T Construction
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>
Searchable by default past ten options
With more than ten options the search box appears on its own; with ten or fewer it does not.
RPG Bhiwadi DC Tata Power Mumbai Adani Green Gujarat L&T Construction JSW Steel Vijayanagar NTPC Dadri BHEL Haridwar ONGC Hazira SAIL Bokaro Hindalco Renukoot BPCL Kochi
Show code
<app-select label="Client" name="client">
    <app-option value="rpg">RPG Bhiwadi DC</app-option>
    <!-- … eleven options in all -->
</app-select>
Text when nothing matches
empty-text is shown in the open menu when the search matches no option. Type a word with no match to see it.
Apple Banana Cherry Mango
Show code
<app-select label="Fruit" name="fruit" searchable
            search-placeholder="Search fruit…" placeholder="Select a fruit…" empty-text="No fruit match">
    <app-option value="apple">Apple</app-option>
    <app-option value="banana">Banana</app-option>
    <app-option value="cherry">Cherry</app-option>
    <app-option value="mango">Mango</app-option>
</app-select>
A remote source
source is a URL the element calls as GET source?q=…, reading a JSON array of options. It debounces the typing, shows a spinner while the request runs, and keeps only the latest answer.
Debounced search with a loading spinner.
Show code
<app-select mode="AppSelectMode.Search" label="City (remote)" name="city-remote"
            source="/api/demo/cities" min-chars="1"></app-select>
Static filter
Options are filtered in the page as the reader types; nothing is fetched.
Mumbai Delhi Pune
Show code
<app-select mode='AppSelectMode.Search' label='City' name='city'>…</app-select>
A saved selection with its label
The saved value is not in the list until a search runs. value-label is the text the field shows for it.
Show code
<app-select mode='AppSelectMode.Search' label='Client (preset)' name='client-preset' value='c-204' value-label='Northwind Traders' min-chars='1'></app-select>
Remote, answered by the page
remote with no source: the page answers the search event with the options.
Show code
<app-select mode='AppSelectMode.Search' label='City' name='city-page' remote='true' min-chars='1'></app-select>
Disabled
disabled holds the search select in its state: the value shows, nothing opens.
Pune
Show code
<app-select mode="AppSelectMode.Search" label="City" name="city-locked" disabled="true" value="pune">
    <app-option value="pune">Pune</app-option>
</app-select>

Sizes and icons

Use sm in a dense row and lg beside larger fields; a leading icon names what the select picks.

Small, medium, large
RPG Bhiwadi DC Tata Power Mumbai
RPG Bhiwadi DC Tata Power Mumbai
RPG Bhiwadi DC Tata Power Mumbai
Show code
<app-select label="Small" name="c" size="ControlSize.Sm">…</app-select>
<app-select label="Medium (default)" name="c">…</app-select>
<app-select label="Large" name="c" size="ControlSize.Lg">…</app-select>
A select with a leading icon
RPG Bhiwadi DC Tata Power Mumbai Adani Green Gujarat L&T Construction
Show code
<app-select label="Client" name="client" icon="building" placeholder="Select a client…">…</app-select>
An icon per option
Active Pending Blocked Complete
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 border to sit the label inside the control as a placeholder, or above to rest it above the box; it slides up and shrinks on focus or once a value is chosen.

Label slides up on select
Tata Power Mumbai RPG Bhiwadi DC
Tata Power Mumbai RPG Bhiwadi DC
Show code
<app-select label='Client' name='fl1' floating-label='Border'>…</app-select>
<app-select label='Client' name='fl2' floating-label='Above'>…</app-select>

Custom class & width

class lands on the field wrapper. Reach for it to size the select with a width utility or your own class.

Size the select with a class
class sets the width on the field wrapper; input-class styles the control itself.
Tata Power Mumbai RPG Bhiwadi DC
Tata Power Mumbai RPG Bhiwadi DC
Show code
<app-select label='Full width (default)' name='cw1'>…</app-select>
<app-select label='Half width' class='w-50' name='cw2'>…</app-select>

Compact

Use the compact density for a toolbar or filter picker, and give it an aria-label since it has no visible label.

A compact status filter
All statuses Draft Active Complete
Show code
<app-select density="Density.Compact" size="ControlSize.Sm" name="statusfilter" aria-label="Filter status">
    <app-option value="all" selected>All statuses</app-option>
    <app-option value="draft">Draft</app-option>
    <app-option value="active">Active</app-option>
    <app-option value="done">Complete</app-option>
</app-select>
Rows per page
value-prefix shows Rows inside the control, before the value. Picking a size fires change with the new size.
10 / page 25 / page 50 / page
Show code
<app-select density="Density.Compact" size="ControlSize.Sm" name="pageSize" value-prefix="Rows" aria-label="Rows per page">
    <app-option value="10">10 / page</app-option>
    <app-option value="25" selected>25 / page</app-option>
    <app-option value="50">50 / page</app-option>
</app-select>
Icon and valuePrefix
An icon and a value-prefix together label a compact picker without a visible label.
Pending Complete
Show code
<app-select density='Density.Compact' size='ControlSize.Sm' icon='filter' value-prefix='Sort:' aria-label='Sort orders'>…</app-select>
Small, medium, large
All statuses Draft All statuses Draft All statuses Draft
Show code
<app-select density='Density.Compact' size='ControlSize.Sm' …></app-select>
<app-select density='Density.Compact' …></app-select>
<app-select density='Density.Compact' size='ControlSize.Lg' …></app-select>

Several values

Use multiple to pick several values, each shown as a chip the reader can remove one at a time.

Chosen values as chips
Seed value with the starting selection. Removing a chip or picking an option fires change with the new array.
Risk assessment Lightning protection Surge protection Earthing Bonding Site survey IEC 62305 Reporting
2 selected
Show code
<app-select mode="AppSelectMode.Multiple" label="Skills" name="skills" placeholder="Add skills…">
    <app-option value="earthing" selected>Earthing</app-option>
    <app-option value="iec-62305" selected>IEC 62305</app-option>
    <!-- … -->
</app-select>
Footer count and Clear all
The footer under the open list reads the count and offers a clear. selected-text takes {n} for the count.
Risk assessment Lightning protection Surge protection Earthing Bonding Site survey IEC 62305 Reporting
Show code
<app-select mode="AppSelectMode.Multiple" label="Skills" name="skills-footer"
            selected-text="{n} skills chosen" clear-all-label="Remove all">…</app-select>
Chips fold into +N
collapse-chips keeps the chips on one row and folds the overflow into a +N counter.
Risk assessment Lightning protection Surge protection Earthing Bonding Site survey IEC 62305 Reporting
Show code
<app-select mode="AppSelectMode.Multiple" label="Skills" name="skills-collapse" collapse-chips="true">
    <app-option value="earthing" selected>Earthing</app-option>
    <!-- … -->
</app-select>
Type to filter, tick to add
Earthing Bonding Surge protection
Show code
<app-select mode='AppSelectMode.Multiple' label='Skills' name='skills-filter' searchable='true'>…</app-select>
Multi-select with a leading icon
Earthing Bonding
Show code
<app-select mode='AppSelectMode.Multiple' label='Skills' icon='filter' name='skills-icon'>…</app-select>
Small, medium, large
Earthing Bonding
Earthing Bonding
Earthing Bonding
Show code
<app-select mode='AppSelectMode.Multiple' label='Small' size='ControlSize.Sm' …></app-select>
<app-select mode='AppSelectMode.Multiple' label='Medium (default)' …></app-select>
<app-select mode='AppSelectMode.Multiple' label='Large' size='ControlSize.Lg' …></app-select>

Rich rows

An option can carry a description, which is also matched by the search, an avatar image or initials, and disabled with a short disabled-hint. A disabled row stays in the list, readable and reachable by the arrow keys, but cannot be picked.

People with a secondary line and some rows unavailable
An option can carry a description, initials, and disabled with a disabled-hint. A disabled row stays in the list but cannot be picked.
Asha Rao Ben Das Chitra Iyer Dev Mehta
Show code
<app-select mode='AppSelectMode.Multiple' label='Reviewers' name='reviewers'>…</app-select>

Freeform entry

Search mode with allow-custom takes a typed value that matches no option as its own value; a tag or an address can be typed in and committed on Enter.

Add a tag that doesn't exist yet
Typed text that matches no option is chosen as its own value.
Urgent Billing Onboarding
Show code
<app-select mode='AppSelectMode.Search' label='Tag' name='tag-custom' allow-custom='true'>…</app-select>
Invite by picking a person or typing any address
Tag mode: a pattern checks each typed address, and a refused entry keeps its text and says why under the control.
Show code
<app-select mode='AppSelectMode.Tag' label='Invite people' name='invite' pattern='[^@\s]+@[^@\s]+\.[^@\s]+' invalid-message='Enter an email address.'></app-select>

Person picker

Search mode with value-avatar or value-initials shows the photo or initials of the chosen person, including one the options do not list yet.

A saved person with a photo
value-avatar is the photo for a saved value the options do not list yet; value-label is its name.
Ravi Kumar Asha Menon
Show code
<app-select mode='AppSelectMode.Search' label='Assigned to' name='assignee' value='jane' value-label='Jane Doe' value-avatar='photo.svg'></app-select>
A saved person with initials only
No photo, so the chosen person shows their initials.
Jane Doe Asha Menon
Show code
<app-select mode='AppSelectMode.Search' label='Assigned to' name='assignee' value='ravi' value-label='Ravi Kumar' value-initials='RK'></app-select>
Options that carry a photo or initials
Each option shows its photo or initials.
Jane Doe Ravi Kumar
Show code
<app-select mode='AppSelectMode.Search' label='Assigned to' name='assignee-options'><app-option value='jane' initials='JD'>Jane Doe</app-option></app-select>

Tags

Use tags for free text such as keywords; Enter or a comma adds one, and the options only suggest.

Free tags
Type a word and press Enter or comma.
Show code
<app-select mode="AppSelectMode.Tag" label="Keywords" name="keywords" value="react,javascript"
            placeholder="Add keyword…"></app-select>
Limited to three tags
max-tags caps the count. Once reached, the input stops taking tags and the helper text says so.
2 / 3
Show code
<app-select mode="AppSelectMode.Tag" label="Max 3 tags" name="limited" value="one,two" max-tags="3"></app-select>
Keyboard & behaviour
Enter or a comma commits a tag, Backspace on an empty box removes the last tag, and a pasted list splits into one chip per entry.
Show code
<app-select mode='AppSelectMode.Tag' label='Keywords' name='keywords' value='react,javascript'></app-select>

Paste to add many

Separators commit an entry as it is typed, and a pasted list becomes one chip per entry.

Email list via paste
Commas, semicolons or spaces split a pasted list into chips.
Show code
<app-select mode='AppSelectMode.Tag' label='Email list' name='email-list' separators=',; '></app-select>

Chips with suggestions

Options in tag mode are suggestions only: a pick becomes a chip, and a typed entry that matches no suggestion is still a chip.

Search, pick, and the pick becomes a chip
Options in tag mode are suggestions only: a pick becomes a chip, and a typed entry that matches no suggestion is still a chip.
Mumbai Delhi Pune
Show code
<app-select mode='AppSelectMode.Tag' label='Cities' name='cities-suggest'>…</app-select>

Tag rules

A pattern, a duplicate rule and an invalid message decide what a tag may be.

A pattern with its own message
pattern is a regular expression a typed entry must match; invalid-message says why a refused entry is refused.
Show code
<app-select mode='AppSelectMode.Tag' label='Label' name='label-rule' pattern='^[a-z0-9-]+$' invalid-message='Use lowercase letters, digits and hyphens.'></app-select>
allowDuplicates
By default a repeated entry, ignoring case, is refused. allow-duplicates keeps it.
A repeated keyword is kept.
Show code
<app-select mode='AppSelectMode.Tag' label='Keywords' name='keywords-dupes' allow-duplicates='true'></app-select>

States

A tag field shows its helper text, its error, its disabled and its required state the same way as the other fields.

Helper text and error messages
Helper text sits under the field until an error replaces it.
Helper text sits under the field until an error replaces it.
Add at least one keyword.
Show code
<app-select mode='AppSelectMode.Tag' label='Keywords' error='Add at least one keyword.'></app-select>
Disabled state
Show code
<app-select mode='AppSelectMode.Tag' label='Keywords' disabled='true' value='react'></app-select>
Required field
Show code
<app-select mode='AppSelectMode.Tag' label='Keywords' required='true'></app-select>
Small, medium, large
Show code
<app-select mode='AppSelectMode.Tag' label='Keywords' size='ControlSize.Sm'></app-select>

Countries

Use country mode for a country field: it stores the two-letter ISO code, which stays the same in every language.

Every country
Value: IN
Show code
<app-select mode="AppSelectMode.Country" name="country" label="Country" value="IN"></app-select>
Only the countries you serve
countries limits the list to these ISO codes, listed by name. A short list rarely needs the search box.
We invoice in these countries only.
Show code
<app-select mode="AppSelectMode.Country" label="Billing country" name="billing-country"
    countries="IN,AE,GB,US,SG" searchable="false" clearable="true"></app-select>
Suggested countries first
suggested lists these ISO codes first under a Suggested group, then every other country under All countries.
Show code
<app-select mode='AppSelectMode.Country' label='Country' suggested='IN,AE' suggested-label='Suggested' all-countries-label='All countries'></app-select>
Sizes and states
A country field takes the same error, disabled and floating label states as any other select.
Pick a country
Show code
<app-select mode='AppSelectMode.Country' label='Country' error='Pick a country'></app-select>
<app-select mode='AppSelectMode.Country' label='Country' value='AE' disabled='true'></app-select>
<app-select mode='AppSelectMode.Country' label='Country' floating-label='Border'></app-select>

Recently chosen

Give the select a recents-key and it lists the last options a person chose on this device first, under a Recent heading, above the full list. Pick a client, reload the page and open the select again.

Recent options first
recents-key names where this device remembers the choices; build it from the user's public id. recents-limit (default 5) and recents-label (default Recent) tune the group.
RPG Bhiwadi DCTata Power MumbaiAdani Green GujaratL&T Construction
Show code
<app-select label="Client" name="client-recents" recents-key="clients:@user.PublicId" 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>

Control only

Control only draws just the select, for a dense form that draws its own labels and messages.

Acme

Every option

Every value of every prop, one cell each.

mode: all five

mode="single" (default)
Tata Power MumbaiRPG Bhiwadi DC
mode="multiple"
Tata Power MumbaiRPG Bhiwadi DC
mode="search"
Tata Power MumbaiRPG Bhiwadi DC
mode="tag"
mode="country"

value and defaultValue

value="tata"
Tata Power MumbaiRPG Bhiwadi DC
value="tata,rpg" in multiple
Tata Power MumbaiRPG Bhiwadi DC
default-value="tata"
Tata Power MumbaiRPG Bhiwadi DC

onChange

change event: fires with the chosen value, or the full list in multiple and tag
Tata Power MumbaiRPG Bhiwadi DC

options

app-option with icon
ActivePending

placeholder and searchPlaceholder

placeholder="Select a client…"
Tata Power Mumbai
search-placeholder="Search clients…"
Tata Power Mumbai

searchable and emptyText

searchable
Tata Power MumbaiRPG Bhiwadi DC
empty-text="No fruit match"
AppleMango

clearable and openOnHover

clearable (value set)
Tata Power MumbaiRPG Bhiwadi DC
open-on-hover
Tata Power MumbaiRPG Bhiwadi DC

size: sm · (default) · lg

size="sm"
Tata Power Mumbai
size (default md)
Tata Power Mumbai
size="lg"
Tata Power Mumbai

density: comfortable (default) · compact

density="comfortable" (default)
Tata Power Mumbai
density="compact"
Tata Power Mumbai

icon and valuePrefix

icon="building"
Tata Power Mumbai
value-prefix="Sort:"
Tata Power Mumbai

prefix and suffix

prefix="+91"
+91Tata Power Mumbai
suffix="kg"
Tata Power Mumbaikg

floatingLabel: off (default) · border · above

floating-label="off" (default)
Tata Power Mumbai
floating-label="border"
Tata Power Mumbai
floating-label="above"
Tata Power Mumbai

disabled, readOnly, loading and open

disabled
Tata Power Mumbai
read-only
Tata Power Mumbai
loading
Tata Power Mumbai
open
Tata Power Mumbai

label, required, error, helperText

label="Client"
Tata Power Mumbai
required
Tata Power Mumbai
error
Tata Power Mumbai
Client is required.
helper-text
Tata Power Mumbai
Pick the client that owns the site.

id, name and className

id="client-id"
Tata Power Mumbai
name="client"
Tata Power Mumbai
input-class (the control)
Tata Power Mumbai
class (the field wrapper)
Tata Power Mumbai

help and helpLabel

help
Tata Power Mumbai
help-label="About clients"
Tata Power Mumbai

aria-label, aria-labelledby and aria-describedby

aria-label (no visible label)
Tata Power Mumbai
aria-labelledby
ClientTata Power Mumbai
aria-describedby
Tata Power Mumbai
Used for the monthly invoice.

optional and optionalLabel

optional
Tata Power Mumbai
optional-label="(facultatif)"
Tata Power Mumbai

search mode: loadOptions, remote and onSearch

source (React: loadOptions)
remote (React: remote)
search event: fires with each query when remote is set
Pune

search mode: minChars, debounce, hintText and searchingText

min-chars="3"
debounce="500"
hint-text="Type two letters"
searching-text="Looking…"

search mode: allowCustom, addLabel and the value label

allow-custom="true"
Urgent
add-label="Add this client"
Urgent
value-label="Northwind Traders"
Tata Power Mumbai
value-avatar (the photo)
Tata Power Mumbai
value-initials (no photo)
Tata Power Mumbai

tag mode: maxTags, allowDuplicates, separators and createLabel

max-tags="3"
allow-duplicates="true"
separators=",; "
create-label="New keyword"

tag mode: pattern, invalidMessage and validate

pattern="^[a-z]+$"
invalid-message="Lowercase only."
validate: set from script, a check a pattern cannot express

multiple mode: collapseChips, selectedText and clearAllLabel

collapse-chips="true"
EarthingBondingSurge protection
selected-text="{n} skills chosen"
Earthing
clear-all-label="Remove all"
Earthing

country mode: countries, suggested and their labels

countries="IN,AE"
suggested="IN"
suggested-label="Frequent"
all-countries-label="Every country"

recents: recentsKey, recentsLimit and recentsLabel

recents-key="sandbox:select:every"
Tata Power Mumbai
recents-limit="3"
Tata Power Mumbai
recents-label="Recently used"
Tata Power Mumbai

controlOnly

control-only="true", named with aria-label
Tata Power Mumbai

autocomplete, autofocus, form, onBlur (React only) and style

autocomplete="off"
Tata Power MumbaiRPG Bhiwadi DC
autofocus="true": takes focus when the page loads
Tata Power MumbaiRPG Bhiwadi DC
form: the id of the form the field belongs to
Tata Power MumbaiRPG Bhiwadi DC
onBlur (React only: Razor has no event callback)
Tata Power MumbaiRPG Bhiwadi DC
style="font-style: italic" (React: style object)
Tata Power MumbaiRPG Bhiwadi DC

Guidance

What to do, and what to avoid.

Use it when

  • The user picks one value from a known set of roughly 6 or more options: single mode, the default.
  • The user picks several values from a set: mode multiple, shown as removable chips.
  • The options are long or come from a server as the user types: mode search, with options or loadOptions.
  • The user types free-text entries such as emails or keywords, optionally with suggestions: mode tag.
  • The user picks a country: mode country, which gives the ISO code, the flag and the dial code.
  • compact density for toolbars, sort and filter pickers; a labelled form field omits it.

Reach for something else when

  • There are only 2 to 5 options and they fit comfortably on screen. → AppRadio
  • The user needs to pick a value with no fixed list of options at all. → AppInput

Searchable past ten options

Do
RPG Bhiwadi DCTata Power MumbaiAdani Green GujaratL&T ConstructionJSW Steel VijayanagarNTPC DadriBHEL HaridwarONGC HaziraSAIL BokaroHindalco RenukootBPCL Kochi

Past ten options the search box shows on its own, so leave searchable unset.

Avoid
RPG Bhiwadi DCTata Power MumbaiAdani Green GujaratL&T ConstructionJSW Steel VijayanagarNTPC DadriBHEL HaridwarONGC HaziraSAIL BokaroHindalco RenukootBPCL Kochi

Turning the search box off on a long list forces the user to scroll and scan every time.

A label and a placeholder

Do
RPG Bhiwadi DCTata Power MumbaiAdani Green GujaratL&T Construction

A label names the field and the placeholder tells the user what to pick.

Avoid
RPG Bhiwadi DCTata Power MumbaiAdani Green GujaratL&T Construction

No label and a bare 'Select' leave the field's purpose unclear.

A specific error

Do
RPG Bhiwadi DCTata Power MumbaiAdani Green GujaratL&T Construction
Choose the client this project belongs to.

A specific error says which choice is missing and why it matters.

Avoid
RPG Bhiwadi DCTata Power MumbaiAdani Green GujaratL&T Construction
Required

'Required' just repeats the asterisk without helping.

Reference

Try every prop, read the full list, and check keyboard and screen reader behaviour.

single multiple search tag country
(none) RPG Bhiwadi DC Tata Power Mumbai Adani Green Gujarat L&T Construction
(none) sm lg
(none) building user flag filter sort calendar
off border above
(none) Remote cities
(none) off country
RPG Bhiwadi DC Tata Power Mumbai Adani Green Gujarat L&T Construction
React, generated from the controls
<AppSelect label="Client" value={value} onChange={setValue} size="md" name="pgclient" options={options} />
Razor, the same props
<app-select label="Client" name="pgclient">
    <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>

76 props. The 4 most used come first.

Used on most screens 4 props

PropTypeDefaultDescription
modedefault single single | multiple | search | tag | country single What the control does. single picks one option; multiple picks several and shows them as chips; search filters options as the user types, from options or a loadOptions loader; tag takes free-text chips with optional suggestions, validate, pattern and maxTags; country picks an ISO country code with its flag and dial code. value is a string in single, search and country modes, and a string array in multiple and tag modes.
valuedefault - string, comma-joined in multiple and tag - The selected value: a string in single, search and country, a list in multiple and tag. Leaving it out clears the control.
sizedefault md sm | md | lg md Control size: sm, md or lg (32, 36 or 44px). md is the default.
densitydefault comfortable comfortable | compact comfortable comfortable is the labelled form look. compact is the toolbar, sort and filter picker look: an inline width and a menu sized to its options. Pair compact with size sm.

Less common 72 props

PropTypeDefaultDescription
changedefault - event - Fires with the newly chosen value. detail.isCustom is true in search and tag modes when the value is typed text rather than a listed option.
<app-option>default - child elements - The choices. A label may be markup, such as a subscript: it renders as static markup, and search and the option's accessible name use its text. Each child carries its own attributes, listed below.
placeholderdefault Depends on the mode string Depends on the mode The text in the empty field. Left unset, the element's default for the mode applies: Select… in single, search and multiple, Add… in tag, Select country in country.
searchabledefault on in multiple and country, and in single past ten options bool on in multiple and country, and in single past ten options Show the search box in the menu. Multiple and country modes are searchable by default, and single mode is once it has more than ten options; passing false turns it off, true turns it on.
search-placeholderdefault Search and the label string Search and the label The placeholder of the search box in the menu. Left unset, it is Search and the field's label (Search Client…) in single, multiple and search modes, Search… without a label, and Search countries… in country mode.
empty-textdefault No matches string No matches Text shown in the menu when a search matches nothing.
clearabledefault false bool false Show a control that clears the chosen value.
open-on-hoverdefault false bool false Open the list when the mouse rests on the control, and close it when the mouse leaves the control and the list. Mouse only: touch and pen keep tap to open. A select with a search box (search mode, or searchable) and tag mode ignore it. A click on the control right after it opened on hover keeps the list open.
icondefault - string - Icon name shown in the control.
value-prefixdefault - string - Static text inside the control before the value, such as Sort:. Not prefix, which is the bordered affix box.
prefixdefault - string - A bordered box before the select, e.g. +91. The same shell as <app-input prefix>. Single, search and country only.
suffixdefault - string - A bordered box after the select, as <app-input suffix>. Single, search and country only.
floating-labeldefault off off | border | above off Where the label rests. Off keeps it above the control. Border sits the label inside as a placeholder, then slides it onto the top border on focus or once a value is chosen. Above rests it above the box, clear of the border. Needs label. Single, search and country modes only; ignored with a dev warning in multiple and tag.
disableddefault false bool false Disables the control.
read-onlydefault false bool false Shows the value but blocks editing. The value still posts.
loadingdefault false bool false Shows a busy state and blocks input while data loads.
opendefault false bool false Shows the list open, for a design preview or a controlled caller.
labeldefault - string - The field label. Rendered with the field shell.
requireddefault false bool false Marks the field required.
errordefault - string - Error message shown under the field. Marks the control invalid.
helper-textdefault - string - Helper text shown under the field when there is no error.
iddefault - string - DOM id for the control and the target of the label.
namedefault - string - Form field name.
classdefault - string - Merges onto the field wrapper, e.g. a width utility to size the select.
input-classdefault - string - Extra classes on the control itself. The plain class attribute merges onto the field wrapper instead.
helpdefault - string - Info-tip content shown beside the label.
help-labeldefault More information string More information Accessible name for that info tip.
aria-labeldefault - string - Explicit accessible name for the control. Wins over the label-derived aria-label. Needed for a label-less filter or toolbar select.
aria-labelledbydefault - string - Forwarded verbatim onto the control.
aria-describedbydefault - string - Forwarded verbatim onto the control.
autocompletedefault - string - The browser's autofill hint for the control, such as off or country.
autofocusdefault false bool false The control takes focus when the page loads.
formdefault - string - The id of the form the control posts with when it sits outside that form.
optional-labeldefault (optional) string (optional) Replaces the built-in English text, for other languages.
optionaldefault false bool false Ends the label with (optional) when the field is not required. Required wins when both are set.
sourcedefault - string - Search mode. A URL the element calls as GET source?q=…, reading a JSON array of { value, label }.
remotedefault false bool false Search and tag modes: the page answers each query itself. The element fires its search event (React onSearch) with the query and its number, fetches nothing, and shows the searching row until the page sets options. Leave it off with loadOptions or source.
hint-textdefault - string - Search mode: the row shown while the query is shorter than minChars. Left unset, the element shows Type to search….
min-charsdefault 0 int 0 Search mode: the query length before the element asks for options.
debouncedefault 250 int ms 250 Search mode: milliseconds to wait after typing before the query is sent.
allow-customdefault false bool false Search mode: a typed value that matches no option can be chosen as its own value.
add-labeldefault Add '{query}' string Add '{query}' Search mode: the row that adds a custom entry.
value-labeldefault - string - Search mode: the label of the current value when the options do not carry it.
value-avatardefault - string - Search mode: the image of the current value.
value-initialsdefault - string - Search mode: the initials of the current value.
searching-textdefault Searching… string Searching… Search mode: the row shown while a query loads.
max-tagsdefault - int - Tag mode: the most chips a value may hold.
allow-duplicatesdefault false bool false Tag mode: keep a repeated entry. By default an entry equal to one already chosen, ignoring case, is refused.
separatorsdefault , and Enter string , and Enter Tag mode: characters that commit an entry, such as comma or semicolon, as one string.
patterndefault - string - Tag mode: a regular expression a typed entry must match.
invalid-messagedefault - string - Tag mode: the message shown when pattern or validate refuses an entry.
create-labeldefault Create '{text}' string Create '{text}' Tag mode: the row that creates an entry.
validatedefault - function (property) - Tag mode. Set from script, not an attribute. Checks a tag after pattern: true accepts, a string refuses with that message.
collapse-chipsdefault false bool false Multiple mode: fold the chips past the first few into a +N chip.
selected-textdefault {n} selected string {n} selected Multiple mode: the footer count.
clear-all-labeldefault Clear all string Clear all Multiple mode: the footer clear action.
countriesdefault - string - Country mode. ISO 3166-1 alpha-2 codes, comma-separated, that limit the list. Omitted, every country is listed.
suggesteddefault - string - Country mode. ISO codes listed first under a Suggested group.
suggested-labeldefault Suggested string Suggested Country mode: the group label for suggested countries.
all-countries-labeldefault All countries string All countries Country mode: the group label for the full list.
recents-keydefault - string - Single, search, multiple and country modes: a localStorage key to remember the options a person chooses on this device. The open list shows them first, under a Recent heading, while the search box is empty. Build it per user, for example from the user's public id. Only options still in the list show, so a search that fetches its options per query shows none. Not used in tag mode.
recents-limitdefault 5 int 5 How many recent options to show and keep, 1 to 20.
recents-labeldefault Recent string Recent The heading of the recent options.
<app-option> valuedefault - string - The value of an option child. Its label is the inner content.
<app-option> selecteddefault false bool false Marks that option as initially selected. In multiple mode several options can carry it.
<app-option> icondefault - string - Leading library icon for that option, e.g. check-circle.
<app-option> groupdefault - string - The grey group label the option sits under.
<app-option> descriptiondefault - string - A second line under the option label.
<app-option> metadefault - string - Trailing text on the option row, such as a code.
<app-option> avatar, initialsdefault - string - An image URL, or initials shown when there is no image.
<app-option> disabled, disabled-hintdefault false, - bool, string false, - The option stays in the list but cannot be picked; the hint says why.
control-onlydefault false bool false Draws only the control: no field wrapper, label row or message line. Name it with aria-label, aria-labelledby or a label the page draws, because the component draws none.

Screen reader

3 notes
  • The visible label is the control's accessible name; a select with no visible label takes aria-label or aria-labelledby from the caller.
  • An error sets aria-invalid on the control and is linked by aria-describedby, as is the helper text when there is no error.
  • required and disabled are passed to the control, and required also draws a required mark in the label.

Do and avoid

3 pairs

Searchable past ten options

Do
RPG Bhiwadi DCTata Power MumbaiAdani Green GujaratL&T ConstructionJSW Steel VijayanagarNTPC DadriBHEL HaridwarONGC HaziraSAIL BokaroHindalco RenukootBPCL Kochi

Past ten options the search box shows on its own, so leave searchable unset.

Avoid
RPG Bhiwadi DCTata Power MumbaiAdani Green GujaratL&T ConstructionJSW Steel VijayanagarNTPC DadriBHEL HaridwarONGC HaziraSAIL BokaroHindalco RenukootBPCL Kochi

Turning the search box off on a long list forces the user to scroll and scan every time.

A label and a placeholder

Do
RPG Bhiwadi DCTata Power MumbaiAdani Green GujaratL&T Construction

A label names the field and the placeholder tells the user what to pick.

Avoid
RPG Bhiwadi DCTata Power MumbaiAdani Green GujaratL&T Construction

No label and a bare 'Select' leave the field's purpose unclear.

A specific error

Do
RPG Bhiwadi DCTata Power MumbaiAdani Green GujaratL&T Construction
Choose the client this project belongs to.

A specific error says which choice is missing and why it matters.

Avoid
RPG Bhiwadi DCTata Power MumbaiAdani Green GujaratL&T Construction
Required

'Required' just repeats the asterisk without helping.