astro-tocbutton

astro-tocbutton generates a floating table-of-contents button for Astro blog posts. Reads h2–h6 headings from a #article element and renders a popover with navigation links. Positioned bottom-left by default (so it does not conflict with a bottom-right back-to-top button), and configurable to any corner. RTL-aware: placement mirrors automatically under dir="rtl".

Installation

npm install @rgglez/astro-tocbutton

Usage

import TocButton from "@rgglez/astro-tocbutton";

<TocButton />

Optional props

Prop	Type	Default	Description
label	string	"Table of contents"	aria-label for the toggle button
position	"bottom-left" | "bottom-right" | "top-left" | "top-right"	"bottom-left"	Fixed corner for the button. Uses logical edges, so it mirrors under RTL.

<TocButton position="top-right" label="On this page" />

Under dir="rtl", *-left placements resolve to the right edge and *-right to the left (the inline-start/inline-end edges flip automatically).

Requirements

• Astro ≥ 5.7 — the icon is imported as a native SVG component (import Icon from "./icon.svg"), supported from Astro 5.7 onward.
• The article content must be wrapped in an element with id="article". Headings (h2–h6) inside it must have id attributes (Astro / remark sets these automatically for markdown/MDX).
• Tailwind CSS ≥ 3.3 must be configured in your project (logical start-*/end-* utilities, used for RTL-aware positioning, were added in 3.3). If using Tailwind v4, add the package source to your content scan so utility classes are not purged:

/* global.css (v4) */
@source "../node_modules/@rgglez/astro-tocbutton/src";

Behavior

• Button is always visible on pages that contain headings; hidden if #article has none.
• Clicking the button opens/closes a popover anchored to it (above the button for bottom-* positions, below it for top-*).
• Headings are indented by level: h2 = no indent, h3 = pl-4, h4 = pl-8, h5 = pl-10, h6 = pl-12.
• Clicking a heading link closes the popover and scrolls to the section.
• Also closes on Escape or click outside.
• Compatible with Astro View Transitions (data-astro-rerun guard prevents duplicate listeners).

Development

Target	Description
make tags	List git tags sorted by semver (descending)
make patch	Bump PATCH version in package.json, commit, tag, push
make publish	Publish current version to npm

Typical release flow: make patch → make publish.

License

Copyright (C) 2026 Rodolfo González González.

Licensed under the Apache v2.0 license. Read the LICENSE file.