@k8ordo/ui

AI Chat

Components for building an AI chat screen. Your application holds the requests and the message state, and the components display the message array. They work with the AI SDK and with a backend of your own.

Chat demo

Hi! Ask me anything about the k8ordo UI AI chat components.
Where should I start when building an AI chat in React?
tsx
'use client';
import { Avatar } from '@k8ordo/ui';
import { BotMessageIcon } from '@k8ordo/ui/icons';
import {
  Conversation,
  Message,
  PromptInput,
  Suggestion,
} from '@k8ordo/ui/ai';

const avatar = (
  <Avatar color="primary" icon={<BotMessageIcon />} name="AI" size="sm" />
);

export function Chat({ messages, send }: Props) {
  return (
    <div className={styles.chat}>
      <Conversation.Root>
        <Conversation.Messages>
          {messages.map((m) => (
            <Message.Root
              avatar={m.role === 'assistant' ? avatar : undefined}
              from={m.role}
              key={m.id}
            >
              <Message.Content>{m.text}</Message.Content>
              {m.role === 'assistant' && (
                <Message.Actions>
                  <Message.Copy value={m.text} />
                  <Message.Feedback />
                </Message.Actions>
              )}
            </Message.Root>
          ))}
        </Conversation.Messages>
        <Conversation.ScrollButton />
      </Conversation.Root>

      <Suggestion.List>
        <Suggestion.Item onSelect={send} value="Tell me about IME support" />
      </Suggestion.List>

      <PromptInput.Root accept="image/*,application/pdf" onSubmit={send}>
        <PromptInput.Attachments />
        <PromptInput.Attach />
        <PromptInput.Textarea placeholder="Type a message…" />
        <PromptInput.Submit />
      </PromptInput.Root>
    </div>
  );
}

A chat screen made of these components. Allow the tool call and the answer appears with its sources. You can also send messages, attach files, and copy or rate an answer.

Basic structure

tsx
'use client';
import { Avatar } from '@k8ordo/ui';
import { BotMessageIcon } from '@k8ordo/ui/icons';
import { Conversation, Message, PromptInput } from '@k8ordo/ui/ai';
import { useChat } from '@ai-sdk/react';
import type { UIMessage } from 'ai';

const textOf = (m: UIMessage) =>
  m.parts.map((p) => (p.type === 'text' ? p.text : '')).join('');

export function Chat() {
  const { messages, sendMessage, status, stop } = useChat();

  return (
    <div className={styles.chat}>
      <Conversation.Root>
        <Conversation.Messages isStreaming={status === 'streaming'}>
          {messages.map((m) => (
            <Message.Root
              avatar={
                m.role === 'user' ? undefined : (
                  <Avatar
                    color="primary"
                    icon={<BotMessageIcon />}
                    name="AI"
                    size="sm"
                  />
                )
              }
              from={m.role === 'user' ? 'user' : 'assistant'}
              key={m.id}
            >
              <Message.Content>{textOf(m)}</Message.Content>
            </Message.Root>
          ))}
        </Conversation.Messages>
        <Conversation.ScrollButton />
      </Conversation.Root>

      <PromptInput.Root
        onStop={stop}
        onSubmit={(text) => sendMessage({ text })}
        status={status}
      >
        <PromptInput.Textarea placeholder="Type a message" />
        <PromptInput.Submit />
      </PromptInput.Root>
    </div>
  );
}

Conversation is the scroll region of the log. It scrolls to the end as messages arrive. While you have scrolled up, ScrollButton takes you back to the latest one.

Message.Root is one message. from="user" renders as a right-aligned bubble and from="assistant" as plain text without a bubble. avatar sits beside the message, and the children stack in a column next to it.

PromptInput is the input box. All three are imported from @k8ordo/ui/ai.

Prompt input

tsx
<PromptInput.Root status={status} onSubmit={send} onStop={stop}>
  <PromptInput.Textarea placeholder="Type a message" />
  <PromptInput.Submit />
</PromptInput.Root>

Enter sends and Shift+Enter inserts a newline. The Enter that confirms an IME composition does not send. The body reaches onSubmit trimmed. A message with neither text nor attachments is not sent.

status takes the AI SDK’s values: ready, submitted, streaming or error. While it is submitted or streaming, Submit turns into a stop button that calls onStop.

Attaching files

tsx
<PromptInput.Root
  accept="image/*,application/pdf"
  maxFiles={4}
  onSubmit={(text, files) =>
    sendMessage(text === '' ? { files } : { text, files })
  }
  status={status}
>
  <PromptInput.Attachments />
  <PromptInput.Attach />
  <PromptInput.Textarea placeholder="Type a message" />
  <PromptInput.Submit />
</PromptInput.Root>

