filename names the resource and the actions generated for it; description carries type, size or progress. Your application owns uploading, retrying, previewing and removing: status only changes how the attachment looks.
Status
Statuses
Default density
Compact density
Restart from the initial state
Show the copyable source
<div style="display:grid;gap:var(--tp-space-2);inline-size:100%;max-inline-size:26rem;margin-inline:auto">
<tp-attachment filename="contract-v3.docx" description="Ready to upload · 220 KB" status="idle" removable></tp-attachment>
<tp-attachment filename="product-demo.mp4" description="Uploading · 38%" status="uploading"></tp-attachment>
<tp-attachment filename="survey-results.xlsx" description="Scanning for viruses" status="processing"></tp-attachment>
<tp-attachment filename="receipt-0412.heic" status="error" error-message="HEIC isn't supported. Export as JPG or PNG and try again." removable></tp-attachment>
<tp-attachment filename="brand-guidelines.pdf" file-size="3355443" status="complete" href="#attachment-status" removable></tp-attachment>
</div>
Busy states show a spinner when no media is supplied. An error must explain recovery, through error-message or the description. Without a description, file-size is formatted for you. href turns the attachment into a link to the resource.
Images
Image cards
Default density
Compact density
Restart from the initial state
Show the copyable source
orientation="vertical" with media-treatment="image" makes a thumbnail card. tp-attachment-group lays attachments out in a horizontally scrolling row with snap points; give it an aria-label.
File cards and rows in a group
Scrollable groups
Default density
Compact density
Restart from the initial state
Show the copyable source
File marks work in vertical cards too, and a group mixes files and images freely. Rows scroll the same way as cards, which suits a composer’s attachment tray. The group is focusable so keyboard users can scroll it.
Without media
Title and description only
Default density
Compact density
Restart from the initial state
Show the copyable source
A trigger button makes the whole attachment open something, here a preview dialog registered with registerTrigger(). Buttons in the actions slot stay separate controls, so Download, Retry and Remove never set the trigger off. Do not attach an open handler to the whole attachment: that would conflate its independent actions.
Sizes
Sizes
Default density
Compact density
Restart from the initial state
Show the copyable source
removable adds a Remove button that emits a cancelable tp-remove with the filename. Nothing is removed until your handler does it, so you can confirm first or delete the file on the server.
API Reference
Every element also accepts motion-policy.
Attributes
AttributePropertyTypeDefaultDescriptionfilenamefilenamestring''The resource's name, shown as its title and used in the names of the generated actions.hrefhrefstring''Makes the whole attachment a link to the resource.targettargetstring''Where the link opens, as on a native link.file-sizefileSizenumber0The size in bytes, formatted for the reader's locale when there is no description.descriptiondescriptionstring''Type, size, progress or other detail under the title.error-messageerrorMessagestring''What went wrong and how to recover, shown while status is error.sizesize'xs' | 'sm' | 'default''default'The attachment's density.statusstatusAttachmentStatus'idle'The application's upload status: idle before upload, uploading and processing while busy.media-treatmentmediaTreatment'mark' | 'image''mark'Presents the media as a file mark or as an image that fills the media area.removableremovablebooleanfalseAdds a Remove button that fires tp-remove.
Properties
PropertyTypeDefaultDescriptionmessagesPartial<AttachmentMessages>{}Replacements for the generated text, such as the Remove button's name; missing entries keep the defaults.
Events
EventTypeDescriptiontp-removeCustomEvent<{ filename: string; sourceEvent: Event; }>The Remove button was pressed; detail.filename names the attachment. Cancelable, and nothing is removed until the application does it.
Slots
SlotDescriptionmediaA file mark or an image; while uploading or processing without one, a Spinner shows.previewMedia used when no media content is supplied.titleThe title, in place of filename; keep filename for the names of the generated actions.descriptionDetail or status in place of the generated description; for an error, how to recover.defaultMore content about the resource, below the description.actionsButtons that act on the resource, each a separate control from the trigger.triggerA Button that makes the whole attachment open something, such as a preview Dialog.
CSS parts
PartDescription::part(attachment)The scrolling row of an Attachment group.::part(attachment-action)Each action Button, including the generated Remove button.::part(attachment-actions)The row of actions.::part(attachment-content)The column of title, description and extra content.::part(attachment-description)The description or status line, announced politely when it changes.::part(attachment-media)The area holding the file mark, image or Spinner.::part(attachment-root)The attachment surface, whose border follows the status.::part(attachment-title)The title.::part(attachment-trigger)The trigger Button that covers the attachment.
<tp-attachment-group>
Slots
SlotDescriptiondefaultThe Attachments.
CSS parts
PartDescription::part(attachment)The scrolling row of an Attachment group.
Related
Components, widgets and patterns that use this one.