Navigation

NavigationItem

Single wayfinding item that renders as an anchor when given href or as a button when given onclick, with active-state aria-current.

import { NavigationItem } from '@lostgradient/cinder/navigation-item';
navigationlink
01

Overview

Individual link or button within a navigation bar, supporting active and disabled states.

Usage

svelte 
<script lang="ts">
  import NavigationItem from '@lostgradient/cinder/navigation-item';
</script>

<NavigationItem />
02

When to use

Use when
  • Rendering one entry in a navigation bar, sidebar, or side-navigation group.
  • Switching the active view or section while signalling current location via aria-current.
Avoid when
  • Showing a hierarchical trail of ancestors — use breadcrumbs instead.
  • Triggering a generic action unrelated to navigation — use button instead.
03

Props

Props for navigation-item
Name Type Default Required Bindable Description
active boolean false Marks this item as the currently active destination; emits aria-current and applies active visual styling.
disabled boolean false Prevents interaction: removes the item from the tab order, blocks clicks, and applies disabled visual styling.
variant 'horizontal' | 'mobile' | 'vertical' 'horizontal' Controls item geometry. Emitted as data-variant. Default 'horizontal'. - 'horizontal': top-rounded radius, accent bottom-border active indicator. Used inside NavigationBar and similar horizontal tab-bar contexts. - 'mobile': stacked full-width layout when an owning navigation surface enters its narrow container mode. - 'vertical': square row geometry, neutral selected surface, and accent inline-start border active indicator. Used inside SideNavigation (set automatically by SideNavigationItem) or standalone sidebar footers where flush sidebar edges are required.
current 'page''step''location''date''time''true' 'page' The aria-current token emitted while active is true. Defaults to 'page', which is correct for navigation bars and breadcrumb-adjacent links. Use 'true' (or another standard token such as 'step' / 'location') for section/view switchers, where 'page' would mislabel the current section as the current page in the browsing context.
children snippet req
onclick (event: MouseEvent) => void Optional click handler called for the rendered <a> element. Useful for intercepting plain left-clicks for SPA navigation while letting modified clicks (cmd/ctrl/shift/alt or middle-click) fall through to native browser behavior. Disabled-state preventDefault still applies.
href discriminated-union Destination URL. Providing this prop renders the item as an <a> element instead of a <button>.
tabindex unknown req