SearchBox

The simplest usage only needs a Placeholder. The search icon is rendered by default and animates away as soon as the input is focused, and a clear button shows up as soon as the input has a value.

ReadOnly keeps the value visible and selectable but blocks editing, clearing and picking suggestions, while Disabled renders the disabled state which additionally takes the whole component out of the tab order. Required renders the required html attribute on the input element.

A Label renders a real html label element tied to the input, so clicking it focuses the search box and screen readers announce it as the accessible name of the field. Prefer it over a placeholder-only design: the placeholder disappears as soon as the user starts typing. LabelTemplate takes custom markup instead.

Description (or DescriptionTemplate) renders a hint under the field and points the input at it through aria-describedby, so it is read after the label rather than being decoration only a sighted user benefits from. AriaDescription is referenced the same way but is visually hidden, for what only a screen reader user needs to be told.

Three parameters decide how the box around the field is painted. Underlined drops it and keeps only a bottom border, which lets the search box blend into a dense toolbar or a header; the focus indicator becomes an underline ring with it. NoBorder removes every border but keeps that indicator, so the field stays identifiable for keyboard users. Background switches the surface between the primary, secondary and tertiary tokens of the theme, or makes it Transparent so the field inherits whatever is painted behind it. NoBorder over a colored Background is what builds the filled, borderless field.

By default the leading icon collapses with an animation when the field is focused or hovered while it holds a value, to give the text more room. FixedIcon keeps it permanently visible, DisableAnimation keeps the collapsing behavior but removes the transition, IconName (or Icon for external icon libraries) replaces the magnifier, and HideIcon removes it altogether.

ShowSearchButton appends an explicit submit affordance to the field, which is the recommended pattern for a site-wide search where the user may not know that pressing enter runs the search. Clicking it closes the suggest callout and invokes OnSearch with the current value, exactly like pressing enter does.

Its glyph is customizable through SearchButtonIconName, SearchButtonIcon or a full SearchButtonTemplate, and its accessible name through SearchButtonAriaLabel. SearchButtonText puts a visible label next to the glyph and widens the button to fit it, which is the clearer affordance where the search is the point of the page; the label then names the button itself, so no aria-label is rendered on top of it.

Loading shows a spinner where the clear button sits and marks the input busy while the search the app itself started is still running. It is not the callout's own progress, which an async SuggestItemsProvider drives through LoadingText - the two can be on at the same time.

The clear button appears as soon as the field holds any text and is hidden in the read-only state. It reacts to what is actually typed rather than to the bound value, so it shows up on the first keystroke even without Immediate, when the model is only updated on blur. Clicking it empties the value, returns focus to the input and invokes OnClear. It is kept out of the tab order on purpose, because the escape key already clears the field for keyboard users.

Use HideClearButton to remove it, ClearButtonIconName / ClearButtonIcon / ClearButtonTemplate to restyle it, ClearButtonAriaLabel to localize its accessible name, and NoClearOnEscape to keep the value when escape is pressed.

A Prefix and a Suffix render static adornments inside the field, before and after the input. They are purely decorative: their text is never part of the bound value, so a search box with a https:// prefix still returns only what the user typed.

For anything richer than text, PrefixTemplate and SuffixTemplate take arbitrary markup and replace the plain-text variants entirely.

MaxLength caps the number of characters the browser accepts, and Trim strips the leading and trailing white-spaces while parsing the typed text so the bound value never carries stray spaces.

Three attributes tune the on-screen keyboard of a touch device: InputMode picks which virtual keyboard to bring up (BitInputMode.Search shows the layout optimized for search terms), EnterKeyHint picks the label of its return key and already defaults to BitEnterKeyHint.Search here because pressing enter always runs a search, and SpellCheck turns the red squiggles on or off, AutoCorrect="false" stops a mobile browser from rewriting a term its dictionary does not know, and AutoCapitalize="none" keeps the virtual keyboard from capitalizing it - the three usually belong together in a search field, whose terms are rarely dictionary words.

