Breadcrumbscomplementary
Breadcrumbs show hierarchy, TOC shows page sectionsTableOfContents
Sticky sidebar navigation for long-form content or filterable lists. Renders heading links with a continuous hierarchy rail that branches in for nested groups and back out for parent items, with active-segment highlighting.
Setup
import { TableOfContents } from '@fragments-sdk/ui';Examples
Default
Basic table of contents with section links
Loading preview...
Nested Groups
Filterable list grouped by category — the hierarchy rail branches in for children and back out for the next parent item
Loading preview...
With Active Item
Active state highlighting the current section
Loading preview...
Custom Title
Table of contents with a custom title
Loading preview...
No Title
Table of contents without a visible title
Loading preview...
Props
| Prop | Type | Default | Description |
|---|---|---|---|
childrenRequired | node | Not set | TableOfContents.Item or TableOfContents.Group elements |
label | string | Table of contents | Accessible label for the nav landmark |
title | string | On This Page | Visible title above the list |
hideTitle | boolean | false | Hide the visible title |
Usage Guidelines
When to use
- Long-form content pages (docs, blog posts, articles)
- Component documentation with multiple sections
- Filterable list sidebars where items are grouped by category
- Any page with 3+ headings or nested sections that benefit from quick navigation
When not to use
- Short pages with only 1-2 sections
- Primary site navigation (use Sidebar or Header)
- Step-by-step flows (use Stepper)
Best practices
- Pair with a scroll spy hook (e.g., IntersectionObserver) to track active heading
- Use TableOfContents.Group to nest items under a labeled, optionally-collapsible parent
- The legacy `indent` boolean on Item is preserved for back-compat; prefer Group for new code
- Place in a sticky aside for best UX
- Heading IDs must match between TOC items and the actual DOM headings
- TableOfContents.Item performs smooth scrolling by default; call event.preventDefault() in onClick to override
- Group is uncontrolled (defaultOpen=true) by default; pass open + onOpenChange for controlled state
Accessibility
- Uses <nav aria-label="Table of contents"> for landmark navigation
- Active item is marked with aria-current="location"
- All items are links with smooth scroll behavior
- Group toggle is a real <button> with aria-expanded reflecting open state
- Focus-visible ring on keyboard navigation