Skip to main content

​
Overview

NavigationList provides a flexible vertical navigation system with collapsible items, badges, and actions.
  • Use it for sidebar navigation, settings panels, or file trees.
  • Supports surface and sidebar tone variants.
  • Includes light, subtle, and filled visual variants.
  • Built-in collapsible groups with automatic chevron indicators.
Ideal for application sidebars and hierarchical navigation structures.

​
Installation

npm i @kuzenbo/core

​
Import

import {
  NavigationList,
  NavigationListAction,
  NavigationListBadge,
  NavigationListContent,
  NavigationListGroup,
  NavigationListGroupContent,
  NavigationListGroupLabel,
  NavigationListItem,
  NavigationListLink,
  NavigationListSeparator,
  NavigationListSkeleton,
  NavigationListSub,
  NavigationListSubItem,
  NavigationListSubLink,
} from "@kuzenbo/core/ui/navigation-list";

​
Basic Example

import {
  NavigationList,
  NavigationListItem,
  NavigationListLink,
} from "@kuzenbo/core/ui/navigation-list";

export function BasicNavigationList() {
  return (
    <NavigationList>
      <NavigationListItem>
        <NavigationListLink href="/dashboard" active>
          Dashboard
        </NavigationListLink>
      </NavigationListItem>
      <NavigationListItem>
        <NavigationListLink href="/projects">
          Projects
        </NavigationListLink>
      </NavigationListItem>
      <NavigationListItem>
        <NavigationListLink href="/settings">
          Settings
        </NavigationListLink>
      </NavigationListItem>
    </NavigationList>
  );
}

​
Collapsible Groups

import {
  NavigationList,
  NavigationListGroup,
  NavigationListGroupContent,
  NavigationListGroupLabel,
  NavigationListItem,
  NavigationListLink,
  NavigationListSub,
  NavigationListSubItem,
  NavigationListSubLink,
} from "@kuzenbo/core/ui/navigation-list";

export function CollapsibleNavigationList() {
  return (
    <NavigationList>
      <NavigationListItem collapsible defaultOpened>
        <NavigationListLink label="Projects" />
        <NavigationListSub>
          <NavigationListSubItem>
            <NavigationListSubLink href="/projects/web">
              Web App
            </NavigationListSubLink>
          </NavigationListSubItem>
          <NavigationListSubItem>
            <NavigationListSubLink href="/projects/mobile">
              Mobile App
            </NavigationListSubLink>
          </NavigationListSubItem>
        </NavigationListSub>
      </NavigationListItem>
    </NavigationList>
  );
}

​
Advanced Example

import {
  NavigationList,
  NavigationListBadge,
  NavigationListItem,
  NavigationListLink,
} from "@kuzenbo/core/ui/navigation-list";
import { Bell01Icon } from "@hugeicons/core-free-icons";
import { HugeiconsIcon } from "@hugeicons/react";

export function AdvancedNavigationList() {
  return (
    <NavigationList variant="filled" tone="sidebar">
      <NavigationListItem>
        <NavigationListLink
          href="/notifications"
          label="Notifications"
          description="View your recent activity"
          leftSection={
            <HugeiconsIcon icon={Bell01Icon} strokeWidth={2} />
          }
        />
        <NavigationListBadge>12</NavigationListBadge>
      </NavigationListItem>
    </NavigationList>
  );
}

​
Size and Variants

import { NavigationList } from "@kuzenbo/core/ui/navigation-list";

export function StyledNavigationList() {
  return (
    <NavigationList size="lg" variant="light" tone="surface">
      {/* Navigation items */}
    </NavigationList>
  );
}

​
API Reference

Root navigation container with variant and tone options.
​
size
UISize
default:"md"
Size of the navigation list: xs | sm | md | lg | xl.
​
variant
NavigationListVariant
default:"light"
Visual variant: light | subtle | filled.
​
tone
NavigationListTone
default:"surface"
Color tone: surface | sidebar.
Individual navigation item with optional collapsible behavior.
​
collapsible
boolean
default:false
Whether this item can be expanded/collapsed.
​
opened
boolean
Controlled open state.
​
defaultOpened
boolean
default:false
Initial open state (uncontrolled).
​
onOpenedChange
(opened: boolean) => void
Callback when open state changes.
​
disabled
boolean
default:false
Whether the item is disabled.
Interactive link or button within a navigation item.
​
href
string
URL for the link (uses <a> if provided).
​
active
boolean
default:false
Whether this link represents the current page.
​
label
ReactNode
Primary label text.
​
description
ReactNode
Secondary description text.
​
leftSection
ReactNode
Content before the label (icons, avatars).
​
rightSection
ReactNode
Content after the label (chevron auto-added for collapsible items).
​
noWrap
boolean
default:false
Whether to truncate text with ellipsis.
​
disableRightSectionRotation
boolean
default:false
Disable chevron rotation on collapsible items.
Badge indicator positioned absolutely within the item. Action button positioned absolutely within the item. Additional content wrapper for custom layouts. Semantic group container for related items. Label for a navigation group. Content wrapper for group items. Nested sub-navigation container. Individual item within sub-navigation. Link within sub-navigation. Visual separator between items or groups. Loading skeleton for navigation items.

​
Accessibility

  • Use semantic <nav> element for primary navigation.
  • Mark the current page with active or aria-current="page".
  • Collapsible items announce expanded/collapsed state.
  • Ensure keyboard navigation works for all interactive elements.

​
SSR and RSC Notes

  • NavigationList is client-interactive due to collapsible behavior ("use client").
  • Static navigation lists without collapsible items can be server-rendered.
  • Use client boundaries for interactive navigation.

​
Styling and Tokens

  • surface tone uses standard semantic tokens (bg-muted, text-foreground).
  • sidebar tone uses sidebar-specific tokens (bg-sidebar-accent, text-sidebar-foreground).
  • filled variant applies accent backgrounds to active items.
  • light variant applies subtle backgrounds.
  • subtle variant applies minimal backgrounds.

​
Troubleshooting

  • Collapsible item not expanding: ensure collapsible={true} is set on NavigationListItem.
  • Chevron not rotating: check disableRightSectionRotation is not set to true.
  • Active state not showing: verify active prop on NavigationListLink.
  • Text overflow issues: set noWrap={true} for truncation.

Build docs developers (and LLMs) love

Get started for freeTalk to us