--- title: Attachment description: File and image attachments with previews, states, and actions. group: Components order: 14 --- Show files in composers, threads, and upload lists. Each attachment can combine a preview, metadata, upload state, and actions. ```tsx import { Attachment, AttachmentAction, AttachmentActions, AttachmentContent, AttachmentDescription, AttachmentGroup, AttachmentMedia, AttachmentTitle, } from "@/components/ui/attachment" export function Example() { return (
lake-study.png PNG · 820 KB {/* …two more image attachments */} registry-index.json Uploading · 58% accordion.tsx TSX · 6.2 KB
) } ``` ## Installation ```bash npx @arctis-sh/@arctis-sh/ui@latest add attachment ``` ## Usage ```tsx import { Attachment, AttachmentAction, AttachmentActions, AttachmentContent, AttachmentDescription, AttachmentMedia, AttachmentTitle, } from "@/components/ui/attachment" ``` ```tsx registry-index.json JSON · 48 KB ``` ## Composition ```tree Attachment ├── AttachmentMedia ├── AttachmentContent │ ├── AttachmentTitle │ └── AttachmentDescription ├── AttachmentActions │ └── AttachmentAction └── AttachmentTrigger AttachmentGroup ├── Attachment └── Attachment ``` ## Basic Mix image previews and compact file attachments. Set `state="uploading"` while a file is in progress. ```tsx import { Attachment, AttachmentAction, AttachmentActions, AttachmentContent, AttachmentDescription, AttachmentGroup, AttachmentMedia, AttachmentTitle, } from "@/components/ui/attachment" export function Example() { return (
lake-study.png PNG · 820 KB {/* …two more image attachments */} registry-index.json Uploading · 58% accordion.tsx TSX · 6.2 KB
) } ``` ## Image Set `variant="image"` on `AttachmentMedia` and `orientation="vertical"` to place a preview above the file name and metadata. ```tsx import { Attachment, AttachmentContent, AttachmentDescription, AttachmentGroup, AttachmentMedia, AttachmentTitle, } from "@/components/ui/attachment" export function Example() { return ( lake-study.png PNG · 820 KB ) } ``` ## States `state` controls the visual treatment. `uploading` and `processing` dim the media and show progress, while `error` uses a destructive surface. ```tsx import { Attachment, AttachmentAction, AttachmentActions, AttachmentContent, AttachmentDescription, AttachmentMedia, AttachmentTitle, } from "@/components/ui/attachment" export function Example() { return (
theme-tokens.css Queued · waiting to upload docs-export.md Uploading · 58% component-catalog.json Indexing for the registry og-cover.png Upload failed · try again alert-dialog.tsx Uploaded · 9.4 KB
) } ``` ## Sizes Choose `default`, `sm`, or `xs` with the `size` prop. ```tsx import { Attachment, AttachmentContent, AttachmentDescription, AttachmentMedia, AttachmentTitle, } from "@/components/ui/attachment" export function Example() { return (
Default size MD · 2.1 KB Small size MD · 2.1 KB Extra small MD · 2.1 KB
) } ``` ## Group `AttachmentGroup` arranges items in a horizontal row. Swipe on touch or drag on desktop; the row settles on the nearest card. ```tsx import { Attachment, AttachmentAction, AttachmentActions, AttachmentContent, AttachmentDescription, AttachmentGroup, AttachmentMedia, AttachmentTitle, } from "@/components/ui/attachment" export function Example() { return ( dune-pass.png PNG · 640 KB release-notes.md MD · 12 KB alpine.png PNG · 700 KB button.tsx TSX · 4 KB ) } ``` ## Trigger `AttachmentTrigger` fills the card, making the whole attachment clickable while keeping its actions available. ```tsx import { Attachment, AttachmentAction, AttachmentActions, AttachmentContent, AttachmentDescription, AttachmentMedia, AttachmentTitle, AttachmentTrigger, } from "@/components/ui/attachment" export function Example() { return ( changelog.md Open the full notes ) } ``` ## API Reference ### Attachment | Prop | Type | Default | | --- | --- | --- | | state | "idle" \| "uploading" \| "processing" \| "error" \| "done" | "done" | | size | "default" \| "sm" \| "xs" | "default" | | orientation | "horizontal" \| "vertical" | "horizontal" | | className | string | — | ```tsx report.pdf 2.4 MB ``` ### AttachmentMedia | Prop | Type | Default | | --- | --- | --- | | variant | "icon" \| "image" | "icon" | | className | string | — | ```tsx ``` ### AttachmentContent | Prop | Type | Default | | --- | --- | --- | | className | string | — | ```tsx report.pdf 2.4 MB ``` ### AttachmentTitle | Prop | Type | Default | | --- | --- | --- | | className | string | — | ```tsx report.pdf ``` ### AttachmentDescription | Prop | Type | Default | | --- | --- | --- | | className | string | — | ```tsx 2.4 MB ``` ### AttachmentActions | Prop | Type | Default | | --- | --- | --- | | className | string | — | ```tsx ``` ### AttachmentAction | Prop | Type | Default | | --- | --- | --- | | className | string | — | | aria-label | string | — | ```tsx ``` ### AttachmentTrigger | Prop | Type | Default | | --- | --- | --- | | className | string | — | | aria-label | string | — | ```tsx ... ``` ### AttachmentGroup | Prop | Type | Default | | --- | --- | --- | | className | string | — | ```tsx ... ... ``` ## Source ```tsx "use client"; import { createContext, useContext, useRef, type ButtonHTMLAttributes, type HTMLAttributes, type PointerEvent as ReactPointerEvent, type ReactNode, } from "react"; import { Button } from "@/components/ui/button"; import { cn } from "@/lib/utils"; type AttachmentState = "idle" | "uploading" | "processing" | "error" | "done"; type AttachmentSize = "default" | "sm" | "xs"; type AttachmentOrientation = "horizontal" | "vertical"; type AttachmentContextValue = { state: AttachmentState; size: AttachmentSize; orientation: AttachmentOrientation; }; const AttachmentContext = createContext(null); function useAttachment() { const context = useContext(AttachmentContext); if (!context) { throw new Error("Attachment parts must be used within "); } return context; } type AttachmentProps = HTMLAttributes & { state?: AttachmentState; size?: AttachmentSize; orientation?: AttachmentOrientation; children: ReactNode; }; const sizeRoot: Record = { default: "gap-3 p-3", sm: "gap-2.5 p-2.5", xs: "gap-2 p-2", }; export function Attachment({ state = "done", size = "default", orientation = "horizontal", className, children, ...props }: AttachmentProps) { const busy = state === "uploading" || state === "processing"; return (
{children} {busy ? ( ); } type AttachmentMediaProps = HTMLAttributes & { variant?: "icon" | "image"; children: ReactNode; }; const mediaSize: Record = { default: "size-10", sm: "size-9", xs: "size-8", }; export function AttachmentMedia({ variant = "icon", className, children, ...props }: AttachmentMediaProps) { const { size, orientation, state } = useAttachment(); const busy = state === "uploading" || state === "processing"; return (
svg]:size-4", mediaSize[size]), variant === "image" && (orientation === "vertical" ? "aspect-[4/3] w-full [&>img]:size-full [&>img]:object-cover" : cn("[&>img]:size-full [&>img]:object-cover", mediaSize[size])), className, )} {...props} > {children} {busy ? ( ); } type AttachmentContentProps = HTMLAttributes & { children: ReactNode; }; export function AttachmentContent({ className, children, ...props }: AttachmentContentProps) { return (
{children}
); } type AttachmentTitleProps = HTMLAttributes & { children: ReactNode; }; export function AttachmentTitle({ className, children, ...props }: AttachmentTitleProps) { const { state, size } = useAttachment(); return (
{children}
); } type AttachmentDescriptionProps = HTMLAttributes & { children: ReactNode; }; export function AttachmentDescription({ className, children, ...props }: AttachmentDescriptionProps) { const { size } = useAttachment(); return (
{children}
); } type AttachmentActionsProps = HTMLAttributes & { children: ReactNode; }; export function AttachmentActions({ className, children, ...props }: AttachmentActionsProps) { const { orientation } = useAttachment(); return (
{children}
); } type AttachmentActionProps = ButtonHTMLAttributes & { children: ReactNode; }; export function AttachmentAction({ className, children, ...props }: AttachmentActionProps) { return ( ); } type AttachmentTriggerProps = ButtonHTMLAttributes & { children?: ReactNode; }; export function AttachmentTrigger({ className, children, ...props }: AttachmentTriggerProps) { return ( ); } type AttachmentGroupProps = HTMLAttributes & { children: ReactNode; }; export function AttachmentGroup({ className, children, onPointerDown, onPointerMove, onPointerUp, onPointerCancel, ...props }: AttachmentGroupProps) { const ref = useRef(null); const drag = useRef<{ pointerId: number; startX: number; scrollLeft: number; moved: boolean; } | null>(null); const suppressClick = useRef(false); const settling = useRef(false); const scrollTimer = useRef(null); function nearestLeft(node: HTMLDivElement) { const items = Array.from(node.children) as HTMLElement[]; if (items.length === 0) return 0; const max = Math.max(0, node.scrollWidth - node.clientWidth); const origin = node.getBoundingClientRect().left; let target = 0; let min = Infinity; for (const item of items) { const left = Math.min( Math.max( 0, item.getBoundingClientRect().left - origin + node.scrollLeft, ), max, ); const dist = Math.abs(left - node.scrollLeft); if (dist < min) { min = dist; target = left; } } return target; } function settle(node: HTMLDivElement) { if (drag.current || settling.current) return; const target = nearestLeft(node); if (Math.abs(target - node.scrollLeft) < 1) return; settling.current = true; node.scrollTo({ left: target, behavior: "smooth" }); window.setTimeout(() => { settling.current = false; }, 320); } function queueSettle() { const node = ref.current; if (!node || drag.current) return; if (scrollTimer.current !== null) window.clearTimeout(scrollTimer.current); scrollTimer.current = window.setTimeout(() => settle(node), 60); } function endDrag(event: ReactPointerEvent) { const state = drag.current; if (!state || state.pointerId !== event.pointerId) return; const node = ref.current; if (node?.hasPointerCapture(event.pointerId)) { node.releasePointerCapture(event.pointerId); } const moved = state.moved; if (moved) suppressClick.current = true; drag.current = null; node?.removeAttribute("data-dragging"); if (moved && node) settle(node); } return (
{ if (drag.current || settling.current) return; queueSettle(); }} onPointerDown={(event) => { onPointerDown?.(event); if (event.defaultPrevented || event.button !== 0) return; if (event.pointerType === "touch") return; const target = event.target as HTMLElement | null; if (target?.closest("button, a, input, textarea, select, label")) { return; } const node = ref.current; if (!node) return; if (scrollTimer.current !== null) { window.clearTimeout(scrollTimer.current); scrollTimer.current = null; } settling.current = false; suppressClick.current = false; drag.current = { pointerId: event.pointerId, startX: event.clientX, scrollLeft: node.scrollLeft, moved: false, }; node.setAttribute("data-dragging", ""); node.setPointerCapture(event.pointerId); }} onPointerMove={(event) => { onPointerMove?.(event); if (event.defaultPrevented) return; const state = drag.current; const node = ref.current; if (!state || !node || state.pointerId !== event.pointerId) return; const delta = event.clientX - state.startX; if (!state.moved && Math.abs(delta) < 3) return; state.moved = true; event.preventDefault(); node.scrollLeft = state.scrollLeft - delta; }} onPointerUp={(event) => { onPointerUp?.(event); endDrag(event); }} onPointerCancel={(event) => { onPointerCancel?.(event); endDrag(event); }} onClickCapture={(event) => { if (!suppressClick.current) return; suppressClick.current = false; event.preventDefault(); event.stopPropagation(); }} {...props} > {children}
); } ```