Floating TOC

A floating table of contents that tracks scroll position and provides quick navigation to page sections.

Storybook Source Styles source

Usage

"use client";

import { useState } from "react";

import { FloatingToc } from "@thenamespace/uikit";

Anatomy

Import the FloatingToc component and access all parts using dot notation.

import { FloatingToc } from "@thenamespace/uikit";

<FloatingToc>
  <FloatingToc.Trigger />
  <FloatingToc.Bar />
  <FloatingToc.Content>
    <FloatingToc.Item />
  </FloatingToc.Content>
</FloatingToc>;

Controlled

State: closed

"use client";

import { useState } from "react";

import { FloatingToc } from "@thenamespace/uikit";

Custom Delays

Instant

Default (200/300)

Slow (600/500)

"use client";

import { useState } from "react";

import { FloatingToc } from "@thenamespace/uikit";

Hierarchical

"use client";

import { useState } from "react";

import { FloatingToc } from "@thenamespace/uikit";

In Page Context

Introduction

Welcome to the documentation. This guide covers everything you need to get started with the library, from installation to advanced usage patterns.

Getting Started

Install the package using your preferred package manager. The library supports npm, yarn, and pnpm out of the box with zero configuration needed.

API Reference

The API provides a clean interface for building composable components. Each component follows the compound pattern, giving you full control over rendering.

Examples

Browse through real-world examples to see how the components work in production scenarios. Each example is fully functional and can be copied directly.

FAQ

Find answers to the most commonly asked questions about the library, including migration guides, browser support, and accessibility compliance.

"use client";

import { useState } from "react";

import { FloatingToc } from "@thenamespace/uikit";

Left Aligned Bars

"use client";

import { useState } from "react";

import { FloatingToc } from "@thenamespace/uikit";

Left Placement

"use client";

import { useState } from "react";

import { FloatingToc } from "@thenamespace/uikit";

Press Mode

"use client";

import { useState } from "react";

import { FloatingToc } from "@thenamespace/uikit";

Press Mode In Page

Design principles

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Getting started

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Core components

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Theming

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Advanced patterns

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Changelog

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

"use client";

import { useState } from "react";

import { FloatingToc } from "@thenamespace/uikit";

Virtualized

"use client";

import type { CSSProperties } from "react";
import { useMemo, useState } from "react";

CSS Classes

Element Classes

.floating-toc__trigger - Wrapper around bar indicators, acts as hover/click target
.floating-toc__bar - Individual horizontal indicator line (uses ::after for the visual bar)
.floating-toc__content - Floating panel that appears on hover/tap
.floating-toc__item - Pressable entry in the expanded content

Interactive States

Focus visible: :focus-visible or [data-focus-visible="true"] on .floating-toc__trigger (focus ring)
Active bar: [data-active="true"] on .floating-toc__bar (accent color, wider bar)
Active item: [data-active="true"] on .floating-toc__item (accent text color)
Hover item: :hover or [data-hovered="true"] on .floating-toc__item (default background)
Pressed item: :active or [data-pressed="true"] on .floating-toc__item (darker background)
Disabled item: :disabled or [aria-disabled="true"] on .floating-toc__item (reduced opacity)

Data Attributes

[data-placement="left|right"] on .floating-toc__trigger - Controls bar growth direction
[data-entering="true"] / [data-exiting="true"] on .floating-toc__content - Animation states
[data-placement="top|bottom|left|right"] on .floating-toc__content - Slide direction

CSS Variables

--floating-toc-bar-width - Default bar width (default: 16px)
--floating-toc-bar-active-width - Active bar width (default: 24px)
--floating-toc-bar-height - Bar thickness (default: 2px)
--floating-toc-bar-level-step - Width reduction per nesting level (default: 3px)
--floating-toc-bar-gap - Gap between bars (default: 12px)
--floating-toc-item-indent - Indent per nesting level (default: 0.75rem)
--floating-toc-level - Current nesting depth (set via inline style)

API Reference

FloatingToc

The root component. Manages open/close state and context.

Prop	Type	Default	Description
`placement`	`'left' \| 'right'`	`'right'`	Which side of the page the TOC is on
`triggerMode`	`'hover' \| 'press'`	`'hover'`	How the trigger opens the content
`open`	`boolean`	-	Controlled open state
`defaultOpen`	`boolean`	-	Default open state (uncontrolled)
`onOpenChange`	`(open: boolean) => void`	-	Callback when open state changes
`openDelay`	`number`	`200`	Time in ms before opening after hover
`closeDelay`	`number`	`300`	Time in ms before closing after pointer/focus leave
`children`	`ReactNode`	-	Trigger and Content elements

FloatingToc.Trigger

Wrapper around bar indicators. Acts as hover/click target.

Also supports all native span HTML attributes.

FloatingToc.Bar

Individual horizontal indicator line.

Prop	Type	Default	Description
`active`	`boolean`	-	Highlights this bar as the currently active section
`level`	`number`	-	Nesting depth (1 = top-level). Deeper levels produce shorter bars

Also supports all native span HTML attributes.

FloatingToc.Content

Floating panel that appears on hover/tap. Wraps RAC Popover.

Prop	Type	Default	Description
`offset`	`number`	`8`	Distance from the trigger
`placement`	`Placement`	-	Override the default placement (auto-derived from root `placement`)

Also supports all RAC Popover props except isOpen and triggerRef.

FloatingToc.Item

Pressable entry in the expanded content.

Prop	Type	Default	Description
`active`	`boolean`	-	Highlights this item as the currently active section
`level`	`number`	-	Nesting depth (1 = top-level). Deeper levels are indented

Also supports all native button HTML attributes.

DisclosureGroup

Container that manages multiple Disclosure items with coordinated expanded states

Link

A styled anchor component for navigation with built-in icon support