#Back to Bottom

Back to Bottom appears only in an append-only scroll region, letting people return to the live edge without losing the number of updates that arrived while they read earlier content.

npm install @a3s-lab/ui@0.4.0

<div class="transcript-viewport" data-scroll-owner>
  <ol aria-label="Run output">
    <li>Dependency checks completed.</li>
    <li>Documentation build started.</li>
  </ol>
  <button type="button" class="back-to-bottom" data-unread="3">
    <span data-back-to-bottom-label>Return to latest output</span>
    <span data-unread-count>3</span>
  </button>
</div>

import "@a3s-lab/ui/a3s.css";
import "@a3s-lab/ui/all";

#Usage

Place the button inside the element that truly owns scrolling. The controller appears when the distance from the live edge exceeds the threshold or unread updates exist. Reserve data-always-visible for demonstrations and diagnostics.

<div class="transcript-viewport" data-scroll-owner>
  <ol aria-label="Run output">
    <li>Dependency checks completed.</li>
    <li>Documentation build started.</li>
  </ol>
  <button type="button" class="back-to-bottom" data-unread="3">
    <span data-back-to-bottom-label>Return to latest output</span>
    <span data-unread-count>3</span>
  </button>
</div>

For on-demand loading, import the shared runtime before the controller.

import "@a3s-lab/ui/runtime";
import "@a3s-lab/ui/back-to-bottom";

const button = document.querySelector(".back-to-bottom");

button.addEventListener("a3s:back-to-bottom-activate", () => {
  markVisibleUpdatesAsRead();
});

button.setUnread(3);

#Parameters

#JavaScript API

#States and variants

hidden means the reader remains at the live edge with no unread updates. visible means the reader moved away from the end. unread means new content is waiting. New content increments the count without scrolling. A deliberate return clears the count and respects prefers-reduced-motion.

Use this action only for an independently scrolling, append-only region such as run output, a conversation transcript, or an event stream. Short lists, static articles, and page-level scrolling do not need it.

#Accessibility

Use a native button with a clear action name. Keep the unread count visible and explain its meaning through the button name or accessible text on data-unread-count; an isolated number is not enough. New content must not steal focus or force scrolling. If the product has another live-announcement region, do not announce each update again through this control. The button controls only its owning scroll region and leaves the tab order when hidden. The host owns transport, read receipts, virtualization, and business counts; the component owns scroll position, visibility, and return intent.