Pass accept and files come in from the Attach picker, a drop and a paste. Every route is filtered by the same rule as <input accept>. Without accept the input takes text only, and Attach renders nothing.

Files waiting to be sent are listed in PromptInput.Attachments, each with a remove button. It takes a row of its own above the Textarea, so put it first. Files beyond maxFiles are not accepted.

onSubmit receives them as a FileList in its second argument, which the AI SDK’s sendMessage takes as it is. To send files alone, pass { files } only. Passing text: '' creates an empty text part, which some providers reject with an error.

Suggested prompts

tsx
import { Suggestion } from '@k8ordo/ui/ai';

<Suggestion.List>
  {suggestions.map((s) => (
    <Suggestion.Item key={s} onSelect={send} value={s} />
  ))}
</Suggestion.List>

Suggestion.Item is a chip for one prompt. Pressing it passes value to onSelect. Without children, value is also the visible text.

Markdown

tsx
import { Response } from '@k8ordo/ui/ai/response';

<Message.Content>
  <Response isStreaming={isStreaming}>{markdown}</Response>
</Message.Content>

Response renders Markdown while it is still arriving, and an unclosed code block does not break it. It is imported from @k8ordo/ui/ai/response.

Install streamdown 2.5 or later.

bash
npm install streamdown
Information

Note

Response styles what streamdown renders through the data-streamdown attribute on each element, so no Tailwind CSS is needed. streamdown/styles.css is needed only when you turn on streamdown’s animated.

Tool calls and reasoning

tsx
import { Reasoning, ToolInvocation } from '@k8ordo/ui/ai';

<Reasoning isStreaming={isThinking}>{reasoningText}</Reasoning>

<ToolInvocation
  name="search_web"
  state="output-available"
  input={{ query: 'k8ordo UI' }}
  output="…"
/>

ToolInvocation shows a tool call in a collapsible panel. The icon follows state: a spinner while it runs, then success, error or denied. The values of state are the AI SDK’s tool part states.

input is shown as JSON unless it is a string. A string output goes in a pre, and an element renders as it is. Reasoning shows the model’s reasoning in a collapsible panel. While isStreaming, its label says it is thinking.

Tool approval

tsx
import { useChat } from '@ai-sdk/react';
import { lastAssistantMessageIsCompleteWithApprovalResponses } from 'ai';

const { addToolApprovalResponse } = useChat({
  sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
});

<ToolInvocation
  name={part.name}
  state={part.state}
  input={part.input}
  approval={part.approval}
  onApprovalResponse={addToolApprovalResponse}
/>

When state is approval-requested, pass approval and onApprovalResponse. A question with Deny and Allow buttons appears outside the folded panel. The question is approval.requestReason, or the default wording without one. Pressing a button calls onApprovalResponse({ id, approved }).

That is what the AI SDK’s addToolApprovalResponse takes, so pass it as it is. To send the answer back automatically, give useChat a sendAutomaticallyWhen; without it nothing happens after the user answers.

With approval.isAutomatic neither the question nor the buttons appear. Without onApprovalResponse only the question appears. In output-denied, approval.reason is shown as the reason.

Attachments and sources

tsx
import { Attachment, Source } from '@k8ordo/ui/ai';

<Message.Root from="user">
  <Attachment.List>
    <Attachment.Item filename="diagram.png" mediaType="image/png" url={url} />
  </Attachment.List>
  <Message.Content>{text}</Message.Content>
</Message.Root>

<Source.List>
  <Source.Item href="https://ordo.k8o.me/ui/ai/chat" title="AI chat" />
  <Source.Item title="Internal design doc" />
</Source.List>

Attachment.Item is a file attached to a message. An image shows as a thumbnail with filename as its alt text, and anything else as a chip with the name and media type. An image url is loaded as soon as it renders, so pass a URL your own server produced or a data URL.

Source.Item is a source the answer cites. With an http(s) href it is a link that opens in a new tab. Its text is title, or the host name without one. Anything else is plain text.

Message actions

tsx
<Message.Root avatar={avatar} from="assistant">
  <Message.Content>{text}</Message.Content>
  <Message.Actions>
    <Message.Copy value={text} />
    <Message.Regenerate onAction={() => regenerate({ messageId: message.id })} />
    <Message.Feedback onChange={(value) => saveFeedback(message.id, value)} />
  </Message.Actions>
</Message.Root>

Message.Actions is the row of icon buttons under a message. Copy, Regenerate and Feedback bring their own icons and labels. Any other action is an Action with a label and an icon. The label is also the tooltip.

When onAction returns a promise, the button stays busy until it settles. Feedback is a pair of toggles. Pressing the pressed one again clears it, and onChange receives null.

AI SDK integration

