Select

Overview

Select shows a listbox of options behind a trigger button. It can be controlled (@bind-Value / @bind-Open) or uncontrolled (DefaultValue / DefaultOpen), and also supports multi-select (Multiple, @bind-Values), where selecting an option toggles it in the set and keeps the listbox open. The listbox is portaled to document.body and collision-aware via the positioner engine; a hidden native mirror participates in form submission when Name is set.

Anatomy

@using Navius.Primitives.Components.Select

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

    <NaviusSelectPortal>
        <NaviusSelectPositioner>
            <NaviusSelectPopup>
                <NaviusSelectScrollUpButton />
                <NaviusSelectViewport>
                    <NaviusSelectItem>
                        <NaviusSelectItemText />
                        <NaviusSelectItemIndicator />
                    </NaviusSelectItem>

                    <NaviusSelectGroup>
                        <NaviusSelectLabel />
                        <NaviusSelectItem />
                    </NaviusSelectGroup>

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

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	Description
`Value`	`string?`	-	Controlled selected value (opaque key). Pair with `ValueChanged` (`@bind-Value`).
`ValueChanged`	`EventCallback<string?>`	-	Fires when the controlled `Value` should change.
`DefaultValue`	`string?`	-	Uncontrolled initial value.
`Multiple`	`bool`	`false`	Enables multi-select: selecting an option toggles it in the set and keeps the popup open.
`Values`	`IReadOnlyList<string>`	`[]`	Controlled selected set (opaque keys), used only when `Multiple`. Pair with `ValuesChanged` (`@bind-Values`).
`ValuesChanged`	`EventCallback<IReadOnlyList<string>>`	-	Fires when the controlled `Values` should change.
`DefaultValues`	`IReadOnlyList<string>?`	-	Uncontrolled initial selected set, used only when `Multiple`.
`Open`	`bool`	`false`	Controlled open state. Pair with `OpenChanged` (`@bind-Open`).
`OpenChanged`	`EventCallback<bool>`	-	Fires when the controlled `Open` value should change.
`DefaultOpen`	`bool`	`false`	Uncontrolled initial open state.
`Placeholder`	`string?`	-	Placeholder shown by Value when nothing is selected.
`Disabled`	`bool`	`false`	Disables the whole control; the trigger cannot open.
`Name`	`string?`	-	When set, renders a hidden native mirror for form submission (one hidden input per selected value when `Multiple`).
`Required`	`bool`	`false`	Marks the hidden form mirror required for native validation and sets `aria-required` on the Trigger.
`Dir`	`string?`	-	Reading direction, `"ltr"` or `"rtl"`. Cascades into the positioner and roving focus.
`ChildContent`	`RenderFragment?`	-	The select’s parts.

Trigger

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

Prop	Type	Default	Description
`ChildContent`	`RenderFragment?`	-	Trigger content, typically Value and Icon.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `button`.

Value

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

Prop	Type	Default	Description
`Placeholder`	`string?`	-	Overrides the placeholder text shown when no value is selected.
`ChildContent`	`RenderFragment?`	-	Overrides the auto label. Without it, the registered label or placeholder is shown.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `span`.

Icon

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

Prop	Type	Default	Description
`ChildContent`	`RenderFragment?`	-	Overrides the default chevron-down glyph.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `span`.

Portal

Teleports the popup into document.body (or Container). 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 the select is closed, for exit animations.
`ChildContent`	`RenderFragment?`	-	The Positioner and Popup.

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.

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.
`Sticky`	`string?`	-	Sticky behavior while scrolling: `partial` or `always`.
`HideWhenDetached`	`bool`	`false`	Hide the popup (`data-anchor-hidden`) when the anchor is fully clipped/detached.
`ArrowPadding`	`double`	`0`	Padding in px between the arrow and the popup edges.
`ChildContent`	`RenderFragment?`	-	The Popup.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the positioning element.

The listbox surface, wrapped by the Positioner and self-portaled. Renders a div with role="listbox". Manages roving focus over its options rather than a focus trap; does not lock page scroll.

