Skip to content
Browse documentation
whisk/ui

NavTree

Navigate a nested hierarchy of pages or resources.

Overview

NavTree presents a nested set of destinations using native navigation, list, link, and button semantics. Compose branches when a parent both has a destination and reveals child destinations.

Use when

Users browse a nested hierarchy of pages or resources.

Use instead

Use Breadcrumb for the current path or Tabs for peer views.

Usage

import {
  NavTree,
  NavTreeGroup,
  NavTreeItem,
  NavTreeLink,
  NavTreeRow,
  NavTreeSection,
  NavTreeTrigger,
} from "@smoothie-framework/whisk-react";

<NavTree aria-label="Project navigation">
  <NavTreeSection label="Project" headingLevel={2}>
    <NavTreeItem selected>
      <NavTreeRow><NavTreeLink href="/projects/atlas">Overview</NavTreeLink></NavTreeRow>
    </NavTreeItem>
    <NavTreeItem defaultExpanded>
      <NavTreeRow>
        <NavTreeTrigger aria-label="Toggle settings" />
        <NavTreeLink href="/projects/atlas/settings">Settings</NavTreeLink>
      </NavTreeRow>
      <NavTreeGroup>
        <NavTreeItem>
          <NavTreeRow><NavTreeLink href="/projects/atlas/settings/access">Access</NavTreeLink></NavTreeRow>
        </NavTreeItem>
      </NavTreeGroup>
    </NavTreeItem>
  </NavTreeSection>
</NavTree>

Examples

Keep the destination separate from disclosure

When a parent page has children, render its link and its disclosure trigger as neighbouring controls. This preserves the link's normal browser behavior and gives the toggle a focused job.

import {
  NavTree,
  NavTreeGroup,
  NavTreeItem,
  NavTreeLink,
  NavTreeRow,
  NavTreeTrigger,
} from "@smoothie-framework/whisk-react";

<NavTree aria-label="Documentation">
  <NavTreeItem defaultExpanded>
    <NavTreeRow>
      <NavTreeTrigger aria-label="Toggle foundations" />
      <NavTreeLink href="/docs/foundations">Foundations</NavTreeLink>
    </NavTreeRow>
    <NavTreeGroup>
      <NavTreeItem>
        <NavTreeRow><NavTreeLink href="/docs/foundations/colors">Colors</NavTreeLink></NavTreeRow>
      </NavTreeItem>
    </NavTreeGroup>
  </NavTreeItem>
</NavTree>

Mark the current destination

Set selected only on the page the person is viewing. For a collapsed parent of that page, use containsSelection so the hierarchy stays legible without adding a second current page.

import {
  NavTree,
  NavTreeGroup,
  NavTreeItem,
  NavTreeLink,
  NavTreeRow,
  NavTreeTrigger,
} from "@smoothie-framework/whisk-react";

<NavTree aria-label="Settings">
  <NavTreeItem containsSelection>
    <NavTreeRow>
      <NavTreeTrigger aria-label="Toggle account settings" />
      <NavTreeLink href="/settings/account">Account</NavTreeLink>
    </NavTreeRow>
    <NavTreeGroup>
      <NavTreeItem selected>
        <NavTreeRow><NavTreeLink href="/settings/account/security">Security</NavTreeLink></NavTreeRow>
      </NavTreeItem>
    </NavTreeGroup>
  </NavTreeItem>
</NavTree>

Control an expanded branch

Use expanded with onExpandedChange when application state owns the branch. The callback requests the next state; update expanded to accept it. Do not also pass defaultExpanded.

tsx
import {
  NavTree,
  NavTreeGroup,
  NavTreeItem,
  NavTreeLink,
  NavTreeRow,
  NavTreeTrigger,
} from "@smoothie-framework/whisk-react";

type SettingsTreeProps = {
  settingsExpanded: boolean;
  onSettingsExpandedChange: (expanded: boolean) => void;
};

export function SettingsTree({
  settingsExpanded,
  onSettingsExpandedChange,
}: SettingsTreeProps) {
  return (
    <NavTree aria-label="Settings">
      <NavTreeItem
        expanded={settingsExpanded}
        onExpandedChange={onSettingsExpandedChange}
      >
        <NavTreeRow>
          <NavTreeTrigger aria-label="Toggle settings" />
          <NavTreeLink href="/settings">Settings</NavTreeLink>
        </NavTreeRow>
        <NavTreeGroup>
          <NavTreeItem>
            <NavTreeRow><NavTreeLink href="/settings/profile">Profile</NavTreeLink></NavTreeRow>
          </NavTreeItem>
        </NavTreeGroup>
      </NavTreeItem>
    </NavTree>
  );
}

Use a button for in-page selection