tsx
import { mapMessageParts } from '@k8ordo/ui/ai-sdk';
import { Attachment, Reasoning, Source, ToolInvocation } from '@k8ordo/ui/ai';
import { Response } from '@k8ordo/ui/ai/response';
import { validateGeneratedSpec } from '@k8ordo/ui/json-render';
import { JsonRenderUI } from '@k8ordo/ui/json-render/registry';

const parts = mapMessageParts(message);
const files = parts.filter((part) => part.kind === 'file');
const sources = parts.filter((part) => part.kind === 'source');

<Message.Root from="assistant">
  {files.length > 0 && (
    <Attachment.List>
      {files.map((file) => (
        <Attachment.Item
          filename={file.filename}
          key={file.url}
          mediaType={file.mediaType}
          url={file.url}
        />
      ))}
    </Attachment.List>
  )}
  {parts.map((part, i) => {
    if (part.kind === 'text') {
      return (
        <Message.Content key={i}>
          <Response>{part.text}</Response>
        </Message.Content>
      );
    }
    if (part.kind === 'reasoning') return <Reasoning key={i}>{part.text}</Reasoning>;
    if (part.kind === 'tool') {
      return (
        <ToolInvocation
          key={part.toolCallId}
          name={part.name}
          state={part.state}
          input={part.input}
          output={
            part.output === undefined
              ? undefined
              : JSON.stringify(part.output, null, 2)
          }
          errorText={part.errorText}
          approval={part.approval}
          onApprovalResponse={addToolApprovalResponse}
        />
      );
    }
    if (part.kind === 'data' && part.name === 'ui') {
      const result = validateGeneratedSpec(part.data);
      return result.ok ? <JsonRenderUI key={i} spec={result.spec} /> : null;
    }
    return null;
  })}
  {sources.length > 0 && (
    <Source.List>
      {sources.map((source) => (
        <Source.Item href={source.url} key={source.id} title={source.title} />
      ))}
    </Source.List>
  )}
</Message.Root>

mapMessageParts from @k8ordo/ui/ai-sdk turns the AI SDK’s UIMessage.parts into a single array that is easy to render. Parts of every kind stay in their original order.

A tool part carries its approval, so it can be handed to ToolInvocation as it is. Pull the files and sources out with filter first and show each as one list. Pick data parts by name and validate their contents before rendering them.

ai is an optional peer dependency. Install 7.0.51 or later.

Generative UI in a bubble

tsx
'use client';
import { Message } from '@k8ordo/ui/ai';
import { JsonRenderUI } from '@k8ordo/ui/json-render/registry';

<Message.Root from="assistant">
  <Message.Content>
    <JsonRenderUI spec={spec} />
  </Message.Content>
</Message.Root>

Message.Content takes any children. A UI spec the model returned as a tool result can be rendered inside the bubble with the json-render adapter.

For how to use the adapter, see Generative UI.

Props

The props, derived from the component types. Leave out label or sendLabel and the text comes from the current @k8ordo/i18n locale’s dictionary. The open state of Reasoning and ToolInvocation and the value of Message.Feedback work controlled or uncontrolled.

Conversation.Root

children
Type: ReactNode
Default: -
PropTypeDefault
childrenReactNode-

Conversation.Messages

children
Type: ReactNode
Default: -
isStreaming?
Type: boolean
Default: false
label?
Type: string
Default: -
PropTypeDefault
childrenReactNode-
isStreaming?booleanfalse
label?string-

Conversation.ScrollButton

label?
Type: string
Default: -
PropTypeDefault
label?string-

Message.Root

children
Type: ReactNode
Default: -
from
Type: 'user'|'assistant'
Default: -
avatar?
Type: ReactNode
Default: -
PropTypeDefault
childrenReactNode-
from'user'|'assistant'-
avatar?ReactNode-

Inherited attributes (except the ones set internally): HTMLAttributes<HTMLDivElement>

Message.Content

children
Type: ReactNode
Default: -
isStreaming?
Type: boolean
Default: false
PropTypeDefault
childrenReactNode-
isStreaming?booleanfalse

Inherited attributes (except the ones set internally): HTMLAttributes<HTMLDivElement>

Message.Actions

children
Type: ReactNode
Default: -
label?
Type: string
Default: -
PropTypeDefault
childrenReactNode-
label?string-

Message.Action

children
Type: ReactNode
Default: -
label
Type: string
Default: -
disabled?
Type: boolean
Default: -
onAction?
Type: () => void | Promise<void>
Default: -
PropTypeDefault
childrenReactNode-
labelstring-
disabled?boolean-
onAction?() => void | Promise<void>-

Message.Copy

value
Type: string
Default: -
label?
Type: string
Default: -
PropTypeDefault
valuestring-
label?string-

