Forms

TwAutocomplete

TwAutocomplete is a Blazor autocomplete component. Filter suggestions as you type, search a server with SearchFunc, and bind the chosen SelectedValue.

Last updated 19 October 2026

Please be aware this component is new, may have bugs and/or be subject to change. Please report any bugs at https://github.com/twblazor/twblazor/issues.

Basic usage

Bind SelectedValue and pass the options in Values. Typing opens a list of the options that contain the typed text. Pick one with the mouse, or with the arrow keys and Enter. The list shares its look with TwSelect, and Variant switches between the default, filled and outlined styles.

Country

RAZOR

<div class="flex flex-col lg:flex-row gap-4">
    <TwAutocomplete T="string"
                    Label="Country"
                    Values="@_countries"
                    Placeholder="Start typing a country..."
                    @bind-SelectedValue="@country"
                    RootClass="flex-1" />

    <TwAutocomplete T="string"
                    Label="Country"
                    Values="@_countries"
                    Variant="InputVariant.Filled"
                    @bind-SelectedValue="@country"
                    RootClass="flex-1" />

    <TwAutocomplete T="string"
                    Label="Country"
                    Values="@_countries"
                    Variant="InputVariant.Outlined"
                    @bind-SelectedValue="@country"
                    RootClass="flex-1" />
</div>

@if (!string.IsNullOrEmpty(country))
{
    <p class="mt-3 text-sm text-gray-600 dark:text-gray-400">Selected country: <strong>@country</strong></p>
}

CSHARP

@code {
    private string? country;
    
    private readonly string[] _countries =
    [
        "Australia", "Austria", "Belgium", "Brazil", "Canada", "Denmark", "France", "Germany", "Ireland",
        "Italy", "Japan", "Netherlands", "New Zealand", "Norway", "Portugal", "Spain", "Sweden",
        "Switzerland", "United Kingdom", "United States"
    ];
}

Choosing a value

Only an option from the list can be selected. When focus leaves the field, text that matches an option in full (ignoring case) selects it, and any other text is replaced by the selected option's text. Emptying the field clears the selection, setting SelectedValue back to its default, such as null, unless the field is Required.

Filter mode

Set FilterMode to AutocompleteFilterMode.StartsWith to list only the options that start with the typed text. The default, Contains, matches anywhere. Matching ignores case and accents, so "cafe" finds "Café".

Fruit

RAZOR

<TwAutocomplete T="string"
                Label="Fruit"
                Values="@_fruits"
                FilterMode="AutocompleteFilterMode.StartsWith"
                @bind-SelectedValue="@fruit" />

CSHARP

@code {
    private string? fruit;
    
    private readonly string[] _fruits = ["Apple", "Apricot", "Banana", "Blackberry", "Cherry", "Grape", "Mango", "Pineapple"];
}

Complex objects and item templates

Use PropertyName to show, and match against, one property of a complex object. Add an ItemTemplate to draw each suggestion your own way.

The field always shows the display text

Unlike TwSelect, the autocomplete never switches to the browser's native picker on iOS or Android, so the template is used for the suggestions on every device, and PreferNativePicker has no effect. The text field can only hold text, though: once an option is chosen it shows that option's display text from PropertyName, or ToString() when no property is named, and typing is matched against that text rather than what the template draws.

Team member

RAZOR

<TwAutocomplete T="Person"
                Label="Team member"
                Values="@_people"
                PropertyName="Name"
                @bind-SelectedValue="@person">
    <ItemTemplate>
        <span class="flex flex-col">
            <span>@context.Name</span>
            <span class="text-xs text-gray-600 dark:text-gray-400">@context.Role</span>
        </span>
    </ItemTemplate>
</TwAutocomplete>

@if (person is not null)
{
    <p class="mt-3 text-sm text-gray-600 dark:text-gray-400">Selected: <strong>@person.Name</strong>, @person.Role</p>
}

CSHARP

@code {
    private Person? person;
    
    private readonly Person[] _people =
    [
        new("Ada Lovelace", "Engineer"),
        new("Alan Turing", "Researcher"),
        new("Grace Hopper", "Architect"),
        new("Margaret Hamilton", "Lead")
    ];
    
    private sealed record Person(string Name, string Role);
}

Server side search

Set SearchFunc to fetch suggestions yourself, such as from an API. It is given the typed text and a CancellationToken that is cancelled when the user types again, so a slow search never overwrites newer results. DebounceInterval waits for a pause in typing before searching, and MinCharacters keeps the list closed until enough has been typed. "Loading..." is shown while a search runs.

City

RAZOR

<TwAutocomplete T="string"
                Label="City"
                SearchFunc="@SearchCitiesAsync"
                DebounceInterval="300"
                MinCharacters="2"
                Placeholder="Type at least two letters..."
                @bind-SelectedValue="@city" />

CSHARP

