Skip to content
GaudiGaudi Design System home

Search documentation

Search every page, heading and paragraph.

TableOfContents

Responsive article navigation with active sections, expandable heading branches, and an optional diagram and table index.

Post@gaudi/design-system/post/TableOfContentsView in StorybookSource

Reuses Scrollspy, Collapsible, Link and the shared expansion hook.

Installation

pnpm add github:ahmadassaf/design-system

Import from @gaudi/design-system. Load @gaudi/design-system/global.css once and add transpilePackages: ['@gaudi/design-system'] in Next.js.

import TableOfContents from '@gaudi/design-system/post/TableOfContents';

Usage

import TableOfContents from '@gaudi/design-system/post/TableOfContents';
<TableOfContents toc={toc} contentRef={articleRef} targetRef={readingViewportRef} offset={24} />

Examples

Playground

Storybook

Four or fewer sections

Storybook

API

8 props

Accessibility

Uses real links and marks the active heading with aria-current. Branch toggles have descriptive names and aria-expanded. Modified link clicks remain native; section navigation respects reduced motion and does not steal focus. Hidden branches keep their targets indexed and expand when a descendant becomes active.

ScrollspyTrack the visible section and navigate a long document using anchor links.1 exampleLinkLink centralizes navigation semantics for internal, anchor, and external links.ArticleA complete blog article with Gaudi journal navigation, PostHeader metadata, reading progress, TableOfContents section navigation, expandable images, a gallery, and captioned video. The main Blog article is joined by a centered Focused essay, a Technical tutorial with nested navigation and code, a wider Photo essay with a gallery, and a Series article with PostSeriesBox navigation across three parts. Each workflow reuses the same scroll boundary, header, media controls, and layout component. Contents-enabled examples use the shared TableOfContents block for links, active sections, and nested branch controls.ImageImage renders editorial MDX images with caption, dark-mode source, fallback source, and click-to-open modal behavior.