Migrating from AI Elements

What carries over#

• The source lives in your repo under components/ui/, installed by a CLI, on Tailwind CSS and Radix.
• Composition by named parts: <Tool><ToolHeader>, <PromptInput><PromptInputTextarea>. Many keep their AI Elements names.
• Your data layer. Koala renders state, it does not fetch it: useChat from the AI SDK, assistant-ui, LangGraph or your own stream all drive the same props.

What changes#

• Status is a plain prop. Components take status, streaming or loading instead of the AI SDK’s types, so nothing is tied to one SDK version. The tool states map one to one, below.
• Markdown streams cleanly. Markdown renders the reply inside MessageContent without flashing half-written syntax. Any other renderer works too: MessageContent styles whatever you put in it.
• Themes and density. Four themes, eight accents and a compact density reach the AI components too, where AI Elements inherits one shadcn palette. See Theming.
• Updates that keep your edits. The CLI’s diff and update bring fixes in without overwriting the files you changed. See Installation.
• Most AI components are Pro. Code Snippet and the foundation components are free; markdown, chat, prompt input, tool, plan and the rest come with a one-time license.

Chatbot components#

Every chatbot component in AI Elements and where it lands. A Koala name links to its docs page, where the full API and examples live.

Code, voice and workflow#

Tool states#

The AI SDK’s tool part state and Koala’s status. Map it once and pass it to Tool; the output and the approval appear on their own.

import type { ToolState } from "@/components/ui/tool"

const STATUS = {
  "input-streaming": "pending",
  "approval-requested": "approval",
  "approval-responded": "running",
  "input-available": "running",
  "output-available": "done",
  "output-error": "error",
  "output-denied": "rejected",
} as const satisfies Record<string, ToolState>

// <Tool status={STATUS[part.state]}>…</Tool>

Moving a project over#

1. Run init and log in. init writes the tokens, the helpers and the theme provider. If the project started from shadcn/ui, clear its color blocks first, as Migrating from shadcn/ui describes.
2. Swap one surface at a time. AI Elements installs to components/ai-elements/ and Koala to components/ui/, so both can live in the project while you move the conversation, then the prompt input, then the tools.
3. Rename with the map above, and let the type checker find the props that changed.
4. Keep what has no counterpart yet. The AI Elements source is in your repo, so its code, voice and workflow components keep working after the deprecation.

# 1. Tokens, the lib helpers and the theme provider
npx koalaui-cli@latest init

# 2. Chat, Prompt Input and Tool are Pro: log in once with your license key
npx koalaui-cli@latest login <your-key>

# 3. Add the components the chat uses
npx koalaui-cli@latest add chat prompt-input tool markdown

With the AI SDK#

A useChat chat on Koala: the SDK keeps the messages and the stream, Koala draws them.

"use client"

import { useChat } from "@ai-sdk/react"
import { Conversation, Message, MessageBody, MessageContent } from "@/components/ui/chat"
import {
  PromptInput,
  PromptInputSubmit,
  PromptInputTextarea,
  PromptInputToolbar,
} from "@/components/ui/prompt-input"
import { Markdown } from "@/components/ui/markdown"

export function Chat() {
  const { messages, sendMessage, status, stop } = useChat()
  const busy = status === "submitted" || status === "streaming"
  const last = messages.at(-1)?.id

  return (
    <>
      <Conversation>
        {messages.map((message) => (
          <Message key={message.id} role={message.role === "user" ? "user" : "assistant"}>
            <MessageBody>
              <MessageContent streaming={busy && message.id === last && message.role === "assistant"}>
                {message.parts.map((part, i) =>
                  part.type === "text" ? <Markdown key={i}>{part.text}</Markdown> : null,
                )}
              </MessageContent>
            </MessageBody>
          </Message>
        ))}
      </Conversation>

      <PromptInput loading={busy} onSubmit={(text) => sendMessage({ text })} onStop={stop}>
        <PromptInputTextarea placeholder="Ask anything…" />
        <PromptInputToolbar>
          <PromptInputSubmit />
        </PromptInputToolbar>
      </PromptInput>
    </>
  )
}

FAQ#