Navigation

Osirion.Blazor.Navigation contains three things:

• EnhancedNavigation controls where the page scrolls after a Blazor enhanced navigation.
• ScrollToTop and ScrollToTopProvider show a "back to top" button once the visitor scrolls down.
• Menu and its child components build a site menu with submenus and mega menus. The menu opens and closes with CSS only, so it works under Static SSR without JavaScript.

Setup

dotnet add package Osirion.Blazor.Navigation

The Osirion.Blazor meta-package includes it, and AddOsirion() registers enhanced navigation and the scroll-to-top button with their defaults. With this package alone:

using Osirion.Blazor.Components;
using Osirion.Blazor.Navigation.Extensions;

builder.Services.AddOsirionNavigation(navigation => navigation
    .AddEnhancedNavigation(options => options.Behavior = ScrollBehavior.Smooth)
    .AddScrollToTop(options => options.VisibilityThreshold = 400));

Or from configuration, with AddOsirionNavigation(builder.Configuration) or AddOsirion(builder.Configuration):

{
  "Osirion": {
    "Navigation": {
      "Enhanced": {
        "Behavior": "Smooth",
        "ResetScrollOnNavigation": true,
        "PreserveScrollForSamePageNavigation": true
      },
      "ScrollToTop": {
        "Position": "BottomRight",
        "VisibilityThreshold": 300,
        "Title": "Back to top"
      }
    }
  }
}

Add @using Osirion.Blazor.Navigation.Components to _Imports.razor. The enums ScrollBehavior and Position are in Osirion.Blazor.Components.

EnhancedNavigation

Blazor enhanced navigation replaces the page content without a full load. EnhancedNavigation listens for Blazor's enhancedload event and scrolls to the top of the new page. Place it in App.razor after the Blazor script, because it looks for the Blazor object when it runs:

<body>
    <Routes />
    <script src="_framework/blazor.web.js"></script>
    <EnhancedNavigation />
</body>

The component writes one inline script and needs no interactive render mode.

ScrollToTop

ScrollToTop renders a fixed button that appears after the visitor scrolled past VisibilityThreshold pixels and scrolls back to the top when clicked. ScrollToTopProvider renders the same button from the registered settings, so you configure it once in Program.cs or appsettings.json:

@inherits LayoutComponentBase

@Body

<ScrollToTopProvider />

To set it per layout instead, use the component directly:

<ScrollToTop Position="Position.BottomLeft" Text="Top" IconCssClass="bi bi-arrow-up" />

A parameter left at its default value lets the configured value apply. The button is hidden until its inline script runs, so it needs JavaScript; each button gets a unique id and registers its scroll listener once.

Menu

Menu renders a <nav> with an optional brand link and your items. Below the collapse breakpoint, a hamburger opens the items. The toggle and every submenu are visually hidden checkboxes with labels, so they work from the keyboard and without JavaScript.

<Menu AriaLabel="Main navigation" BrandText="My site" BrandLogo="/favicon.png"
      Alignment="MenuAlignment.Right">
    <MenuItem Text="Home" Href="/" Icon="home" />
    <MenuItem Text="Docs" Href="/docs" Icon="docs" HasSubmenu="true">
        <MenuItem Text="Getting started" Href="/docs/getting-started" />
        <MenuItem Text="Components" Href="/docs/components" />
    </MenuItem>
    <MenuItem Text="GitHub" Href="https://github.com/obrana-boranija/Osirion.Blazor" Target="_blank" />
</Menu>

Menu items

MenuItem is a link. It marks itself active (aria-current="page") when the current path matches Href; the comparison ignores the query string, the fragment and surrounding slashes.

Under Static SSR the active state is computed once per request. In an interactive render mode the item also follows later navigations.

The other building blocks:

• MenuDivider draws a separator (role="separator"), with an optional Label.
• MenuGroup groups items in a submenu column: Label, Description, and a footer link from FooterText, FooterHref and FooterTarget. Collapsible with Expanded="false" hides the items; there is no built-in control that opens the group again.
• MenuCallToAction is a highlighted link with Text, Description, Href and Target.
• MenuPanel (Title, Description, AriaLabel) holds MenuPanelLink items (Text, Href, Target, IconTemplate) as a promotional aside.
• MenuImageCard is a linked image with a caption: ImageUrl, ImageAlt, Title, Description, Href, Target.

A mega menu with an aside:

<MenuItem Text="Product" Href="/product" HasSubmenu="true" SubmenuVariant="SubmenuVariant.Mega">
    <ChildContent>
        <MenuGroup Label="Build" FooterText="All features" FooterHref="/features">
            <MenuItem Text="Content" Description="Markdown from GitHub or the file system." Href="/features/content" />
            <MenuItem Text="SEO" Description="Metadata, sitemaps and feeds." Href="/features/seo" />
        </MenuGroup>
        <MenuCallToAction Text="Get started" Description="Install the package." Href="/docs" />
    </ChildContent>
    <SubmenuAside>
        <MenuPanel Title="New in this release">
            <MenuPanelLink Text="Changelog" Href="/changelog" />
        </MenuPanel>
    </SubmenuAside>
</MenuItem>

Security

MenuItem, MenuGroup footers, MenuPanelLink, MenuImageCard, MenuCallToAction and the brand link render an href only for relative URLs and the http, https, mailto and tel schemes. With a javascript: URL from CMS-driven menu data the element is rendered without an href (a MenuGroup footer is left out), so nothing can run.

Styling

The menu reads the theme tokens (--osirion-text-primary, --osirion-background-primary, --osirion-border-color and others), so it follows the light and dark theme. Useful hooks:

• osirion-menu-container, osirion-menu-horizontal or osirion-menu-vertical, osirion-menu-align-*, osirion-menu-sticky on the container;
• osirion-menu-item, osirion-menu-item-active, osirion-submenu, osirion-submenu-mega on items and submenus;
• --osirion-menu-panel-background and --osirion-menu-panel-color for MenuPanel.

ScrollToTop gets the framework's primary button class (btn btn-primary with Bootstrap) plus osirion-scroll-to-top and its position class (bottom-right and so on). --osirion-scroll-size sets its size (default 45px, 40px at 768px and below).

Related

• Theming: put a ThemeToggle in the menu.
• CMS navigation: menus, breadcrumbs and a table of contents built from your content.
• Core navigation: breadcrumbs and read-more links.
• Osirion.Blazor.Navigation on NuGet