Chat

Chat is the whole conversation: a fixed header, the flexible transcript and a fixed composer. The transcript is a MessageScroller, each turn is a Message around a Bubble, and the field is ChatComposer. The transport is yours; the status machine is shared so the composer and the header cannot disagree.

Every turn wears a bubble — the reader's on the default fill and the end edge, the agent's muted on the start — and the row supplies the avatar, author and timestamp. Only the row that starts a run paints its avatar and meta line; the rows after it are a MessageGroup (6px apart) whose bubbles name group="first" and group="last" so their inner corners join.

InstallationCopy Anchor Link

nub add @gpuixui/components

UsageCopy Anchor Link

import {
  Bubble,
  BubbleContent,
  ChatComposer,
  ChatHeader,
  ChatMessages,
  ChatRoot,
  Message,
  MessageAvatar,
  MessageContent,
  MessageHeader,
  chatMove,
} from "@gpuixui/components";

<ChatRoot
  status={status}
  onStatusChange={setStatus}
  onSubmit={send}
  onStop={stop}
  onRetry={retry}
>
  <ChatHeader title="Release thread" />
  <ChatMessages>
    {messages.map((message) => (
      <Message key={message.id} variant={message.role} timestamp={message.at}>
        <MessageAvatar />
        <MessageContent streaming={message.streaming}>
          <MessageHeader />
          <Bubble
            align={message.role === "user" ? "end" : "start"}
            variant={message.role === "user" ? "default" : "muted"}
            group={message.group}
          >
            <BubbleContent>{message.body}</BubbleContent>
          </Bubble>
        </MessageContent>
      </Message>
    ))}
  </ChatMessages>
  <ChatComposer hint="Enter sends · Shift+Enter adds a line" />
</ChatRoot>;

CompositionCopy Anchor Link

ChatRoot
├── ChatHeader
├── ChatMessages        the MessageScroller
│   ├── MessageScrollerViewport
│   │   └── MessageScrollerContent
│   │       └── MessageScrollerItem
│   └── MessageScrollerJumpToLatest
└── ChatComposer

The fixed rowsCopy Anchor Link

ChatRoot is a column whose middle grows. ChatHeader and ChatComposer do not shrink; ChatMessages is flex: 1 1 0 with min-height: 0, so a row arriving, a reply streaming or the jump control appearing changes nothing above or below the transcript. Give ChatRoot a bounded height — directly, or through a sized flex parent — because the transcript needs one to scroll.

The passed-in ChatMessages children are rows. Wrap each turn in a Message (or a MessageGroup for consecutive rows from one sender). A Bubble is always a child of MessageContent; the message never builds one.

StatusCopy Anchor Link

The four states are idle, submitting, streaming and error, and chatMove is the only rule set. Send is refused while a reply is open, the refused draft stays in the field, Stop emits the stop intent, and Escape stops a reply. The header announces the state; the failure sentence replaces the status line in place, so a failed reply does not take height from the transcript.

While a reply is openCopy Anchor Link

• Send is replaced by Stop.
• Enter still arrives as the field's image submit; the machine refuses it, so the draft is kept.
• A reply's row can grow token by token; the transcript follows it only while the reader is at the end.

Failed repliesCopy Anchor Link

The failure copy is one line in the header with the full sentence in aria-description; Retry is beside it. It used to be a row between the viewport and the composer, which shrank the viewport when it appeared — the layout shift this release removes.

APICopy Anchor Link

ChatMessages is also the transcript's public seam: render MessageScrollerItem rows inside it (through Message) and pass MessageScrollerItem scrollAnchor on a turn's first row if you want that turn placed near the top.

Edit this page on GitHubpackages/components/docs/chat.mdx