# Document (/docs/agent-ui/components/document)

Use a document when the agent hands over a file, like a README, a script or notes, rather than a reply. It shows the title with what the document is and its size, Copy and Download in a toolbar, and the content in a preview that expands to show it all.

<Example caption="Press Show more to see the whole README, and Show less to collapse it. Press Copy to copy its source, or Markdown or Text to download it.">
<Basic />

```tsx
"use client";

import { Document } from "@/components/ui/document";

const readme = `# Rate limits

The REST API allows 5,000 requests an hour for each authenticated user.

## Headers

| Header | Meaning |
| --- | --- |
| \`x-ratelimit-remaining\` | Requests left in this window |
| \`x-ratelimit-reset\` | When the window resets |

## Backing off

1. Read \`x-ratelimit-remaining\` on every response.
2. When it reaches zero, wait until \`x-ratelimit-reset\`.
3. Retry with exponential backoff on a 429.

## Conditional requests

Send \`If-None-Match\` with the last \`ETag\`. A 304 doesn't count against the limit.
`;

const downloads = [
  { id: "md", label: "Markdown" },
  { id: "txt", label: "Text" },
];

function save(formatId: string | undefined) {
  const name = formatId === "txt" ? "README.txt" : "README.md";
  const link = document.createElement("a");
  link.href = URL.createObjectURL(new Blob([readme], { type: "text/plain" }));
  link.download = name;
  link.click();
  URL.revokeObjectURL(link.href);
}

export default function DocumentExample() {
  return (
    <Document
      label="README.md"
      content={readme}
      downloads={downloads}
      onDownload={save}
      className="w-full max-w-lg"
    />
  );
}
```
</Example>

## Installation [#installation]

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

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

## Composition [#composition]

```text
Document
├── DocumentHeader
│   ├── DocumentTitle
│   ├── DocumentMeta
│   └── DocumentToolbar
│       ├── DocumentCopy
│       └── DocumentDownload
└── DocumentBody
    ├── DocumentContent
    └── DocumentExpand
