Combobox

The RzCombobox is a robust, autocomplete-enabled select component powered by Tom Select. It supports single and multiple selections, asynchronous loading, option grouping, rich templating, and plugin extensibility, all while maintaining native form compatibility.

Basic Single Select

A standard single-select dropdown bound to a list of strings.

Source

<RzCombobox TItem="string" TValue="string"
            Items="@_fruits"
            @bind-Value="_model.Fruit"
            For="@(() => _model.Fruit)"
            Placeholder="Pick a fruit..." />

@code {
    private List<string> _fruits = ["Apple", "Banana", "Cherry", "Date", "Elderberry", "Fig"];
}

Multiple Selection

Enable multiple selection by setting Multiple="true". The remove_button and checkbox_options plugins are automatically enabled for better UX.

Source

<RzCombobox TItem="string" TValue="IEnumerable<string>"
            Items="@_skills"
            Multiple="true"
            @bind-Value="_model.Skills"
            For="@(() => _model.Skills)" />

Binding to Objects

Bind to complex objects by specifying ValueSelector (what is stored) and TextSelector (what is displayed). Here we bind to the Id (int) of a Person object.

Source

<RzCombobox TItem="UserData" TValue="int?"
            Items="@_users"
            ValueSelector="@(u => u.Id.ToString())"
            TextSelector="@(u => u.Name)"
            @bind-Value="_model.AssigneeId" />

Option Grouping

RzCombobox natively supports SelectListItem grouping.

Source

// Setup SelectListItems with Groups
var frontendGroup = new SelectListGroup { Name = "Frontend" };
var backendGroup = new SelectListGroup { Name = "Backend" };

_groupedItems = [
    new SelectListItem("React", "react") { Group = frontendGroup },
    new SelectListItem("Vue", "vue") { Group = frontendGroup },
    new SelectListItem(".NET", "dotnet") { Group = backendGroup },
    new SelectListItem("Django", "django") { Group = backendGroup },
];

Item Creation (Tags)

Allow users to create new items on the fly by setting Create="true" in the options.

Source

<RzCombobox Items="@_tags"
            Multiple="true"
            Options="@(new ComboboxOptions { Create = true })"
            @bind-Value="_model.Tags" />

Plugins: Clear Button

Easily extend functionality using plugins. Here we add a 'Clear' button to a single-select input.

Source

private ComboboxOptions _clearButtonOptions = new()
{
    Plugins = new List<IComboboxPlugin> { new ComboboxClearButtonPlugin() }
};

Custom Templates

Customize how options and selected items are rendered using OptionTemplate and ItemTemplate. Alpine.js syntax is used within the template, with access to the item object.

Source

<EditForm Model="@_model">
    <Field>
        <Label>Select User</Label>
        <RzCombobox TItem="UserData" TValue="int?"
                    Items="@_users"
                    ValueSelector="@(u => u.Id.ToString())"
                    TextSelector="@(u => u.Name)"
                    Value="_model.AssigneeId"
                    For="@(() => _model.AssigneeId)"
                    Placeholder="Search users...">
            <OptionTemplate>
                <div class="flex items-center gap-3 py-1">
                    <div class="flex items-center justify-center size-8 rounded-full bg-secondary text-secondary-foreground">
                        <RzAvatar Size="Size.Small">
                            <AvatarImage :src="item.photo"/>
                        </RzAvatar>
                    </div>
                    <div class="flex flex-col">
                        <span class="font-medium text-sm" x-text="item.name"></span>
                        <span class="text-xs text-muted-foreground" x-text="item.email"></span>
                    </div>
                </div>
            </OptionTemplate>
        </RzCombobox>
    </Field>
</EditForm>

Max Items Limit

Restrict the number of selections in multi-select mode. Here, you can only select up to 2 items.

Component Parameters

The following table summarizes the core parameters on RzCombobox<TItem, TValue>.

Property	Description	Type	Default
`Items`	Data source used to populate options.	`IEnumerable<TItem>`	`Empty`
`Options`	Tom Select configuration options.	`ComboboxOptions`	`new()`
`Multiple`	Enables multi-select mode.	`bool`	`false`
`Placeholder`	Placeholder text shown when no value is selected.	`string?`	`Localized default`
`ValueSelector`	Maps an item to the stored option value.	`Func<TItem, string>?`	`Auto for SelectListItem`
`TextSelector`	Maps an item to display text.	`Func<TItem, string>?`	`Auto for SelectListItem`
`OptionTemplate`	Custom template for dropdown options.	`RenderFragment?`	`null`
`ItemTemplate`	Custom template for selected item rendering.	`RenderFragment?`	`null`

Alpine API

The combobox client behavior is provided by Alpine x-data component rzCombobox.

Method	Parameters	Description
`initTomSelect`	`None`	Creates and configures the Tom Select instance.