HxAutosuggest #

Component for single item selection with dynamic suggestions (based on typed characters).

HxAutosuggest component is similar to HxSearchBox component, but it is designed to be used in forms.

  • HxAutosuggest supports validation,
  • HxAutosuggest supports Value-binding to the model,
  • HxAutosuggest supports HxFormState,
  • HxAutosuggest does not support free-text queries.

Basic usage #

Selected employee ID: 1

@inject IDemoDataService DemoDataService

<HxAutosuggest Label="Employee"
			   Placeholder="Start typing to search by name"
			   TItem="EmployeeDto"
			   TValue="int?"
			   @bind-Value="@selectedEmployeeId"
			   DataProvider="ProvideSuggestions"
			   ValueSelector="employee => employee.Id"
			   TextSelector="employee => employee.Name"
			   ItemFromValueResolver="ResolveAutosuggestItemFromValue">
	<EmptyTemplate>
		<span class="p-2">Couldn't find any matching employee</span>
	</EmptyTemplate>
</HxAutosuggest>

<p class="mt-3">Selected employee ID: @selectedEmployeeId</p>

@code
{
	private int? selectedEmployeeId = 1;

	private async Task<AutosuggestDataProviderResult<EmployeeDto>> ProvideSuggestions(AutosuggestDataProviderRequest request)
	{
		var matchingEmployees = await DemoDataService.FindEmployeesByNameAsync(request.UserInput, limitCount: 10, request.CancellationToken);

		return new AutosuggestDataProviderResult<EmployeeDto> { Data = matchingEmployees };
	}

	private async Task<EmployeeDto> ResolveAutosuggestItemFromValue(int? value)
	{
		if (value is null)
		{
			return null;
		}

		return await DemoDataService.GetEmployeeByIdAsync(value.Value);
	}
}

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

Initial suggestions #

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

Selected employee ID:

API #

Parameters #

Name Type Description
AdditionalAttributes IReadOnlyDictionary<string, object> A collection of additional attributes that will be applied to the created element.
ChipTemplate RenderFragment The chip template.
ClearIcon IconBase Icon displayed in the input on the selection clear button when an item is selected.
CssClass string The custom CSS class to render with the wrapping div.
DataProvider AutosuggestDataProviderDelegate<TItem> Method (delegate) that provides data for the suggestions.
Delay int? The debounce delay in milliseconds.
DisplayName string Gets or sets the display name for this field.
This value is used when generating error messages when the input value fails to parse correctly.
EmptyTemplate RenderFragment Template to display when items are empty.
Enabled bool? When null (default), the Enabled value is received from the cascading FormState. When the value is false, the input is rendered as disabled. To set multiple controls as disabled, use HxFormState.
GenerateChip bool When true, HxChipGenerator is used to generate chip item(s). The default is true.
Hint string The hint to render after the input as form-text.
HintTemplate RenderFragment The hint to render after the input as form-text.
InputCssClass string The custom CSS class to render with the input element.
InputGroupEndTemplate RenderFragment The input-group at the end of the input.
Hides the search icon when used!
InputGroupEndText string The input-group at the end of the input.
Hides the search icon when used!
InputGroupStartTemplate RenderFragment The input-group at the beginning of the input.
InputGroupStartText string The input-group at the beginning of the input.
InputSize InputSize? The size of the input.
ItemFromValueResolver Func<TValue, Task<TItem>> Returns the corresponding item for the (selected) value.
ItemTemplate RenderFragment<TItem> Template to display an item. When not set, TextSelector is used.
Label string The label text.
LabelCssClass string The custom CSS class to render with the label.
LabelTemplate RenderFragment The label content.
LabelType LabelType? Label type.
MinimumLength int? The minimal number of characters to start suggesting.
Placeholder string A short hint displayed in the input field before the user enters a value.
SearchIcon IconBase Icon displayed in the input when no item is selected.
Settings AutosuggestSettings Set of settings to be applied to the component instance (overrides Defaults, overridden by individual parameters).
TextSelector Func<TItem, string> Selects the text to display from an item. When not set, ToString() is used.
ValidationMessageMode ValidationMessageMode? Specifies how the validation message should be displayed.
The default is ValidationMessageMode.Regular, you can override the application-wide default for all inputs in Defaults.
Value TValue Value of the input. This should be used with two-way binding.
ValueChanged EventCallback<TValue> A callback that updates the bound value.
ValueExpression Expression<Func<TValue>> An expression that identifies the bound value.
ValueSelector Func<TItem, TValue> Selects a value from an item. Not required when TValue is the same as TItem.

Methods #

Method Returns Description
FocusAsync() ValueTask Gives focus to the input element.

Static properties #

Property Type Description
Defaults AutosuggestSettings Application-wide defaults for the HxAutosuggest and derived components.

CSS variables #

Name Description Default
--hx-autosuggest-input-close-icon-opacity Opacity of the close icon. .25
--hx-autosuggest-item-highlighted-background-color When HxAutosuggest.HighlightFirstSuggestion is true, the first item receives this background color. var(--bs-tertiary-bg)
--hx-autosuggest-dropdown-menu-height Maximum height of the results dropdown menu. 300px
--hx-autosuggest-dropdown-menu-width Width of the results dropdown menu. 100%
An unhandled error has occurred. Reload 🗙