File cards, status rows, progress rings, and type glyphs for upload, download, and delete feedback.

FileAttachment and StatusAttachment are the cards the upload family renders, built on shadcn Attachment. Use them, with the smaller pieces on this page, when you build your own parts.

Preview

Layout

State

quarterly-report.pdf2.3 MB

avatar.png175.8 KB

budget.xlsx82.0 KB

"use client";import { AttachmentPlayground } from "@/components/demos/attachment-playground";// UploadStatus, UploadFileList, and UploadFieldValue already render these// cards.export function AttachmentPlaygroundDemo() {  return <AttachmentPlayground />;}

Install

Complete UI Setup first: the stylesheet and one <Toaster />. Then add this component:

import { FileAttachment, StatusAttachment } from "@dimah-s3/ui";

Usage

UploadStatus, UploadFileList, and UploadFieldValue already render these cards. Reach for them when you render a file yourself:

"use client";

import { UploadFileList, FileAttachment } from "@dimah-s3/ui";

export function CompactFiles() {
  return (
    <UploadFileList className="flex-row flex-wrap">
      {(file) => (
        <FileAttachment
          className="w-32"
          state={
            file.phase === "success"
              ? "done"
              : file.phase === "error"
                ? "error"
                : "uploading"
          }
          fileName={file.fileName}
          fileSize={file.fileSize}
          contentType={file.contentType}
          previewUrl={file.previewUrl}
          percent={file.progress.percent}
          error={file.error}
        />
      )}
    </UploadFileList>
  );
}

Render UploadFileList inside Upload. UploadFileItem maps every phase and adds cancel for you.

Set the width with className. The card is a size container: below a 9rem content width, such as className="w-32", the media stacks above the text. Wider, it is a row. StatusAttachment is always a row and fills its parent unless you set a width.

state is idle, uploading, processing, done, or error. The ring shows percent while the card is idle or uploading; processing shows a spinner instead.

Actions

onCancel adds a Cancel {name} action while the card is idle (queued), uploading, or processing.
onRetry adds a Retry {name} action while it is error. It is the same button as cancel, so focus stays on it when the file goes back in flight.
onDismiss adds a Dismiss {name} action once it is done or error.
actions takes your own AttachmentActions, placed before those.

The title is a FileName: a long name ends its stem in an ellipsis and keeps the extension visible, and title holds the whole name.

trigger takes an AttachmentTrigger that makes the whole card one control, such as opening the file. Give it an accessible name.

<FileAttachment
  state="done"
  fileName={file.name}
  fileSize={file.size}
  trigger={
    <AttachmentTrigger aria-label={`Open ${file.name}`} onClick={open} />
  }
  actions={
    <AttachmentAction aria-label={`Share ${file.name}`} onClick={share}>
      <Share2Icon />
    </AttachmentAction>
  }
/>

Wrap several cards in AttachmentGroup for a scrolling row.

Examples

Every state

FileAttachment for one file in each state, and StatusAttachment for a result that has no single file.

FileAttachment

waiting-in-queue.pdf1.1 MB

holiday-video.mp448 MB · 9s left

dataset.csvFinishing…

avatar.png175.8 KB

too-large-archive.zipThe file is larger than the 75 MB limit.

StatusAttachment

Preparing 4 files…

All 4 files uploaded12.6 MB

Upload failed2 of 4 files could not be uploaded.

"use client";import { FileAttachment, StatusAttachment } from "@dimah-s3/ui";export function AttachmentStatesDemo() {  return (    <div className="mx-auto grid w-full max-w-2xl gap-6 sm:grid-cols-2">      <section className="flex flex-col gap-2">        <h3 className="text-xs font-medium text-muted-foreground">          FileAttachment        </h3>        <FileAttachment          state="idle"          fileName="waiting-in-queue.pdf"          fileSize={1_200_000}          onCancel={() => {}}        />        <FileAttachment          state="uploading"          fileName="holiday-video.mp4"          contentType="video/mp4"          fileSize={48_000_000}          percent={62}          description="48 MB · 9s left"          onCancel={() => {}}        />        <FileAttachment          state="processing"          fileName="dataset.csv"          description="Finishing…"        />        <FileAttachment          state="done"          fileName="avatar.png"          contentType="image/png"          previewUrl="/dimah-avatar.png"          fileSize={180_000}          onDismiss={() => {}}        />        <FileAttachment          state="error"          fileName="too-large-archive.zip"          error="The file is larger than the 75 MB limit."          onDismiss={() => {}}        />      </section>      <section className="flex flex-col gap-2">        <h3 className="text-xs font-medium text-muted-foreground">          StatusAttachment        </h3>        <StatusAttachment state="processing" title="Preparing 4 files…" />        <StatusAttachment          state="done"          title="All 4 files uploaded"          description="12.6 MB"          onDismiss={() => {}}        />        <StatusAttachment          state="error"          title="Upload failed"          description="2 of 4 files could not be uploaded."          onDismiss={() => {}}        />      </section>    </div>  );}

