HxSearchBox #

A search input component with automatic suggestions, initial dropdown template, and support for free-text queries.

HxSearchBox component is similar to HxAutosuggest component, but it is designed to be used for searching.

  • HxSearchBox allows you to customize item rendering,
  • HxSearchBox supports free-text query,
  • HxSearchBox does not support Value binding to the model,
  • HxSearchBox does not support validation.

Basic usage #

Last selected item:
Last triggered text-query:

Note: The demos on this page use DemoDataService, in-memory simulation of a simple data store. Find the implementation on GitHub.

Suggestions only #

You can disable free-text query by setting AllowTextQuery="false". Only suggestions will be allowed.

Last selected item:

Initial suggestions #

You can provide initial suggestions to the user by setting MinimumLength="0". This is useful when you want to display some suggestions to the user before they start typing.

Last selected item:

Text query without suggestions #

You may want to include a straightforward search box to initiate text-based searches. No suggestions, just visual cues to assist the user.

Last triggered text-query:

API #

Parameters #

Name Type Description
AllowTextQuery bool Indicates whether text-query mode is enabled (accepts free text in addition to suggested items).
Default is true.
ClearIcon IconBase Icon of the input, displayed when text is entered, allowing the user to clear the text.
CssClass string Additional CSS classes for the dropdown.
DataProvider SearchBoxDataProviderDelegate<TItem> Method (delegate) that provides data for the suggestions.
DefaultContentTemplate RenderFragment Rendered when no input is entered (i.e. initial state).
Delay int? Debounce delay in milliseconds. Default is 300 ms.
DropdownOffset ValueTuple<int, int> Offset between the dropdown and the input.
Enabled bool Allows you to disable the input. The default is true.
InputCssClass string Additional CSS classes for the search box input.
InputGroupCssClass string Custom CSS class to render with the input-group span.
InputGroupEndTemplate RenderFragment Input-group at the end of the input.
Hides the search icon when used!
InputGroupEndText string Input-group at the end of the input.
Hides the search icon when used!
InputGroupStartTemplate RenderFragment Input-group at the beginning of the input.
InputGroupStartText string Input-group at the beginning of the input.
InputSize InputSize? Input size of the input field.
ItemCssClass string Additional CSS classes for the items in the dropdown menu.
ItemIconSelector Func<TItem, IconBase> Selector to display the icon from the data item.
ItemSelectionBehavior SearchBoxItemSelectionBehavior? Behavior when the item is selected.
ItemSubtitleSelector Func<TItem, string> Selector to display the item subtitle from the data item.
ItemTemplate RenderFragment<TItem> Template for the item content.
ItemTitleSelector Func<TItem, string> Selector to display the item title from the data item.
Label string Label of the input field.
LabelType LabelType? Label type.
MinimumLength int? Minimum length to call the data provider (display any results). Default is 2.
NotFoundTemplate RenderFragment Rendered when the DataProvider doesn't return any data.
Placeholder string Placeholder text for the search input.
SearchIcon IconBase Icon of the input when no text is written.
SearchIconPlacement SearchBoxSearchIconPlacement? Placement of the search icon.
Default is SearchBoxSearchIconPlacement.End.
Settings SearchBoxSettings Set of settings to be applied to the component instance (overrides Defaults, overridden by individual parameters).
TextQuery string Text written by the user (input text).
TextQueryChanged EventCallback<string>
TextQueryItemTemplate RenderFragment<string> Template for the text-query item content (requires AllowTextQuery="true").

Event callbacks #

Name Type Description
OnHiding EventCallback<DropdownHidingEventArgs> Fired immediately when the 'hide' method of the dropdown is called. To prevent hiding, set DropdownHidingEventArgs.Cancel to true.
OnItemSelected EventCallback<TItem> Occurs when any of the suggested items (other than plain text-query) is selected.
OnTextQueryTriggered EventCallback<string> Raised when the enter key is pressed or when the text-query item is selected in the dropdown menu. (Does not trigger when AllowTextQuery is false.)

Methods #

Method Returns Description
FocusAsync() Task Gives focus to the input element.
HideDropdownAsync() Task Hides the dropdown menu.

Static properties #

Property Type Description
Defaults SearchBoxSettings Application-wide defaults for the HxSearchBox and derived components.

CSS variables #

Name Description Default
--hx-search-box-item-icon-margin Item icon margin. 0 .5rem 0 0
--hx-search-box-item-icon-font-size Item icon font-size. inherit
--hx-search-box-item-title-font-size Item title font-size. inherit
--hx-search-box-item-title-color Item title color. inherit
--hx-search-box-item-subtitle-font-size Item subtitle font-size. .75rem
--hx-search-box-item-subtitle-color Item subtitle color. var(--bs-secondary)
--hx-search-box-dropdown-menu-height Maximum height of the results dropdown menu. 300px
--hx-search-box-item-highlighted-background-color Background color of an item when highlighted. var(--bs-tertiary-bg)
--hx-search-box-input-search-icon-color Color of the search icon. unset
--hx-search-box-input-clear-icon-color Color of the clear icon. unset
--hx-search-box-dropdown-menu-width Minimal width of the results dropdown menu. 100%
An unhandled error has occurred. Reload 🗙