# Chat Thread
> Lay out a conversation that scrolls, with a place for the composer under it.
Source: https://ai.honestui.com/docs/components/chat-thread
```tsx
"use client"
import * as React from "react"
import { ChatMessage, ChatThread } from "@/components/ai/chat-thread"
import { PromptBar } from "@/components/ai/prompt-bar"
type Message = { id: number; role: "user" | "assistant"; text: string }
// Sample conversation.
const sampleMessages: Message[] = [
{ id: 1, role: "user", text: "Why are export totals off by a cent?" },
{
id: 2,
role: "assistant",
text: "Each row is rounded before the rows are summed. Rounding once, after the sum, removes the drift.",
},
]
/** No model replies here. A sent prompt is added to the thread as a user message. */
export function ChatThreadDemo() {
const [messages, setMessages] = React.useState(sampleMessages)
return (
)
}
```
## Overview [#overview]
Chat Thread is the frame of a chat: a scrolling list of messages and a slot under it for the composer. Put a [Prompt Bar](/docs/components/prompt-bar) in the footer and render one `ChatMessage` for each message you hold.
A message can also show the files sent with it, an editor for changing and resending it, and arrows for moving between its versions. Each appears only when you pass the props for it.
It stores no messages and sends nothing. Your application owns the conversation.
Chat Thread replaces the Chat panel from Beautiful UI, which played a scripted reply.
## Anatomy [#anatomy]
Installing `chat-thread` brings [Button](https://www.honestui.com/docs/components/button) along as a registry dependency.
## Behavior [#behavior]
### Scrolling [#scrolling]
When a message is added, the thread scrolls to it. If the person has scrolled up to read, the thread leaves their position alone until they return to the end.
### Messages [#messages]
A `user` message sits in a bubble on the trailing side. An `assistant` message is plain text with its author above it. Message content is yours: text, [Streaming Text](/docs/components/streaming-text), [Tool Chips](/docs/components/tool-chips), or any other component. Set `announce` to `false` on a Streaming Text inside the thread, because the log already announces new text.
### Attachments [#attachments]
`attachments` lists the files that were sent with a message, above it. Each has a name and can have a short note, such as its size. Passing `href` makes the name a link. Chat Thread does not read, upload, or preview the files.
### Editing [#editing]
Passing `editText` and `onEdit` adds an Edit button under the message. `editText` is the message as plain text, because the message's children may be elements. Edit swaps the message for a text area holding that text, with Cancel and Send.
Send calls `onEdit` with the trimmed text and waits for it. If the promise you return rejects, or the handler throws, the editor stays open with the person's changes and an error line. When it resolves, the editor closes. Send is disabled while the text is empty.
What an edit does to the conversation is your application's decision. Most products send the edited text as a new version of the message and discard the replies that followed the old one. If yours does, say so near the editor, since `onEdit` gives no warning of it.
The Edit button is always visible, so it does not depend on hover.
### Versions [#versions]
Editing a message, or asking for a reply again, leaves more than one version of it. Pass `version`, counting from 1, and `versionCount`. When there is more than one version, the message shows arrows and its position, such as "2 of 3". The arrows call `onVersionChange` with the version to show. Rendering that version's content is your application's work.
### Empty [#empty]
With no messages, `emptyMessage` is centered in the thread.
### Height [#height]
The thread fills its parent's height. Give the parent a height, or the thread will grow with its content and never scroll.
## Accessibility [#accessibility]
The message list is a log named by `label`, so screen readers announce messages as they are added, in order. It can take focus, so it can be scrolled from the keyboard.
Every message has an author. On user messages the author is read but not shown. Set `hideAuthor` to do the same for an assistant message.
Attachments are a list named "Attachments". Edit and the two version arrows are buttons with names, and an arrow that has nowhere to go is marked disabled but keeps focus. The editor is a text area named "Message". Opening it moves focus into it, and closing it returns focus to Edit. A failed send is an alert.
Every string in a message comes from its `labels`.
The previews have been checked with a keyboard and with axe. They have not been checked with a screen reader yet. The editor opens inside the log, and screen readers differ in how they announce a change there.
| Key | Action |
| ----------------------------------- | ------------------------------------------------ |
| Tab | Move to the message list, then into the composer |
| Arrow keys | Scroll the focused message list |
| Enter | Send the edit, from the editor |
| Shift + Enter | Add a line in the editor |
| Escape | Close the editor and discard the changes |
## Installation [#installation]
Add the component it is built from.
Copy and paste this file into your project.
### components/ai/chat-thread.tsx
```tsx
"use client"
import * as React from "react"
import {
ChevronLeft as ChevronLeftIcon,
ChevronRight as ChevronRightIcon,
CircleAlert as CircleAlertIcon,
File as FileIcon,
Pencil as PencilIcon,
} from "honestui/icons"
import { cn } from "@/lib/utils"
import { Button } from "@/components/ui/button"
export type ChatThreadProps = React.ComponentProps<"div"> & {
/** Names the conversation for screen readers. */
label: string
/** Shown while there are no messages. */
emptyMessage?: React.ReactNode
/** Fixed under the messages. Put your Prompt Bar here. */
footer?: React.ReactNode
}
/**
* A scrolling conversation with a slot for the composer under it. It keeps
* the newest message in view unless the person has scrolled up to read.
*/
function ChatThread({
label,
emptyMessage,
footer,
className,
children,
...props
}: ChatThreadProps) {
const scrollRef = React.useRef(null)
const isPinnedToEnd = React.useRef(true)
const messageCount = React.Children.count(children)
React.useEffect(() => {
const scroller = scrollRef.current
if (scroller && isPinnedToEnd.current) scroller.scrollTop = scroller.scrollHeight
})
return (
{/* A log announces messages as they are added, in order. Focusable so it can be scrolled by keyboard. */}
{
const scroller = event.currentTarget
isPinnedToEnd.current =
scroller.scrollHeight - scroller.scrollTop - scroller.clientHeight < 24
}}
// `relative` keeps absolutely positioned content, such as visually hidden
// labels, inside this scroller. Without it they extend the page instead.
className="relative flex min-h-0 flex-1 flex-col gap-[var(--hui-space-5)] overflow-y-auto p-[var(--hui-space-5)] outline-none focus-visible:[outline:var(--hui-focus-ring)] focus-visible:outline-offset-[var(--hui-focus-ring-offset-inset)]"
>
{messageCount === 0 && emptyMessage ? (
{emptyMessage}
) : (
children
)}
{footer && (
{footer}
)}
)
}
export type ChatAttachment = {
name: string
/** Makes the name a link to the file. */
href?: string
/** A short note after the name, such as "48 KB". */
meta?: string
}
export type ChatMessageLabels = {
attachments: string
edit: string
editField: string
cancel: string
resend: string
editError: string
previousVersion: string
nextVersion: string
version: (current: number, total: number) => string
}
export const defaultChatMessageLabels: ChatMessageLabels = {
attachments: "Attachments",
edit: "Edit message",
editField: "Message",
cancel: "Cancel",
resend: "Send",
editError: "The edit was not sent. Your changes are still here.",
previousVersion: "Previous version",
nextVersion: "Next version",
version: (current, total) => `${current} of ${total}`,
}
const MAX_EDITOR_HEIGHT = 240
const smallText =
"[font-size:var(--hui-font-size-small)] [letter-spacing:var(--hui-letter-spacing-small)] [line-height:var(--hui-line-height-small)]"
export type ChatMessageProps = React.ComponentProps<"div"> & {
/** "user" sets the message in a bubble on the trailing side. */
role: "user" | "assistant"
/** Who is speaking, read before the message. Shown above assistant messages. */
author: string
/**
* Hides the author and `meta` line from view. It is still read aloud, so a
* screen reader can tell who is speaking. A user message always hides it.
*/
hideAuthor?: boolean
/** A short note beside the author, such as a time or a duration. */
meta?: string
/** The files sent with the message, listed above it. */
attachments?: ChatAttachment[]
/** The message as plain text, which fills the editor. Edit needs it and `onEdit`. */
editText?: string
/** Receives the edited text. Throw, or reject, to report that it was not sent. */
onEdit?: (text: string) => void | Promise
/** Which version of the message is shown, counting from 1. */
version?: number
/** How many versions exist. More than one shows the buttons to move between them. */
versionCount?: number
onVersionChange?: (version: number) => void
labels?: Partial
}
/**
* One message in a `ChatThread`, with its attachments, an editor, and a way
* to move between its versions. Each of those appears only when you pass it.
*/
function ChatMessage({
role,
author,
hideAuthor = false,
meta,
attachments = [],
editText,
onEdit,
version,
versionCount = 1,
onVersionChange,
labels: labelsProp,
className,
children,
...props
}: ChatMessageProps) {
const labels = { ...defaultChatMessageLabels, ...labelsProp }
const isUser = role === "user"
const canEdit = editText !== undefined && onEdit !== undefined
const hasVersions = version !== undefined && versionCount > 1
const [isEditing, setIsEditing] = React.useState(false)
const [draft, setDraft] = React.useState("")
const [phase, setPhase] = React.useState<"idle" | "sending" | "error">("idle")
const editorRef = React.useRef(null)
const editButtonRef = React.useRef(null)
const hasEdited = React.useRef(false)
// Opening the editor replaces the Edit button, and closing it brings the
// button back. Focus follows, so it is never left on a removed control.
React.useEffect(() => {
if (isEditing) {
const editor = editorRef.current
editor?.focus()
editor?.setSelectionRange(editor.value.length, editor.value.length)
hasEdited.current = true
} else if (hasEdited.current) {
editButtonRef.current?.focus()
}
}, [isEditing])
React.useLayoutEffect(() => {
const editor = editorRef.current
if (!editor) return
// Grow with the text up to a limit, then scroll.
editor.style.height = "0px"
editor.style.height = `${Math.min(editor.scrollHeight, MAX_EDITOR_HEIGHT)}px`
editor.style.overflowY = editor.scrollHeight > MAX_EDITOR_HEIGHT ? "auto" : "hidden"
}, [draft, isEditing])
const startEditing = () => {
setDraft(editText ?? "")
setPhase("idle")
setIsEditing(true)
}
const text = draft.trim()
const isSending = phase === "sending"
const sendEdit = async () => {
if (!onEdit || text === "" || isSending) return
setPhase("sending")
try {
await onEdit(text)
setPhase("idle")
setIsEditing(false)
} catch {
setPhase("error")
}
}
return (