Navigation@knitui/components
TableOfContents
TableOfContents renders a list of heading entries as pressable controls. It supports controlled and uncontrolled active state, depth-based indentation, three visual variants, and seven sizes. Pass data (or the alias initialData) as an array of { value, depth } objects.
import { TableOfContents } from "@knitui/components";Playground
Loading playground…
<TableOfContents
data={[{ value: "Introduction", depth: 1 }, { value: "Getting Started", depth: 1 }, { value: "Installation", depth: 2 }, { value: "Configuration", depth: 2 }, { value: "Basic Usage", depth: 3 }, { value: "Advanced Topics", depth: 1 }, { value: "API Reference", depth: 2 }]}
variant="light"
size="md"
defaultActive={0}
depthOffset="$lg"
minDepthToOffset={1}
/>Examples
Variants
All three visual variants of the active-item highlight, side by side.
Loading example…
Sizes
The seven sizes from xxs to xxl, all using the same data.
Loading example…
Shadows
The shadow elevation prop, inherited from Box, across all token levels.
Loading example…
Controlled
Controlled active index — the parent drives which heading is highlighted.
Loading example…
Deep Nesting
Deeply nested headings — shows how depthOffset and minDepthToOffset affect indentation.
Loading example…
No Initial Active
No active selection — defaultActive is -1 so nothing is highlighted on mount.
Loading example…
Custom Control Props
Custom control content via getControlProps — adds an icon prefix to each entry.
Loading example…
Matrix
Full variant × size matrix for visual regression.
Loading example…
Styles
Per-slot styles targets individual parts — here the control and text.
Loading example…
Themed
Accent color comes from Tamagui theme, not a public color prop.
Loading example…
Props
| Prop | Type | Default | Description |
|---|---|---|---|
active | number | undefined | — | Controlled index of the active heading |
autoContrast | boolean | undefined | — | No-op cross-platform: the palette ramp already contrasts (parity only) |
data | TableOfContentsItem[] | undefined | — | Heading data to render |
defaultActive | number | undefined | -1 | Uncontrolled initial active index (-1 = none). |
depthOffset | TableOfContentsDepthOffset | undefined$xxs · $xs · $sm · $md · $lg · $xl · $xxl | "$lg" | Left-padding added per depth level. |
disabled system | boolean | undefined | — | |
getControlProps | ((payload: { active: boolean; data: TableOfContentsItem; }) => Partial<TocControlProps>) | undefined | — | Per-control prop overrides, computed per heading from its active state + data. The dynamic escape hatch over the `control` slot: it merges OVER `styles.control` (the "explicit beats sugar" rule), so per-item props always win. |
initialData | TableOfContentsItem[] | undefined | — | Alias for `data`, accepted for Mantine parity |
minDepthToOffset | number | undefined | 1 | Minimum depth that starts receiving the offset. |
onChange | ((index: number) => void) | undefined | — | Called with the index of the heading whose control was activated |
radius system | string | number | undefined | — | Border radius of each control |
shadow system | "xs" | "sm" | "md" | "lg" | "xl" | "xxs" | "xxl" | undefined | — | |
size system | number | "xs" | "sm" | "md" | "lg" | "xl" | "xxs" | "xxl" | undefinedxxs · xs · sm · md · lg · xl · xxl | "md" | Controls font-size and padding of every control. |
styles system | SlotStyles<TableOfContentsStyles> | undefined | — | Per-slot style sugar — props spread onto the matching parts. |
theme system | ThemeName | null | undefined | — | Applies a theme to this element |
variant system | TableOfContentsVariant | undefinedfilled · light · none | "light" | Active-item highlight style. |
Style slots
Every part of TableOfContents can be styled through the styles prop. Explicit props on the component always win over slot styles.
| Slot | Usage |
|---|---|
control | styles={{ control: { … } }} |
root | styles={{ root: { … } }} |
text | styles={{ text: { … } }} |
Accessibility & DOM props (2)
| Prop | Type |
|---|---|
key | Key | null | undefined |
ref | Ref<TamaguiElement> | undefined |
Plus 497 inherited style props from Box — the full Tamagui/React Native style surface, including token shorthands like p, mx, bg and c. See Tokens for the scales they accept, or the full list.