NavTreeButton is for host-owned in-page changes, not navigation. It does not submit an enclosing form. Use NavTreeLink whenever activation changes location.

import {
  NavTree,
  NavTreeButton,
  NavTreeItem,
  NavTreeRow,
} from "@smoothie-framework/whisk-react";

<NavTree aria-label="Preview files">
  <NavTreeItem selected>
    <NavTreeRow><NavTreeButton onClick={showReadme}>README.md</NavTreeButton></NavTreeRow>
  </NavTreeItem>
  <NavTreeItem>
    <NavTreeRow><NavTreeButton onClick={showChangelog}>CHANGELOG.md</NavTreeButton></NavTreeRow>
  </NavTreeItem>
</NavTree>

Opt into native drag placement

Drag support reports a permitted placement but does not move data. Keep the source of truth in application state, validate the drag in canDrop, and apply the move in onDropIntent.

tsx
import {
  NavTree,
  NavTreeItem,
  NavTreeLink,
  NavTreeRow,
} from "@smoothie-framework/whisk-react";

type FileTreeProps = {
  moveFile: (id: string, position: "before" | "after") => void;
};

export function FileTree({ moveFile }: FileTreeProps) {
  return (
    <NavTree aria-label="Project files">
      <NavTreeItem>
        <NavTreeRow
          draggable
          dropPositions={["before", "after"]}
          canDrop={() => true}
          onDropIntent={(_event, target) => {
            if (target.position === "before" || target.position === "after") {
              moveFile("readme", target.position);
            }
          }}
        >
          <NavTreeLink href="/files/readme">README.md</NavTreeLink>
        </NavTreeRow>
      </NavTreeItem>
    </NavTree>
  );
}

Props

Component props

PropTypeDefaultDescription
NavTree: aria-label | aria-labelledbystringnoneName the navigation landmark. Use a distinct name when the page has more than one navigation region.
NavTree: sizesm | md | lgmdChoose the density of navigation rows.
NavTree: showLinesbooleantrueShow decorative indentation rails. This does not change navigation semantics.
NavTree: groupSelectionbooleanfalseVisually group the visible descendants of an open selected branch. It does not select descendants.
NavTree: selectParentsbooleanfalseUsed by the legacy NavTreeItem shorthand. In new compound markup, render NavTreeLink and NavTreeTrigger as separate controls instead.
NavTreeSection: label | headingLevelReactNode; 2 | 3 | 4 | 5 | 6none; 2Add an optional labelled section with a heading that fits the surrounding document outline. title is a legacy alias for label.
NavTreeItem: selected | containsSelection | disabledbooleanfalseMark the current destination, show that a collapsed branch contains it, or disable every control in one item. selected adds aria-current="page" to its link or button by default.
NavTreeItem: expanded | defaultExpanded | onExpandedChangeboolean | (expanded: boolean) => voidfalseControl or initialize a branch. Pass either expanded or defaultExpanded, not both. In controlled mode, update expanded after the callback.
NavTreeRownative div propsnoneRequired row wrapper for compound markup. It places destination and disclosure controls beside each other without nesting controls.
NavTreeLink: hrefstringnoneRequired destination anchor. Disabled items remove the href and leave the link out of the tab order.
NavTreeButtonnative button propsnoneUse for host-owned in-page selection or an action. It always renders type="button".
NavTreeTriggernative button propsnoneToggle a NavTreeGroup. Give an icon-only trigger an aria-label. It manages aria-expanded and aria-controls.
NavTreeGroupnative ul propsnoneWrap a branch's child NavTreeItems. Closed groups are hidden and inert; Escape closes the nearest open group and returns focus to its trigger.
NavTreeRow: draggable | dropPositions | canDrop | onDropIntentboolean | readonly (before | inside | after | after-parent)[] | callbacksnoneOpt into native drag feedback and report an accepted placement. The host validates data and performs the reorder or move; NavTree never mutates your tree.
NavTree: droppable | onDropIntent | canDropboolean | callbacksnoneEnable the end-of-root drop zone. Use the compound drag API for new code; droppable is retained for the legacy shorthand.

Accessibility

NavTree is a labelled navigation landmark with nested native lists. It does not use the ARIA tree role or tree-view arrow-key model, so links and buttons stay in normal Tab order. Use NavTreeLink for a destination and NavTreeButton only for an in-page action. A branch that also has a destination needs a separate NavTreeTrigger beside its link, not a link nested in a button. NavTreeTrigger manages expanded state and the group relationship. Closed NavTreeGroup content is hidden and inert. Give an icon-only trigger a clear aria-label, mark only the current destination selected, and use a section heading level that preserves the document outline.

Content guidance

Use concise, parallel nouns for destinations. Expandable parent labels should describe the group, not the disclosure action.