Message scroller
A chat scroll area that follows new messages, keeps your place while you read back, and counts what you missed on the jump button.
- Chat UI components
- 6 parts
- 6 examples
- vs shadcn/ui
@shadcn/react@tabler/icons-react
See it in a real product: Chat Thread and Image Studio
View blockNew chat
How can I help you today?
The prompt is read only. Press send to play the next turn.
pnpm dlx shadcn@latest add https://hextaui.com/r/message-scroller.jsonAdds the component, the HextaUI theme tokens and any HextaUI components it depends on.
Add the theme tokens to your global CSS, if you haven’t yet.
Install the dependencies.
pnpm add @shadcn/react @tabler/icons-react cnCopy and paste the following code into your project.
components/ui/message-scroller.tsx components/ui/button.tsx lib/motion.ts Update the import paths to match your project setup.
Give every item a stable messageId. The scroller uses it to follow new messages, keep your place and count what you haven't seen. Pair it with <Message /> and <Bubble /> for the rows.
Anchors don't have to be messages. Here a <Marker /> for someone joining starts the turn. Scroll up, receive messages, and the jump button counts what arrived while you were away.
scrollPreviousItemPeek keeps a slice of the previous turn above a newly anchored one, so the thread still feels continuous. Try each amount, then ask the next question.
defaultScrollPosition="last-anchor" reopens a conversation at its last question, with the answer below, instead of dropping the reader mid-answer at the bottom.
Older messages added above keep what you're reading in place (preserveScrollOnPrepend, on by default).
useMessageScroller drives the thread from outside it, and useMessageScrollerVisibility reports the current turn, so the outline highlights where you are.
Inside the provider, these hooks let your own controls scroll the thread and react to what's on screen.
| Key | Action |
|---|---|
| Tab | Focuses the conversation. The jump button joins the tab order only while it's showing. |
| ↑↓ | Scrolls the conversation. |
| Page UpPage Down | Scrolls by a screen. |
| HomeEnd | Jumps to the first or latest message. |
- The viewport is a labelled, focusable region and the content is a
role="log", so screen readers announce new messages as they arrive. Give the viewport anaria-label. - The jump button's label says how many messages are new, so "3 new messages" is read out, not just an arrow.
- Following new messages never moves you while you're reading back. It only resumes once you're at the bottom again.
| Prop | Type | Default |
|---|---|---|
autoScrollFollow new messages while the reader is at the bottom. | boolean | false |
defaultScrollPositionWhere the thread opens. | "start" | "end" | "last-anchor" | "end" |
scrollPreviousItemPeekHow much of the previous item stays visible above a new anchor. | number | 64 |
scrollEdgeThresholdPixels from an edge that still count as at it. | number | – |
scrollMarginSpace kept above messages scrolled into view. | number | – |
| Prop | Type | Default |
|---|---|---|
preserveScrollOnPrependKeep the reading position when messages are added above. | boolean | false |
aria-labelNames the conversation region. | string | – |
| Attribute | Description |
|---|---|
data-scrollable="start end" | Which edges have more to scroll. Drives the edge fades. |
data-autoscrolling | Present while following new messages. The scrollbar hides. |
--scroller-fade-start / --scroller-fade-end | Size of the edge fades. They animate in and out. |
| Prop | Type | Default |
|---|---|---|
messageIdStable id for following, anchors and counts. | string | – |
scrollAnchorScroll this item to the top when it arrives, with defaultScrollPosition="last-anchor". | boolean | false |
| Prop | Type | Default |
|---|---|---|
direction | "start" | "end" | "end" |
showUnseenGrow into a pill that counts messages that arrived while you were scrolled up. | boolean | true |
unseenLabel | (count: number) => ReactNode | "3 new messages" |
variant | Button variant | "outline" |
behavior | ScrollBehavior | "smooth" |
| Attribute | Description |
|---|---|
data-slot="message-scroller-button" | Target the button in CSS. |
data-active | "true" while there's somewhere to jump to. |
data-unseen | The unseen count, while it's above zero. |
- ButtonButtons in every variant and size, with a built-in loading, success and error flow that skips the spinner for fast requests.
- MotionThe easing curves, durations and reduced-motion check every component animates with, plus hooks for size morphs and sliding highlights.
- MessageA chat message row with an avatar, name, bubbles and status, where new messages rise in from the sender's side.
- AttachmentFile and image cards for uploads, with progress, states, actions, a full-card trigger and names that keep their extension.
- BubbleChat message bubbles with variants, grouped corners, reactions and room for interactive content.
- MarkerQuiet notes between content, like date dividers and system events, with sticky dates and times that read as Today or Yesterday.
Used in Pro blocks
Blocks that build on Message scroller.
Every block comes with HextaUI Pro, and Prompt Input is free.