LgSuggestBox

LgSuggestBox is a text field that offers suggestions during input: matching values are displayed in a dropdown menu and the retained value remains free-form input (selecting a suggestion is optional). Suggestions come from a local list (Items) or a remote controller (ControllerUri).

<LgSuggestBox Label="#City" Items="_cities" @bind-Value="_model.City" />

• Namespace : Lagoon.UI.Components
• Inherits from : LgSuggestBoxBase<string> → LgTextBox → LgInputRenderBase<string> → LgInputBase<string> → LgAriaComponentBase → LgComponentBase
• Interfaces : ILgDropDownComponent
• NuGet Package : Lagoon.UI

Suggestion or selection?

LgSuggestBox accepts a free value; suggestions are only an input aid. To constrain the value to a closed list, use LgSelect.

Usage

Demo

Try this component in the Lagoon showcase.

Local suggestions

Items provides the list of proposed values. The entered text filters the list (default Contains mode) and the menu only opens if there are results.

CityPage.razor

<LgSuggestBox Label="#City"
              Items="_cities"
              Placeholder="#TypeCityName"
              @bind-Value="_model.City" />

CityPage.razor.cs

public partial class CityPage : LgPage
{
    // Suggested values: input remains free, the list is only an aid.
    private readonly List<string> _cities = new() { "Paris", "Lyon", "Marseille", "Toulouse", "Nantes" };

    private readonly CityVm _model = new();

    private sealed class CityVm
    {
        public string City { get; set; }
    }
}

Remote suggestions with ControllerUri

For a large or server-dependent list, ControllerUri points to a queryable action: the component automatically posts a data request to {ControllerUri}/$qd with the entered text, filter, and pagination.

SupplierPage.razor

<LgSuggestBox Label="#Supplier"
              ControllerUri="api/suppliers/names"
              MinSearchCharacter="2"
              SeeAllEnabled="true"
              @bind-Value="_model.Supplier" />

SupplierPage.razor.cs

public partial class SupplierPage : LgPage
{
    private readonly SupplierVm _model = new();

    private sealed class SupplierVm
    {
        public string Supplier { get; set; }
    }
}

Endpoint contract

ControllerUri points to a queryable action. The component calls {ControllerUri}/$qd in POST via the Lagoon remote loader; the source action remains exposed in GET and decorated with [Queryable].

GET + POST $qd — Suggestion search (ControllerUri)

SuppliersController.cs

[ApiController]
[Route("api/suppliers")]
public class SuppliersController : LgControllerBase
{
    private readonly ApplicationDbContext _db;

    public SuppliersController(ApplicationDbContext db)
    {
        _db = db;
    }

    [HttpGet("names")]
    [Queryable]
    public IQueryable<string> GetNames()
    {
        // Returns IQueryable<string> to allow [Queryable] to apply the search text,
        // pagination, and sorting sent by the component.
        return _db.Suppliers.Select(s => s.Name);
    }
}

Filtering, collation, and result count

FilterTextSearchMode, TextFilterCollation, MinSearchCharacter and MaxItemsInView adjust search behavior. HighlightText highlights found text in results and SeeAllEnabled adds a "See all" button when more results are available than MaxItemsInView.

ProductPage.razor

<LgSuggestBox Label="#Product"
              Items="_products"
              FilterTextSearchMode="FilterTextSearchMode.StartsWith"
              TextFilterCollation="CollationType.IgnoreCaseAndAccent"
              MinSearchCharacter="1"
              MaxItemsInView="10"
              HighlightText="true"
              @bind-Value="_model.Product" />

ProductPage.razor.cs

public partial class ProductPage : LgPage
{
    private readonly List<string> _products = new() { "Écrou M6", "Écrou M8", "Vis M6", "Vis M8", "Rondelle M6" };

    private readonly ProductVm _model = new();

    private sealed class ProductVm
    {
        public string Product { get; set; }
    }
}

Customize suggestion rendering

ItemContent replaces the default rendering of a suggestion. With HighlightText, add the highlightable class to the element containing the text to highlight.

AccountPage.razor

