StackNavigation

Icon-and-label navigation rail with vertical or horizontal orientation

Interactive-mode

Divergence from Blok

Icon is a RenderFragment, not a string path. Blok's icon: ReactNode accepts any React element. The Blazor equivalent is RenderFragment, so items take a pre-built content fragment rather than an icon-path string. This lets you compose any inline markup (our Icon component, a custom SVG, a colored dot, an emoji) without a separate integration.

OnItemClick uses an event-args object with PreventDefault. Blok's callback returns false to cancel navigation via e.preventDefault(). Blazor's event model runs the C# callback after the browser has already scheduled the navigation, so we instead pass a StackNavigationItemClickedEventArgs whose PreventDefault property your handler can set to true. When the callback is wired, we short-circuit the <a> default via @onclick:preventDefault and drive the navigation ourselves via NavigationManager, honouring your PreventDefault choice.

Active-item detection uses Blazor's NavigationManager. Blok reads window.location.pathname via a useEffect if no pathname prop is supplied. We inject NavigationManager and compute the current path from its Uri as a fallback. Supply the Pathname parameter explicitly if you'd rather drive highlighting from a router state or a bound property.

Thin styled vertical scrollbar; horizontal scroll suppressed; items never clip. Blok uses overflow-auto on the scrollable body, which both triggers a horizontal scrollbar when a long label ellipsizes AND lets the vertical scrollbar claim 16px off the items' available width — the min-w-14 items then clip against it. BlazorUI substitutes overflow-y-auto overflow-x-hidden (no horizontal scroll) and reserves a stable 6px gutter on the body via scrollbar-gutter:stable. A -mr-1.5 on the same body extends the scrollable viewport into what was the rail's right padding, so the scrollbar sits at the rail's outer right edge rather than crowding the items. Webkit/Chromium/Edge styling mirrors ScrollArea (bg-border thumb, transparent track, rounded-full thumb, no scrollbar buttons); Firefox uses scrollbar-width:thin.

Examples

Vertical (default)

Primary color scheme with active item

Main content (Projects active)

With badge

Badges render top-right (vertical orientation only)

Horizontal orientation

OnItemClick callback (intercepts navigation)

API

The element family below can be composed together. Click an element to jump to its properties.

Element Purpose
StackNavigation Icon-and-label navigation rail. Renders StackNavigationItem entries and StackNavigationDivider separators from the Items list, supports optional Header/Footer slots, and highlights the item whose Path matches the current URL.
StackNavigationItem A clickable rail entry. Record passed into StackNavigation.Items; not a Blazor component.
StackNavigationDivider Horizontal (or vertical, when the rail is horizontal) line separator. Record passed into StackNavigation.Items; not a Blazor component.
StackNavigationItemClickedEventArgs Payload for StackNavigation.OnItemClick. Set PreventDefault = true to stop the default navigation.

StackNavigation

Icon-and-label navigation rail. Renders StackNavigationItem entries and StackNavigationDivider separators from the Items list, supports optional Header/Footer slots, and highlights the item whose Path matches the current URL.

Property Type Required Description
Items List<StackNavigationElement> The items to render. Each entry is either a StackNavigationItem (clickable rail item) or a StackNavigationDivider.
Orientation StackNavigationOrientation Rail orientation. Default: StackNavigationOrientation.Vertical. Other value: Horizontal.
ColorScheme StackNavigationColorScheme Active-item colour palette. Default: StackNavigationColorScheme.Neutral. Other value: Primary.
Pathname string? Path to compare against each item's Path for active highlighting. When null, falls back to NavigationManager.Uri.
OnItemClick EventCallback<StackNavigationItemClickedEventArgs> Invoked before navigation. Set e.PreventDefault = true to suppress the navigation and keep handling the click yourself.
Width string Tailwind width utility applied when vertical. Default: w-[72px].
Header RenderFragment? Optional content rendered above the items (vertical orientation only).
Footer RenderFragment? Optional content rendered below the items (vertical orientation only).
RenderItem RenderFragment<StackNavigationItem>? Overrides the default per-item markup. Receives the item and should render its full row.
RenderDivider RenderFragment<StackNavigationDivider>? Overrides the default divider markup.
ClassName string? Extra CSS classes appended to the <aside>. Supplying shadow-none drops the default shadow-base.
NavClassName string? Extra CSS classes appended to the inner <nav> that wraps the items.
AdditionalAttributes Dictionary<string, object>? Captured unmatched attributes, forwarded to the <aside>.

StackNavigationItem

A clickable rail entry. Record passed into StackNavigation.Items; not a Blazor component.

Property Type Required Description
Name string Visible label shown under the icon.
Path string Target URL. Also used for active-item detection against Pathname.
Icon RenderFragment Icon fragment. Use Icon or any inline markup — RenderFragment lets you compose freely.
Badge RenderFragment? Optional badge rendered at the top-right of the item (vertical orientation only).
ClassName string? Extra CSS classes appended to this item.

StackNavigationDivider

Horizontal (or vertical, when the rail is horizontal) line separator. Record passed into StackNavigation.Items; not a Blazor component.

Property Type Required Description
ClassName string? Extra CSS classes appended to the divider element.

StackNavigationItemClickedEventArgs

Payload for StackNavigation.OnItemClick. Set PreventDefault = true to stop the default navigation.

Property Type Required Description
Item StackNavigationItem The item that was clicked.
Mouse MouseEventArgs The underlying Blazor mouse event.
PreventDefault bool Set to true in your handler to cancel navigation. Default: false.

Rejoining the server...

Rejoin failed... trying again in seconds.

Failed to rejoin.
Please retry or reload the page.

The session has been paused by the server.

Failed to resume the session.
Please retry or reload the page.