Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

Basic

A search field with a leading icon, a placeholder and a one-click clear that resets the query.

A controlled search box
Show code
<app-search name="q" placeholder="Search members…"></app-search>

Sizes

Use sm or lg to line the search box up with the controls beside it; md is the default.

Small, medium, large
Show code
<app-search name="q" size="ControlSize.Sm" placeholder="Small" />
<app-search name="q" placeholder="Medium (default)" />
<app-search name="q" size="ControlSize.Lg" placeholder="Large" />

Loading

Show a spinner in place of the magnifier while a debounced or server-backed search is in flight.

Spinner while searching
Show code
<app-search name="q" loading="true" placeholder="Type to search…" />

Filtering a list

Use search to filter the rows below as the person types, deriving the list from the query.

Search filters the list live
  • Navneet Singh
  • Kanchan Sharma
  • Ramshankar Verma
  • Akshat Gupta
  • Priya Nair

The rows in this sample are fixed, so typing here does not change them.

Show code
<app-search name="q" placeholder="Search members…"></app-search>
<!-- render the filtered rows below -->

Every option

Every value of every prop, one cell each.

value

value="": clear hidden
value="acme": clear visible
value: long text overflows the fixed-width field

defaultValue

defaultValue: React only, Razor sets value

onChange

onChange: React only, Razor posts the field under its name with the form

onKeyDown

onKeyDown: React only, Razor has no key hook

placeholder

placeholder="Search…" (default)
placeholder="Find a member"

ariaLabel

aria-label="Search members": names the field for screen readers; no visible change

iconSize

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 icon

collapsible

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 value
disabled + loading

name

name="q": posted under this name; no visible change

form

form="filters": joins the filter form with that id; no visible change

clearLabel

clear-label="Clear the query": names the clear button; no visible change

searchLabel

search-label="Find": names the collapsed button when there is no aria-label or placeholder

className

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

Do

A placeholder that names what is being searched sets the right expectation.

Avoid

A vague 'Type here' doesn't say what the box searches.

Clear to reset the list

Do

With a value present, the clear (×) lets the user reset to the full list in one click.

Avoid

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.

(none) sm lg
React, generated from the controls
<AppSearch value={value} onChange={setValue} ariaLabel="Search" size="md" name="pgquery" />
Razor, the same props
<app-search name="pgquery" aria-label="Search"></app-search>

12 props. The 4 most used come first.

Used on most screens 4 props

PropTypeDefaultDescription
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

PropTypeDefaultDescription
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 pairs

Name what the search covers

Do

A placeholder that names what is being searched sets the right expectation.

Avoid

A vague 'Type here' doesn't say what the box searches.

Clear to reset the list

Do

With a value present, the clear (×) lets the user reset to the full list in one click.

Avoid

A raw input with a magnifier drawn on top has no clear control and drifts from the theme.