Navigation

NavigationBar

Top-level application header that pairs a brand mark with a horizontal set of navigation items and an optional mobile menu toggle.

import { NavigationBar } from '@lostgradient/cinder';
navigationchrome
01

Overview

Reference usage

Top-level navigation bar for primary site or app destinations. Use placement="top" for header navigation and placement="bottom" for a mobile tab-bar composition.

Usage

svelte 
<script lang="ts">
  import { NavigationBar } from '@lostgradient/cinder';
  import { NavigationItem } from '@lostgradient/cinder';
</script>

<NavigationBar>
  {#snippet items({ variant })}
    <NavigationItem {variant} href="/home" active>Home</NavigationItem>
    <NavigationItem {variant} href="/settings">Settings</NavigationItem>
  {/snippet}
</NavigationBar>

Bottom placement keeps the same link semantics and leaves viewport pinning to the app shell:

svelte 
<div style="position: sticky; bottom: 0;">
  <NavigationBar placement="bottom" labelsVisible="active">
    {#snippet items({ variant })}
      <NavigationItem {variant} href="/home" active>
        <span aria-hidden="true">⌂</span>
        <span data-cinder-navigation-label>Home</span>
      </NavigationItem>
      <NavigationItem {variant} href="/settings">
        <span aria-hidden="true">⚙</span>
        <span data-cinder-navigation-label>Settings</span>
      </NavigationItem>
    {/snippet}
  </NavigationBar>
</div>

When a top navigation bar collapses behind a menuToggle, activating an enabled navigation item closes the mobile menu and returns focus to the toggle. Item or bar-level click handlers can call event.preventDefault() to keep the menu open for guarded navigation, local state changes, or custom routing.

Live preview

Basic navigation bar

02

When to use

Use when
  • Anchoring an app shell with primary sections, branding, and account actions across the top edge.
  • Providing a responsive nav that collapses items behind a menu toggle below a breakpoint.
Avoid when
  • Showing the ancestor trail of the current page — use breadcrumbs instead.
  • Building a tall, dense sidebar of grouped sections — use side-navigation instead.
03

Examples

Basic navigation bar

Brand, link and button navigation items, disabled state, and an action in the trailing slot.

Bottom mobile tabs

NavigationBar can render a bottom tab-bar composition while links keep aria-current semantics.

04

Props

Props for navigation-bar
Name
Type
Default
Description
placement 'top' | 'bottom' 'top' Visual placement mode. bottom renders a mobile tab-bar composition, but still does not fix or stick itself to the viewport.
labelsVisible 'always' | 'active' | 'never' 'always' Label visibility for mobile bottom-tab compositions. Hidden labels remain in the accessibility tree when wrapped in [data-cinder-navigation-label].
menuTogglePlacement 'after-brand' | 'before-brand' 'after-brand' Placement for the collapsible mobile menu toggle in top navigation bars. Ignored for placement="bottom".
brand snippet
items required snippet Receives a context object with the current variant.
actions snippet
menuToggle snippet Snippet receiving toggle button attributes. Consumer renders the actual <button> and should mark decorative glyphs or icons inside it as aria-hidden so the button name comes from text or aria-label, not the ornament.
mobileMenuOpen bindable boolean false Two-way bindable open state of the mobile menu.
label text 'Main navigation' Accessible name for the <nav> landmark. Wins over any aria-label passed via rest. Default 'Main navigation'.
onclick MouseEventHandler<T> | undefined | null
onkeydown KeyboardEventHandler<T>undefinednull