<LgSuggestBox Label="#Account" Items="_accounts" HighlightText="true" @bind-Value="_model.Account">
    <ItemContent Context="item">
        <LgIcon IconName="@IconNames.All.PersonFill" />
        <span class="highlightable">@item</span>
    </ItemContent>
</LgSuggestBox>

AccountPage.razor.cs

public partial class AccountPage : LgPage
{
    private readonly List<string> _accounts = new() { "compta-fournisseurs", "compta-clients", "banque" };

    private readonly AccountVm _model = new();

    private sealed class AccountVm
    {
        public string Account { get; set; }
    }
}

Properties

All [Parameter] properties of the component, including inherited ones.

Name	Type	Default	Declared in	Description
ControllerUri	string	null	LgSuggestBoxBase<TItem>	URI of the controller used to load suggestions remotely.
DropDownMaxHeight	int	-1	LgSuggestBoxBase<TItem>	Maximum height of the dropdown menu, in pixels. -1 uses available space.
FilterTextSearchMode	FilterTextSearchMode	Contains	LgSuggestBoxBase<TItem>	Comparison mode used to filter the search text.
HighlightText	bool	false	LgSuggestBoxBase<TItem>	Highlights found text in the displayed suggestions.
ItemContent	RenderFragment<string>	null	LgSuggestBoxBase<TItem>	Custom template to render a suggestion.
Items	IEnumerable<string>	null	LgSuggestBoxBase<TItem>	Local source of suggestions.
MaxItemsInView	int	8	LgSuggestBoxBase<TItem>	Maximum number of suggestions displayed. 0 displays all results.
MinSearchCharacter	int	0	LgSuggestBoxBase<TItem>	Minimum number of characters before starting the search.
SeeAllEnabled	bool	false	LgSuggestBoxBase<TItem>	Displays a "See all" button when more results are available than MaxItemsInView.
TextFilterCollation	CollationType?	null	LgSuggestBoxBase<TItem>	Case and accent sensitivity. If null, the application behavior configuration applies.
AllowResize	bool	false	LgTextBox	Allows resizing when TextMode is TextBoxMode.Multiline.
AutoComplete	bool	false	LgTextBox	Enables browser autocomplete if true; otherwise the autocomplete="off" attribute is rendered.
AutoUnmask	bool	false	LgTextBox	Returns the value without the mask when InputMask is used.
ClearIncomplete	bool	false	LgTextBox	Clears the value if the input mask is incomplete.
DataList	List<string>	null	LgTextBox	List of values used to render a datalist associated with the input.
InputMask	string	null	LgTextBox	Input mask applied to the text field.
InputMaskKind	InputMaskKind	None	LgTextBox	Type of input mask.
InputMaskPlaceholder	string	null	LgTextBox	Character filling the empty positions of the input mask (for example # with the mask 99-99-99-99-99 displays ##-##-##-##-##). Not to be confused with Placeholder. Without a value, the mask's default character (_) is retained.
MaxLength	int?	null	LgTextBox	Maximum number of characters.
MaxRows	int?	null	LgTextBox	Maximum number of rows when TextMode is TextBoxMode.Multiline.
MinRows	int?	null	LgTextBox	Minimum number of rows when TextMode is TextBoxMode.Multiline.
OnChangeDisabled	bool	false	LgTextBox	Disables the native onchange handler of the field.
OnChangingAsync	Func<ChangingEventArgs<string>, Task>	null	LgTextBox	Callback called before value change; the change can be cancelled here.
OnFocus	EventCallback<FocusEventArgs>	—	LgTextBox	Callback called on focus (also triggers initial search).
OnInput	EventCallback<ChangeEventArgs>	—	LgTextBox	Callback called on input (oninput), used by the search.
OnKeyUp	EventCallback<KeyboardEventArgs>	—	LgTextBox	Callback called on key release.
Placeholder	string	null	LgTextBox	Placeholder text displayed when the field is empty. Distinct from InputMaskPlaceholder.
Rows	int?	null	LgTextBox	Number of rows when TextMode is TextBoxMode.Multiline.
TextMode	TextBoxMode?	null	LgTextBox	Text field mode. null renders a simple text field.
Prefix	string	null	LgInputRenderBase	Prefix displayed in the field.
PrefixType	InputLabelType	Text	LgInputRenderBase	Nature of the prefix.
Suffix	string	null	LgInputRenderBase	Suffix displayed in the field.
SuffixType	InputLabelType	Text	LgInputRenderBase	Nature of the suffix.
AdditionalAttributes	IReadOnlyDictionary<string, object>	null	LgInputBase	Additional HTML attributes applied to the rendered element.
AutoFocus	bool	false	LgInputBase	Gives focus to the field on first render.
ConfirmationMessage	string	null	LgInputBase	Confirmation message displayed before applying a value change.
Container	IInputContainer<string>	null	LgInputBase	Internal use: attaches a GridView cell to the field.
CssClass	string	null	LgInputBase	Additional CSS classes.
Disabled	bool	false	LgInputBase	Disables the field.
DisplayName	string	null	LgInputBase	Field name used in error messages.
HideValidationMessage	bool	false	LgInputBase	Hides the validation message below the field.
Label	string	null	LgInputBase	Field label.
LabelContent	RenderFragment	null	LgInputBase	Custom content of the label area.
OnChange	EventCallback<ChangeEventArgs>	—	LgInputBase	Callback called after value change.
OnReset	EventCallback<ChangeEventArgs>	—	LgInputBase	Callback called when the field is reset by the clear button.
PolicyEdit	string	null	LgInputBase	Policy required to edit the field.
PolicyVisible	string	null	LgInputBase	Policy required to display the field.
ReadOnly	bool	false	LgInputBase	Displays the field as read-only.
Required	bool?	null	LgInputBase	Required field. If null, inferred from the [Required] attribute of the bound property.
ResetButton	bool?	null	LgInputBase	Displays the clear button. If null, the application behavior configuration applies.
ResetText	string	null	LgInputBase	Clear button text.
ResetTextAriaLabel	string	null	LgInputBase	Accessible label (aria-label) of the clear button.
Tooltip	string	null	LgInputBase	Tooltip.
TooltipIsHtml	bool	false	LgInputBase	Indicates if the Tooltip content is in HTML format (otherwise plain text).
Value	string	null	LgInputBase	Bound value (@bind-Value).
ValueChanged	EventCallback<string>	—	LgInputBase	Update callback for the bound value.
ValueExpression	Expression<Func<string>>	—	LgInputBase	Expression identifying the bound property.
AriaLabel	string	null	LgAriaComponentBase	Value of the aria-label attribute.
AriaLabelledBy	string	null	LgAriaComponentBase	Value of the aria-labelledby attribute.

Cascading parameters

LgSuggestBox also consumes parameters automatically provided by ancestor components (you do not need to define them): ParentAuthorizeView (LgAuthorizeView) and the editing context of a parent LgEditForm.

Events

Event	Type	Description
OnChangingAsync	Func<ChangingEventArgs<string>, Task>	Before value change; set args.Cancel = true to cancel the change.
OnChange	EventCallback<ChangeEventArgs>	After value change (input validated or suggestion selected).
OnInput	EventCallback<ChangeEventArgs>	On input; this is also the event that triggers the search.
OnKeyUp	EventCallback<KeyboardEventArgs>	On key release.
OnFocus	EventCallback<FocusEventArgs>	On focus (triggers initial search).
OnReset	EventCallback<ChangeEventArgs>	On reset by the clear button.

Associated enumerations

The enumerations of the suggest family (FilterTextSearchMode, CollationType, InputMaskKind, TextBoxMode) are documented on the LgNavigationBox page, which shares the same base LgSuggestBoxBase.

Best practices / accessibility

• Set MinSearchCharacter to 2 or 3 with ControllerUri to limit server requests on first characters.
• The bound value remains free-form input: validate it on the model side if only suggested values are acceptable — or use LgSelect for a closed list.

Complete reference

All parameters (including inherited ones): API Reference — LgSuggestBox.

Related components

• LgSelect — selection in a closed list.
• LgTextBox — basic text field.
• LgNavigationBox — navigation search based on the same suggest family.