Skip to main content
WireKit

Reading Sidebar

A sticky vertical reading sidebar whose progress + TOC track one article, not the whole page. Reach for this over the on-page TOC recipe when the reading surface is scoped to a container rather than the document — an article embedded in a dashboard panel, one of several articles on a page, a modal/drawer reading view, or a Livewire pane. The distinction is the progress math: page-scoped progress fills as you scroll the whole document; article-scoped progress fills as you scroll just the bounded article.

The canonical wiring

One tag does it: <x-wirekit::reading-shell boundary="container"> composes the progress bar + the sidebar TOC + the bookmark, and boundary="container" scopes every composed piece to the shell's nearest positioned ancestor instead of the viewport. Wrap your article body inside it; the spine reads the <h2> / <h3> headings, the progress bar tracks scroll through that container, and the active link updates as the reader moves.

Article-scoped reading sidebar 
{{-- # 1. reading-shell composes progress + sidebar TOC + bookmark in one tag --}}
{{-- # 2. boundary="container" scopes them to THIS container, not the viewport --}}
{{-- # 3. The scroll container needs its own height + overflow:auto; label it as --}}
{{--      a keyboard-reachable region (WCAG 2.1.1) so it is operable by keyboard --}}
<div role="region" aria-label="Article" tabindex="0" style="height: 100vh; overflow: auto;">
    <x-wirekit::reading-shell boundary="container" bookmarkKey="article-42">
        <article>
            <h2 id="intro">Introduction</h2>
            <p>…</p>

            <h2 id="setup">Setup</h2>
            <h3 id="prerequisites">Prerequisites</h3>
            <p>…</p>
        </article>
    </x-wirekit::reading-shell>
</div>

Always-expanded sidebar

The default sidebar is narrow at rest and expands on hover. On a dedicated reading layout where the reader expects the TOC, compose the primitives directly instead of the shell: place a <x-wirekit::reading-progress target="#article" boundary="container" /> and a <x-wirekit::reading-spine target="#article" expand="always" boundary="container" /> next to your <main id="article">. The expand="always" prop keeps the spine permanently open, and boundary="container" keeps both scoped to the article container.

CSS variables

Variable Default Purpose
--reading-spine-width-expanded 14rem Expanded sidebar width
--reading-spine-offset-top 1rem Sticky offset from the container top
--color-wk-reading-spine-active var(--color-wk-accent) Active-link color

For the full token reference, see /theming.

See also