SelectTextOnFocus selects whatever is already in the field every time it takes the focus, so that typing replaces the previous term instead of appending to it - the behavior a search box the user keeps coming back to needs.

FullWidth stretches the search box to fill the width of its container, which is required when the component sits inside a flex layout that would otherwise shrink it to its content.

Go

By default the value is committed on the change event (that is, when the input loses focus). Adding Immediate switches the binding to the input event so the value updates on every keystroke, and DebounceTime / ThrottleTime keep that from firing too often.

OnChange is raised whenever the value changes, while OnSearch is raised only when the user actually asks for a search: pressing enter, clicking the search button, or picking a suggest item. Use DefaultValue instead of Value for the uncontrolled mode where the component owns its own state.

Besides OnChange and OnSearch, the search box surfaces the full set of input events: OnFocusIn, OnFocus, OnFocusOut, OnClick, OnKeyDown, OnKeyUp, OnEscape (raised on every escape key press, whether it closes the callout or clears the value) and OnClear (raised by the clear button, by escape and by the public Clear method).

Type, click, tab away and press escape in the field below to watch the event log fill up.

SuggestItems (an in-memory list) or SuggestItemsProvider (an async, cancellable function) turns the search box into a combobox with an auto-complete callout. The suggestions react to the bound value, so searching as the user types needs Immediate.

SuggestFilterFunction replaces the default case-insensitive "contains" matching; SuggestIgnoreDiacritics keeps it but folds the accents away on both sides, so "Jose" finds "José". MinSuggestTriggerChars (3) sets how many characters are needed before searching, MaxSuggestCount (5) caps the rendered suggestions, and DebounceTime keeps the search from running on every keystroke, which is what a remote provider needs. A superseded provider call is cancelled through the CancellationToken of its request, so a slow response can never overwrite a newer one.

Modeless removes the invisible overlay that captures the first outside click, and FixedCalloutWidth pins the callout to the width of the component instead of letting it grow with the longest suggestion.

Picking a suggestion writes it into the field, leaves the caret at its end so the term can be refined right away, and raises OnSuggestItemSelect followed by OnSearch.

Everything inside the suggest callout is customizable. HighlightSuggestItems emphasizes the matched part of every suggestion, falling back to each word of a term that does not appear in the item as a whole - what a multi-word term or a server-side match usually produces. SuggestItemTemplate takes over a whole row, and CalloutHeaderTemplate / CalloutFooterTemplate pin content above and below the scrollable list.

Three outcomes otherwise look the same - a callout with nothing in it - so each gets its own message: NoResultsText / NoResultsTemplate for a search that found nothing, SuggestFailedText / SuggestFailedTemplate for one that could not run at all (OnSuggestFailed hands the exception to the log), and MinSuggestTriggerCharsText for a term still shorter than MinSuggestTriggerChars - a composite format receiving how many characters are missing. LoadingText / LoadingTemplate show progress while an async SuggestItemsProvider is running. Each text also replaces the built-in sentence announced to screen readers.

AutoSelectSuggestItem pre-highlights the first suggestion so enter picks it right away. AutoFillSuggestItem completes the typed term with it in place and selects the added part - the inline completion of a browser's address bar: typing on replaces it, backspace removes it, escape puts the typed term back, and the bound value only takes the completion once enter, the search button or tab accepts it. ShowSuggestItemsOnFocus with MinSuggestTriggerChars="0" opens the list on focus, which is how default or recent searches are surfaced.

The search box implements the WAI-ARIA combobox pattern, so the whole suggest list is reachable without a mouse: down / up move the highlight (wrapping at both ends), alt + down opens the list and alt + up closes it, page down / page up jump five items and stop at the edges, home / end jump to the first and the last suggestion, enter accepts the highlighted one, tab and escape dismiss the list, and a second escape clears the field. While the list is open these keys no longer move the caret, scroll the page or submit the surrounding form - and while an input method editor is composing (Chinese, Japanese, Korean) none of them reach the list at all, so enter commits the composition and the arrows walk the candidate window. NoWrapNavigation stops the wrapping, which in a long list reads more like the highlight having been lost than like a deliberate jump.

