Components / Select

Select

Displays a list of options for the user to pick from, triggered by a button.

razor

<NaviusSelect @bind-Value="_value">
    <NaviusSelectTrigger class="... data-[placeholder]:text-muted-foreground">
        <NaviusSelectValue Placeholder="Select a food…" />
        <NaviusSelectIcon />
    </NaviusSelectTrigger>

    <NaviusSelectPositioner>
        <NaviusSelectPopup class="... bg-popover text-popover-foreground shadow-md"
                           style="width: var(--anchor-width);">
            <NaviusSelectViewport class="max-h-72 overflow-y-auto p-1">
                <NaviusSelectGroup>
                    <NaviusSelectLabel class="... text-muted-foreground">Fruits</NaviusSelectLabel>
                    <NaviusSelectItem Value="apple"
                        class="... pl-8 data-[highlighted]:bg-accent">
                        <span class="absolute left-2">
                            <NaviusSelectItemIndicator>✓</NaviusSelectItemIndicator>
                        </span>
                        <NaviusSelectItemText Text="Apple">Apple</NaviusSelectItemText>
                    </NaviusSelectItem>
                    <NaviusSelectItem Value="banana">
                        <NaviusSelectItemText Text="Banana">Banana</NaviusSelectItemText>
                    </NaviusSelectItem>
                </NaviusSelectGroup>

                <NaviusSelectSeparator class="-mx-1 my-1 h-px bg-border" />

                <NaviusSelectGroup>
                    <NaviusSelectLabel class="... text-muted-foreground">Vegetables</NaviusSelectLabel>
                    <NaviusSelectItem Value="carrot" Disabled="true">
                        <NaviusSelectItemText Text="Carrot">Carrot</NaviusSelectItemText>
                    </NaviusSelectItem>
                </NaviusSelectGroup>
            </NaviusSelectViewport>
        </NaviusSelectPopup>
    </NaviusSelectPositioner>
</NaviusSelect>

@code { private string? _value; }

Features

Can be controlled (@bind-Value / @bind-Open) or uncontrolled (DefaultValue / DefaultOpen).
Full keyboard navigation with type-ahead and a roving listbox focus.
The listbox is portaled to <body> and collision-aware via the positioner engine.
Supports items, groups, labels, separators, a scrollable viewport, and an optional arrow.
The trigger shows the selected item's label (not the raw value key).
Renders a hidden native mirror so the select participates in form submission.
Multi-select (Multiple="true") keeps the listbox open and toggles values into a set.
role="combobox" trigger and role="listbox" content per the APG.

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.

Terminal bash

navius add select

Anatomy

Import the parts and assemble them.

razor

@using Navius.Primitives.Components.Select

<NaviusSelect>
    <NaviusSelectTrigger>
        <NaviusSelectValue />
        <NaviusSelectIcon />
    </NaviusSelectTrigger>

    <NaviusSelectPositioner>
        <NaviusSelectPopup>
            <NaviusSelectScrollUpButton />
            <NaviusSelectViewport>
                <NaviusSelectItem Value="...">
                    <NaviusSelectItemText />
                    <NaviusSelectItemIndicator />
                </NaviusSelectItem>

                <NaviusSelectGroup>
                    <NaviusSelectLabel />
                    <NaviusSelectItem Value="..." />
                </NaviusSelectGroup>

                <NaviusSelectSeparator />
            </NaviusSelectViewport>
            <NaviusSelectScrollDownButton />
            <NaviusSelectArrow />
        </NaviusSelectPopup>
    </NaviusSelectPositioner>
</NaviusSelect>

API Reference

Root

Owns the value and open state and cascades the context. Renders no visible DOM (plus an optional visually-hidden form mirror).

Prop	Type	Default
Value	string?	-
ValueChanged	EventCallback<string?>	-
DefaultValue	string?	-
Multiple	bool	false
Values	IReadOnlyList<string>	[]
ValuesChanged	EventCallback<IReadOnlyList<string>>	-
DefaultValues	IReadOnlyList<string>?	-
Open	bool	false
OpenChanged	EventCallback<bool>	-
DefaultOpen	bool	false
Placeholder	string?	-
Disabled	bool	false
Name	string?	-
Required	bool	false
Dir	string?	-
ChildContent	RenderFragment?	-

Trigger

The button that opens the listbox. Renders a button with role=combobox.

Prop	Type	Default
ChildContent	RenderFragment?	-
Attributes	IDictionary<string, object>?	-

Data attributes

Data attribute	Values
[data-popup-open]	Present while the listbox is open.
[data-disabled]	Present when the root is disabled
[data-placeholder]	Present when no value is selected
[data-multiple]	Present when the root is a multi-select

Value

Shows the selected item's label, or the placeholder when nothing is selected. Renders a span.

Prop	Type	Default
Placeholder	string?	-
ChildContent	RenderFragment?	-
Attributes	IDictionary<string, object>?	-

Data attributes

Data attribute	Values
[data-placeholder]	Present when no value is selected

Icon

A decorative affordance (chevron) inside the trigger. Renders a span.

Prop	Type	Default
ChildContent	RenderFragment?	-
Attributes	IDictionary<string, object>?	-

Portal

Teleports the listbox into document.body (or Container). Renders no DOM of its own.

