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 IsEnabled="false" 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 that is programmatically 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.

Use LabelTemplate when the label needs custom markup such as an icon or a required marker.

The Underlined variant drops the box around the field and keeps only a bottom border, which makes the search box blend into dense toolbars and headers. The focus indicator turns into an underline ring as well.

NoBorder removes every border of the search box while keeping the focus ring intact, so the field is still clearly identifiable for keyboard users. It pairs well with a colored Background to build a filled, borderless field.

Background switches the surface color of the field between the primary, secondary and tertiary background tokens of the theme, or makes it fully Transparent so the search box inherits whatever is painted behind it (handy inside a colored header or a hero banner).

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.

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 - setting it to false is usually the right call for 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.

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

SuggestFilterFunction replaces the default case-insensitive "contains" matching, SuggestIgnoreDiacritics keeps that default matching but folds the accents away on both sides, so that "Jose" finds "José" without the user having to reproduce the diacritics, MinSuggestTriggerChars (3 by default) sets how many characters are needed before searching, MaxSuggestCount (5 by default) caps the number of rendered suggestions, and DebounceTime avoids hammering a remote provider on every keystroke. Stale provider calls are cancelled automatically through the CancellationToken of the request, so a slow response can never overwrite a newer one.

Modeless removes the invisible overlay that otherwise 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 (by clicking it or by pressing enter while it is highlighted) 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 so the user can see why a row was returned (a term that does not appear as a whole in the item, which is what a multi-word term or a server-side match usually produces, has each of its words highlighted instead), SuggestItemTemplate takes over the rendering of a whole row, and CalloutHeaderTemplate / CalloutFooterTemplate pin custom content above and below the scrollable list.

NoResultsText (or NoResultsTemplate) keeps the callout open with an explanatory message when a search returns nothing, instead of silently closing it, LoadingText / LoadingTemplate show progress while an async SuggestItemsProvider is still running, and MinSuggestTriggerCharsText explains the third silent state: a term that is still shorter than MinSuggestTriggerChars, which otherwise looks exactly like a search that found nothing. It is a composite format receiving how many characters are still missing, and it also replaces the built-in sentence announced to screen readers.

AutoSelectSuggestItem pre-highlights the first suggestion so enter picks it right away, and ShowSuggestItemsOnFocus combined with MinSuggestTriggerChars="0" opens the list as soon as the field is focused, which is the usual way to surface default or recent searches.

The search box implements the WAI-ARIA combobox pattern, so the whole suggest list is reachable without a mouse. The down and up arrows move the highlight (wrapping around at both ends), alt + down opens the list without moving the highlight and alt + up closes it, page down and page up jump five items at a time and stop at the edges, home and end jump straight to the first and the last suggestion, enter accepts the highlighted one (and places the caret at the end of it), tab and escape dismiss the list, and a second escape clears the field. While the list is open these keys no longer move the text 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 as they should. NoWrapNavigation stops the up and down arrows from cycling between the two ends of the list, which in a long list reads more like the highlight having been lost than like a deliberate jump.

Screen readers never see the list appear, so the component also 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. The AnnouncementProvider replaces those built-in English sentences with your own, which is the hook to localize them; it receives the search term, the suggestions, whether the provider is still loading and whether the term is too short, and returning null keeps the region silent.

Turn on a screen reader (or inspect the role="status" element inside the component) and type in both fields below to hear the difference between the default and the custom announcements.

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. The read-only IsSuggestItemsOpen property tells whether the callout is currently open, and OnSuggestItemsToggle is raised with true when it opens and with false when it closes, which is what a page needs to dim a backdrop or pause a background poll while the user is browsing suggestions.

InputElement exposes the underlying ElementReference for anything the component does not wrap itself.

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.

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.

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