FocusShortcut puts the focus into the field from anywhere on the page. It takes the syntax of the aria-keyshortcuts attribute it also renders on the input, so the shortcut is announced rather than left for whoever guessed it, and a space-separated list covers a Windows and a macOS keyboard at once. A combination with no modifier only fires while the focus is outside of a field, so it never steals a character from something being typed elsewhere. Render it in a SuffixTemplate to make it discoverable with the eyes too.

The search box in the header of this page is one: it asks for FocusShortcut="Control+K Meta+K /", so ctrl/cmd + K jumps into it from anywhere and a bare / does the same while you are not typing. It already owns those three, so the two below take Alt combinations instead - a shortcut is a page-wide claim, and two controls claiming the same keys both answer.

A screen reader never sees the list appear, so the component owns a visually hidden live region that reports the outcome of every search: how many suggestions were found, that there were none, or that the term is still shorter than MinSuggestTriggerChars. AnnouncementProvider replaces those built-in English sentences, which is the hook to localize them; returning null keeps the region silent.

Capturing the component with @ref gives access to its public API: FocusAsync moves the focus into the input, Clear empties the value and raises OnClear exactly like the clear button does, ShowSuggestItems runs the search for the current value and opens the callout even when the field is not focused, and HideSuggestItems dismisses it again. IsSuggestItemsOpen reads back whether the callout is open, and OnSuggestItemsToggle is raised with true when it opens and false when it closes. InputElement exposes the underlying ElementReference.

Inside an EditForm the search box behaves like any other bit input: it registers itself with the cascading EditContext, reports its changes to it, renders the aria-invalid attribute and an error state when the field is invalid, and works with ValidationMessage. Set NoValidate to opt out of that integration.

Outside a form, ErrorMessage (or ErrorMessageTemplate) reports a rejection the app itself knows about: a server response, or a rule spanning two fields. It marks the field invalid on its own, is referenced by the input through aria-describedby, and is announced by the live region of the component the moment it shows up rather than only on the next focus.

BitParams carries a BitSearchBoxParams down to every search box under it, so a toolbar, a filter panel or a whole page sets the shared look and the shared suggest behavior once instead of at every field. What it carries is a default and not an override: a search box that writes a parameter for itself keeps its own value, and only what it left unset is filled in from the cascade. Each parameter is filled in on its own, so a field can take its Size from the cascade and its Underlined from its own markup. What belongs to one field alone - the value, the label, the suggest source, the templates and the callbacks - stays in its own markup.

Offering a range of specialized color variants with Primary being the default, providing visual cues for specific actions or states within your application.

Use icons from external libraries like FontAwesome, Material Icons, and Bootstrap Icons with the Icon, SearchButtonIcon and ClearButtonIcon parameters.

FontAwesome (Icon):

Bootstrap (Icon):

Search button with external icons (ShowSearchButton + SearchButtonIcon):

Clear button with external icons (ClearButtonIcon):

The Size parameter scales the height, the font size and the icons of the search box in one go, so the component can match a compact toolbar or a prominent hero search. Medium is the default when no size is specified.

Style and Class apply to the root element, while Styles and Classes reach every internal part of the component (the label, the wrapper, the input container, the icon, the clear and search buttons, the callout, the suggest items and the highlighted text). The Focused key of both objects is applied to the root only while the input holds the focus, which makes it easy to build custom focus visuals.

For a re-skin that follows every state on its own, set the public CSS variables listed in the API section instead: on :root they re-skin every search box of the app, on Style they re-skin one. The suggest callout is rendered outside the root element, so its own variables are set through the Callout key of Styles.

Use the BitSearchBox component in right-to-left (RTL).