Attachment
A file or image attachment with its media, metadata, upload state and actions.
Use an attachment for a file or an image in a chat composer, a message thread or an upload list. It shows the file's media, name and metadata, and takes actions and an upload state.
Installation
Needs the arene setup first. Also adds Button.
Install the packages it imports:
Set up the token layer and the StyleX compiler, if you have not already. See
Installation, and paste states.ts from the same page.
The trigger's focus ring comes from it. Paste shimmer.ts from the
Shimmer page too. The title shimmers through it while
a file uploads. The attachment also needs interop.css, which sizes icons, fits
an image to the media slot and provides the group's scroll-fade-x and
no-scrollbar classes.
Add the Button. AttachmentAction renders it.
Paste this source into the file named in its title.
Change the @/ imports if your project uses different aliases.
Usage
Composition
Use AttachmentGroup to lay out several attachments in a row that scrolls:
The attachment is a flat card with a hairline edge. It passes its state and
orientation to every part through context, so the media, the title and the
description restyle themselves for an upload or an error.
Image
Set variant="image" on AttachmentMedia and put an img inside it. The image
covers the slot. Set orientation="vertical" to put the media above the
content.
A vertical attachment is 120px wide with content and 96px with media alone. Its
actions sit over the image's top corner, and AttachmentAction defaults to the
outline variant there so it stays visible on a photo.
States
Set state to follow the upload. With idle the edge is dashed. uploading
and processing shimmer the title. error gives the edge, fill, media and
description the destructive colour. An image dims while it is not idle or done. For a percentage, put a
Progress in the content, as the uploading example
does.
The shimmer stops under reduced motion, and the title shows in its plain colour.
Sizes
size takes default, sm or xs.
Group
Wrap attachments in AttachmentGroup for a row that scrolls sideways, snaps to
each attachment and fades at the edge that has more to show.
Trigger
Add an AttachmentTrigger to make the whole attachment open a link or a dialog.
It spans the attachment underneath the actions, so each action can still be clicked. The
trigger highlights the attachment on hover and draws the focus ring around it.
While the pointer is on an action, only the action highlights.
The dialog's trigger goes in the attachment trigger's render, not the other
way round. DialogTrigger passes data-slot="dialog-trigger" to the element
it renders, which would replace the attachment trigger's own slot.
Accessibility
AttachmentAction renders a Button, and
AttachmentTrigger renders a button, or your element through render.
Icon-only actions
An AttachmentAction usually shows only an icon. Its aria-label should name
both the action and the file.
Label the trigger
AttachmentTrigger has no text of its own. Give it an aria-label that says
what activating it does.
The trigger sits under the actions, so each action and the trigger can be focused and clicked on their own.
Keyboard scrolling
When the attachments in a group have a trigger or actions, keyboard users reach
the ones off screen by tabbing to them. For a row of attachments with nothing to
focus, give the group tabIndex={0}, role="group" and an aria-label so the
row itself can be focused and scrolled.
Meaning beyond colour
The error state is a colour. Put the reason for the failure in
AttachmentDescription so the state is not carried by colour alone.
API reference
Pass render to replace a part's element or compose it with another component.
Every part also takes xstyle, className and style.
Attachment
Renders a div.
| Prop | Type | Default |
|---|---|---|
state | "idle" | "uploading" | "processing" | "error" | "done" | "done" |
size | "default" | "sm" | "xs" | "default" |
orientation | "horizontal" | "vertical" | "horizontal" |
A horizontal attachment fits its content, with a 160px minimum. Pass a width
through xstyle to fill a column.
AttachmentMedia
Renders a div.
| Prop | Type | Default |
|---|---|---|
variant | "icon" | "image" | "icon" |
A square tile, 40px at default, 32px at sm and 28px at xs. In a vertical
attachment it takes the full width and its icon grows to 24px. A
Spinner inside it follows the icon size.
AttachmentContent
Renders a div. Holds the title and description and takes the remaining width.
AttachmentTitle
Renders a span, truncated to one line. It shimmers when state is
uploading or processing.
AttachmentDescription
Renders a span at 12px, truncated to one line.
AttachmentActions
Renders a div that holds the actions above the trigger.
AttachmentAction
Renders a Button and accepts its props.
| Prop | Type | Default |
|---|---|---|
variant | ButtonVariant | "ghost", or "outline" in a vertical attachment |
size | ButtonSize | "icon-xs" |
AttachmentTrigger
Renders a button with type="button" that covers the attachment, its edge
included. With render, it renders your element and leaves type to you.
AttachmentGroup
Renders a div that scrolls sideways and snaps each attachment to its start.
attachmentStyles
The style maps behind the component. Spread them onto any element.
| Key | What it is |
|---|---|
base | The card: fill, hairline edge, inset and radius |
orientations | One entry per orientation |
sizes | One entry per size, the variables it changes |
states | One entry per state: the edge or fill |
media | The media tile |
mediaVertical | The full-width tile of a vertical attachment |
mediaError | The destructive tile |
mediaDimmed | The dimmed image while in progress or failed |
content | The flexible column |
contentVertical | The fixed-width column of a vertical attachment |
title | The truncated title |
description | The truncated metadata |
descriptionError | The destructive metadata |
actions | The actions row, above the trigger |
actionsVertical | The actions pinned over the image |
trigger | The covering trigger, its hover and focus ring |
group | The scrolling, snapping row |
Data attributes
| Attribute | On | Effect |
|---|---|---|
data-slot="attachment" | the root | Targets the attachment from a parent |
data-state | the root | Reflects state |
data-size | the root | Reflects size |
data-orientation | the root | Reflects orientation |
data-slot="attachment-media" | the media | Where interop.css fits an image |
data-variant | the media | Reflects variant |
data-slot="attachment-content" | the content | Targets the content from a parent |
data-slot="attachment-title" | the title | Targets the title from a parent |
data-slot="attachment-description" | the description | Targets the description from a parent |
data-slot="attachment-actions" | the actions | Targets the actions from a parent |
data-slot="attachment-action" | each action | Targets an action from a parent |
data-slot="attachment-trigger" | the trigger | Targets the trigger from a parent |
data-slot="attachment-group" | the group | Targets the group from a parent |
CSS variables
The root sets these, and each size other than default overrides some of
them. Set one through style to override it. xstyle rejects a style that
holds only custom properties.
| Variable | Effect |
|---|---|
--arene-attachment-inset | The padding, and what the media's corner subtracts |
--arene-attachment-gap | The gap between media, content and actions |
--arene-attachment-radius | The corner radius |
--arene-attachment-media-size | The media tile's width in a horizontal attachment |
--arene-attachment-icon-size | The icon size in the media tile |