On this page
@addTagHelper *, Webority.Ui.RazorSingle choice
A labelled select with a placeholder picks one value from a list, and it can be cleared or marked required.
Searchable
Add a type-to-filter box once the list runs past about ten options, so the reader can type to find one.
Sizes and icons
Use sm in a dense row and lg beside larger fields; a leading icon names what the select picks.
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.
Custom class & width
class lands on the field wrapper. Reach for it to size the select with a width utility or your own class.
Compact
Use the compact density for a toolbar or filter picker, and give it an aria-label since it has no visible label.
Several values
Use multiple to pick several values, each shown as a chip the reader can remove one at a time.
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.
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.
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.
Tags
Use tags for free text such as keywords; Enter or a comma adds one, and the options only suggest.
Paste to add many
Separators commit an entry as it is typed, and a pasted list becomes one chip per entry.
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.
Tag rules
A pattern, a duplicate rule and an invalid message decide what a tag may be.
States
A tag field shows its helper text, its error, its disabled and its required state the same way as the other fields.
Countries
Use country mode for a country field: it stores the two-letter ISO code, which stays the same in every language.
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.
Control only
Control only draws just the select, for a dense form that draws its own labels and messages.
Every option
Every value of every prop, one cell each.
mode: all five
mode="single" (default)mode="multiple"mode="search"mode="tag"mode="country"value and defaultValue
value="tata"value="tata,rpg" in multipledefault-value="tata"onChange
change event: fires with the chosen value, or the full list in multiple and tagoptions
app-option with iconplaceholder and searchPlaceholder
placeholder="Select a client…"search-placeholder="Search clients…"searchable and emptyText
searchableempty-text="No fruit match"clearable and openOnHover
clearable (value set)open-on-hoversize: sm · (default) · lg
size="sm"size (default md)size="lg"density: comfortable (default) · compact
density="comfortable" (default)density="compact"icon and valuePrefix
icon="building"value-prefix="Sort:"prefix and suffix
prefix="+91"suffix="kg"floatingLabel: off (default) · border · above
floating-label="off" (default)floating-label="border"floating-label="above"disabled, readOnly, loading and open
disabledread-onlyloadingopenlabel, required, error, helperText
label="Client"requirederrorhelper-textid, name and className
id="client-id"name="client"input-class (the control)class (the field wrapper)help and helpLabel
helphelp-label="About clients"aria-label, aria-labelledby and aria-describedby
aria-label (no visible label)aria-labelledbyaria-describedbyoptional and optionalLabel
optionaloptional-label="(facultatif)"search mode: loadOptions, remote and onSearch
source (React: loadOptions)remote (React: remote)search event: fires with each query when remote is setsearch 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"add-label="Add this client"value-label="Northwind Traders"value-avatar (the photo)value-initials (no photo)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 expressmultiple mode: collapseChips, selectedText and clearAllLabel
collapse-chips="true"selected-text="{n} skills chosen"clear-all-label="Remove all"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"recents-limit="3"recents-label="Recently used"controlOnly
control-only="true", named with aria-labelautocomplete, autofocus, form, onBlur (React only) and style
autocomplete="off"autofocus="true": takes focus when the page loadsform: the id of the form the field belongs toonBlur (React only: Razor has no event callback)style="font-style: italic" (React: style object)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
Past ten options the search box shows on its own, so leave searchable unset.
Turning the search box off on a long list forces the user to scroll and scan every time.
A label and a placeholder
A label names the field and the placeholder tells the user what to pick.
No label and a bare 'Select' leave the field's purpose unclear.
A specific error
A specific error says which choice is missing and why it matters.
'Required' just repeats the asterisk without helping.
Reference
Try every prop, read the full list, and check keyboard and screen reader behaviour.
76 props. The 4 most used come first.
Used on most screens 4 props
| Prop | Type | Default | Description |
|---|---|---|---|
| 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
| Prop | Type | Default | Description |
|---|---|---|---|
| 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 pairsSearchable past ten options
Past ten options the search box shows on its own, so leave searchable unset.
Turning the search box off on a long list forces the user to scroll and scan every time.
A label and a placeholder
A label names the field and the placeholder tells the user what to pick.
No label and a bare 'Select' leave the field's purpose unclear.
A specific error
A specific error says which choice is missing and why it matters.
'Required' just repeats the asterisk without helping.