Skip to content
WunderUI

Chat Attachment

Pro

A file chip for a message or a prompt: a tile, the name, the size and an optional remove button.

Playground

Q3-report.pdf2.4 MB

Installation

Chat Attachment comes with WunderUI Core and Pro, in the package from your plan. See the plans.

Then import what you need:

tsx
import {
  ChatAttachment,
  ChatAttachmentStatus,
  ChatAttachmentTone,
} from "@wunderui/react"

Then use it:

tsx
import { ChatAttachment } from "@wunderui/react"

export function Attached({ onRemove }: { onRemove: () => void }) {
  return <ChatAttachment name="Q3-report.pdf" size="2.4 MB" onRemove={onRemove} />
}

export function Uploading({ progress }: { progress: number }) {
  return <ChatAttachment name="Q3-report.pdf" status="uploading" progress={progress} />
}

Expected result: You see a small card with a grey file tile, the name Q3-report.pdf, 2.4 MB under it and an X on the right. The second chip shows a progress bar instead of the size.

When to use

Use Chat Attachment for

  • A file attached to a prompt before it is sent, with a remove button
  • A file shown on a sent or received message, read-only
  • An image or a video with a small preview and its running time
  • A file that is uploading, failed to upload or is not accepted, with a Retry button

Use something else for

  • Drop Zone for the area where people drop or choose the files
  • Progress for the progress of anything that is not a file chip, such as a job or an import
  • Chat Message for the bubble the chip sits in

Preview

The 36 px tile shows what the file is: the picture for an image or video with a preview, an icon otherwise. A video also shows its running time.

Q3-report.pdf2.4 MB

Content

Name and size are one line each and cut off at the end, so put what tells files apart first. The size is optional and shows the text you pass.

Q3-report.pdf2.4 MB

Upload state

Uploading shows a progress bar and turns Remove into Cancel. Failed turns the chip red with a Retry button, and Unsupported says the file type is not accepted.

Q3-report.pdf42%

Newer props

tone="auto" colours the tile by extension (csv green, png purple, pdf red). compact is the 22 px tile with a thin upload bar for messages and composers.

Tile colour from the file type, compact size

interviews-q3.csv42 KB
checkout-v3.png1.1 MB
brief.pdf310 KB
export.csv

Keyboard interactions

The remove button and, after a failed upload, the Retry button are native buttons, so the browser handles focus and activation. The chip itself takes no focus.

TaborShiftTab
Moves focus to the next or previous button, Retry before Remove, in page order. Focus shows as an indigo border with a 2 px ring.
EnterorSpace
Presses the focused button: Remove (Cancel while uploading) calls , Retry calls . The chip does not remove itself: take the file out of your list, then move focus.

Behavior and motion

What the chip does with its remove button, its text, assistive technology and motion.

Remove
The chip does not hold the file. It calls the remove handler, you take the file out of your state, and the chip goes, so move focus yourself because the focused button disappears too.
Upload state
Uploading swaps the size line for a progress bar, or a pulsing bar when no progress is given. Failed and unsupported turn the chip red and show a message, and Retry appears on failed only.
Names
The remove button is named after the file, so every chip in a list has a name of its own. The chip is not a list item, so put chips in a labelled list.
Preview
The preview image has an empty alt, because the name sits right next to it. The kind icon is hidden from assistive technology.
Live region
Only the message of a failed or unsupported file is announced when it appears. A removal reaches a screen reader only through a status line that is already on the page.
Width
The name and size are cut at the end, so the chip takes the width of its container. Give it a width, or put it in a flex row that can shrink.
States
Hover fills the Remove button with the page tone, pressing with the subtle tone, and focus is an indigo border with a 2 px ring. The Retry button is 24 px high and follows the plain button states.
Motion
The progress fill grows smoothly. With reduced motion it jumps to the new value, and an upload without progress stops pulsing.

Anatomy

