Message Scroller

Message Scroller manages scrolling for conversation views. MessageScrollerProvider creates the scroll controller and holds options such as the initial position and auto-scroll. Inside it, MessageScroller is the root, MessageScrollerViewport is the scrollable region, and MessageScrollerContent lists one MessageScrollerItem per message. MessageScrollerButton sits inside the root and jumps to the start or end.

The scroller opens at the end by default, preserves the reading position when older messages are prepended, and can anchor a newly added message to the top of the viewport. Use it for chat and activity feeds; use Scroll Area for general scrollable content.

Installation

CLI

$ pnpm dlx shadcn@latest add @esuiss/message-scroller

Works in any project with a components.json. See Installation for the one-line registry setup. Or use the suiss/ui CLI:

$ pnpm dlx @esuiss/ui@latest add message-scroller

Manual

1. Install the dependencies and add the cn helper:

$ pnpm add @base-ui/react @phosphor-icons/react

2. Add the pieces it builds on: Button, Scroll Area, use-message-scroller.

3. Copy the source into components/ui/message-scroller.tsx:

4. Update the import paths to match your project.

Usage

import { MessageScrollerProvider, MessageScroller, MessageScrollerViewport, MessageScrollerContent, MessageScrollerItem, MessageScrollerButton } 

<div

Place every part inside MessageScrollerProvider; the components and hooks throw outside of it. Provider options:

• defaultScrollPosition: "end" (default), "start", or "last-anchor" to open at the last item marked with scrollAnchor.
• autoScroll: when true, follows new content at the bottom until the user scrolls away. Defaults to false.
• scrollEdgeThreshold, scrollPreviousItemPeek and scrollMargin: pixel values that tune edge detection and anchoring (defaults 8, 64 and 0).

Give each item a stable messageId so it can be targeted programmatically. The exported useMessageScroller hook returns scrollToEnd, scrollToStart and scrollToMessage; useMessageScrollerScrollable reports whether each edge can scroll, and useMessageScrollerVisibility reports the visible message IDs.

Examples

Start at top

A scroller that opens at the first message with defaultScrollPosition="start", with buttons for both directions.

API Reference

Accessibility

• The viewport has role="region", an aria-label of Messages by default, and tabIndex={0} so it can be scrolled with the keyboard.
• The content has role="log" with aria-relevant="additions", so assistive technology can announce new messages.
• MessageScrollerButton includes a visually hidden label, Scroll to end or Scroll to start. While it cannot scroll, the button is inert and removed from the tab order.
• Wheel, touch and scrolling keys stop auto-follow so the user's reading position is respected.

Notes

• Styling hooks: data-slot values message-scroller, message-scroller-viewport, message-scroller-content, message-scroller-item and message-scroller-button.
• The root and viewport receive data-pending-scroll until the initial position is applied; the viewport is invisible during that time. They also get data-scrollable with the scrollable edges and data-autoscrolling while a programmatic scroll is running.
• The button exposes data-active, data-direction, data-variant and data-size. It defaults to the secondary variant and icon-sm size of Button.
• Items set data-scroll-anchor and use content-visibility: auto to keep long transcripts fast.

MessageScroller is a View that hosts a scroll controller. MessageScrollerViewport renders your messages in an inverted FlatList, so the newest message sits at the bottom and new messages keep the list anchored there through maintainVisibleContentPosition. You pass data in chronological order; the viewport reverses it internally and maps indexes back for renderItem and keyExtractor.

MessageScrollerButton is a floating icon button that animates in with Reanimated when there is more content in its direction. When the user has scrolled up and new messages arrive, it shows an unread count badge.

Installation

$ pnpm dlx shadcn@latest add @esuiss-rn/message-scroller

$ pnpm dlx @esuiss/ui@latest add message-scroller

$ pnpm dlx @esuiss/ui@latest add message-scroller --platform swift