Combobox

Overview

Combobox is a value-selection input: the Input filters a list, and selecting an item commits its value and shows its label, kept separate from whatever text was typed to filter. It supports single or multi-select (Multiple, with chip parts for the committed values), can be controlled or uncontrolled for value, values, and open state, and self-portals its Popup to document.body, anchored to the input and flipping when space is tight.

Anatomy

@using Navius.Primitives.Components.Combobox

<NaviusCombobox Items="_options" @bind-Value="_value" TItem="string">
    <ItemTemplate Context="item">
        <NaviusComboboxItem>
            <NaviusComboboxItemIndicator />
            @item
        </NaviusComboboxItem>
    </ItemTemplate>
    <ChildContent>
        <NaviusComboboxInput />
        <NaviusComboboxPortal>
            <NaviusComboboxPositioner>
                <NaviusComboboxPopup>
                    <NaviusComboboxList />
                    <NaviusComboboxEmpty />
                </NaviusComboboxPopup>
            </NaviusComboboxPositioner>
        </NaviusComboboxPortal>
    </ChildContent>
</NaviusCombobox>

Root

Owns the filtered collection, the open state, and the selected value(s). Generic over the item type TItem (items are the values). Cascades the Combobox context. Renders no DOM of its own.

Prop	Type	Default	Description
`Items`	`IReadOnlyList<TItem>`	`[]`	The full item set to filter. Items are the values.
`Value`	`TItem?`	-	Single-select committed value. Pair with `ValueChanged` (`@bind-Value`).
`ValueChanged`	`EventCallback<TItem?>`	-	Fires when the controlled `Value` should change.
`Multiple`	`bool`	`false`	Enables multi-select (chips): toggling a value keeps the popup open.
`Values`	`IReadOnlyList<TItem>`	`[]`	Multi-select committed values. Pair with `ValuesChanged` (`@bind-Values`).
`ValuesChanged`	`EventCallback<IReadOnlyList<TItem>>`	-	Fires when the controlled `Values` should change.
`InputValue`	`string?`	-	The filter text (not the value). Pair with `InputValueChanged` (`@bind-InputValue`) to control it.
`InputValueChanged`	`EventCallback<string?>`	-	Fires when the controlled `InputValue` should change.
`Open`	`bool`	`false`	Controlled open state. Pair with `OpenChanged` (`@bind-Open`).
`OpenChanged`	`EventCallback<bool>`	-	Fires when the controlled `Open` should change.
`DefaultOpen`	`bool`	`false`	Initial open state when used uncontrolled.
`ItemToString`	`Func<TItem, string>?`	-	Projects an item to its display/match text. Defaults to `item?.ToString()`.
`Filter`	`Func<TItem, string, bool>?`	-	Predicate `(item, query) => keep`. Defaults to a case-insensitive substring match; an empty query shows all items.
`ItemTemplate`	`RenderFragment<TItem>?`	-	Per-row template. When null, the List renders the item’s text in a default item.
`ChipTemplate`	`RenderFragment<TItem>?`	-	Per-chip template for `Multiple`. When null, a default chip (label + remove) renders per value.
`Disabled`	`bool`	`false`	Disables the input.
`ReadOnly`	`bool`	`false`	Makes the input read-only.
`Placeholder`	`string?`	-	Placeholder text.
`Dir`	`string?`	-	`"ltr"` or `"rtl"`. Cascaded to the popup and the arrow-key mapping. Falls back to the cascaded direction.
`ChildContent`	`RenderFragment?`	-	The combobox’s parts.

Input

The filter field. Typing filters the list; the committed value stays separate. Also acts as the trigger/anchor for the popup. Renders an input.

Prop	Type	Default	Description
`Placeholder`	`string?`	-	Placeholder text.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `input`.

Portal

Records a custom mount container and keep-mounted flag into the context; the Popup performs the actual teleport. Renders no DOM of its own.

Prop	Type	Default	Description
`Container`	`string?`	-	CSS selector for the mount target. `null` uses `document.body`.
`KeepMounted`	`bool`	`false`	Keeps the popup mounted while closed, for exit animations.
`ChildContent`	`RenderFragment?`	-	The Positioner and Popup.

Positioner

Owns placement (side, align, offsets, collision). Publishes the placement options into the context; the Popup renders the actual positioning div. Renders no DOM of its own.

Prop	Type	Default	Description
`Side`	`string?`	`"bottom"`	Preferred side: `"top"` \| `"right"` \| `"bottom"` \| `"left"`.
`Align`	`string?`	`"start"`	Alignment along the side: `"start"` \| `"center"` \| `"end"`.
`SideOffset`	`double`	`0`	Distance in px from the anchor along the side.
`AlignOffset`	`double`	`0`	Offset in px along the alignment axis.
`Flip`	`bool`	`true`	Flip to the opposite side on collision.
`AvoidCollisions`	`bool`	`true`	Avoid collisions with the viewport boundary.
`CollisionPadding`	`double?`	-	Padding in px between the popup and the collision boundary.
`HideWhenDetached`	`bool`	`false`	Hide the popup (`data-anchor-hidden`) when the anchor is fully clipped or detached.
`ChildContent`	`RenderFragment?`	-	The Popup.