Glyphs and progress

FileTypeGlyph picks a colored glyph from the content type, else the extension. FolderGlyph is the object list's folder, and CircleProgress the ring a card shows while its file uploads.

Folder
report.pdf
notes.docx
budget.xlsx
slides.pptx
data.csv
archive.zip
photo.jpg
song.mp3
clip.mp4
app.ts
README.md
unknown.bin

25%

50%

75%

100%

"use client";import { CircleProgress, FileTypeGlyph, FolderGlyph } from "@dimah-s3/ui";const FILES = [  ["report.pdf", "application/pdf"],  ["notes.docx", null],  ["budget.xlsx", null],  ["slides.pptx", null],  ["data.csv", "text/csv"],  ["archive.zip", "application/zip"],  ["photo.jpg", "image/jpeg"],  ["song.mp3", "audio/mpeg"],  ["clip.mp4", "video/mp4"],  ["app.ts", null],  ["README.md", null],  ["unknown.bin", null],] as const;export function AttachmentGlyphsDemo() {  return (    <div className="mx-auto flex w-full max-w-xl flex-col gap-6">      <ul className="grid grid-cols-4 gap-x-2 gap-y-4 sm:grid-cols-7">        <li className="flex flex-col items-center gap-1.5">          <FolderGlyph className="size-8" />          <span className="text-xs text-muted-foreground">Folder</span>        </li>        {FILES.map(([name, type]) => (          <li key={name} className="flex flex-col items-center gap-1.5">            <FileTypeGlyph layout="icon" fileName={name} contentType={type} />            <span className="max-w-full truncate text-xs text-muted-foreground">              {name}            </span>          </li>        ))}      </ul>      <div className="flex items-center justify-center gap-6">        {[0, 25, 50, 75, 100].map((percent) => (          <div key={percent} className="flex flex-col items-center gap-1.5">            <CircleProgress              percent={percent}              fileName="example.pdf"              className="size-6"            />            <span className="text-xs text-muted-foreground tabular-nums">              {percent}%            </span>          </div>        ))}      </div>    </div>  );}

Building blocks

Export	Renders
`CircleProgress`	A progress ring with `role="progressbar"`, named `Progress for {name}`
`FileName`	A name that fits its width and keeps the extension (`report-for-q….pdf`)
`FileTypeGlyph`	A colored glyph for the file type, from the content type or the extension
`FolderGlyph`	The folder glyph the object list uses
`DismissAttachmentAction`	The dismiss icon button. `label` sets its accessible name
`AttachmentGroup`	A horizontal, scrolling group of cards, from shadcn Attachment
`AttachmentAction`	An icon button in the card's actions, from shadcn Attachment
`AttachmentTrigger`	A button over the whole card, from shadcn Attachment

For chrome that does not fit these, compose shadcn Attachment with the headless hooks; see Custom UI.

Props

import type {
  FileAttachmentProps,
  StatusAttachmentProps,
  CircleProgressProps,
  FileNameProps,
  FileTypeGlyphProps,
  DismissAttachmentActionProps,
} from "@dimah-s3/ui";

Attachment

PreviewCopy Anchor Link

InstallCopy Anchor Link

UsageCopy Anchor Link

LayoutCopy Anchor Link

ActionsCopy Anchor Link

ExamplesCopy Anchor Link

Every stateCopy Anchor Link

FileAttachment

StatusAttachment

Glyphs and progressCopy Anchor Link

Building blocksCopy Anchor Link

PropsCopy Anchor Link

FileAttachmentCopy Anchor Link

StatusAttachmentCopy Anchor Link

CircleProgressCopy Anchor Link

FileNameCopy Anchor Link

FileTypeGlyphCopy Anchor Link

DismissAttachmentActionCopy Anchor Link

On this page

Preview

Install

Usage

Layout

Actions

Examples

Every state

Glyphs and progress

Building blocks

Props

FileAttachment

StatusAttachment

CircleProgress

FileName

FileTypeGlyph

DismissAttachmentAction