AG Design System

Component

Uploader

File attachment card with media, metadata, and upload lifecycle states. Use for chat composers, message threads, and upload lists.

Installation

Install from the live registry into any shadcn-initialized app (another project). Prefer installing ag-globals first so AG tokens and fonts are present.

npx shadcn@latest add https://design.ag.org/r/uploader

Usage

Use default when nothing is attached (no file name). Show the file name in attach and complete. Compose media, title, and description without inline remove actions for embedded contexts.

Composition

Button

Playground

Preview
Upload a fileNo file attached

Configure

Not used when size is card

Shown only in attach and complete. Default (empty) has no file name.

Code

import {
Uploader,
  UploaderContent,
  UploaderDescription,
  UploaderMedia,
  UploaderTitle,
} from "@/components/ui/uploader"
import { UploadSimple } from "@phosphor-icons/react"

<Uploader className="w-full max-w-sm">
  <UploaderMedia>
    <UploadSimple weight="bold" aria-hidden />
  </UploaderMedia>
  <UploaderContent>
    <UploaderTitle>Upload a file</UploaderTitle>
    <UploaderDescription>No file attached</UploaderDescription>
  </UploaderContent>
</Uploader>

Variants & States

Supported variants, sizes, and interaction states for this component.

States

Default is empty (no file name). Attach and complete show the file name.

  • Default (empty, no file)
  • Attach (file name + uploading)
  • Complete (file name)

Sizes

  • Default
  • Small (`sm`)
  • Extra small (`xs`)
  • Card (full-width drop zone, dashed border when empty)

Orientation

  • Horizontal
  • Vertical

Props

PropTypeDefault valueDescription
state"default" | "attach" | "complete""default"Upload lifecycle. Default is empty (no file). Attach and complete show the file name.
size"default" | "sm" | "xs" | "card""default"Chip density (`default`, `sm`, `xs`) or a full-width drop-zone layout (`card`). Card default state uses a dashed border.
orientation"horizontal" | "vertical""horizontal"Lay media beside or above the content. Ignored when size is card.

Do

  • Use default when nothing is attached — no file name yet
  • Show the file name only in attach and complete
  • Embed without inline remove actions; clear files from the parent context

Don't

  • Don't show a file name in the empty default state
  • Don't add dismiss or remove buttons when the uploader is embedded inline