StackNavigation
Icon-and-label navigation rail with vertical or horizontal orientation
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
With badge
With header and footer
Horizontal orientation
OnItemClick callback (intercepts navigation)
/homeAPI
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. |