---
title: "AI chat"
description: "A conversation with an assistant: starter prompts, markdown replies, a typing state and the composer, composed from the registry."
---

A whole assistant conversation, ready to wire to a model: who you are talking to, the exchange so far, and the composer. Before the first message the list gives way to a greeting and a few prompts to start from, and while a reply is on its way the assistant is shown writing.

The block is the arrangement, not a client. It calls no model and knows no transport: it draws the `messages` you give it and tells you what was sent. Calling the model, appending the reply (or growing it as it streams) and setting `pending` stay in your application, so it works with any SDK or none.

Send a message in the preview: the reply is canned and arrives after a pause.

_Live example of AI chat — see the page for the rendered demo._

## Installation

```bash
npx newtui@latest add ai-chat
``` Registry dependencies, installed with it: chat, message-list, message-group, message-composer, markdown, typing-indicator, avatar, button.

Files written — React: components/ai-chat.tsx. Vue: components/ai-chat/AiChat.vue, components/ai-chat/types.ts, components/ai-chat/index.ts.

## Usage

React:

```tsx
import { AiChat } from "@/components/ai-chat"
```

Vue:

```ts
import { AiChat } from "@/components/ai-chat"
```

Keep the conversation in state, append the user's message when the block reports it, and set `pending` while your model answers. To stream, append the assistant's message once and replace its `body` as the text arrives; the block renders whatever the array holds.

## API reference

**`AiChat`**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `assistantName` | `string` | — | The assistant's name. It labels the header, the assistant's messages, the composer and the conversation for screen readers. |
| `messages` | `readonly AiChatMessage[]` | — | The conversation, oldest first. An empty array shows the greeting and the prompts. |
| `caption` | `string` | — | A quiet line under the name: the model in use, or what the assistant is for. |
| `userName` | `string` | `"You"` | The name shown on the user's messages. |
| `pending` | `boolean` | `false` | A reply is being written. Shows the assistant writing above the composer. |
| `greeting` | `string` | `"How can I help?"` | The line above the prompts, before the first message. |
| `suggestions` | `readonly string[]` | `[]` | Prompts offered before the first message. Choosing one sends it as written. |
| `onSend / @send` | `(message: string) => void` | — | Called with the text when the user submits the composer or chooses a prompt. |
| `onAttach / @attach` | `() => void` | — | Called when the add button in the composer is pressed. The composer always draws that button, so without a handler it does nothing: open your own file picker here. |

**`AiChatMessage`**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | — | A stable key for the message. |
| `role` | `"user" \| "assistant"` | — | Who wrote it. An assistant's message carries the AI tag and its body is rendered as chat markdown; a user's body is shown as written. |
| `body` | `string` | — | The text of the message. |
| `sentAt` | `string` | — | ISO timestamp, for the `<time>` element. |
| `displayTime` | `string` | — | The timestamp as the reader sees it. |

The root takes the native attributes of the `<div>` it renders; React uses `className`, Vue uses `class`.

## Accessibility

The conversation is a labelled, focusable scrolling region, so a keyboard user can reach it and scroll back through it. The writing state is a `role="status"` region that is always in the page, so the "is writing" text appearing is announced without moving focus. The composer is named "Message" plus the assistant's name. The list follows new text while the reader is at the bottom and stays put once they have scrolled up; sending a message scrolls to the bottom again. In React pass a new `messages` array as a reply streams in; in Vue a deep change to it is enough. The AI tag has an accessible name of its own ("AI assistant") rather than relying on the two letters. Say plainly somewhere in your product that the replies are generated: the tag marks who is speaking, it does not explain what that means.

## Tokens

AI chat reads its colours, radii and motion from the `--newt-*` tokens. Override a token rather than editing the component.