The floating listbox surface, self-portaled and anchored to the input. Renders a div. Non-modal: it neither traps focus nor moves focus into itself on open, since focus stays in the Input (virtual focus) and the highlighted option is tracked via aria-activedescendant.

Prop	Type	Default	Description
`KeepMounted`	`bool`	`false`	Keeps the popup mounted while closed, for exit animations.
`OnCloseAutoFocus`	`EventCallback<NaviusCloseAutoFocusEventArgs>`	-	Fires when the popup closes; cancelable.
`OnEscapeKeyDown`	`EventCallback<NaviusEscapeKeyDownEventArgs>`	-	Fires on `Escape`; cancelable.
`OnPointerDownOutside`	`EventCallback<NaviusPointerDownOutsideEventArgs>`	-	Fires on pointer-down outside the popup; cancelable.
`OnFocusOutside`	`EventCallback<NaviusFocusOutsideEventArgs>`	-	Fires when focus moves outside the popup; cancelable.
`OnInteractOutside`	`EventCallback<NaviusInteractOutsideEventArgs>`	-	Fires on any outside interaction; cancelable.
`ChildContent`	`RenderFragment?`	-	The List and Empty.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `div`.

List

The listbox. Iterates the context’s filtered rows and renders each through the Root’s ItemTemplate (or a default text item). Renders a ul with role="listbox".

Prop	Type	Default	Description
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `ul`.

Item

A selectable value. Highlighted by keyboard or pointer; selecting it commits its value and, single-select, closes the popup. Its value comes from the row the List is currently rendering, not from an explicit prop. Renders a li with role="option".

Prop	Type	Default	Description
`ChildContent`	`RenderFragment?`	-	Item content.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `li`.

ItemIndicator

Renders the check glyph for a selected Item. Present only when the parent Item is selected, unless KeepMounted. Renders a span.

Prop	Type	Default	Description
`KeepMounted`	`bool`	`false`	Keeps the indicator mounted (hidden) while unselected, for CSS exit animations.
`ChildContent`	`RenderFragment?`	-	The check glyph.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `span`.

Empty

Renders only when the popup is open and there are no filtered rows (e.g. “No results”). Renders a div.

Prop	Type	Default	Description
`ChildContent`	`RenderFragment?`	-	Empty-state content.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `div`.

Data attributes

Part	Attribute	Description
Input	`data-readonly`	Present when the input is read-only.
Input	`data-disabled`	Present when the input is disabled.
Popup	`data-open`	Present while the popup is open.
Popup	`data-closed`	Present while the popup is closed (during the exit transition).
Popup	`data-starting-style`	Present at the start of the open transition.
Popup	`data-ending-style`	Present at the start of the close transition.
Popup	`data-empty`	Present when there are no filtered rows.
Popup	`data-side`	`"top"` \| `"right"` \| `"bottom"` \| `"left"`.
Popup	`data-align`	`"start"` \| `"center"` \| `"end"`.
List	`data-empty`	Present when there are no filtered rows.
Item	`data-highlighted`	Present when the item is the active (`aria-activedescendant`) option.
Item	`data-selected`	Present when the item is part of the committed value.
ItemIndicator	`data-selected`	Present when the parent item is selected.

Keyboard interactions

Key	Behavior
`ArrowDown`	Opens the list if closed; otherwise moves the highlight to the next option.
`ArrowUp`	Opens the list (highlighting the last option) if closed; otherwise moves the highlight to the previous option.
`Enter`	Selects the highlighted option; single-select closes the list.
`Home` / `PageUp`	Moves the highlight to the first option.
`End` / `PageDown`	Moves the highlight to the last option.
`Backspace`	In multi-select, when the input is empty, removes the last committed value.
`Escape`	Closes the list, keeping focus in the input.
`Tab`	Closes the list and moves focus to the next element.

ARIA mechanism

The Input renders role="combobox" with aria-expanded, aria-controls pointing at the List’s id, aria-autocomplete="list", and aria-activedescendant pointing at the highlighted option, so DOM focus never leaves the input. The List renders role="listbox" and aria-multiselectable when Multiple. Each Item renders role="option" and aria-selected. The Input ships without an accessible name; pair it with a NaviusLabel or supply an aria-label, since a placeholder is not an accessible name. This mechanism is covered by the Playwright browser test suite and gated by axe-core in CI.