Chat

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

# Add this component (its dependencies come along)
npx koalaui-cli@latest add chat

Usage#

Anatomy#

Every part is a named export, never dot-notation, so each one crosses the server and client boundary cleanly. Conversation is the scrollable thread; each Message carries its role to its parts through context, so one prop drives the side, tint, and meta alignment. Compose only the parts a turn needs.

import {
  Conversation,
  ConversationScrollButton,
  Message,
  MessageAvatar,
  MessageBody,
  MessageHeader,
  MessageName,
  MessageTime,
  MessageReasoning,
  MessageReasoningTrigger,
  MessageReasoningContent,
  MessageReasoningStep,
  MessageReasoningFiles,
  MessageReasoningFile,
  MessageReasoningFilesMore,
  MessageReasoningQueries,
  MessageReasoningQuery,
  MessageReasoningSources,
  MessageReasoningSource,
  MessageContent,
  MessageTyping,
  MessageActions,
  MessageAction,
} from "@/components/ui/chat"

<Conversation>
  <Message>
    <MessageAvatar />
    <MessageBody>
      <MessageHeader>
        <MessageName />
        <MessageTime />
      </MessageHeader>
      <MessageReasoning>
        <MessageReasoningTrigger />
        <MessageReasoningContent>
          <MessageReasoningStep>
            <MessageReasoningQueries>
              <MessageReasoningQuery />
            </MessageReasoningQueries>
            <MessageReasoningSources>
              <MessageReasoningSource />
            </MessageReasoningSources>
            <MessageReasoningFiles>
              <MessageReasoningFile />
              <MessageReasoningFilesMore />
            </MessageReasoningFiles>
          </MessageReasoningStep>
        </MessageReasoningContent>
      </MessageReasoning>
      <MessageContent>
        <MessageTyping />
      </MessageContent>
      <MessageActions>
        <MessageAction />
      </MessageActions>
    </MessageBody>
  </Message>
  <ConversationScrollButton />
</Conversation>

Roles#

A message's role is the only switch. assistant aligns left with an avatar and a muted bubble; user aligns right with a solid blue bubble. Both use a soft, uniform radius on all four corners.

With avatar (bubble)#

The default is the document style above. For a chat with an identity, the “robotized” look, set variant="bubble" on the Conversation: every turn gets a bubble, and you pair the assistant with a MessageAvatar, name, time, and actions. A per-message variant overrides the conversation default.

Rich content#

MessageContent is markup-agnostic. Drop in plain text or your own rendered markdown; the bubble styles the common elements (paragraphs, headings, lists, inline code, pre blocks, and links) through descendant selectors, tinted to read on either bubble.

const button = tv({
  base: "inline-flex items-center justify-center",
  variants: { size: { sm: "h-8 px-3", md: "h-10 px-4" } },
})

Actions#

MessageActions holds a row of MessageAction buttons for copy, regenerate, and feedback. Each wraps our Button, so it inherits the focus ring and a tooltip drawn from its aria-label.

Typing indicator#

While a response streams, drop a MessageTyping inside a MessageContent. Three dots ripple left to right, and hold still under reduced-motion.

Reasoning#

The collapsible “thinking” block, the way Claude and ChatGPT show it. While streaming the icon pulses and the trigger reads “Investigating…”; once done, it settles to a summary like “Investigated 14 sources” that anyone can expand. For a simple answer, pass plain text; for an agentic run, the block becomes a log of what it did. Group each phase in a MessageReasoningStep (an optional label captions it, a dot pins onto the rail so a column reads as a timeline, and status="active" pulses the in-progress one). Show the searches it ran with MessageReasoningQuery and the URLs it consulted with MessageReasoningSource, as compact favicon and domain chips by default or a bordered title list via layout="list". The domain and favicon are derived from the href. Built on Radix Collapsible, so keyboard and ARIA come for free. Press Ask again to watch it stream through the phases.

PreviewCode

Ask again

Dark mode flashes the wrong theme on first load. Can you trace the hydration flicker?

K

Investigated 14 sources

Reproducing the flash of the wrong theme. The theme looks read on the client after hydration, so the first paint always uses the default.

Searching the codebase

useTheme localStoragedata-theme on <html>suppressHydrationWarning

Reading the docs

nextjs.orgreact.devweb.devgithub.com+10 more

Reviewing sources · 4

Avoiding a theme hydration mismatchnextjs.orgYou Might Not Need an Effectreact.devPrevent a flash of the wrong themeweb.devnext-themes: blocking inline scriptgithub.com

The theme is applied in a useEffect, so the server sends the default and the client only corrects it after the first paint. Set data-theme from localStorage in a small blocking script in the head, and add suppressHydrationWarning to <html>.

Agent trace#

For a coding agent, write each step as one line with title, in the present while it runs (“Reading 3 of 6 files”) and in the past once done (“Read 6 files about sessions and cookies”). The live line takes full ink and a slow sweep; finished lines go muted. Give a step an icon for its kind, a search or the final check. Mark an approach that went nowhere with status="dead-end": a cross on the rail, and the line fades back. Set elapsed on the trigger and it counts “Thinking 9s”, then settles to “Thought for 14s”. Press Run again to watch the full trace.

Jump to latest#

Drop a ConversationScrollButton as the last child of a Conversation. It stays hidden while the reader is at the newest turn; scroll up and a pill fades in, centered over the thread's bottom edge (a sticky row, so it never scrolls with the history and takes no room in it). Pressing it glides back down and resumes following. The follow survives streaming and resizing: a turn that grows by itself, or a panel that changes size, keeps a reader who was at the bottom there, and the thread's own glide never flashes the pill on the way down. Stream the answer below, then scroll up while it writes.

The Conversation must be the element that scrolls: give it a height (here min-h-0 flex-1 in a sized column; in an AI Panel, <AIPanelBody scrollable={false}>).

API reference#

FAQ#