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.