@versini/ui-scroll

A semantic and accessible React scroll affordance built with TypeScript and TailwindCSS.

Height-capped regions hide their overflow silently — nothing tells the reader the content keeps going. This package floats a button over a scrolling region whenever there is unreached content toward the edge it points at, and takes the reader there on click.

It ships in three layers so a host can take as much or as little as it needs: a batteries-included wrapper, the button on its own, and the headless hook underneath both.

Table of Contents

• Features
• Installation
• Usage
• API

Features

• 👀 Discoverable overflow: The affordance appears only when there is unreached content toward to, and hides again on arrival
• 🧩 Three layers: Take the whole component, just the button, or just the hook
• ↕️ Both directions: Send a click to the bottom or back to the top — the arrow and the accessible name follow
• 📐 Six corners: Anchor the button at any corner — independently of where a click travels to
• 🎬 Motion-aware: Falls back to an instant jump for readers who asked for reduced motion
• 📏 Self-measuring: Re-measures on scroll, on resize, and on content growth via ResizeObserver
• ♿ Accessible: A real button with an accessible name that keeps focus when it goes idle, instead of vanishing from under the reader who just clicked it
• 🌲 Tree-shakeable: Lightweight and optimized for bundle size
• 🔧 TypeScript: Fully typed with comprehensive prop definitions

Installation

npm install @versini/ui-scroll

Note: This component requires TailwindCSS and the @versini/ui-styles plugin for proper styling. See the installation documentation for complete setup instructions.

Usage

Basic Example

ScrollableContent owns the scrolling element, so the height cap goes in className alongside any prose classes.

import { ScrollableContent } from "@versini/ui-scroll/scrollable-content";

function App() {
  return (
    <ScrollableContent className="max-h-80">
      <LongArticle />
    </ScrollableContent>
  );
}

Choosing a direction

to names the edge a click travels to, and picks the arrow and the default accessible name with it.

// Down arrow, "Scroll to bottom", appears while content sits below the fold.
<ScrollableContent className="max-h-80">{children}</ScrollableContent>

// Up arrow, "Scroll to top", appears once the reader has scrolled away from it.
<ScrollableContent className="max-h-80" to="top">{children}</ScrollableContent>

The two are mirror images, not variants: to="bottom" measures the pixels below the fold and lands on the last one, to="top" measures the pixels already scrolled past and lands on zero. Each goes idle exactly where the other becomes active.

That symmetry has one consequence worth planning for. A down arrow clears itself off on arrival — its distance reaches zero exactly when the reader reaches the bottom. An up arrow does the opposite: its distance is the scroll offset, which is largest at that same resting place, so it is at its most visible sitting over the last lines of text. The component adds no bottom gutter, so reserving one is the host's job — put pb-* in className, or move the button out of the text column with placement="bottom-end".

Both directions over one region

Nothing stops a host from offering both, but the two default to the same corner, so at least one needs an explicit placement or they stack on top of each other. Both are active for most of the scroll range, and with identical positioning the DOM order decides which one is reachable while a screen reader still announces two.

<ScrollButton to="bottom" show={canGoDown} onClick={goDown} />
<ScrollButton to="top" show={canGoUp} onClick={goUp} placement="bottom-end" />

Placing the button

<ScrollableContent className="max-h-80" placement="bottom-end">
  <Changelog />
</ScrollableContent>

placement names a corner as <vertical>-<horizontal>. The horizontal half is logical, not physical, so start and end mirror themselves in a right-to-left document.

It defaults to bottom-center — a fixed corner, not one derived from to. The two props are independent in their defaults as well as when both are set: to picks the arrow and the accessible name, placement picks the corner, and changing one never moves the other.

That matters most when you flip a destination. to="top" on its own gives an up arrow that stays exactly where the down arrow was, rather than jumping to the top of the region. That is not the conventional "back to top" corner — that is bottom-end, and it costs an explicit placement:

// Up arrow, bottom-center. Nothing moved.
<ScrollableContent className="max-h-80" to="top">
  <LongArticle />
</ScrollableContent>

// The conventional back-to-top control.
<ScrollableContent className="max-h-80" to="top" placement="bottom-end">
  <LongArticle />
</ScrollableContent>

Bring your own scrolling element

When the region already exists — or its markup is not yours to change — pair the hook with the button yourself.

