On this page
@addTagHelper *, Webority.Ui.RazorBasic
A search field with a leading icon, a placeholder and a one-click clear that resets the query.
Sizes
Use sm or lg to line the search box up with the controls beside it; md is the default.
Loading
Show a spinner in place of the magnifier while a debounced or server-backed search is in flight.
Filtering a list
Use search to filter the rows below as the person types, deriving the list from the query.
- Navneet Singh
- Kanchan Sharma
- Ramshankar Verma
- Akshat Gupta
- Priya Nair
The rows in this sample are fixed, so typing here does not change them.
Every option
Every value of every prop, one cell each.
value
value="": clear hiddenvalue="acme": clear visiblevalue: long text overflows the fixed-width fielddefaultValue
defaultValue: React only, Razor sets valueonChange
onChange: React only, Razor posts the field under its name with the formonKeyDown
onKeyDown: React only, Razor has no key hookplaceholder
placeholder="Search…" (default)placeholder="Find a member"ariaLabel
aria-label="Search members": names the field for screen readers; no visible changeiconSize
icon-size="14"icon-size="18" (default)icon-size="24"size
size="sm"size="md" (default)size="lg"loading
loading: off (default)loading="true": spinner replaces the iconcollapsible
collapsible: off (default)collapsible="true": an icon button that opens the field on click or "/"disabled
disabled: off (default)disabled="true": clear suppressed even with a valuedisabled + loadingname
name="q": posted under this name; no visible changeform
form="filters": joins the filter form with that id; no visible changeclearLabel
clear-label="Clear the query": names the clear button; no visible changesearchLabel
search-label="Find": names the collapsed button when there is no aria-label or placeholderclassName
class: extra class on the wrapper…rest
…rest: any other attribute reaches the input, e.g. autocomplete="off"Guidance
What to do, and what to avoid.
Use it when
- The user narrows a list, table, or set of cards by typing a few characters.
- You want a consistent search affordance, a magnifier and a clear button, above a collection.
- The match is a simple contains-filter over data already on screen.
Reach for something else when
- It is an ordinary text value in a form. → AppInput
- The user types to find one item from a large or remote list. → AppSelect mode="search"
- The user picks from a fixed, known set of options. → AppSelect
Name what the search covers
A placeholder that names what is being searched sets the right expectation.
A vague 'Type here' doesn't say what the box searches.
Clear to reset the list
With a value present, the clear (×) lets the user reset to the full list in one click.
A raw input with a magnifier drawn on top has no clear control and drifts from the theme.
Reference
Try every prop, read the full list, and check keyboard and screen reader behaviour.
12 props. The 4 most used come first.
Used on most screens 4 props
| Prop | Type | Default | Description |
|---|---|---|---|
| placeholderdefault Search… | string | Search… | Placeholder text shown while the field is empty. |
| valuedefault - | string | - | The text in the field. |
| aria-labeldefault - | string | - | The accessible name of the field. |
| clear-labeldefault Clear search | string | Clear search | Accessible name of the clear button. Replaces the built-in English text, for other languages. |
Less common 8 props
| Prop | Type | Default | Description |
|---|---|---|---|
| namedefault - | string | - | Field name the search input posts under. |
| icon-sizedefault 18 | int | 18 | The size in pixels of the leading magnifier. It is 18 when left out. |
| sizedefault - | sm | md | lg | - | Control size. Omit it for the default, md. |
| loadingdefault false | bool | false | Swap the leading glyph for a spinner while a search is in flight. |
| collapsibledefault false | bool | false | Render as an icon button labelled by aria-label (or placeholder) that opens the field on click or "/"; Escape or leaving an empty field folds it, and a value keeps it open. |
| formdefault - | string | - | Id of the filter form this search joins, so it submits with the filters. |
| disableddefault false | bool | false | Turns the field off so it cannot be typed in or cleared. |
| search-labeldefault Search | string | Search | Accessible name of the collapsed search button when there is no aria-label or placeholder. Replaces the built-in English text, for other languages. |
Screen reader
4 notes- The field is a native search input named by ariaLabel.
- A collapsible search shows a toggle button named by ariaLabel (or the placeholder) with aria-expanded, and the / key opens the first collapsible search on the page unless focus is in a field.
- Escape in an empty collapsible field folds it, and leaving an empty one folds it too.
- The clear button is named Clear search, and the spinner is hidden from assistive technology.
Do and avoid
2 pairsName what the search covers
A placeholder that names what is being searched sets the right expectation.
A vague 'Type here' doesn't say what the box searches.
Clear to reset the list
With a value present, the clear (×) lets the user reset to the full list in one click.
A raw input with a magnifier drawn on top has no clear control and drifts from the theme.