Message.Regenerate

onAction
Type: () => void | Promise<void>
Default: -
disabled?
Type: boolean
Default: -
label?
Type: string
Default: -
PropTypeDefault
onAction() => void | Promise<void>-
disabled?boolean-
label?string-

Message.Feedback

defaultValue?
Type: MessageFeedback|null
Default: null
onChange?
Type: (value: MessageFeedback | null) => void
Default: -
value?
Type: MessageFeedback|null
Default: -
PropTypeDefault
defaultValue?MessageFeedback|nullnull
onChange?(value: MessageFeedback | null) => void-
value?MessageFeedback|null-

PromptInput.Root

children
Type: ReactNode
Default: -
accept?
Type: string
Default: -
defaultValue?
Type: string
Default: ''
maxFiles?
Type: number
Default: -
onChange?
Type: (value: string) => void
Default: -
onStop?
Type: () => void
Default: -
onSubmit?
Type: (message: string, files: FileList) => void
Default: -
status?
Type: ChatStatus
Default: 'ready'
value?
Type: string
Default: -
PropTypeDefault
childrenReactNode-
accept?string-
defaultValue?string''
maxFiles?number-
onChange?(value: string) => void-
onStop?() => void-
onSubmit?(message: string, files: FileList) => void-
status?ChatStatus'ready'
value?string-

PromptInput.Attachments

label?
Type: string
Default: -
PropTypeDefault
label?string-

PromptInput.Attach

label?
Type: string
Default: -
PropTypeDefault
label?string-

PromptInput.Textarea

children?
Type: ReactNode
Default: -
placeholder?
Type: string
Default: -
ref?
Type: Ref<HTMLTextAreaElement>
Default: -
PropTypeDefault
children?ReactNode-
placeholder?string-
ref?Ref<HTMLTextAreaElement>-

Inherited attributes (except the ones set internally): TextareaHTMLAttributes<HTMLTextAreaElement>

PromptInput.Submit

sendLabel?
Type: string
Default: -
stopLabel?
Type: string
Default: -
PropTypeDefault
sendLabel?string-
stopLabel?string-

Suggestion.List

children
Type: ReactNode
Default: -
label?
Type: string
Default: -
PropTypeDefault
childrenReactNode-
label?string-

Suggestion.Item

value
Type: string
Default: -
children?
Type: ReactNode
Default: -
onSelect?
Type: (value: string) => void
Default: -
PropTypeDefault
valuestring-
children?ReactNode-
onSelect?(value: string) => void-

Response

children
Type: string
Default: -
isStreaming?
Type: boolean
Default: false
PropTypeDefault
childrenstring-
isStreaming?booleanfalse

Inherited attributes (except the ones set internally): StreamdownProps

Reasoning

children
Type: ReactNode
Default: -
defaultOpen?
Type: boolean
Default: false
isOpen?
Type: boolean
Default: -
isStreaming?
Type: boolean
Default: false
onChange?
Type: (isOpen: boolean) => void
Default: -
PropTypeDefault
childrenReactNode-
defaultOpen?booleanfalse
isOpen?boolean-
isStreaming?booleanfalse
onChange?(isOpen: boolean) => void-

ToolInvocation

name
Type: string
Default: -
state
Type: ToolState
Default: -
approval?
Type: ToolApproval
Default: -
defaultOpen?
Type: boolean
Default: false
errorText?
Type: string
Default: -
input?
Type: unknown
Default: -
isOpen?
Type: boolean
Default: -
onApprovalResponse?
Type: (response: ToolApprovalResponse) => void | PromiseLike<void>
Default: -
onChange?
Type: (isOpen: boolean) => void
Default: -
output?
Type: ReactNode
Default: -
PropTypeDefault
namestring-
stateToolState-
approval?ToolApproval-
defaultOpen?booleanfalse
errorText?string-
input?unknown-
isOpen?boolean-
onApprovalResponse?(response: ToolApprovalResponse) => void | PromiseLike<void>-
onChange?(isOpen: boolean) => void-
output?ReactNode-

Attachment.List

children
Type: ReactNode
Default: -
label?
Type: string
Default: -
PropTypeDefault
childrenReactNode-
label?string-

Attachment.Item

mediaType
Type: string
Default: -
url
Type: string
Default: -
filename?
Type: string
Default: -
PropTypeDefault
mediaTypestring-
urlstring-
filename?string-

Source.List

children
Type: ReactNode
Default: -
label?
Type: string
Default: -
PropTypeDefault
childrenReactNode-
label?string-

Source.Item

href?
Type: string
Default: -
title?
Type: string
Default: -
PropTypeDefault
href?string-
title?string-
k8ordo

React libraries that use Baseline features without holding back.