Document
Show a document the agent wrote as a card, with its kind and size, Copy, Download and a preview that expands.
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.
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
Read
x-ratelimit-remainingon every response.When it reaches zero, wait until
x-ratelimit-reset.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.
Installation
npx shadcn@latest add @kind-ui/documentComposition
Document
โโโ DocumentHeader
โ โโโ DocumentTitle
โ โโโ DocumentMeta
โ โโโ DocumentToolbar
โ โโโ DocumentCopy
โ โโโ DocumentDownload
โโโ DocumentBody
โโโ DocumentContent
โโโ DocumentExpandDocument 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
Formats
Pass the source as content and say how it shows with format. "markdown", the default, renders through Markdown, "code" through a Code Block 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.
<Document label="backoff.ts" format="code" language="ts" content={source} />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
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
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
Prop
Type
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.
Prop
Type
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.