```

`Document` is a region named by its title. `DocumentTitle` shows the `label`, and `DocumentMeta` what the document is (Markdown, Text, or the code's `language`) and its size, like "Markdown · 2.4 kB". `DocumentToolbar` is a toolbar with `DocumentCopy` and a `DocumentDownload` for each format. `DocumentBody` holds `DocumentContent` in a scroll area, and `DocumentExpand` is **Show more** while the content is taller than the preview. To arrange the parts yourself, pass them as children of `Document`.

## Usage [#usage]

### Formats [#formats]

Pass the source as `content` and say how it shows with `format`. `"markdown"`, the default, renders through [Markdown](./markdown.mdx), `"code"` through a [Code Block](./code-block.mdx) without its header, and `"text"` as plain text that wraps. Give code its `language`, which shows beside the title and goes to `highlight`, as Code Block's does.

```tsx
<Document label="backoff.ts" format="code" language="ts" content={source} />
```

### Copy and Download [#copy-and-download]

**Copy** writes `content` to the clipboard, shows a check for two seconds and announces "Copied". Cancel `onCopy`'s details to copy something else yourself.

**Download** shows while `onDownload` is set. The component never builds or fetches a file: it calls `onDownload` with the chosen format's `id`, and your handler saves it, as the example's `save` does. With more than one of `downloads`, each format has its own button named after its `label`; with one or none, there's a single **Download**. Return a promise to keep Download pending until it settles; if it rejects, the component announces "Download failed".

The toolbar is one Tab stop. Use the arrow keys to move between its buttons, and Enter or Space to press one.

### Preview [#preview]

The preview shows the document up to `--kind-document-max-height`, 20rem by default, and scrolls inside, with its edges fading while there's more past them. Once the content is taller, **Show more** sits over the preview's end; press it to show the whole document and **Show less** to collapse it. Pass `defaultOpen` to start expanded, or `open` with `onOpenChange` to control it.

At full motion the preview slides open; under `prefers-reduced-motion`, or with `motion="reduced"` or `"none"`, it changes height at once.

### Streaming [#streaming]

Set `streaming` while `content` arrives. The header holds still, the preview grows up to its collapsed height, then follows the end of the document. **Show more** appears once the content passes the preview, over its end, so nothing below it moves.

## API Reference [#api-reference]

### DocumentOptions

| Prop            | Type                                                                                             | Description                                                                                                                                                                                           |
| --------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `label?`        | `string \| undefined`                                                                            | The document's title, which also names it. Default: `"Document"`                                                                                                                                      |
| `content?`      | `string \| undefined`                                                                            | The document's source: markdown, code or plain text, as `format` says. Default: `""`                                                                                                                  |
| `format?`       | `"code" \| "markdown" \| "text"`                                                                 | How `content` shows: `"markdown"` through Markdown, `"code"` through Code Block, `"text"` as wrapped plain text. Default: `"markdown"`                                                                |
| `language?`     | `string \| undefined`                                                                            | The code's language, like `"ts"`, shown beside the title and passed to `highlight`. For `"code"`.                                                                                                     |
| `highlight?`    | `Highlight \| undefined`                                                                         | Resolves colored tokens for code, as Code Block's `highlight` does.                                                                                                                                   |
| `streaming?`    | `boolean \| undefined`                                                                           | Whether `content` is still arriving. The preview grows up to its collapsed height, then follows the end. Default: `false`                                                                             |
| `downloads?`    | `DocumentDownload[] \| undefined`                                                                | The formats `onDownload` offers. With more than one, each has its own button; with one or none, one Download. Default: `[]`                                                                           |
| `onDownload?`   | `((formatId: string \| undefined, details: ActionDetails) => unknown) \| undefined`              | Called with the chosen download's `id`, or `undefined` without `downloads`. Shows Download while set. The host builds and saves the file; return a promise to keep Download pending until it settles. |
| `onCopy?`       | `((content: string, details: ChangeDetails<"copy-press" \| "imperative">) => void) \| undefined` | Called before `content` is copied. Cancel it to copy something else yourself.                                                                                                                         |
| `open?`         | `boolean \| undefined`                                                                           | Whether the preview shows in full rather than up to `--kind-document-max-height`. Passing it controls it.                                                                                             |
| `defaultOpen?`  | `boolean \| undefined`                                                                           | Whether the preview shows in full at first, when `open` isn't passed. Default: `false`                                                                                                                |
| `onOpenChange?` | `((open: boolean, details: ChangeDetails<DocumentOpenChangeReason>) => void) \| undefined`       | Called when the preview expands or collapses, with what caused it.                                                                                                                                    |
| `motion?`       | `"auto" \| "none" \| "reduced"`                                                                  | `"auto"` follows `prefers-reduced-motion`. Default: `"auto"`                                                                                                                                          |

### Agent [#agent]

An agent connected with `createAgent` finds the document by its title and reads `open`. `copy()` is always offered, `download(formatId)` while `onDownload` is set and no download is pending, with the `downloads` listed as its choices, and `expand()` or `collapse()` while the content is taller than the preview. Like any component with a button, it also has UI SDK's generic `press`.

### DocumentAgentActions

| Prop       | Type                                                        | Description                                                                                                                                                                      |
| ---------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `expand`   | `(() => boolean) \| undefined`                              | Shows the preview in full. Offered while it's collapsed and overflowing.                                                                                                         |
| `collapse` | `(() => boolean) \| undefined`                              | Collapses the preview. Offered while it shows in full and overflows when collapsed.                                                                                              |
| `copy`     | `(event?: Event) => Promise<boolean>`                       | Copies `content` and resolves with whether it worked.                                                                                                                            |
| `download` | `((formatId?: string, event?: Event) => void) \| undefined` | Calls `onDownload` with a format's `id`, the first one's when left out. Offered while `onDownload` is set and no download is pending; refuses an `id` that isn't in `downloads`. |

<Caption>
Runs in React and Web Components. On `<kind-document>`, set `downloads` and `highlight` as properties; the other props are kebab-case attributes. The `can-download` attribute offers Download, which fires the `download` event with the format's `id` as `detail.value`. `onCopy` is the `documentcopy` event and `onOpenChange` is `openchange`. The element fills in its header and body when it has no children.
</Caption>