Chat

Installation#

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

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

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.

<Conversation>
  <Message role="assistant">
    <MessageAvatar name="Koala" />
    <MessageBody>
      <MessageHeader>
        <MessageName>Koala</MessageName>
        <MessageTime>2:34 PM</MessageTime>
      </MessageHeader>

      <MessageReasoning>
        <MessageReasoningTrigger>Thought for 6s</MessageReasoningTrigger>
        <MessageReasoningContent>…</MessageReasoningContent>
      </MessageReasoning>

      <MessageContent>…</MessageContent>

      <MessageActions>
        <MessageAction aria-label="Copy">…</MessageAction>
      </MessageActions>
    </MessageBody>
  </Message>
</Conversation>

Usage#

import {
  Conversation,
  Message,
  MessageAvatar,
  MessageBody,
  MessageContent,
} from "@/components/ui/chat"

export function Thread() {
  return (
    <Conversation className="max-h-[32rem]">
      <Message role="user">
        <MessageBody>
          <MessageContent>Where is the theme applied on load?</MessageContent>
        </MessageBody>
      </Message>
      <Message role="assistant">
        <MessageAvatar name="Koala" />
        <MessageBody>
          <MessageContent>In app/layout.tsx, via a blocking script before paint.</MessageContent>
        </MessageBody>
      </Message>
    </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 press scale, 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>.

API reference#

FAQ#