Skip to content

Conversation

A scrolling thread of messages that follows a reply as it streams in.

Installation

  1. Add the registryOnce per project
  2. Add conversation

Usage

A conversation opens at its latest message. While someone is scrolled to the bottom, it follows a reply as it streams in. If they scroll up, it keeps their place until they scroll back down or press ConversationScrollButton. The button shows whenever there's more below and the conversation isn't following. The messages fade out under the button, and content focused with the keyboard scrolls clear of the fade. Pressing the button from the keyboard moves focus to the messages, since the button hides once they're at the bottom.

Opening or closing something in a message, such as a Trace or a Tool, keeps the pressed control in place rather than scrolling to follow the revealed content to the bottom, even in the latest message.

Mark the start of each turn, usually the person's message, with anchor. When an anchored item is added, it settles anchorOffset pixels below the top, and the reply fills the space below it rather than pushing it out of view. Once the reply fills that space, the conversation follows it again.

Give Conversation a height, or put it in a flex column where it can grow. It never grows wider than its container, so a long line wraps or scrolls inside its message rather than widening the page. The scrolling area is a region labeled "Messages" that can be scrolled with the keyboard. Change its label through viewportProps. The conversation inherits its parent's corner radius, so its focus ring follows the corners of a rounded card.

ConversationContent has the log role, so screen readers announce new messages. Set aria-busy on it while a reply is submitted or streaming, as in the example above. Otherwise screen readers read each paragraph as it begins rather than the whole reply. Clear aria-busy once the reply ends, including when it fails, or the log stays silent. Not every screen reader announces what changed while the log was busy once it clears, so also announce the finished reply in a polite status region. The example at the top of the page does this with a visually hidden role="status" element.

Composition

Examples

Loading earlier messages

When messages are added above the ones in view, such as older messages loaded on request, the conversation keeps the message someone was looking at in place rather than letting the new ones push it down. Messages marked anchor that are added above don't move it either.

Set aria-busy on ConversationContent while the messages load and until one frame after they render, so screen readers don't announce the history as new messages. If the button that loaded them disappears, move focus to the first loaded message, using tabIndex={-1} and preventScroll. Keyboard navigation then continues from the start of the history without scrolling the view.

Props

Base UI's styling (opens in a new tab) and composition (opens in a new tab) guides say more about className, style and render.

Conversation

ConversationContent

ConversationItem

ConversationScrollButton

useConversation

useConversation() reads the Conversation that your part renders in, and returns: