ai attachment.md
AI Attachment
A file dropped into the chat uploads, then the assistant reads it page by page. Page citations in the answer light up the page they point at.
Source: https://kokonutui.com/docs/ai/ai-attachment
Installation
npx shadcn@latest add @kokonutui/ai-attachment
Props
| Prop | Type | Default | Description |
|---|---|---|---|
file? |
AttachedFile |
demo |
|
prompt? |
string |
The user's message under the file. Only the demo draws one by default. | |
answer? |
AnswerPart[] |
The answer, with page citations. Shown once the file is read; it can stream. | |
status? |
AttachmentStatus |
Pass it to drive the card from your upload and parser; leave it out and the demo plays on uploadMs and pageMs. |
|
uploaded? |
number |
Share of the file uploaded, 0 to 1, while uploading. |
|
pagesRead? |
number |
Pages read so far, while reading. |
|
duration? |
number |
Seconds the reading took, shown once it's done. | |
error? |
string |
Why it failed, when status is error. |
|
uploadMs? |
number |
1400 |
Demo only: how long the upload takes, in ms. |
pageMs? |
number |
260 |
Demo only: how long each page takes to read, in ms. |
className? |
string |
Extra classes for the root element. |
AttachedFile
| Field | Type | Description |
|---|---|---|
name |
string |
|
size |
number |
In bytes. |
pages |
number |
AnswerPart
A run of text, or a citation to a page (1-based).
type AnswerPart = string | { page: number };
AttachmentStatus
Where the file is: on its way up, being read, read, or failed.
type AttachmentStatus = "uploading" | "reading" | "done" | "error";
Source
"use client";
/**
* @author: @kokonutui
* @description: AI Attachment
* @version: 1.1.0
* @date: 2026-11-05
* @license: MIT
* @website: https://kokonutui.com
* @github: https://github.com/kokonut-labs/kokonutui
*/
//... (rest of the source code not shown for brevity)
Usage
With no props it plays the demo. Pass status to drive it from your own upload and parser: uploading with uploaded from 0 to 1, reading with pagesRead, then done or error. The answer shows once it's done and can stream in a part at a time; a part is text or { page }, a citation that lights its page when pointed at. The file chip always shows, since it is the upload; the question bubble only shows when you pass prompt.
"use client";
import AIAttachment, { type AnswerPart } from "@/components/kokonutui/ai-attachment";
export function UploadedFile({
file,
upload,
parse,
answer,
}: {
file: { name: string; size: number; pages: number };
/** From your upload, e.g. XMLHttpRequest progress events. */
upload: { loaded: number; total: number; done: boolean };
/** From your parser, as it works through the pages. */
parse: { pagesRead: number; done: boolean; error?: string };
answer: AnswerPart[];
}) {
let status: "uploading" | "reading" | "done" | "error" = "uploading";
if (parse.error) status = "error";
else if (parse.done) status = "done";
else if (upload.done) status = "reading";
return (
<AIAttachment
answer={answer}
error={parse.error}
file={file}
pagesRead={parse.pagesRead}
status={status}
uploaded={upload.loaded / upload.total}
/>
);
}
Here it's fed an upload, a page-by-page read and a streamed answer. Play with an error stops on a page with no text.