import { ScrollButton } from "@versini/ui-scroll/scroll-button";
import { useScrollAffordance } from "@versini/ui-scroll/use-scroll-affordance";

function Panel({ children }) {
  const { containerRef, contentRef, canScroll, scrollToEdge, to } =
    useScrollAffordance();

  return (
    <div className="relative">
      <div ref={containerRef} className="max-h-80 overflow-y-auto">
        <div ref={contentRef}>{children}</div>
      </div>
      <ScrollButton to={to} show={canScroll} onClick={scrollToEdge} />
    </div>
  );
}

The hook and the button take to as two independent props, and nothing keeps them in step for you. Hand the hook's to straight to the button, as above — leave it off and a hook pointed at the top still renders a down arrow announcing "Scroll to bottom", which type-checks and lints clean.

Bring your own everything

Some regions do not scroll to a plain edge — a chat log may want to land on the newest message rather than the last pixel, and its button may be pinned above a floating footer rather than inside the region. placement="none" drops every positioning class so the host keeps full control of both.

import { ScrollButton } from "@versini/ui-scroll/scroll-button";

function Chat() {
  return (
    <>
      <MessageList />
      <div className="fixed left-1/2 -translate-x-1/2" style={{ bottom }}>
        <ScrollButton
          placement="none"
          show={!inViewport && !streaming}
          onClick={scrollToNewestMessage}
          label="Scroll to the latest message"
        />
      </div>
    </>
  );
}

API

ScrollableContent Props

| Prop | Type | Default | Description | | ---------------- | ------------------- | ----------------- | ---------------------------------------------------------------- | | children | React.ReactNode | required | The scrolling content | | className | string | — | Merged onto the scrolling element — where the height cap belongs | | wrapperClassName | string | — | Merged onto the outer positioned wrapper the button anchors to | | to | "bottom" \| "top" | "bottom" | The edge a click travels to | | placement | ScrollAnchor | "bottom-center" | The corner to anchor the button against | | threshold | number | 8 | Slack, in px, before the region counts as scrollable | | label | string | — | Accessible name for the button; defaults to one describing to | | buttonClassName | string | — | Merged onto the button |

ScrollButton Props

| Prop | Type | Default | Description | | --------- | ------------------------ | ----------------- | ---------------------------------------------------------------------------------- | | onClick | () => void | required | Called when the button is activated | | to | "bottom" \| "top" | "bottom" | The edge the arrow points at — picks the icon and default label | | show | boolean | true | false fades it out and drops it from the tab sequence (stays mounted, see below) | | placement | ScrollAnchor \| "none" | "bottom-center" | Corner to anchor against; "none" lets the host place it | | label | string | — | Accessible name; defaults to one describing to | | className | string | — | Merged onto the button, never a replacement for its own classes |

Why show={false} does not unmount

The button keeps its place in the DOM when idle. Unmounting it dropped keyboard focus to <body> on every successful click: the button holds focus, the scroll it triggers reaches the edge, and the control the user just activated disappeared from under them.

Idle means opacity-0, pointer-events-none, tabIndex={-1}, and aria-disabled, with onClick guarded so it cannot fire. Deliberately not aria-hidden or display: none — hiding an element that currently holds focus is its own violation, and both would drop focus exactly the way unmounting did.

ScrollEdge

type ScrollEdge = "bottom" | "top";

ScrollAnchor

type ScrollAnchor =
  | "top-start" | "top-center" | "top-end"
  | "bottom-start" | "bottom-center" | "bottom-end";

useScrollAffordance(options)

| Option | Type | Default | Description | | --------- | ------------------- | ---------- | ---------------------------------------------------- | | to | "bottom" \| "top" | "bottom" | The edge to measure against and travel to | | threshold | number | 8 | Slack, in px, before the region counts as scrollable |

Returns:

| Key | Type | Description | | ------------ | ----------------------------------------- | -------------------------------------------------------------------------- | | containerRef | React.RefObject<HTMLDivElement \| null> | Attach to the element that scrolls | | contentRef | React.RefObject<HTMLDivElement \| null> | Optional. Attach inside the container to catch content growth | | canScroll | boolean | Whether there is more than threshold px of unreached content toward to | | scrollToEdge | () => void | Travel to to, smoothly unless the reader asked for reduced motion | | to | "bottom" \| "top" | The edge being measured, resolved to its default. Pass to ScrollButton |