Prop	Type	Default
Container	string?	document.body
KeepMounted	bool	false
ChildContent	RenderFragment?	-

Positioner

Owns placement (side / align / offsets / collision). A flag-setter that publishes the placement options; the Popup renders the positioning element the engine anchors to the trigger.

Prop	Type	Default
Side	string	"bottom"
Align	string	"start"
SideOffset	double	0
AlignOffset	double	0
Flip	bool	true
AvoidCollisions	bool	true
CollisionPadding	double?	-
Sticky	string?	-
HideWhenDetached	bool	false
ArrowPadding	double	0
ChildContent	RenderFragment?	-
Attributes	IDictionary<string, object>?	-

The listbox surface, wrapped by the Positioner and self-portaled to <body>. Renders a div with role=listbox while open.

Prop	Type	Default
Loop	bool	false
KeepMounted	bool	false
OnOpenAutoFocus	EventCallback<NaviusOpenAutoFocusEventArgs>	-
OnCloseAutoFocus	EventCallback<NaviusCloseAutoFocusEventArgs>	-
OnEscapeKeyDown	EventCallback<NaviusEscapeKeyDownEventArgs>	-
OnPointerDownOutside	EventCallback<NaviusPointerDownOutsideEventArgs>	-
OnFocusOutside	EventCallback<NaviusFocusOutsideEventArgs>	-
OnInteractOutside	EventCallback<NaviusInteractOutsideEventArgs>	-
ChildContent	RenderFragment?	-
Attributes	IDictionary<string, object>?	-

Data attributes

Data attribute	Values
[data-open]	Present while open.
[data-closed]	Present while closing (through the exit transition).
[data-starting-style]	Present at the start of the open transition.
[data-ending-style]	Present at the start of the close transition.
[data-side]	"top" \| "right" \| "bottom" \| "left" (set by the positioner)
[data-align]	"start" \| "center" \| "end" (set by the positioner)
[data-multiple]	Present when the root is a multi-select

Viewport

The scrollable container wrapping the items inside the content. Renders a div with role=presentation.

Prop	Type	Default
ChildContent	RenderFragment?	-
Attributes	IDictionary<string, object>?	-

Item

A selectable option. Selecting it sets the value and closes the listbox. Renders a div with role=option.

Prop	Type	Default
Value	string	""
Disabled	bool	false
TextValue	string?	-
OnSelect	EventCallback<NaviusSelectEventArgs>	-
ChildContent	RenderFragment?	-
Attributes	IDictionary<string, object>?	-

Data attributes

Data attribute	Values
[data-selected]	Present when the item is the selected value.
[data-highlighted]	Present while the item is the roving-focus target
[data-disabled]	Present when the item is disabled

ItemText

The label content for an item; also supplies the text the trigger shows for this value. Renders a span.

Prop	Type	Default
Text	string?	-
ChildContent	RenderFragment?	-
Attributes	IDictionary<string, object>?	-

ItemIndicator

Renders its content only when its parent item is selected. Renders a span.

Prop	Type	Default
ChildContent	RenderFragment?	-
Attributes	IDictionary<string, object>?	-

Group

Groups related items, labelled by a child Label via aria-labelledby. Renders a div with role=group.

Prop	Type	Default
ChildContent	RenderFragment?	-
Attributes	IDictionary<string, object>?	-

Label

An accessible heading for a Group. Renders a div.

Prop	Type	Default
ChildContent	RenderFragment?	-
Attributes	IDictionary<string, object>?	-

Separator

A decorative divider between item sections. Renders a div.

Prop	Type	Default
Attributes	IDictionary<string, object>?	-

ScrollUpButton

Mounts only when the viewport is scrolled down from the top. Renders a div.

Prop	Type	Default
ChildContent	RenderFragment?	-
Attributes	IDictionary<string, object>?	-

ScrollDownButton

Mounts only when there is more content below the fold. Renders a div.

Prop	Type	Default
ChildContent	RenderFragment?	-
Attributes	IDictionary<string, object>?	-

Arrow

An optional triangular pointer rendered inside the content, pointed at the trigger by the positioner. Renders a span.

Prop	Type	Default
Width	int	10
Height	int	5
ChildContent	RenderFragment?	-
Attributes	IDictionary<string, object>?	-

Accessibility

Implements the roles, states, and keyboard map of the combobox / listbox WAI-ARIA APG pattern. Behavior is covered by the browser test suite and an axe-core WCAG gate in CI.

Keyboard interactions

Key	Description
`Space`	When focus is on the trigger, opens the listbox and focuses the selected item. When focus is on an item, selects it.
`Enter`	When focus is on the trigger, opens the listbox and focuses the selected item. When focus is on an item, selects it.
`ArrowDown`	When focus is on the trigger, opens the listbox and focuses the first item. When focus is on an item, moves focus to the next item.
`ArrowUp`	When focus is on the trigger, opens the listbox and focuses the last item. When focus is on an item, moves focus to the previous item.
`Home`	When the listbox is open, moves focus to the first item.
`End`	When the listbox is open, moves focus to the last item.
`Esc`	Closes the listbox and returns focus to the trigger.
`Type a character`	Type-ahead moves focus to the next item whose label starts with the typed characters.