Setting the file. One moment.
Subchapter 2.8
rules/chat.mdMarkdown7 KBView on GitHub
Components for conversation and chat UI. Compose these instead of hand-rolling bubbles, scroll containers, dividers, or attachment cards.
Install: npx shadcn@latest add message-scroller message bubble attachment marker
The same component names and props ship for both base and radix; only
composition differs (render vs ). See .
asChildA conversation that scrolls, follows new messages, restores position, or jumps
to a message uses MessageScroller. Don’t build a raw overflow container with
manual scroll wiring, and don’t reach for ScrollArea.
The parts nest in a fixed order. Every direct child of the content is wrapped in
a MessageScrollerItem so the scroller can measure, anchor, preserve position,
track visibility, and jump to it. MessageScrollerButton sits inside
MessageScroller, after the viewport.
Incorrect:
// Hand-rolled scroll container with manual stick-to-bottom logic.
<div ref={scrollRef} onScroll={handleScroll} className="flex-1 overflow-y-auto">
<div className="flex flex-col gap-6 p-4">
{messages.map((m) => (
<ChatMessage key={m.id} message={m} />
))}
</div>
</div>Correct:
<MessageScrollerProvider autoScroll>
<MessageScroller>
<MessageScrollerViewport>
<MessageScrollerContent>
{messages.map((message) => (
<MessageScrollerItem
key={message.id}
messageId={message.id}
scrollAnchor={message.role === "user"}
>
<Message align={message.role === "user" ? "end" : "start"}>
{/* ...message content... */}
</Message>
</MessageScrollerItem>
))}
</MessageScrollerContent>
</MessageScrollerViewport>
<MessageScrollerButton />
</MessageScroller>
</MessageScrollerProvider>Message lays out a single row: avatar, header, content, footer, with
alignment. Group consecutive rows from one sender with MessageGroup. Don’t
rebuild the row from flex divs.
align="end" is the current user’s side; align="start" is everyone else.
<Message align="start">
<MessageAvatar>
<Avatar>
<AvatarImage src={sender.avatar} alt={sender.name} />
<AvatarFallback>{initials}</AvatarFallback>
</Avatar>
</MessageAvatar>
<MessageContent>
<MessageHeader>{sender.name}</MessageHeader>
<Bubble>
<BubbleContent>{text}</BubbleContent>
</Bubble>
<MessageFooter>{time}</MessageFooter>
</MessageContent>
</Message>The colored message surface is Bubble + BubbleContent, never a styled div
with bg-muted / bg-primary and hand-managed corners.
variant: default, secondary, muted, tinted, outline, ghost, destructive.align: start or end (matches the Message side).BubbleReactions renders the reaction cluster. side (top | bottom) and
align (start | end) position it against the bubble. Don’t lay reactions out
with absolutely-positioned Badges.
Incorrect:
<div className="w-fit rounded-2xl bg-primary px-3 py-2 text-primary-foreground">
{text}
</div>Correct:
<Bubble variant="default" align="end">
<BubbleContent>{text}</BubbleContent>
<BubbleReactions side="bottom" align="end">
<Badge variant="secondary">👍 2</Badge>
</BubbleReactions>
</Bubble>File and image attachments use Attachment, not Item or a custom card. It
carries upload state, so wire state to the real status rather than rendering a
separate spinner.
state: idle, uploading, processing, error, done. uploading and
processing apply the shimmer animation to the title automatically.size: default, sm, xs. orientation: horizontal, vertical.AttachmentGroup to lay out several attachments in a scrolling row.<Attachment state="done">
<AttachmentMedia variant="icon">
<FileTextIcon />
</AttachmentMedia>
<AttachmentContent>
<AttachmentTitle>homepage-feedback.pdf</AttachmentTitle>
<AttachmentDescription>PDF · 2.4 MB</AttachmentDescription>
</AttachmentContent>
<AttachmentActions>
<AttachmentAction>
<DownloadIcon />
</AttachmentAction>
</AttachmentActions>
</Attachment>For an image, use <AttachmentMedia variant="image"> with an img child.
Status lines (“Sarah joined the conversation”), date dividers (“Today”), and
labeled separators are Marker, not a Separator plus a centered span.
variant: default (plain row), separator (centered label with rules on
each side), border (bottom-bordered row).MarkerIcon holds a leading icon; MarkerContent holds the label.Incorrect:
<div className="flex items-center gap-3 py-2">
<Separator className="flex-1" />
<span className="text-xs text-muted-foreground">Today</span>
<Separator className="flex-1" />
</div>Correct:
<Marker variant="separator">
<MarkerContent>Today</MarkerContent>
</Marker>MessageScroller handles the behavior that chat UIs usually reinvent. Don’t
write a useStickToBottom hook, a ResizeObserver, or manual scrollTop math.
MessageScrollerProvider with
autoScroll keeps the view pinned to new content and yields the moment the
user scrolls up. Streaming token updates that grow the last message are
followed automatically.scrollAnchor on a MessageScrollerItem marks the row to
hold in view (typically the user’s message that started the turn).MessageScrollerButton appears when the user scrolls away
and scrolls back on click. direction="end" (default) or direction="start".
It is a self-managing control, so don’t gate it behind your own scroll-position
state.For a “thinking…” indicator while the model generates, apply the shimmer
utility to text. Don’t author a custom keyframe animation. See
styling.md.
For behavior the parts don’t expose, read state from the hooks rather than
re-implementing the scroller: useMessageScroller,
useMessageScrollerVisibility, and useMessageScrollerScrollable. They come
from the auto-installed @shadcn/react dependency, so there’s nothing extra to
install. Reach for them only when composition can’t express what you need.