Table of Contents

Accessible, unstyled table of contents that tracks the section in view.

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/ui

Add the public import below to <script setup lang="ts">. Components provide behavior without styles; the preview uses optional Paper styles.

import { Toc, TocRoot, TocItem, TocLink, TocList } from "@vizejs/ui/toc";

Or copy the source into your project with vize lib pull toc (see Source Distribution).

Try it

This is the basic example maintained with the component source, using the public package imports. The preview adds the optional Paper styles.

Open the interactive example · Styling these components

Copy the example

<!-- Table of contents that links to article headings and tracks the active section. -->
<script setup lang="ts">
import { useId } from "vue";

import { TocItem, TocLink, TocList, TocRoot } from "@vizejs/ui/toc";

const sections = [
  { id: useId(), title: "Installation" },
  { id: useId(), title: "Configuration" },
  { id: useId(), title: "Deployment" },
];
</script>

<template>
  <div>
    <TocRoot aria-label="On this page">
      <TocList>
        <TocItem v-for="section in sections" :key="section.id" :target-id="section.id">
          <TocLink :target-id="section.id">{{ section.title }}</TocLink>
        </TocItem>
      </TocList>
    </TocRoot>
    <article>
      <section v-for="section in sections" :key="section.id">
        <h2 :id="section.id">{{ section.title }}</h2>
        <p>Details about {{ section.title.toLowerCase() }}.</p>
      </section>
    </article>
  </div>
</template>

API

Toc

Source: src/families/navigation/toc/toc-root.vue

Props

Events

Slots

Exposed

TocRoot

Source: src/families/navigation/toc/toc-root.vue

Props

Events

Slots

Exposed

TocItem

Source: src/families/navigation/toc/toc-item.vue

Props

Slots

TocLink

Source: src/families/navigation/toc/toc-link.vue

Props

Slots

Exposed

TocList

Source: src/families/navigation/toc/toc-list.vue

Props

Slots

Behavior

Normative state x input -> outcome table for toc-root.vue, toc-list.vue, toc-item.vue, and toc-link.vue (@vizejs/ui/toc), plus collectTocEntries. Every row is proven by the named test in toc.test.ts or toc-ssr.test.ts; compile-only guarantees live in toc.types.test-d.ts.

The root is a labelled <nav> landmark with nested <ol> lists of native fragment links. The link whose section is in view carries aria-current="location". Active tracking reuses the @vizejs/ui/scroll-spy composable over the ids of the registered links.