# Streaming Text (/docs/agent-ui/components/streaming-text)

Use streaming text for a reply that arrives a few words at a time and needs no formatting. For Markdown, use [Markdown](./markdown.mdx).

<Example caption="Words fade in as the reply streams, with a caret after them until it ends.">
<Basic />

```tsx
"use client";
import { useEffect, useState } from "react";
import { StreamingText } from "@/components/ui/streaming-text";

const reply =
  "The three timeouts all come from the same upstream call. Adding a retry with backoff should cover them.";
const words = reply.split(/(?<= )/);

export default function StreamingTextExample() {
  const [count, setCount] = useState(0);

  useEffect(() => {
    const timer = setInterval(() => setCount((count) => (count > words.length + 8 ? 0 : count + 1)), 120);
    return () => clearInterval(timer);
  }, []);

  return (
    <p className="max-w-md">
      <StreamingText text={words.slice(0, count).join("")} caret={count < words.length} />
    </p>
  );
}
```
</Example>

## Installation [#installation]

```bash tab="React"
npx shadcn@latest add @kind-ui/streaming-text
```

```bash tab="Web Components"
npx shadcn@latest add @kind-ui/streaming-text-web
```

## Usage [#usage]

### Text [#text]

Pass the whole `text` so far on every update, not just the new part. When it extends the last text, only the added part fades in, and nothing before it moves. Any other text, like a shorter or regenerated reply, replaces it at once without fading. Pieces that have finished fading join into one, so the element stays small however long the text grows.

### Caret [#caret]

Set `caret` while the text streams to show a blinking caret after it, and turn it off when the reply ends. The caret adds no width or line height, and screen readers skip it.

### Motion [#motion]

New text fades in only at full motion. Under `prefers-reduced-motion`, or with `motion="reduced"` or `"none"`, it appears at once and the caret stops blinking.

### Announcements [#announcements]

Streaming text is content, not a status: it has no role and announces nothing. If people need to hear progress, announce it from the container.

## API Reference [#api-reference]

### StreamingTextOptions

| Prop      | Type                            | Description                                                                                                                            |
| --------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `text?`   | `string \| undefined`           | The whole text so far: text that extends the last fades its new part in, and any other text replaces it at once. Default: `""`         |
| `caret?`  | `boolean \| undefined`          | Shows a caret after the text, for while it streams. Default: `false`                                                                   |
| `motion?` | `"auto" \| "none" \| "reduced"` | Whether new text fades in: `"auto"` follows `prefers-reduced-motion`, and `"reduced"` or `"none"` append it at once. Default: `"auto"` |

### Agent [#agent]

An agent connected with `createAgent` sees streaming text by its kind, with no name, since it has no role. It has no actions of its own.

<Caption>
Runs in React and Web Components. On `<kind-streaming-text>`, `text` is a property or attribute, `caret` is a boolean attribute and `motion` an attribute of the same name.
</Caption>