@code {
    private string? city;
    
    private static readonly string[] _cities =
    [
        "Aberdeen", "Bath", "Belfast", "Birmingham", "Brighton", "Bristol", "Cambridge", "Cardiff", "Edinburgh",
        "Glasgow", "Leeds", "Liverpool", "London", "Manchester", "Newcastle", "Norwich", "Oxford", "York"
    ];
    
    private static async Task<IEnumerable<string>> SearchCitiesAsync(string query, CancellationToken cancellationToken)
    {
        // Stands in for a call to your API.
        await Task.Delay(400, cancellationToken);
        return _cities.Where(c => c.Contains(query, StringComparison.OrdinalIgnoreCase));
    }
}

Clearable, max items and no results text

Set Clearable for a button that empties the field and clears the selection. MaxItems caps how many suggestions are listed, and NoResultsText replaces the "No results" message.

Programming language

RAZOR

<TwAutocomplete T="string"
                Label="Programming language"
                Values="@_languages"
                Clearable
                MaxItems="5"
                NoResultsText="No matching language"
                @bind-SelectedValue="@language" />

CSHARP

@code {
    private string? language = "C#";
    
    private readonly string[] _languages =
    [
        "C", "C#", "C++", "Dart", "F#", "Go", "Java", "JavaScript", "Kotlin", "PHP", "Python", "Ruby", "Rust",
        "Scala", "Swift", "TypeScript"
    ];
}

Dense, required, disabled and read only

Set Dense for a more compact field. Required marks the field as required, Disabled turns it off, and ReadOnly keeps it focusable while stopping it from changing.

Dense

Required

Disabled

Read only

RAZOR

<div class="grid gap-4 sm:grid-cols-2">
    <TwAutocomplete T="string" Label="Dense" Values="@_countries" Dense @bind-SelectedValue="@denseCountry" />
    <TwAutocomplete T="string" Label="Required" Values="@_countries" Required @bind-SelectedValue="@requiredCountry" />
    <TwAutocomplete T="string" Label="Disabled" Values="@_countries" SelectedValue="@("France")" Disabled />
    <TwAutocomplete T="string" Label="Read only" Values="@_countries" SelectedValue="@("Germany")" ReadOnly />
</div>

Accessibility

The field follows the WAI-ARIA combobox pattern with list autocomplete. It has the combobox role with aria-autocomplete="list", aria-expanded and aria-controls, and focus never leaves it: the highlighted suggestion is exposed through aria-activedescendant, so you can keep typing while you browse. Each suggestion is an option in a labelled listbox, with aria-selected on the chosen one, and a polite live region announces how many suggestions are available as they change. The chevron and clear buttons are left out of the Tab order, as the APG pattern recommends.

Focus stays in the text field while you move through the suggestions, so you can keep typing to narrow them down. Typing opens the list.

Key	What it does
`Arrow Down` or `Arrow Up`	Opens the list and highlights the first or last suggestion. With the list open, moves to the next or previous suggestion, wrapping at the ends.
`Alt` plus `Arrow Down`	Opens the list without highlighting a suggestion.
`Enter`	Selects the highlighted suggestion, puts its text in the field and closes the list.
`Escape`	Closes the list. Focus stays in the field.
`Home` or `End`	Moves the cursor to the start or end of the text.
`Tab`	Leaves the field. Text that matches no suggestion is replaced by the selected value's text, and emptying the field clears the selection.

Theme configuration

Styling is controlled by TwBlazorTheme.Components (a TwInputTheme), configured via the AddTwBlazor() options callback described on the Get Started page. Every property is a set of Tailwind classes, so changes are picked up by your own Tailwind build.

Inherited from TwTextfield - this component reuses that theme rather than defining its own.

Property	Type	Controls
`DefaultInputVariant`	InputVariant
`TextfieldBase`	string
`SelectBase`	string
`Size`	string
`DenseSize`	string
`MultilineSize`	string
`MultilineDenseSize`	string
`MultilineResize`	string
`MultilineAutoGrow`	string
`FieldWrapper`	string
`FieldStartContent`	string
`FieldEndContent`	string
`ClearablePadding`	string
`ClearButton`	string
`ClearButtonIcon`	string
`SelectOption`	string
`SelectNativeBackground`	string
`SelectDefaultPadding`	string
`SelectReadOnlyBackground`	string
`SelectMultiTriggerLayout`	string
`SelectNativeMultiOverlay`	string
`SelectMultiOpenButton`	string
`SelectPanelPosition`	string
`SelectPanelSurface`	string
`SelectPanelItemText`	string
`SelectCustomTrigger`	string
`SelectCustomPlaceholder`	string
`SelectCustomChevron`	string
`SelectCustomChevronOpen`	string
`SelectCustomListbox`	string
`SelectCustomOption`	string
`SelectCustomCheck`	string
`SelectMultiTriggerBase`	string
`SelectMultiChevron`	string
`SelectMultiChipsPadding`	string
`LabelBase`	string
`InputLegendBase`	string
`OutlinedBorder`	string
`FilledBorder`	string
`FocusBorder`	string
`FocusVisibleBorder`	string
`FocusWithinBorder`	string
`FilledBackgroundColor`	string
`ErrorMessage`	string

Full reference: TwInputTheme on the API docs.

TwAutocomplete

Basic usage

Choosing a value

Filter mode

Complex objects and item templates

Server side search

Clearable, max items and no results text

Dense, required, disabled and read only

Accessibility

Keyboard navigation

Theme configuration