In-Page Navigation

🧭 When to Use In-Page Navigation

Use In-Page Navigation when:

• A single page contains multiple distinct content sections

• Users need to quickly jump to a specific block of content (e.g. overview, settings, billing)

• The page is long enough that scrolling to locate sections becomes inefficient

Avoid using this pattern when:

• The page content is short or linear

• Navigation should route to different pages — use Tabs or Breadcrumbs in that case

🧩 Component Structure

In-Page Navigation includes:

• A container holding the navigation items

• Navigation Items that act as anchors to scrollable sections

• Optional active indicator (like a dot, line, or highlight) to show the current section

• Optional scrollspy behavior to track which section is currently visible

Variants allow it to display as either:

• Vertical list (ideal for left-side navigation in dashboards or docs)

• Horizontal bar (common in forms, wizards, or mobile UIs)

🎨 Types

• Underline – Shows an underline below the active item; great for minimal UIs

• Filled – Applies a background to the active item; ideal for stronger emphasis or complex UIs

• Default – Neutral styling with optional hover states and simple active markers

All types are available in both vertical and horizontal orientations.

📏 Sizes

• Medium (md) – Default for web and most desktop use cases

• Large (lg) – Use for mobile-first interfaces, onboarding steps, or hero-level navigation

Size tokens affect padding, font size, and spacing between items.

🎯 Item States

• Default – Neutral, unselected state

• Hover – Shows visual feedback like color change or underline

• Focus – Keyboard-accessible state with outline or focus ring

• Active (Selected) – The current section; styled clearly with emphasis

States are token-driven and work consistently across themes.

⚙️ Behavior (Optional Enhancements)

• Scrollspy Mode – Highlights the active item automatically based on scroll position

• Sticky Positioning – The navigation container stays pinned to the top or side while scrolling

• Smooth Scroll – Clicking a nav item scrolls smoothly to its anchor section

• Icons – Items can include icons to reinforce meaning or context (e.g. 🛡 Settings)

These features can be visualized in Figma as variants or behaviors for handoff notes.

♿ Accessibility Considerations

From a design perspective:

• Use strong visual indicators for the active item

• Don’t rely on color alone — pair with underline, bold type, or indicators

• Ensure spacing is comfortable for touch and cursor interaction

From a code perspective (if implemented):

• Use semantic elements (e.g. <nav> with aria-label="In-page navigation")

• Indicate the current section with aria-current="true"

• Ensure that navigation items use anchor links (<a href="#section-id">)

• Enable keyboard navigation between items with Tab and Enter

✅ Best Practices

• Keep item labels short and clear (e.g. “Overview”, “Settings”, “Billing”)

• Use spacing and separators to visually group related items if needed

• Combine with sticky behavior for long-scroll pages

• Match the order of navigation items to the visual structure of the page