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.
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.
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
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.