Skip to Content
Hashti Design System
Components

Navigation Tree

Hierarchical documentation and application navigation tree with link href integration, expandable sections, and active state indicators.

The NavigationTree component presents hierarchical navigation structures tailored for application sidebars, documentation hierarchies, and administrative menus. Built upon React Aria Components’ tree navigation semantics, it provides keyboard navigation, smooth expand/collapse transitions, active link indicators, and nested branch support.

Spatial Sequences

Import

import {
  NavigationTree,
  NavigationTreeItem,
  NavigationTreeSection,
  NavigationTreeHeader,
} from "@hashti/react";

Anatomy & Compound Composition

<NavigationTree aria-label="Documentation Tree" size="md">
  <NavigationTree.Section>
    <NavigationTree.Header>Getting Started</NavigationTree.Header>
    <NavigationTree.Item href="/docs/installation">Installation</NavigationTree.Item>
    <NavigationTree.Item href="/docs/theming">Theming</NavigationTree.Item>
  </NavigationTree.Section>
  <NavigationTree.Section>
    <NavigationTree.Header>Components</NavigationTree.Header>
    <NavigationTree.Item href="/docs/components/button">Button</NavigationTree.Item>
    <NavigationTree.Item href="/docs/components/select">Select</NavigationTree.Item>
  </NavigationTree.Section>
</NavigationTree>

Examples

Application Navigation Tree

<NavigationTree> automatically manages selection and handles navigation clicks with keyboard roving arrow support:

import {
  NavigationTree,
  NavigationTreeSection,
  NavigationTreeHeader,
  NavigationTreeItem,
  Icon,
} from "@hashti/react";

export function AppNavigationTreeDemo() {
  return (
    <div className="w-64 border rounded-xl p-3 bg-white dark:bg-black">
      <NavigationTree aria-label="App Navigation">
        <NavigationTreeSection>
          <NavigationTreeHeader>Main Portal</NavigationTreeHeader>
          <NavigationTreeItem href="/dashboard" textValue="Dashboard">
            <span className="flex items-center gap-2">
              <Icon name="search" size={16} />
              <span>Overview</span>
            </span>
          </NavigationTreeItem>
          <NavigationTreeItem href="/analytics" textValue="Analytics">
            <span className="flex items-center gap-2">
              <Icon name="filter" size={16} />
              <span>Spatial Analytics</span>
            </span>
          </NavigationTreeItem>
        </NavigationTreeSection>

        <NavigationTreeSection>
          <NavigationTreeHeader>Design Tokens</NavigationTreeHeader>
          <NavigationTreeItem href="/tokens/colors" textValue="Colors">
            Palette & Mineral Glazes
          </NavigationTreeItem>
          <NavigationTreeItem href="/tokens/geometry" textValue="Geometry">
            Concentric Arches & Vaults
          </NavigationTreeItem>
        </NavigationTreeSection>
      </NavigationTree>
    </div>
  );
}

Nested Hierarchy with Expandable Branches

For deep folder structures, nest <NavigationTreeItem> children within an expandable item:

import { NavigationTree, NavigationTreeItem } from "@hashti/react";

export function NestedTreeDemo() {
  return (
    <div className="w-72 border rounded-xl p-3">
      <NavigationTree aria-label="Project Structure">
        <NavigationTreeItem id="packages" textValue="packages">
          <span className="font-semibold text-sm">packages</span>
          <NavigationTreeItem id="pkg-react" href="/packages/react" textValue="react">
            @hashti/react
          </NavigationTreeItem>
          <NavigationTreeItem id="pkg-tokens" href="/packages/tokens" textValue="tokens">
            @hashti/tokens
          </NavigationTreeItem>
        </NavigationTreeItem>
        <NavigationTreeItem id="apps" textValue="apps">
          <span className="font-semibold text-sm">apps</span>
          <NavigationTreeItem id="app-docs" href="/apps/docs" textValue="docs">
            Documentation (Astro + Fumadocs)
          </NavigationTreeItem>
          <NavigationTreeItem id="app-storybook" href="/apps/storybook" textValue="storybook">
            Storybook Workshop
          </NavigationTreeItem>
        </NavigationTreeItem>
      </NavigationTree>
    </div>
  );
}

Props Reference

PropTypeDefaultDescription
size"sm" | "md""md"Density size preset governing item padding and typography scale.
selectedKeysSelectionundefinedControlled active route keys.
defaultSelectedKeysSelectionundefinedDefault active route keys.
onSelectionChange(keys: Selection) => voidundefinedSelection handler.
PropTypeDefaultDescription
hrefstringundefinedLink URL for navigation. When provided, renders a semantic anchor tag.
targetstringundefinedAnchor target attribute (e.g. "_blank").
textValuestringundefinedString representation used for typeahead search.
isDisabledbooleanfalseWhether the item is disabled and non-interactive.

Accessibility & Keyboard Interaction

  • Arrow Navigation: Up and Down arrow keys move focus through visible tree items.
  • Expand/Collapse: Right arrow expands a collapsed branch; Left arrow collapses an open branch or moves to its parent.
  • Link Activation: Pressing Enter follows the href link.
  • Typeahead Search: Typing character keys jumps directly to matching items in the hierarchy.

Keyboard Interactions

KeyAction
↓ / ↑Navigates through navigation items.
→ / ←Expands or collapses navigation group.
EnterActivates link or toggles group.

WAI-ARIA & Data Attributes

AttributeTargetDescription
[data-hovered]ItemPresent on pointer hover.
[data-selected]ItemSet on the active route item.
[data-focused]ItemPresent on keyboard focus.

Tree

Hierarchical data grid for visualizing nested folders, file explorers, and deep parent-child navigation.

Content Switcher

Segmented button control enabling instant toggling between alternative views or data modes.

On this page

ImportAnatomy & Compound CompositionExamplesApplication Navigation TreeNested Hierarchy with Expandable BranchesProps ReferenceNavigationTree (Root)NavigationTreeItemAccessibility & Keyboard InteractionKeyboard InteractionsWAI-ARIA & Data Attributes