Back To Top
Free · MITHeadless, accessible, and styled entirely through the attribute surface below — bring your own CSS system, or start from the reference theme.
Install
Without a flag you get no styling at all — plain HTML carrying the attribute surface below. --theme copies the same theme in two dialects;--bridge lumos re-points either one onto Lumos for Astro's tokens (it needs a theme to re-point, and Lumos itself, already in your project).
Unstyled — behavior only, you write the CSS
npx astrocraft-ui add navigation/back-to-topPlain-CSS theme — no build step
npx astrocraft-ui add navigation/back-to-top --theme cssTailwind theme — needs Tailwind v4
npx astrocraft-ui add navigation/back-to-top --theme tailwindPlain-CSS theme, re-pointed onto Lumos tokens
npx astrocraft-ui add navigation/back-to-top --theme css --bridge lumosTailwind theme, re-pointed onto Lumos tokens
npx astrocraft-ui add navigation/back-to-top --theme tailwind --bridge lumosLive demo
BackToTop & SkipLink
Both are focus moves that happen to scroll, which is the half everyone drops. The button below appears once you are 400px down and sends the caret — not just the viewport — back to <main>. SkipLink is not in this box at all: it is the first element in the page's <body>, which is the only place a bypass block means anything. Reload and press Tab.
Attribute surface
With no class-merging machinery, these attributes are the whole extension point. State is a data-attribute or a native attribute; visibility is the hiddenattribute. Generated from source by pnpm slots.
| Component | Slots | Variants | Runtime state | Native state |
|---|---|---|---|---|
| `BackToTop.astro` | `back-to-top` | — | — | `[hidden]` |
Source
What the command copies — 2 files, alias-free so the copy lands standing alone. This is the whole component; there is nothing else.
---
// src/components/ui/navigation/back-to-top/BackToTop.astro — headless primitive (see ../../README.md).
// Appears once the page has scrolled past `threshold`, and returns the user to the top.
//
// The part every hand-rolled version misses is that "back to top" is a FOCUS move, not a scroll.
// Scroll the window and nothing else and a keyboard user is looking at the top of the page with the
// caret still halfway down it, so their next Tab jumps them back to where they came from — the exact
// thing they just asked to leave. This moves focus to `for`'s element (or <body>), adding
// `tabindex="-1"` when the target is not natively focusable, and lets the scroll follow.
//
// Motion: the scroll is smooth, EXCEPT under `prefers-reduced-motion`, where it is instant. A
// long smooth scroll is vestibular motion like any other, and it is the one bit of animation in the
// library that JavaScript rather than a theme decides.
//
// Visibility is the `hidden` attribute (contract rule 4), so it starts hidden in the markup and the
// script reveals it — no flash of a button on a page that has not been scrolled.
import "../../../../styles/structure.css";
import type { HTMLAttributes } from "astro/types";
type Props = HTMLAttributes<"button"> & {
/** Scroll distance, in pixels, past which the button appears. */
threshold?: number;
/** id of the element focus should land on. Defaults to the document body. */
for?: string;
};
const { threshold = 400, for: target, class: className, ...rest } = Astro.props;
---
<button
type="button"
hidden
class={className}
data-slot="back-to-top"
data-threshold={threshold}
data-for={target}
{...rest}
>
<slot>Back to top</slot>
</button>
<script>
import { onReady } from "../../_client";
function sync(btn: HTMLElement) {
btn.hidden = window.scrollY <= (Number(btn.dataset.threshold) || 0);
}
// Both listeners are bound at MODULE scope, not per element: the module is an ES singleton, so a
// <ClientRouter /> view transition cannot stack a second scroll listener (and the first would go
// on holding a detached button). This is the ONE primitive that keeps plain `onReady` rather than
// `_once`'s `onReadyOnce`: `sync` binds nothing and starts nothing — it just reads scrollY and sets
// `hidden` — so re-running it after every swap is the point, not a bug. A persisted button whose
// page scrolled back to the top must hide again before the reader's first scroll event.
// passive: neither handler calls preventDefault, and saying so keeps scrolling off the main
// thread's critical path.
window.addEventListener(
"scroll",
() => document.querySelectorAll<HTMLElement>('[data-slot="back-to-top"]').forEach(sync),
{ passive: true },
);
document.addEventListener("click", (event) => {
if (!(event.target instanceof Element)) return;
const btn = event.target.closest<HTMLElement>('[data-slot="back-to-top"]');
if (!btn) return;
const id = btn.dataset.for;
const target = (id && document.getElementById(id)) || document.body;
// tabIndex reads -1 for anything not natively focusable; setting the ATTRIBUTE is what makes it
// programmatically focusable. Writing an attribute, not a class — contract rule 4 is intact.
if (target.tabIndex < 0) target.tabIndex = -1;
target.focus({ preventScroll: true });
window.scrollTo({
top: 0,
behavior: matchMedia("(prefers-reduced-motion: reduce)").matches ? "instant" : "smooth",
});
});
onReady('[data-slot="back-to-top"]', sync);
</script>
import BackToTop from "./BackToTop.astro";
export { BackToTop };
export default BackToTop;
What you get
The component source, copied into your project by npx astrocraft-ui add navigation/back-to-top — no package dependency, no CSS to fight. Whatever the paid blocks compose, this is it.