use-stick-to-bottom

use-stick-to-bottom is a lightweight, zero-dependency React hook and companion component designed for AI chat interfaces, where new messages and streamed tokens continuously grow the message list. It automatically keeps the scroll container pinned to the bottom and smoothly animates content into place, while letting users escape the lock the moment they scroll up.

Built on the modern ResizeObserver API rather than CSS overflow-anchor, it works consistently across browsers (including Safari), handles content that both grows and shrinks, and correctly manages scroll anchoring so off-screen resizes don’t cause visible jumps. A custom velocity-based spring animation makes streaming content feel natural instead of relying on fixed-duration easing.

What You Get

• A useStickToBottom hook that returns scrollRef and contentRef to wire up any existing scroll container
• A ready-made StickToBottom component with a Content subcomponent and React context so children can read isAtBottom and call scrollToBottom
• A custom velocity-based spring scrolling animation with configurable damping, stiffness, and mass
• Automatic user-escape detection that cancels stickiness when the user scrolls up, without debouncing
• Correct scroll-anchoring behavior so content resizing above the viewport doesn’t cause visible jumps

Common Use Cases

• Keeping an AI chatbot conversation pinned to the latest streamed tokens
• Auto-scrolling a live log or terminal output view as new lines arrive
• Maintaining bottom position in a real-time messaging or comments feed
• Adding a scroll-to-bottom button that appears only when the user has scrolled away

Under The Hood

Architecture

The package is split into three source files under src/: useStickToBottom.ts holds the core logic, StickToBottom.tsx wraps it in a component plus React context, and index.ts re-exports both. The hook manages a rich mutable StickToBottomState (scrollTop, targetScrollTop, velocity, escapedFromLock, isAtBottom, and a live ResizeObserver) held in refs to avoid re-renders, and drives a custom animation loop via requestAnimationFrame. A ResizeObserver on the content element detects growth and shrinkage, recomputes the target scroll position, and either snaps or spring-animates toward it; scrollToBottom returns a Promise<boolean> that resolves true on success or false if the scroll is cancelled by the user scrolling up.

Tech Stack

Written in TypeScript (~97% of the codebase) with zero runtime dependencies and a single peer dependency on React (^16.8 through ^19). It builds to ESM with tsc -b and vite-plugin-dts for type declarations, uses Biome for linting/formatting, and ships a Vite + Tailwind demo app. It relies only on standard browser APIs (ResizeObserver, requestAnimationFrame) rather than CSS overflow-anchor.

Code Quality

The code is strongly typed with exported interfaces for state, options, spring parameters, and the context, and uses an isomorphic layout-effect guard for SSR safety. Logic is dense but well-commented, with documented defaults for the spring animation. There is no automated test suite in the repository; correctness is exercised through the interactive demo app rather than unit tests, which is the main quality gap.

API Design

The public surface is deliberately small and ergonomic: a hook returning refs for full control, or a drop-in StickToBottom/StickToBottom.Content component pair plus a useStickToBottomContext hook for children. Options like resize, initial, and per-call scroll behavior are consistently named, and JSDoc on options documents defaults inline, making it approachable for common chat use cases with minimal boilerplate.