Prop	Type	Default	Description
`Loop`	`bool`	`false`	When true, arrow navigation among options wraps at the ends.
`KeepMounted`	`bool`	`false`	Keeps the popup mounted while closed, for exit animations.
`OnOpenAutoFocus`	`EventCallback<NaviusOpenAutoFocusEventArgs>`	-	Fires when focus moves into the popup on open; cancelable.
`OnCloseAutoFocus`	`EventCallback<NaviusCloseAutoFocusEventArgs>`	-	Fires when focus returns to the trigger on close; 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 listbox’s content.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `div`.

ScrollUpButton

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

Prop	Type	Default	Description
`ChildContent`	`RenderFragment?`	-	Overrides the default chevron-up glyph.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `div`.

Viewport

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

Prop	Type	Default	Description
`ChildContent`	`RenderFragment?`	-	The listbox’s items, groups and separators.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `div`.

Item

A selectable option. Selecting it sets the value and closes the listbox (unless multi-select, or OnSelect prevents it). Renders a div with role="option".

Prop	Type	Default	Description
`Value`	`string`	`""`	This option’s opaque value key.
`Disabled`	`bool`	`false`	Disables the option; skipped by roving focus and selection.
`TextValue`	`string?`	-	Explicit text for type-ahead and the trigger label, overriding the item’s rendered content.
`OnSelect`	`EventCallback<NaviusSelectEventArgs>`	-	Cancelable callback fired before selection completes. Call `PreventDefault` to keep the listbox open.
`ChildContent`	`RenderFragment?`	-	Item content.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `div`.

ItemText

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

Prop	Type	Default	Description
`Text`	`string?`	-	Plain-string label registered for this item’s value. Falls back to the parent Item’s `TextValue` when omitted.
`ChildContent`	`RenderFragment?`	-	Rendered label content.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `span`.

ItemIndicator

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

Prop	Type	Default	Description
`ChildContent`	`RenderFragment?`	-	Indicator content (e.g. a check glyph).
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `span`.

Group

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

Prop	Type	Default	Description
`ChildContent`	`RenderFragment?`	-	The group’s label and items.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `div`.

Label

An accessible heading for a Group. Renders a div.

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

Separator

A decorative divider between item sections. Renders a div.

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

ScrollDownButton

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

Prop	Type	Default	Description
`ChildContent`	`RenderFragment?`	-	Overrides the default chevron-down glyph.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `div`.

Arrow

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

Prop	Type	Default	Description
`Width`	`int`	`10`	Arrow width in px.
`Height`	`int`	`5`	Arrow height in px.
`ChildContent`	`RenderFragment?`	-	Overrides the default triangular shape.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `span`.

Data attributes

Part	Attribute	Description
Trigger	`data-popup-open`	Present while the listbox is open.
Trigger	`data-disabled`	Present when the root is disabled.
Trigger	`data-placeholder`	Present when no value is selected.
Trigger	`data-multiple`	Present when `Multiple` is enabled.
Value	`data-placeholder`	Present when no value is selected.
Popup	`data-open`	Present while open.
Popup	`data-closed`	Present while closing (through 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-side`	`"top"` \| `"right"` \| `"bottom"` \| `"left"`, set by the positioner.
Popup	`data-align`	`"start"` \| `"center"` \| `"end"`, set by the positioner.
Popup	`data-multiple`	Present when `Multiple` is enabled.
Popup	`data-anchor-hidden`	Present when `HideWhenDetached` is set and the anchor is fully clipped/detached.
Item	`data-selected`	Present when the item is the selected value.
Item	`data-highlighted`	Present while the item is the roving-focus target.
Item	`data-disabled`	Present when the item is disabled.

Keyboard interactions

Key	Behavior
`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.

ARIA mechanism

Implements the roles, states and keyboard map of the combobox / listbox WAI-ARIA APG pattern. The Trigger wires role="combobox", aria-haspopup="listbox", aria-expanded, aria-controls pointing at the Popup’s id, and aria-required when Required is set. The Popup wires role="listbox" and aria-multiselectable when Multiple. Each Item wires role="option" and aria-selected; disabled items also carry aria-disabled. Groups wire role="group" with aria-labelledby pointing at their Label. This mechanism is covered by the Playwright browser test suite and gated by axe-core in CI.