The figure marks the chip and its parts. The duration badge shows only for a video, and the upload progress only while uploading, so neither has a number.

Q3-report.pdf2.4 MB
  • data-slot="chat-attachment"

    A card with a 1 px border, a 4 px radius, 8 px padding and 12 px between its parts. It takes the width of its container.

  • A 36 px tile showing the picture of an image, or of a video with a poster, and a file, image or film icon in every other case. The picture is decorative, because the name sits next to it.

  • The file name in 12 px medium text, on one line and cut at the end.

  • Optional

    The size in 12 px tertiary text, on one line, which also holds the upload state such as the percentage. Without a size there is no second line.

  • Optional

    While uploading, a 4 px bar with an indigo fill and the rounded percentage replace the size line. The bar is a progressbar named after the file.

  • Optional

    A 16 px round icon button named after the file, shown only when a remove handler is set. A 24 px area around it takes the press.

  • Optional

    The running time of a video: a dark badge over the poster, or text under the icon when there is no poster. Ignored for other kinds.

  • data-slot="chat-attachment-preview"
  • data-slot="chat-attachment-duration"Optional
  • data-slot="chat-attachment-progress"Optional

Best practices

  • Do

    Pass the size already formatted with its unit, such as 2.4 MB. The chip shows it as given.

  • Do

    Set the status as the upload goes: uploading, failed (add a retry handler) or unsupported for a type that is not accepted. Pass your own error text when you can say more.

  • Do

    Add the remove handler only while the file can still be taken back, typically before sending. On a sent message leave it out.

  • Do

    After Remove, move focus to the list or the next chip and say what was removed in a status line. The button that had focus is gone with the chip.

  • Do

    Put chips in a list with an accessible name such as Attachments, so a screen reader counts them.

  • Don’t

    Don't pass a path as the name. It is cut at the end, so the part that tells files apart should come first, and the chip has no tooltip.

  • Don’t

    Don't leave a failed chip without a way forward: add a retry handler or remove the chip, and say why in the error text. Red is not the only signal, since the message is text.

  • Don’t

    Don't offer Retry for an unsupported file. It can never succeed, so ask for a different file.

API reference

ChatAttachment is a plain component, so this table lists every prop.

A card with a 1 px border, a 4 px radius, 8 px padding and 12 px between its parts. It takes the width of its container.

PropTypeDefaultDescription
name requiredstring—The file name, shown on one line and truncated at the end. It also names the remove button ().
sizestring—The second line, shown as given: a size such as . Leave it out for one line. Not shown while the chip is uploading, failed or unsupported.
kind"file" | "image" | "video""file"What the file is: (default), or . It picks the icon of the tile and sets .
previewSrcstring—The source of the picture in the tile, for an , or the poster frame of a . Without it the tile shows an icon.
durationstring—The running time of a video, for example . Ignored for other kinds.
status"ready" | "failed" | "uploading" | "unsupported""ready" (default), (progress bar), (red, with the message and Retry) or (red, with the message).
progressnumber—Upload progress from 0 to 100, used while is . Values outside the range are clamped. Without it the bar is indeterminate.
errorstring—Replaces the message of () and ().
onRetry() => void—Shows a Retry button when is . Start the upload again and set the status back to in this handler.
onRemove() => void—Called when the remove button is pressed. Without it there is no button. While uploading the button cancels the upload. Take the file out of your state here and move focus.
classNamestring—Extra classes for the chip, for example in a flex row.
compactbooleanfalseCompact variant (22 px tile, thin bar, no percentage). Named because already holds the file size.
tone"auto" | "blue" | "purple" | "red" | "green" | "neutral" | "amber""auto"Tile colour. picks the tone from the file extension of . Tiles with a preview image stay neutral; a failed or unsupported attachment ignores this and uses the red error style.

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("chat-attachment")
InstallIncluded in Core and Pro

The full library index for assistants is at /llms.txt.