Skip to content

Lookups that search as you type

A customer out of thousands fits no dropdown. SearchFrom makes the combobox ask a service as the user types - once enough is typed and the user pauses, with a search typed past cancelled so its answer never lands over a newer one. The model only ever receives a choice.

This is an existing deal being edited: the form opened holding the id C-0042, and asked the service once for that customer, so the box shows a name rather than an id. Type two letters of a company or a city to search 2,400 customers. Text that names no customer is refused, because a search field stands for a record. The account manager searches with nothing typed at all, so the first few appear as soon as the box opens.
Live form
Deal

Type at least 2 characters to search

6 choices available

View source
@page "/search-lookup"
@inject DemoDirectory Directory

<BormView State="_state" OnValidSubmit="HandleSubmit" SubmitText="Save deal" />

@code {
    // An existing deal: the customer is stored by id.
    private readonly DealAssignment _model = new() { Title = "Renewal 2027", CustomerId = "C-0042" };
    private BormState _state = default!;

    protected override void OnInitialized()
    {
        var schema = BormBuilder.For<DealAssignment>()
            .Title("Deal")
            .Field(x => x.Title, f => f.Required())
            .Field(x => x.CustomerId, f => f.Required().SearchFrom(
                // With no text and a current value, the search is asked for the one record the id names.
                search: ctx => Directory.SearchCustomersAsync(ctx.SearchText, ctx.CurrentValue as string, ctx.CancellationToken),
                value: c => c.Id,
                label: DemoDirectory.LabelOf,
                minLength: 2,                     // nothing is asked before two characters
                debounceMilliseconds: 250))       // and only once the user pauses
            .Field(x => x.ManagerId, f => f.SearchFrom(
                search: ctx => Directory.SearchManagersAsync(ctx.SearchText, ctx.CancellationToken),
                value: m => m,
                label: m => m,
                minLength: 0))                    // the top results, before anything is typed
            .Build();

        _state = new BormState(schema, new BormModelDataAccessor(_model));
    }

    public void Dispose() => _state.Dispose();
}

How the lookup behaves

  • The service is asked once minLength characters are typed and the user pauses for debounceMilliseconds. A search typed past is cancelled through ctx.CancellationToken, and its answer never lands over a newer one. A minLength of 0 searches with empty text - "the top results".
  • A field that opens holding a value is asked once with no SearchText and the value in ctx.CurrentValue, so the box can show a name instead of a bare id. A chosen option is remembered, so its label stays after a later search no longer returns it.
  • Nothing is written to the model per keystroke - only a choice, or leaving the box. Text committed before its results arrived is searched for exactly and matched if it is a result; text that names no result is refused, and the model keeps its last value. SearchFrom(..., allowCustom: true) stores such text as typed instead.
  • A submit, or a wizard's Next, pressed while that search is out waits for its answer rather than sending the value from before. Until enough is typed the box tells assistive technology how much is needed; then how many results there are.
  • For a control of your own, state.SearchOptionsAsync(field, path, text) runs the same search and state.TrackEntryAsync(task) makes a submit wait for an entry still being committed.

A search provider is code, so it is not exported to JSON Schema; check the chosen id on the server, where the same lookup lives. For a list short enough to load whole, use OptionsFrom and a combobox.

An unhandled error has occurred. Reload 🗙