Attachment
File and image attachments with upload progress, errors and actions. Adapted from HextaUI (MIT).
File and image
import { FileTextIcon, XIcon } from "@keyline-icons/react"
import {
Attachment,
AttachmentAction,
AttachmentActions,
AttachmentContent,
AttachmentDescription,
AttachmentMedia,
AttachmentTitle,
} from "@/components/ui/attachment"
// A drawn chart, so the example needs no image file.
const chart = `data:image/svg+xml,${encodeURIComponent(
'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 40 40"><rect width="40" height="40" fill="#ebebeb"/><path d="M8 30V20h5v10zm9 0V12h5v18zm9 0V16h5v14z" fill="#5c5c5c"/></svg>',
)}`
export default function AttachmentFileAndImage() {
return (
<div className="flex flex-wrap items-start justify-center gap-3">
<Attachment>
<AttachmentMedia>
<FileTextIcon aria-hidden />
</AttachmentMedia>
<AttachmentContent>
<AttachmentTitle>release-notes.md</AttachmentTitle>
<AttachmentDescription>4.2 KB</AttachmentDescription>
</AttachmentContent>
<AttachmentActions>
<AttachmentAction aria-label="Remove release-notes.md">
<XIcon aria-hidden />
</AttachmentAction>
</AttachmentActions>
</Attachment>
<Attachment>
<AttachmentMedia variant="image">
<img src={chart} alt="" />
</AttachmentMedia>
<AttachmentContent>
<AttachmentTitle>tasks-by-week.svg</AttachmentTitle>
<AttachmentDescription>12 KB</AttachmentDescription>
</AttachmentContent>
<AttachmentActions>
<AttachmentAction aria-label="Remove tasks-by-week.svg">
<XIcon aria-hidden />
</AttachmentAction>
</AttachmentActions>
</Attachment>
</div>
)
}
Sizes
import { FileTextIcon } from "@keyline-icons/react"
import {
Attachment,
AttachmentContent,
AttachmentDescription,
AttachmentMedia,
AttachmentTitle,
} from "@/components/ui/attachment"
const sizes = [
{ size: "default", name: "project-brief.pdf" },
{ size: "sm", name: "invoice-0142.pdf" },
{ size: "xs", name: "tasks.csv" },
] as const
export default function AttachmentSizes() {
return (
<div className="flex flex-wrap items-center justify-center gap-3">
{sizes.map(({ size, name }) => (
<Attachment key={size} size={size}>
<AttachmentMedia>
<FileTextIcon aria-hidden />
</AttachmentMedia>
<AttachmentContent>
<AttachmentTitle>{name}</AttachmentTitle>
{size === "xs" ? null : <AttachmentDescription>{size === "sm" ? "Small" : "Default"}</AttachmentDescription>}
</AttachmentContent>
</Attachment>
))}
</div>
)
}
States
import { FileTextIcon, RefreshCwIcon, XIcon } from "@keyline-icons/react"
import {
Attachment,
AttachmentAction,
AttachmentActions,
AttachmentContent,
AttachmentDescription,
AttachmentMedia,
AttachmentTitle,
} from "@/components/ui/attachment"
export default function AttachmentStates() {
return (
<div className="grid w-full max-w-lg gap-3 sm:grid-cols-2">
<Attachment state="idle" className="w-full">
<AttachmentMedia>
<FileTextIcon aria-hidden />
</AttachmentMedia>
<AttachmentContent>
<AttachmentTitle>project-brief.pdf</AttachmentTitle>
<AttachmentDescription>Ready to upload</AttachmentDescription>
</AttachmentContent>
</Attachment>
<Attachment state="uploading" progress={64} className="w-full">
<AttachmentMedia>
<FileTextIcon aria-hidden />
</AttachmentMedia>
<AttachmentContent>
<AttachmentTitle>release-notes.md</AttachmentTitle>
<AttachmentDescription>Uploading 64%</AttachmentDescription>
</AttachmentContent>
<AttachmentActions>
<AttachmentAction aria-label="Cancel the upload of release-notes.md">
<XIcon aria-hidden />
</AttachmentAction>
</AttachmentActions>
</Attachment>
<Attachment state="processing" className="w-full">
<AttachmentMedia>
<FileTextIcon aria-hidden />
</AttachmentMedia>
<AttachmentContent>
<AttachmentTitle>tasks.csv</AttachmentTitle>
<AttachmentDescription>Reading 48 rows</AttachmentDescription>
</AttachmentContent>
</Attachment>
<Attachment state="error" className="w-full">
<AttachmentMedia>
<FileTextIcon aria-hidden />
</AttachmentMedia>
<AttachmentContent>
<AttachmentTitle>invoice-0142.pdf</AttachmentTitle>
<AttachmentDescription>Larger than 10 MB</AttachmentDescription>
</AttachmentContent>
<AttachmentActions>
<AttachmentAction aria-label="Retry invoice-0142.pdf">
<RefreshCwIcon aria-hidden />
</AttachmentAction>
<AttachmentAction aria-label="Remove invoice-0142.pdf">
<XIcon aria-hidden />
</AttachmentAction>
</AttachmentActions>
</Attachment>
</div>
)
}
Vertical
import { FileTextIcon, XIcon } from "@keyline-icons/react"
import {
Attachment,
AttachmentAction,
AttachmentActions,
AttachmentContent,
AttachmentDescription,
AttachmentMedia,
AttachmentTitle,
} from "@/components/ui/attachment"
// A drawn page, so the example needs no image file.
const page = `data:image/svg+xml,${encodeURIComponent(
'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 40 40"><rect width="40" height="40" fill="#ebebeb"/><path d="M9 10h14v3H9zm0 7h22v2H9zm0 5h22v2H9zm0 5h16v2H9z" fill="#5c5c5c"/></svg>',
)}`
export default function AttachmentVertical() {
return (
<div className="flex flex-wrap items-start justify-center gap-3">
<Attachment orientation="vertical">
<AttachmentMedia variant="image">
<img src={page} alt="" />
</AttachmentMedia>
<AttachmentContent>
<AttachmentTitle>plan.pdf</AttachmentTitle>
<AttachmentDescription>2 pages</AttachmentDescription>
</AttachmentContent>
<AttachmentActions>
<AttachmentAction aria-label="Remove plan.pdf">
<XIcon aria-hidden />
</AttachmentAction>
</AttachmentActions>
</Attachment>
<Attachment orientation="vertical">
<AttachmentMedia>
<FileTextIcon aria-hidden />
</AttachmentMedia>
<AttachmentContent>
<AttachmentTitle>tasks.csv</AttachmentTitle>
<AttachmentDescription>48 rows</AttachmentDescription>
</AttachmentContent>
<AttachmentActions>
<AttachmentAction aria-label="Remove tasks.csv">
<XIcon aria-hidden />
</AttachmentAction>
</AttachmentActions>
</Attachment>
</div>
)
}
With a trigger
Not opened yet
"use client"
import { useState } from "react"
import { FileTextIcon, XIcon } from "@keyline-icons/react"
import {
Attachment,
AttachmentAction,
AttachmentActions,
AttachmentContent,
AttachmentDescription,
AttachmentMedia,
AttachmentTitle,
AttachmentTrigger,
} from "@/components/ui/attachment"
export default function AttachmentWithATrigger() {
const [opened, setOpened] = useState(0)
return (
<div className="flex flex-col items-center gap-3">
<Attachment>
<AttachmentTrigger aria-label="Open project-brief.pdf" onClick={() => setOpened(opened + 1)} />
<AttachmentMedia>
<FileTextIcon aria-hidden />
</AttachmentMedia>
<AttachmentContent>
<AttachmentTitle>project-brief.pdf</AttachmentTitle>
<AttachmentDescription>3 pages</AttachmentDescription>
</AttachmentContent>
<AttachmentActions>
<AttachmentAction aria-label="Remove project-brief.pdf">
<XIcon aria-hidden />
</AttachmentAction>
</AttachmentActions>
</Attachment>
<p role="status" className="text-sm text-muted-foreground">
{opened === 0 ? "Not opened yet" : opened === 1 ? "Opened once" : `Opened ${opened} times`}
</p>
</div>
)
}
Group
"use client"
import { useRef, useState } from "react"
import { FileTextIcon, XIcon } from "@keyline-icons/react"
import {
Attachment,
AttachmentAction,
AttachmentActions,
AttachmentContent,
AttachmentDescription,
AttachmentGroup,
AttachmentMedia,
AttachmentTitle,
} from "@/components/ui/attachment"
import { Button } from "@/components/ui/button"
const all = [
{ name: "project-brief.pdf", detail: "3 pages" },
{ name: "release-notes.md", detail: "4.2 KB" },
{ name: "tasks.csv", detail: "48 rows" },
{ name: "invoice-0142.pdf", detail: "1 page" },
]
export default function AttachmentGroupExample() {
const [files, setFiles] = useState(all)
const restore = useRef<HTMLButtonElement>(null)
return (
<div className="flex w-full max-w-md flex-col items-start gap-3">
<AttachmentGroup className="w-full">
{files.map((file) => (
<Attachment key={file.name} size="sm">
<AttachmentMedia>
<FileTextIcon aria-hidden />
</AttachmentMedia>
<AttachmentContent>
<AttachmentTitle>{file.name}</AttachmentTitle>
<AttachmentDescription>{file.detail}</AttachmentDescription>
</AttachmentContent>
<AttachmentActions>
<AttachmentAction
aria-label={`Remove ${file.name}`}
onClick={() => {
setFiles(files.filter((other) => other !== file))
// The removed button takes focus with it: hand focus to the way back.
restore.current?.focus()
}}
>
<XIcon aria-hidden />
</AttachmentAction>
</AttachmentActions>
</Attachment>
))}
</AttachmentGroup>
<Button ref={restore} variant="outline" onClick={() => setFiles(all)}>
Put them back
</Button>
</div>
)
}
Installation
npx shadcn@latest add @khaeli/attachmentbunx --bun shadcn@latest add @khaeli/attachmentInstall @khaeli/foundation first: this item's styling lives in its tokens and [data-slot] rules.
Installs with
- Registry items
- npm packages
- @base-ui/react ^1.7.0
- @keyline-icons/react ^2.2.0
- class-variance-authority ^0.7.1
Keyboard
Tab- Moves to the attachment's trigger when it has one, then to each of its actions. A group's strip takes focus before its attachments.
EnterSpace- Activates the focused trigger or action. Actions sit above the trigger, so pressing one does not open the attachment.
Arrow LeftArrow Right- Scroll a group's strip when it has focus.
Accessible name
AttachmentTitleis the attachment's name. It also names the upload progress bar thatstate="uploading"withprogressdraws.AttachmentActionis an icon-only button: give it anaria-labelthat says what it does to which file, such as Remove release-notes.md.AttachmentTriggercovers the whole attachment and has no text of its own: give it anaria-label, such as Open project-brief.pdf.- The icon or thumbnail in
AttachmentMediais decorative beside the title:aria-hiddenon an icon, an emptyalton an image. - A state is shown by a dashed or red border and a moving title. Say it in
AttachmentDescriptiontoo, such as Uploading 64% or the reason an upload failed. - In a vertical attachment the actions are hidden until the pointer is over it or focus is inside it.
- An action is drawn 20px square and takes presses over 24px with a mouse or trackpad. Two actions in a row sit 4px apart, so their press areas do not overlap.
Registry JSON
The item as the shadcn CLI reads it, with every file it ships: https://ui.khaeli.com/r/attachment.json