Autocomplete

<NaviusAutocomplete Items="_frameworks" @bind-Value="_value" TItem="string">
    <ItemTemplate Context="framework">
        <NaviusAutocompleteItem class="... data-[highlighted]:bg-accent data-[selected]:font-medium">
            @framework
        </NaviusAutocompleteItem>
    </ItemTemplate>
    <ChildContent>
        <NaviusAutocompleteInput Placeholder="Search framework…" aria-label="Framework" class="..." />
        <NaviusAutocompletePortal>
            <NaviusAutocompletePositioner Side="bottom" Align="start" SideOffset="4">
                <NaviusAutocompletePopup class="... bg-popover shadow-md
                        data-[open]:animate-in data-[closed]:animate-out">
                    <NaviusAutocompleteList class="outline-none" />
                    <NaviusAutocompleteEmpty class="...">No frameworks found.</NaviusAutocompleteEmpty>
                </NaviusAutocompletePopup>
            </NaviusAutocompletePositioner>
        </NaviusAutocompletePortal>
    </ChildContent>
</NaviusAutocomplete>

@code {
    private string? _value;
    private static readonly string[] _frameworks =
    {
        "Next.js", "SvelteKit", "Nuxt.js", "Remix",
        "Astro", "Blazor", "SolidStart", "Qwik City",
    };
}

Features

• A compound of composable parts (Root, Input, Portal, Positioner, Popup, List, Item, Empty) you assemble and style yourself.
• Live, case-insensitive filtering with a pluggable Filter and generic Items<T>.
• Focus stays in the input; the highlight moves via aria-activedescendant; arrows never steal focus.
• Can be controlled (@bind-Value, @bind-Open) or uncontrolled (DefaultOpen).
• The Popup self-portals to document.body, stays anchored, and flips when space is tight.
• Styles off the discrete contract: data-open/data-closed on the Popup, data-highlighted/data-selected on items.

Installation

Reference the Navius.Primitives package for the headless primitive, or vendor a styled version with the CLI: navius add copies the styled zits/ui component plus the brain files it depends on.

navius add autocomplete

Anatomy

Import the parts and assemble them. The List renders the filtered Items through your ItemTemplate.

@using Navius.Primitives.Components.Autocomplete

<NaviusAutocomplete Items="_options" @bind-Value="_value" TItem="string">
    <ItemTemplate Context="item">
        <NaviusAutocompleteItem>@item</NaviusAutocompleteItem>
    </ItemTemplate>
    <ChildContent>
        <NaviusAutocompleteInput />
        <NaviusAutocompletePortal>
            <NaviusAutocompletePositioner>
                <NaviusAutocompletePopup>
                    <NaviusAutocompleteList />
                    <NaviusAutocompleteEmpty />
                </NaviusAutocompletePopup>
            </NaviusAutocompletePositioner>
        </NaviusAutocompletePortal>
    </ChildContent>
</NaviusAutocomplete>

API Reference

Root

Owns the filtered collection, the open state and the committed value. Cascades the Autocomplete context. Renders no DOM of its own.

Input

The editable text field (role=combobox). Typing filters the list and updates the value. Renders an input.

Positioner

Owns placement (side / align / offsets / collision). A flag-setter; the Popup renders the positioning element the engine anchors and writes data-side / data-align + --anchor-* onto.

Popup

The floating listbox surface, self-portaled and anchored to the input. role=listbox.

Data attributes

List

Renders one Item per filtered entry using the Root's ItemTemplate. Renders a div.

Item

A single suggestion. Highlighted by keyboard/pointer; selecting it commits its value. Renders a div with role=option.

Data attributes

Empty

Shown inside the Popup when the filter matches nothing. Renders a div.

Accessibility

Implements the combobox WAI-ARIA APG pattern (editable, list-autocomplete): the highlighted option is tracked with aria-activedescendant so DOM focus never leaves the input. This behavior is covered by the browser test suite and an axe-core WCAG gate in CI.

The Input renders role="combobox" but ships without an accessible name. Pair it with a NaviusLabel or supply an aria-label; a placeholder is not an accessible name.

Keyboard interactions