# SearchBox
**Also known as:** AutoComplete, Typeahead
## Description
A search box (SearchBox) provides an input field for searching content within a site or app to find specific items. On top of a plain text input it adds a search icon, a clear button, an optional search button, and an optional suggest (auto-complete) callout backed either by an in-memory list or by an async, cancellable items provider. The input follows the WAI-ARIA combobox pattern: it exposes the suggest list to screen readers, announces the outcome of every search through its own live region, and supports full keyboard navigation with the arrow keys, Page Up/Page Down, Home/End, Enter and Escape.
## Parameters
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| AnnouncementProvider | `Func<BitSearchBoxAnnouncementArgs, string?>?` | null | Builds the text that the screen reader announces through the live region of the search box whenever the suggest items change, in place of the built-in English announcements. Returning null or an empty string announces nothing. |
| AriaDescription | `string?` | null | Detailed description of the search box for the benefit of screen readers, rendered into a visually hidden element that the input references through its aria-describedby attribute. |
| AutoCapitalize | `string?` | null | Sets the autocapitalize html attribute of the input element, which tells a virtual keyboard whether and how to capitalize what is typed. |
| AutoCorrect | `bool?` | null | Sets the autocorrect html attribute of the input element. Turning it off stops a mobile browser from rewriting a search term its dictionary does not know. |
| AutoFillSuggestItem | `bool` | false | Completes what is being typed with the first suggest item that starts with it, appending the rest of that item into the field and selecting the appended part. The completion is written into the input element only: the bound value keeps following what the user typed until enter, the search button or tabbing out accepts it, and escape puts the typed term back. |
| AutoSelectSuggestItem | `bool` | false | Automatically highlights the first suggest item as soon as the suggest list opens, so pressing enter selects it without pressing the arrow keys first. |
| Background | `BitColorKind?` | null | The background color kind of the search box. An explicit value wins over --bit-SearchBox-background; left unset, the background is the primary kind unless it says otherwise. |
| CalloutFooterTemplate | `RenderFragment?` | null | The custom template rendered at the bottom of the suggest items callout. |
| CalloutHeaderTemplate | `RenderFragment?` | null | The custom template rendered at the top of the suggest items callout. |
| Classes | `BitSearchBoxClassStyles?` | null | Custom CSS classes for different parts of the search box. |
| ClearButtonAriaLabel | `string` | Clear | The accessible label (aria-label) of the clear button. |
| ClearButtonIcon | `BitIconInfo?` | null | Gets or sets the icon to display on the clear button using custom CSS classes for external icon libraries. Takes precedence over ClearButtonIconName when both are set. |
| ClearButtonIconName | `string?` | Cancel | Gets or sets the name of the icon to display on the clear button from the built-in Fluent UI icons. |
| ClearButtonTemplate | `RenderFragment?` | null | The custom template for clear button icon. |
| Color | `BitColor?` | null | The general color of the search box, used for colored parts like icons. An explicit value wins over the --bit-SearchBox-* color variables it paints (the icon, the focus rings, the disabled colors, the search button, the spinner and the ring of the highlighted suggestion); left unset, the search box is primary unless they say otherwise. |
| Description | `string?` | null | The hint rendered under the field, referenced by the input through its aria-describedby attribute so a screen reader reads it after the label. |
| DescriptionTemplate | `RenderFragment?` | null | The custom content of the description under the field, which replaces the plain Description text and is referenced by the input in the same way. |
| DisableAnimation | `bool` | false | Whether or not to animate the search box icon on focus. |
| EnterKeyHint | `BitEnterKeyHint?` | BitEnterKeyHint.Search | Sets the enterkeyhint html attribute of the input element, which tells virtual keyboards which action label to render on their enter key. It defaults to Search because pressing enter always runs a search here. |
| ErrorMessage | `string?` | null | The message shown under the field when the value was rejected. It marks the field invalid on its own, is referenced by the input through its aria-describedby attribute, and is announced by the live region of the component. |
| ErrorMessageAriaLabel | `string?` | null | The text a screen reader is given for an ErrorMessageTemplate, which is free to render anything at all and so has no text of its own. It is announced through the live region the moment the template shows up, in place of the default "Invalid input", and the input references it through aria-describedby, so the same reason is read out on every later focus too. A plain ErrorMessage is its own text and never uses it. Give it the reason the template shows, in the language of the page: a template switching to another reason is only announced again when this text switches along with it. Cascaded through BitParams it reaches every search box under it, so set it there only as a generic replacement for "Invalid input". |
| ErrorMessageTemplate | `RenderFragment?` | null | The custom content of the error message, which replaces the plain ErrorMessage text and marks the field invalid in the same way. It replaces the message for a screen reader as well: a template is free to render anything at all, so the live region announces ErrorMessageAriaLabel for it, or a bare "Invalid input" when that is not set. |
| FixedCalloutWidth | `bool` | false | Forces the suggest callout width to be always fixed at the component's width. |
| FixedIcon | `bool` | false | Whether or not to make the icon be always visible (it hides by default when the search box is focused). |
| FocusShortcut | `string?` | null | The keyboard shortcut that moves the focus into the search box from anywhere on the page, written in the syntax of the aria-keyshortcuts attribute the input is given (e.g. "Control+K Meta+K"). A combination with no modifier only fires while the focus is outside of a field. |
| FullWidth | `bool` | false | Expands the search box to fill the available width of its container. |
| HideClearButton | `bool` | false | Whether to hide the clear button when the search box has value. |
| HideIcon | `bool` | false | Whether or not the icon is visible. |
| HighlightSuggestItems | `bool` | false | Highlights the part of each suggest item that matches the current search term. |
| Icon | `BitIconInfo?` | null | Gets or sets the icon to display using custom CSS classes for external icon libraries. Takes precedence over IconName when both are set. |
| IconName | `string?` | Search | Gets or sets the name of the icon to display from the built-in Fluent UI icons. |
| InputMode | `BitInputMode?` | null | Sets the inputmode html attribute of the input element. |
| Label | `string?` | null | The text of the label of the search box, rendered as a real label element tied to the input. |
| LabelTemplate | `RenderFragment?` | null | The custom template for the label of the search box. |
| Loading | `bool` | false | Shows a spinner in the trailing slot of the field and marks the input busy, for a search the app itself is running. It is not the progress of the suggest callout, which LoadingText and LoadingTemplate drive. |
| LoadingAriaLabel | `string` | Searching | What the live region of the component announces while Loading is on. |
| LoadingTemplate | `RenderFragment?` | null | The custom template rendered in place of the default spinner in the suggest callout while the SuggestItemsProvider is resolving the suggest items. |
| LoadingText | `string?` | null | The text rendered next to the loading indicator while the SuggestItemsProvider is resolving the suggest items. |
| MaxLength | `int` | -1 | Sets the maxlength html attribute of the input element. A negative value means no limit. |
| MaxSuggestCount | `int` | 5 | The maximum number of items or suggestions that will be displayed. A value of zero or less means no limit. |
| MinSuggestTriggerChars | `int` | 3 | The minimum character requirement for doing a search in suggest items. Setting it to zero also enables searching with an empty search term which is useful for showing default or recent items. |
| MinSuggestTriggerCharsText | `string?` | null | The composite format of the hint the callout shows while the typed term is still shorter than MinSuggestTriggerChars, which receives the number of characters that are still missing, for example "Type {0} more characters to search". The hint is never shown while the field is empty, and it replaces the built-in English sentence announced to screen readers as well. |
| Modeless | `bool` | false | Removes the overlay of suggest items callout. |
| NoBorder | `bool` | false | Removes the default border of the search box. |
| NoClearOnEscape | `bool` | false | Prevents clearing the value of the search box when the user presses the escape key, which hands the key back to the Dialog, the Modal, the Panel or the Overlay the field sits in. Without it, the press that clears the field is the field's alone, and they close on the next one. |
| NoResultsTemplate | `RenderFragment?` | null | The custom template rendered in the callout when the search finds no suggest item. |
| NoResultsText | `string?` | null | The text rendered in the callout when the search finds no suggest item. |
| NoWrapNavigation | `bool` | false | Stops the up and down arrows from cycling between the two ends of the suggest list, so that the highlight stops at the first and the last item instead of jumping from one to the other. |
| OnClear | `EventCallback` | | Callback executed when the user clears the search box by either clicking 'X' or hitting escape. |
| OnClick | `EventCallback<MouseEventArgs>` | | Callback executed when the user clicks on the input of the search box. |
| OnEscape | `EventCallback` | | Callback executed when the user presses escape in the search box. |
| OnFocus | `EventCallback<FocusEventArgs>` | | Callback executed when the input of the search box gets focused. |
| OnFocusIn | `EventCallback<FocusEventArgs>` | | Callback executed when the input of the search box gets focused in. |
| OnFocusOut | `EventCallback<FocusEventArgs>` | | Callback executed when the input of the search box loses focus. |
| OnKeyDown | `EventCallback<KeyboardEventArgs>` | | Callback executed on each key down of the input of the search box. |
| OnKeyUp | `EventCallback<KeyboardEventArgs>` | | Callback executed on each key up of the input of the search box. |
| OnSearch | `EventCallback<string?>` | | Callback executed when the user presses enter in the search box, clicks the search button, or picks one of the suggest items. |
| OnSuggestFailed | `EventCallback<Exception>` | | Callback executed with the exception a SuggestItemsProvider threw. A cancelled call is not a failure and never raises it. |
| OnSuggestItemSelect | `EventCallback<string>` | | Callback executed when the user selects one of the suggest items either by clicking on it or by pressing enter while it is highlighted. |
| OnSuggestItemsToggle | `EventCallback<bool>` | | Callback executed with true when the suggest items callout opens and with false when it closes. |
| Placeholder | `string?` | null | Placeholder for the search box. |
| Prefix | `string?` | null | Prefix text displayed before the search box input. This is not included in the value. |
| PrefixTemplate | `RenderFragment?` | null | The custom template for the prefix of the search box. |
| SearchButtonAriaLabel | `string` | Search | The accessible label (aria-label) of the search button. |
| SearchButtonIcon | `BitIconInfo?` | null | Gets or sets the icon to display on the search button using custom CSS classes for external icon libraries. Takes precedence over SearchButtonIconName when both are set. |
| SearchButtonIconName | `string?` | ChromeBackMirrored | Gets or sets the name of the icon to display on the search button from the built-in Fluent UI icons. |
| SearchButtonTemplate | `RenderFragment?` | null | The custom template for search button icon. |
| SearchButtonText | `string?` | null | The label rendered on the search button next to its icon. The button widens to fit it, and the label names the button for a screen reader, so SearchButtonAriaLabel is no longer rendered while it is set. |
| SelectTextOnFocus | `bool` | false | Selects the text already in the search box whenever the input takes the focus, so that typing replaces the previous term instead of appending to it. It does nothing while the field is empty. |
| ShowSearchButton | `bool` | false | Whether to show the search button. |
| ShowSuggestItemsOnFocus | `bool` | false | Opens the suggest items callout as soon as the input gets focused, without waiting for the user to type. Combine it with a zero MinSuggestTriggerChars to implement default or recent search items. |
| Size | `BitSize?` | null | The size of the search box. An explicit value wins over the --bit-SearchBox-* size variables (height, font sizes, icon sizes, search button width and padding, spinner size, suggest row height and font size); left unset, the search box is medium unless they say otherwise. |
| SpellCheck | `bool?` | null | Sets the spellcheck html attribute of the input element. Leaving it null keeps the default behavior of the browser, setting it to false removes the red squiggles from search terms that are not real words. |
| Styles | `BitSearchBoxClassStyles?` | null | Custom CSS styles for different parts of the search box. |
| Suffix | `string?` | null | Suffix text displayed after the search box input. This is not included in the value. |
| SuffixTemplate | `RenderFragment?` | null | The custom template for the suffix of the search box. |
| SuggestFailedTemplate | `RenderFragment?` | null | The custom content rendered in the callout when the SuggestItemsProvider throws, which replaces the plain SuggestFailedText. |
| SuggestFailedText | `string?` | null | The text rendered in the callout when the SuggestItemsProvider throws, which is what tells a search that could not run apart from one that found nothing. It replaces the built-in sentence announced to screen readers as well. |
| SuggestFilterFunction | `Func<string?, string?, bool>?` | null | Custom search function to be used in place of the default search algorithm. The first argument is the current search term and the second one is the suggest item to examine. |
| SuggestIgnoreDiacritics | `bool` | false | Matches the search term against the suggest items with the diacritics of both removed, so that "Jose" finds "José" and "Muller" finds "Müller". The item text itself is left untouched, and so is the part of it that HighlightSuggestItems emphasizes. Ignored when a SuggestFilterFunction is provided, but still applied to the highlight. |
| SuggestItems | `IEnumerable<string>?` | null | The list of suggest items to display in the callout. |
| SuggestItemsAriaLabel | `string` | Suggestions | The accessible label (aria-label) of the suggest items list. |
| SuggestItemsProvider | `BitSearchBoxSuggestItemsProvider?` | null | The item provider function providing suggest items. |
| SuggestItemTemplate | `RenderFragment<string>?` | null | The custom template for rendering the suggest items of the search box. |
| Trim | `bool` | false | Trims the leading and trailing white-spaces of the value of the search box. |
| Underlined | `bool` | false | Whether or not the search box is underlined. |
| AutoComplete | `string?` | null | Specifies the value of the autocomplete attribute of the input component. |
| AutoFocus | `bool` | false | Determines if the text input is auto focused on first render. |
| DebounceTime | `int` | 0 | The debounce time in milliseconds. |
| Immediate | `bool` | false | Change the content of the input field when the user write text (based on 'oninput' HTML event). |
| ThrottleTime | `int` | 0 | The throttle time in milliseconds. |
| DefaultValue | `TValue?` | null | The default value of the input to be used in uncontrolled mode (i.e. when the Value is not bound), typically used alongside the OnChange callback. |
| DisplayName | `string?` | null | Gets or sets the display name for this field. |
| InputHtmlAttributes | `IReadOnlyDictionary<string, object>?` | null | Gets or sets a collection of additional attributes that will be applied to the created element. |
| Name | `string?` | null | Gets or sets the name of the element. Allows access by name from the associated form. |
| NoValidate | `bool` | false | Disables the validation of the input. |
| OnChange | `EventCallback<TValue?>` | | Callback for when the input value changes. |
| ReadOnly | `bool` | false | Makes the input read-only. |
| Required | `bool` | false | Makes the input required. |
| Value | `TValue?` | null | Gets or sets the value of the input. This should be used with two-way binding. |
| AriaLabel | `string?` | null | Gets or sets the accessible label for the component, used by assistive technologies. |
| Class | `string?` | null | Gets or sets the CSS class name(s) to apply to the rendered element. |
| Dir | `BitDir?` | null | Gets or sets the text directionality for the component's content. |
| Disabled | `bool` | false | Gets or sets a value indicating whether the component is disabled and cannot respond to user interaction. |
| ForceAnimation | `bool` | false | Gets or sets a value indicating whether the component's animations play at their full duration even when reduced motion is requested. |
| HtmlAttributes | `Dictionary<string, object>` | new Dictionary<string, object>() | Captures additional HTML attributes to be applied to the rendered element, in addition to the component's parameters. An attribute written on the component wins over an entry of the same name. |
| Id | `string?` | null | Gets or sets the unique identifier for the component's root element. |
| Style | `string?` | null | Gets or sets the CSS style string to apply to the rendered element. |
| TabIndex | `string?` | null | Gets or sets the tab order index for the component when navigating with the keyboard. |
| Visibility | `BitVisibility` | BitVisibility.Visible | Gets or sets the visibility state (visible, hidden, or collapsed) of the component. |
## Public Members
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| InputElement | `ElementReference` | | The ElementReference to the input element of the BitSearchBox. |
| FocusAsync | `ValueTask` | | Gives focus to the input element of the BitSearchBox. |
| IsSuggestItemsOpen | `bool` | false | Whether the callout of the suggest items is currently open. |
| Clear | `Task` | | Clears the value of the BitSearchBox and invokes the OnClear callback. |
| ShowSuggestItems | `Task` | | Runs the suggest items search of the current value and opens the callout of the suggest items. |
| HideSuggestItems | `Task` | | Closes the callout of the suggest items. |
| InputElement | `ElementReference` | | The ElementReference of the input element. |
| FocusAsync() | `() => ValueTask` | | Gives focus to the input element. |
| FocusAsync(bool preventScroll) | `(bool preventScroll) => ValueTask` | | Gives focus to the input element. |
| UniqueId | `Guid` | Guid.NewGuid() | Gets the readonly unique identifier for the component's root element, assigned when the component instance is constructed. |
| RootElement | `ElementReference` | | Gets the reference to the root HTML element associated with this component. |
## Enums
### BitColorKind Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Primary | 0 | The primary color kind. |
| Secondary | 1 | The secondary color kind. |
| Tertiary | 2 | The tertiary color kind. |
| Transparent | 3 | The transparent color kind. |
### BitColor Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Primary | 0 | Primary general color. |
| Secondary | 1 | Secondary general color. |
| Tertiary | 2 | Tertiary general color. |
| Info | 3 | Info general color. |
| Success | 4 | Success general color. |
| Warning | 5 | Warning general color. |
| SevereWarning | 6 | SevereWarning general color. |
| Error | 7 | Error general color. |
| PrimaryBackground | 8 | Primary background color. |
| SecondaryBackground | 9 | Secondary background color. |
| TertiaryBackground | 10 | Tertiary background color. |
| PrimaryForeground | 11 | Primary foreground color. |
| SecondaryForeground | 12 | Secondary foreground color. |
| TertiaryForeground | 13 | Tertiary foreground color. |
| PrimaryBorder | 14 | Primary border color. |
| SecondaryBorder | 15 | Secondary border color. |
| TertiaryBorder | 16 | Tertiary border color. |
### BitSize Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Small | 0 | The small size. |
| Medium | 1 | The medium size. |
| Large | 2 | The large size. |
### BitEnterKeyHint Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Enter | 0 | Typically inserting a new line. |
| Done | 1 | Typically meaning there is nothing more to input and the input method editor will be closed. |
| Go | 2 | Typically meaning to take the user to the target of the text they typed. |
| Next | 3 | Typically taking the user to the next field that will accept text. |
| Previous | 4 | Typically taking the user to the previous field that will accept text. |
| Search | 5 | Typically taking the user to the results of searching for the text they have typed. |
| Send | 6 | Typically delivering the text to its target. |
### BitInputMode Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| None | 0 | No virtual keyboard. For when the page implements its own keyboard input control. |
| Text | 1 | Standard input keyboard for the user's current locale. |
| Decimal | 2 | Fractional numeric input keyboard containing the digits and decimal separator for the user's locale. |
| Numeric | 3 | Numeric input keyboard, but only requires the digits 0–9. |
| Tel | 4 | A telephone keypad input, including the digits 0–9, the asterisk (*), and the pound (#) key. |
| Search | 5 | A virtual keyboard optimized for search input. |
| Email | 6 | A virtual keyboard optimized for entering email addresses. |
| Url | 7 | A keypad optimized for entering URLs. |
### BitVisibility Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Visible | 0 | The content of the component is visible. |
| Hidden | 1 | The content of the component is hidden, but the space it takes on the page remains (visibility:hidden). |
| Collapsed | 2 | The component is hidden (display:none). |
### BitDir Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Ltr | 0 | Ltr (left to right) is to be used for languages that are written from the left to the right (like English). |
| Rtl | 1 | Rtl (right to left) is to be used for languages that are written from the right to the left (like Arabic). |
| Auto | 2 | Auto lets the user agent decide. It uses a basic algorithm as it parses the characters inside the element until it finds a character with a strong directionality, then applies that directionality to the whole element. |
## Sub Classes
### BitSearchBoxClassStyles Properties
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| Root | `string?` | null | Custom CSS classes/styles for the root element of the search box. |
| Focused | `string?` | null | Custom CSS classes/styles for the focus state of the search box. |
| Label | `string?` | null | Custom CSS classes/styles for the search box's label. |
| Wrapper | `string?` | null | Custom CSS classes/styles for the wrapper of the input container and the search button of the search box. |
| InputContainer | `string?` | null | Custom CSS classes/styles for the search box's input container. |
| IconWrapper | `string?` | null | Custom CSS classes/styles for the search box's icon wrapper. |
| Icon | `string?` | null | Custom CSS classes/styles for the search box's search icon. |
| PrefixContainer | `string?` | null | Custom CSS classes/styles for the search box's search prefix container. |
| Prefix | `string?` | null | Custom CSS classes/styles for the search box's search prefix. |
| Input | `string?` | null | Custom CSS classes/styles for the search box's Input. |
| SuffixContainer | `string?` | null | Custom CSS classes/styles for the search box's search suffix container. |
| Suffix | `string?` | null | Custom CSS classes/styles for the search box's search suffix. |
| ClearButton | `string?` | null | Custom CSS classes/styles for the search box's clear button. |
| ClearButtonIcon | `string?` | null | Custom CSS classes/styles for the search box's clear button icon. |
| SearchButton | `string?` | null | Custom CSS classes/styles for the search box's search button. |
| SearchButtonIcon | `string?` | null | Custom CSS classes/styles for the search box's search button icon. |
| SearchButtonText | `string?` | null | Custom CSS classes/styles for the search box's search button text. |
| LoadingSpinner | `string?` | null | Custom CSS classes/styles for the spinner slot shown in the field while the search box is Loading. The spinner of the suggest callout is Loading instead. |
| Spinner | `string?` | null | Custom CSS classes/styles for the search box's busy spinner itself - the ring drawn in the field while it is Loading, and in the suggest callout when no LoadingTemplate is set. |
| ErrorMessageContainer | `string?` | null | Custom CSS classes/styles for the container of the search box's error message. |
| ErrorMessage | `string?` | null | Custom CSS classes/styles for the search box's error message. |
| DescriptionContainer | `string?` | null | Custom CSS classes/styles for the container of the search box's description. |
| Description | `string?` | null | Custom CSS classes/styles for the search box's description. |
| Overlay | `string?` | null | Custom CSS classes/styles for the search box's overlay. |
| Callout | `string?` | null | Custom CSS classes/styles for the search box's callout. |
| CalloutHeader | `string?` | null | Custom CSS classes/styles for the header of the search box's callout. |
| CalloutFooter | `string?` | null | Custom CSS classes/styles for the footer of the search box's callout. |
| Loading | `string?` | null | Custom CSS classes/styles for the loading container of the search box's suggest callout. |
| NoResults | `string?` | null | Custom CSS classes/styles for the no-results container of the search box's callout. |
| SuggestFailed | `string?` | null | Custom CSS classes/styles for the container the search box's callout reports a failing suggest items provider in. |
| Hint | `string?` | null | Custom CSS classes/styles for the too-short-term hint of the search box's callout. |
| ScrollContainer | `string?` | null | Custom CSS classes/styles for the search box's scroll container. |
| SuggestItemWrapper | `string?` | null | Custom CSS classes/styles for the search box's suggest item wrapper. |
| SuggestItemButton | `string?` | null | Custom CSS classes/styles for the search box's suggest item button. |
| SuggestItemText | `string?` | null | Custom CSS classes/styles for the search box's suggest item text. |
| SuggestItemHighlight | `string?` | null | Custom CSS classes/styles for the highlighted part of the search box's suggest item text. |
### BitSearchBoxSuggestItemsProviderRequest Properties
The context passed to the SuggestItemsProvider delegate on every search.
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| SearchTerm | `string?` | null | The current value of the search box that the suggest items must be resolved for. |
| Take | `int` | 0 | The value of the MaxSuggestCount parameter, so the provider can only fetch as many items as will be rendered. |
| CancellationToken | `CancellationToken` | | A token that is cancelled as soon as a newer search starts, so an outdated request can be aborted and can never overwrite a newer result. |
### BitSearchBoxAnnouncementArgs Properties
The state of the suggest items at the moment the screen reader announcement is built, passed to the AnnouncementProvider.
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| SearchTerm | `string?` | null | The current value of the search box that the suggest items were resolved for. |
| SuggestItems | `IReadOnlyList<string>` | [] | The suggest items that are about to be rendered in the callout. |
| IsLoading | `bool` | false | Whether an asynchronous SuggestItemsProvider is still resolving the suggest items. |
| IsSearchTermTooShort | `bool` | false | Whether the search term is still shorter than the MinSuggestTriggerChars, so no search was performed at all. |
| MinSuggestTriggerChars | `int` | 3 | The value of the MinSuggestTriggerChars parameter. |
| HasFailed | `bool` | false | Whether the SuggestItemsProvider threw, so the suggest items are empty because the search could not run rather than because nothing matched. |
### BitIconInfo Properties
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| Name | `string?` | null | Gets or sets the name of the icon. |
| BaseClass | `string?` | null | Gets or sets the base CSS class for the icon. For built-in Fluent UI icons, this defaults to "bit-icon". For external icon libraries like FontAwesome, you might set this to "fa" or leave empty. |
| Prefix | `string?` | null | Gets or sets the CSS class prefix used before the icon name. For built-in Fluent UI icons, this defaults to "bit-icon--". For external icon libraries, you might set this to "fa-" or leave empty. |
## CSS Variables
Public CSS custom properties read off the component's root. Set one on `:root` to restyle every instance, on any ancestor to restyle the ones inside it, or on the `Style` of one instance to restyle it and every instance nested inside it, which inherits the value too - a parameter changes one alone, as does the real CSS property on its `Style` / `Styles` when that property does not inherit (`opacity`); an inherited one (`color`, `font-family`) reaches the nested instances that do not set it themselves.
| Name | Default Value | Description |
| :--- | :------------ | :---------- |
| `--bit-SearchBox-color` | $clr-fg-pri | Text color of the input, the prefix and the suffix. |
| `--bit-SearchBox-placeholder-color` | --bit-clr-fg-sec | Text color of the placeholder. |
| `--bit-SearchBox-background` | $clr-bg-pri | Background of the field. The Background parameter wins over it. |
| `--bit-SearchBox-border-color` | $clr-brd-pri | Border color of the field at rest. |
| `--bit-SearchBox-border-width` | $shp-border-width | Border thickness of the field and of the search button. |
| `--bit-SearchBox-radius` | $shp-radius-control | Corner radius of the field, its buttons and its focus ring. |
| `--bit-SearchBox-height` | $siz-ctrl-md | Height of the field, and the width of its square icon and button slots. The Size parameter wins over it. |
| `--bit-SearchBox-padding` | spacing(1) | Inline padding of the text input. |
| `--bit-SearchBox-font-size` | $tg-fs-sm | Text size of the label, the field, its affixes, the description and the error message. The Size parameter wins over it. |
| `--bit-SearchBox-icon-size` | $siz-icon-md | Glyph size of the leading icon and of the buttons. The Size parameter wins over it. |
| `--bit-SearchBox-icon-color` | $clr-pri | Color of the leading icon. The Color parameter wins over it. |
| `--bit-SearchBox-hover-border-color` | $clr-brd-pri-hover | Border color while the field is hovered. |
| `--bit-SearchBox-hover-icon-color` | $clr-pri-hover | Color of the leading icon while the field is hovered. The Color parameter wins over it. |
| `--bit-SearchBox-focus-color` | $clr-pri-focus | Focus ring color of the field, the clear button and the search button. The Color parameter wins over it. While it is unset, the focus ring is the library's own --bit-shd-focus-ring, so replacing that token re-shapes it too. |
| `--bit-SearchBox-disabled-color` | $clr-pri-dis-text | Text, icon and affix color when the search box is disabled. The Color parameter wins over it. |
| `--bit-SearchBox-disabled-background` | $clr-pri-dis | Background and border color when the search box is disabled. The Color parameter wins over it. |
| `--bit-SearchBox-invalid-color` | $clr-err | Border and icon color of a rejected field, and the color of its error message. |
| `--bit-SearchBox-label-color` | $clr-fg-pri | Color of the label. |
| `--bit-SearchBox-label-font-weight` | $tg-field-label-font-weight | Weight of the label. |
| `--bit-SearchBox-required-color` | $clr-req | Color of the asterisk next to the label of a required field. |
| `--bit-SearchBox-description-color` | $clr-fg-sec | Color of the description under the field. |
| `--bit-SearchBox-affix-color` | $clr-fg-pri | Text color of the prefix and of the suffix. |
| `--bit-SearchBox-affix-background` | $clr-bg-sec | Background of the prefix and of the suffix. |
| `--bit-SearchBox-clear-button-color` | $clr-fg-sec | Glyph color of the clear button. |
| `--bit-SearchBox-clear-button-icon-size` | Three quarters of --bit-SearchBox-icon-size | Glyph size of the clear button, which is drawn smaller than the leading icon. The Size parameter wins over it. |
| `--bit-SearchBox-clear-button-hover-color` | $clr-fg-pri-hover | Glyph color of the hovered clear button. |
| `--bit-SearchBox-clear-button-active-background` | $clr-bg-pri-active | Background of the pressed clear button. |
| `--bit-SearchBox-clear-button-hover-background` | $clr-bg-pri-hover | Background of the hovered clear button. |
| `--bit-SearchBox-search-button-color` | $clr-pri-text | Glyph color of the search button. The Color parameter wins over it. |
| `--bit-SearchBox-search-button-background` | $clr-pri | Background and border color of the search button. The Color parameter wins over it. |
| `--bit-SearchBox-search-button-hover-background` | $clr-pri-hover | Background of the hovered search button. The Color parameter wins over it. |
| `--bit-SearchBox-search-button-active-background` | $clr-pri-active | Background of the pressed search button. The Color parameter wins over it. |
| `--bit-SearchBox-search-button-width` | The height of the field, or its content when SearchButtonText is set | Width of the search button. The Size parameter wins over it for the square button, which is as wide as the field is tall. |
| `--bit-SearchBox-search-button-padding` | $siz-ctrl-pad-x-md | Inline padding of a search button that carries a SearchButtonText. The Size parameter wins over it. |
| `--bit-SearchBox-search-button-gap` | spacing(0.5) | Room between the glyph and the label of the search button. |
| `--bit-SearchBox-callout-background` | $clr-bg-pri | Background of the suggest callout. |
| `--bit-SearchBox-callout-radius` | $shp-radius-popup | Corner radius of the callout, on the two corners away from the field. |
| `--bit-SearchBox-callout-shadow` | $box-shadow-popup | Elevation of the callout. |
| `--bit-SearchBox-callout-max-height` | $siz-popup-max-height | Tallest the suggest list grows before it scrolls. |
| `--bit-SearchBox-callout-border-color` | $clr-brd-pri | The hairlines under the callout header and above the callout footer. |
| `--bit-SearchBox-callout-text-color` | $clr-fg-pri / $clr-fg-sec | Color of the callout header and footer, and of the loading, empty and too-short messages. |
| `--bit-SearchBox-callout-failed-color` | $clr-err | Color of the message a failing suggest items provider is reported with. |
| `--bit-SearchBox-spinner-color` | $clr-pri | Arc color of the loading spinner, in the field and in the callout. The Color parameter wins over it. |
| `--bit-SearchBox-spinner-track-color` | --bit-clr-brd-pri | Color of the ring the arc of the loading spinner travels on, in the field and in the callout. |
| `--bit-SearchBox-spinner-size` | $siz-icon-md (the icon size in the field) | Diameter of the loading spinner, in the field and in the callout. The Size parameter wins over it. |
| `--bit-SearchBox-item-color` | $clr-fg-pri | Text color of a suggest item. |
| `--bit-SearchBox-item-min-height` | $siz-item-md | Smallest height of a suggest item. The Size parameter wins over it. |
| `--bit-SearchBox-item-padding` | spacing(0.5) spacing(1) | Padding of a suggest item. |
| `--bit-SearchBox-item-font-size` | $tg-fs-sm | Text size of everything inside the callout. The Size parameter wins over it. |
| `--bit-SearchBox-item-hover-background` | $clr-bg-pri-hover | Background of a hovered suggest item. |
| `--bit-SearchBox-item-hover-color` | The item color | Text color of a hovered suggest item, which a hover background dark enough to need its own text color has to be paired with. |
| `--bit-SearchBox-item-selected-background` | $clr-bg-sec | Background of the suggest item the arrow keys highlight. |
| `--bit-SearchBox-item-selected-color` | The item color | Text color of the suggest item the arrow keys highlight. |
| `--bit-SearchBox-item-selected-border-color` | $clr-pri-focus | Ring drawn inside the suggest item the arrow keys highlight, which is the only thing that says where the keyboard is (the focus itself never leaves the input). The Color parameter wins over it. |
| `--bit-SearchBox-highlight-color` | Inherited from the item | Text color of the matched part of a suggest item. |
| `--bit-SearchBox-highlight-background` | transparent | Background of the matched part of a suggest item. |
| `--bit-SearchBox-highlight-font-weight` | $tg-fw-semibold | Weight of the matched part of a suggest item. |
## Examples
\n**Basic**:
```razor
Advanced search
```
\n**Variants**:
```razor
```
\n**Input Behavior**:
```razor
Go
```
```csharp
private string? maxLengthValue;
private string? trimmedValue;
```
\n**Binding**:
```razor
@foreach (var log in eventLogs)
{
@log
}
```
```csharp
private readonly List eventLogs = [];
private void Log(string message)
{
eventLogs.Insert(0, message);
if (eventLogs.Count > 20)
{
eventLogs.RemoveAt(eventLogs.Count - 1);
}
}
private void HandleOnClick() => Log("OnClick");
private void HandleOnFocusIn() => Log("OnFocusIn");
private void HandleOnFocusOut() => Log("OnFocusOut");
private void HandleOnEscape() => Log("OnEscape");
private void HandleOnClear() => Log("OnClear");
private void HandleOnSearch(string? value) => Log($"OnSearch: {value}");
private void HandleOnKeyDown(KeyboardEventArgs args) => Log($"OnKeyDown: {args.Key}");
```
\n**Suggestion (AutoComplete)**:
```razor
GetSuggestedItems() =>
[
"Apple",
"Red Apple",
"Blue Apple",
"Green Apple",
"Banana",
"Orange",
"Grape",
"Broccoli",
"Carrot",
"Lettuce"
];
private List GetAccentedSuggestedItems() =>
[
"José Álvarez",
"Jürgen Müller",
"Renée Fauré",
"Zoë Brontë",
"Søren Kierkegaard"
];
private List GetLongSuggestedItems() =>
[
"Apple Apple Apple Apple Apple Apple Apple Apple Apple Apple Apple Apple Apple Apple Apple Apple",
"Red Apple Apple Apple Apple Apple Apple Apple Apple Apple Apple Apple Apple Apple Apple Apple Apple",
"Blue Apple Apple Apple Apple Apple Apple Apple Apple Apple Apple Apple Apple Apple Apple Apple Apple",
"Green Apple Apple Apple Apple Apple Apple Apple Apple Apple Apple Apple Apple Apple Apple Apple Apple",
"Banana Banana Banana Banana Banana Banana Banana Banana Banana Banana Banana Banana Banana Banana Banana",
"Orange Orange Orange Orange Orange Orange Orange Orange Orange Orange Orange Orange Orange Orange Orange",
"Grape Grape Grape Grape Grape Grape Grape Grape Grape Grape Grape Grape Grape Grape Grape Grape Grape Grape",
"Broccoli Broccoli Broccoli Broccoli Broccoli Broccoli Broccoli Broccoli Broccoli Broccoli Broccoli Broccoli",
"Carrot Carrot Carrot Carrot Carrot Carrot Carrot Carrot Carrot Carrot Carrot Carrot Carrot Carrot Carrot Carrot",
"Lettuce Lettuce Lettuce Lettuce Lettuce Lettuce Lettuce Lettuce Lettuce Lettuce Lettuce Lettuce Lettuce Lettuce"
];
private Func SearchFunc = (string? searchText, string? itemText) =>
{
if (string.IsNullOrEmpty(searchText) || string.IsNullOrEmpty(itemText)) return false;
return itemText.StartsWith(searchText, StringComparison.OrdinalIgnoreCase);
};
private async ValueTask> LoadItems(BitSearchBoxSuggestItemsProviderRequest request)
{
try
{
var query = new Dictionary()
{
{ "$top", request.Take < 1 ? 5 : request.Take },
};
if (string.IsNullOrEmpty(request.SearchTerm) is false)
{
query.Add("$filter", $"contains(toupper(Name),'{request.SearchTerm.ToUpper()}')");
}
var url = NavManager.GetUriWithQueryParameters("api/Products/GetProducts", query);
var data = await HttpClient.GetFromJsonAsync(url, AppJsonContext.Default.PagedResultProductDto, request.CancellationToken);
return data!.Items!.Select(i => i.Name)!;
}
catch
{
return [];
}
}
```
\n**Suggest Callout**:
```razor
@item
Top matches
See all results
GetRecentSearches() =>
[
"Wireless keyboard",
"Noise cancelling headphones",
"Mechanical switches",
"USB-C hub"
];
private string? suggestFailure;
private async ValueTask> LoadItemsThatFail(BitSearchBoxSuggestItemsProviderRequest request)
{
await Task.Delay(600, request.CancellationToken);
throw new HttpRequestException("The suggestions endpoint is unreachable.");
}
private async ValueTask> LoadItemsSlowly(BitSearchBoxSuggestItemsProviderRequest request)
{
// an artificial delay to make the loading indicator of the callout observable.
await Task.Delay(1500, request.CancellationToken);
// LoadItems is the remote provider of the Suggestion (AutoComplete) example above.
return await LoadItems(request);
}
```
\n**Keyboard & Screen Readers**:
```razor
Focus
Clear
Show suggestions
Hide suggestions
```
```csharp
private bool isSuggestOpen;
private BitSearchBox searchBoxRef = default!;
```
\n**Validation**:
```razor
GetSuggestedItems() =>
[
"Apple",
"Red Apple",
"Blue Apple",
"Green Apple",
"Banana",
"Orange",
"Grape",
"Broccoli",
"Carrot",
"Lettuce"
];
```
\n**RTL**:
```razor
GetPersianSuggestedItems() =>
[
"سیب",
"سیب قرمز",
"سیب سبز",
"موز",
"پرتقال",
"انگور"
];
```
Value: [@maxLengthValue]
Value: [@trimmedValue]
Search Value: @onChangeSearchValue
Search Value: @onSearchValue
Search Value: @uncontrolledValue
```
```csharp
private string? twoWaySearchValue;
private string? immediateTwoWaySearchValue;
private string? onChangeSearchValue;
private string? onSearchValue;
private string? uncontrolledValue;
```
\n**Events**:
```razor
SearchValue: @searchValue
Selected item: @selectedSuggestItem
Logged: @suggestFailure
AltK
AltS
Announced: @announcedText
The suggest callout is @(isSuggestOpen ? "open" : "closed").