---
title: "Attachment"
description: "Attachment with accessible presentation and local state."
---

# Attachment

Attachment with accessible presentation and local state.

## Installation

Install the shared package once in your Exact app. This version is a beta.

```sh
bun add --exact @rightui/ui@0.4.0-beta.4
```

Or choose another package manager:

```sh
npm install --save-exact @rightui/ui@0.4.0-beta.4
pnpm add --save-exact @rightui/ui@0.4.0-beta.4
yarn add --exact @rightui/ui@0.4.0-beta.4
```

Exact compilation uses Bun 1.4.2. Register Geist and Newsreader, declare the font marker and add the root provider using [Installation](/docs/installation).

### Manual source setup

Install an editable copy of the complete package:

```sh
mkdir -p vendor/rightui vendor/rightui-ui
npm pack @rightui/ui@0.4.0-beta.4 --pack-destination vendor/rightui
tar -xzf ./vendor/rightui/rightui-ui-0.4.0-beta.4.tgz -C vendor/rightui-ui --strip-components=1
bun add file:./vendor/rightui-ui
```

Keep package.json, the Contract files, ui.tamber, assets and licenses together.

### Import

```contract
use Attachment, AttachmentOptions, AttachmentFrame, AttachmentMedia, AttachmentContent, AttachmentTitle, AttachmentDescription, AttachmentActions, AttachmentAction, AttachmentTrigger, AttachmentGroup, AttachmentPreview from "@rightui/ui"
```

## Usage

Import Attachment(id, name, metadata, content, status, remove) for the legacy wrapper. Use AttachmentOptions for explicit size, orientation, imageSource, cardWidth, previewHref, reduced, copyable and copyValue, alongside the legacy props. Compose groups and previews with the public Attachment parts. Empty previewHref opens the built-in content preview; a nonempty value is a real link. Retry is a caller-owned AttachmentAction that updates status and content. Pass every prop explicitly; image examples use external image URLs.

## Example

```contract
use FontWeights from "@rightui/ui"
use uiFontFamily, AttachmentOptions, Button, AttachmentGroup, AttachmentFrame, AttachmentMedia, AttachmentContent, AttachmentTitle, AttachmentDescription, AttachmentActions, AttachmentAction, AttachmentTrigger, AttachmentPreview from "@rightui/ui"
use AttachmentDemoFile, attachmentDemoFiles, attachmentDemoDocuments from "./attachment-data.contract"

component Demo
  props
    width: number
    reduced: bool
  inject
    uiWeights: FontWeights
    uiFont: string
  state attached = true
  state linked = true
  state uploading = true
  state failed = true
  state processing = true
  state idle = true
  state processed = false
  state retried = false
  state recoveredContent = ""
  state errorPreview = false
  state files: AttachmentDemoFile[] = attachmentDemoFiles()
  state compactFiles: AttachmentDemoFile[] = attachmentDemoFiles()
  state documents: AttachmentDemoFile[] = attachmentDemoDocuments()
  action remove
    attached = false
  action removeLink
    linked = false
  action removeUpload
    uploading = false
  action removeError
    failed = false
  action removeProcessing
    processing = false
  action removeIdle
    idle = false
  action finish
    processed = true
  action retry
    recoveredContent = "component,status\nButton,ready\nCard,ready\nCheckbox,ready"
    retried = true
  action previewError
    errorPreview = true
  action closeError
    errorPreview = false
    focus("attachment-error-preview")
  action removeFile(key: string)
    files = files.filter(file => file.id != key)
  action removeCompact(key: string)
    compactFiles = compactFiles.filter(file => file.id != key)
  action removeDocument(key: string)
    documents = documents.filter(file => file.id != key)
  action restore
    attached = true
    linked = true
    uploading = true
    failed = true
    processing = true
    idle = true
    processed = false
    retried = false
    recoveredContent = ""
    files = attachmentDemoFiles()
    compactFiles = attachmentDemoFiles()
    documents = attachmentDemoDocuments()
  view
    column gap="ui.space-16" min-width="0px" max-width="100%" width="100%"
      text "Preview and actions" font-weight=uiWeights.semibold font-family=uiFontFamily(uiFont) data-rightui-font="body"
      if attached
        AttachmentOptions(id="content-attachment", name="project-brief.txt", metadata="Text · Project overview · Ready", content="RightUI component review\nCheck keyboard navigation, responsive layouts and shared themes.\nDeliver a reusable Exact interface.", status="done", copyable=true, reduced=reduced, remove=remove, size="default", orientation="horizontal", imageSource="", cardWidth="", previewHref="", copyValue="")
      Button(id="attachment-restore", label="Restore sample attachments", variant="outline", disabled=false, press=restore)
      if linked
        AttachmentOptions(id="attachment-link", name="rightui-guide.txt", metadata="Text · Open the RightUI guide", content="", imageSource="", previewHref="https://rightui.dev/llms.txt", copyable=true, copyValue="https://rightui.dev/llms.txt", status="done", reduced=reduced, remove=removeLink, size="default", orientation="horizontal", cardWidth="")
      text "Document previews" font-weight=uiWeights.semibold font-family=uiFontFamily(uiFont) data-rightui-font="body"
      AttachmentGroup(id="attachment-documents", label="Document previews", compact=false)
        for file in documents key=file.id
          AttachmentOptions(id="attachment-document-" + file.id, name=file.name, metadata=file.metadata, content=file.content, imageSource=file.source, orientation="vertical", status="done", reduced=reduced, remove=removeDocument(file.id), size="default", cardWidth="", previewHref="", copyable=false, copyValue="")
      if documents.length == 0
        text "No documents. Restore the samples to start again." role="status" font-family=uiFontFamily(uiFont) data-rightui-font="body"
      text "Full attachment group" font-weight=uiWeights.semibold font-family=uiFontFamily(uiFont) data-rightui-font="body"
      AttachmentGroup(id="attachment-group-full", label="Project files", compact=false)
        for file in files key=file.id
          AttachmentOptions(id="attachment-full-" + file.id, name=file.name, metadata=file.metadata, content=file.content, imageSource=file.source, cardWidth="18rem", status="done", reduced=reduced, remove=removeFile(file.id), size="default", orientation="horizontal", previewHref="", copyable=false, copyValue="")
      if files.length == 0
        text "No attachments. Restore the samples to start again." role="status" font-family=uiFontFamily(uiFont) data-rightui-font="body"
      text "Compact attachment group" font-weight=uiWeights.semibold font-family=uiFontFamily(uiFont) data-rightui-font="body"
      AttachmentGroup(id="attachment-group-compact", label="Compact attachments", compact=true)
        for file in compactFiles key=file.id
          AttachmentOptions(id="attachment-compact-" + file.id, name=file.name, metadata=file.metadata, content=file.content, imageSource=file.source, cardWidth="15rem", size="xs", status="done", reduced=reduced, remove=removeCompact(file.id), orientation="horizontal", previewHref="", copyable=false, copyValue="")
      if compactFiles.length == 0
        text "No compact attachments." role="status" font-family=uiFontFamily(uiFont) data-rightui-font="body"
      text "States and sizes" font-weight=uiWeights.semibold font-family=uiFontFamily(uiFont) data-rightui-font="body"
      text "The following states demonstrate local preparation; no file is sent." font-size="ui.text-sm" color="ui.muted-foreground" font-family=uiFontFamily(uiFont) data-rightui-font="body"
      if idle
        AttachmentOptions(id="attachment-idle", name="component-inventory.csv", metadata="CSV · Ready to upload", content="component,status\nButton,ready", status="idle", size="xs", reduced=reduced, remove=removeIdle, orientation="horizontal", imageSource="", cardWidth="", previewHref="", copyable=false, copyValue="")
      if uploading
        AttachmentOptions(id="attachment-uploading", name="layout-outline.txt", metadata="Uploading · 64% · Local demo", content="Header, content and footer share the same page container.", status="uploading", reduced=reduced, remove=removeUpload, size="default", orientation="horizontal", imageSource="", cardWidth="", previewHref="", copyable=false, copyValue="")
      if processing
        AttachmentOptions(id="attachment-processing", name="accessibility-notes.txt", metadata=(processed ? "Prepared locally" : "Processing document"), content="Check focus order, labels and keyboard controls in each component.", status=(processed ? "done" : "processing"), size="sm", reduced=reduced, remove=removeProcessing, orientation="horizontal", imageSource="", cardWidth="", previewHref="", copyable=false, copyValue="")
        Button(id="attachment-finish", label="Finish local processing", variant="outline", disabled=processed, press=finish)
      if failed
        AttachmentFrame(id="attachment-error", status=(retried ? "done" : "error"), size="default", orientation="horizontal", cardWidth="")
          AttachmentMedia(name="release-checklist.csv", status=(retried ? "done" : "error"), reduced=reduced, source="", size="default", orientation="horizontal")
          AttachmentContent()
            AttachmentTitle(name="release-checklist.csv", status=(retried ? "done" : "error"), reduced=reduced, size="default")
            AttachmentDescription(text=(retried ? "Local preview ready · CSV · 3 rows" : "Local preview unavailable. Retry preparation."), status=(retried ? "done" : "error"))
          AttachmentActions(orientation="horizontal")
            if not retried
              AttachmentAction(id="attachment-error-retry", label="Retry release-checklist.csv preparation", icon="retry", press=retry)
            AttachmentAction(id="attachment-error-remove", label="Remove release-checklist.csv", icon="remove", press=removeError)
          AttachmentTrigger(id="attachment-error-preview", label="Preview release-checklist.csv", disabled=(not retried), expanded=errorPreview, controls="attachment-error-dialog", press=previewError, href="")
        if retried
          text "Preview prepared. Open the card to inspect the CSV." role="status" font-size="ui.text-xs" font-family=uiFontFamily(uiFont) data-rightui-font="body"
      AttachmentPreview(id="attachment-error-dialog", open=errorPreview, name="release-checklist.csv", metadata="CSV · Prepared locally", content=recoveredContent, reduced=reduced, dismiss=closeError, contentId="", imageSource="")

```

## API Reference

| Property | Type |
| --- | --- |
| AttachmentFrame.id | string |
| AttachmentFrame.status | string |
| AttachmentFrame.size | string |
| AttachmentFrame.orientation | string |
| AttachmentFrame.cardWidth | string |
| AttachmentMedia.name | string |
| AttachmentMedia.source | string |
| AttachmentMedia.status | string |
| AttachmentMedia.size | string |
| AttachmentMedia.orientation | string |
| AttachmentMedia.reduced | bool |
| AttachmentTitle.name | string |
| AttachmentTitle.status | string |
| AttachmentTitle.size | string |
| AttachmentTitle.reduced | bool |
| AttachmentDescription.text | string |
| AttachmentDescription.status | string |
| AttachmentActions.orientation | string |
| AttachmentAction.id | string |
| AttachmentAction.label | string |
| AttachmentAction.icon | string |
| AttachmentAction.press | action |
| AttachmentTrigger.id | string |
| AttachmentTrigger.label | string |
| AttachmentTrigger.disabled | bool |
| AttachmentTrigger.expanded | bool |
| AttachmentTrigger.controls | string |
| AttachmentTrigger.href | string |
| AttachmentTrigger.press | action |
| AttachmentGroup.id | string |
| AttachmentGroup.label | string |
| AttachmentGroup.compact | bool |
| AttachmentPreview.id | string |
| AttachmentPreview.open | bool |
| AttachmentPreview.name | string |
| AttachmentPreview.metadata | string |
| AttachmentPreview.content | string |
| AttachmentPreview.contentId | string |
| AttachmentPreview.imageSource | string |
| AttachmentPreview.reduced | bool |
| AttachmentPreview.dismiss | action |
| Attachment.id | string |
| Attachment.name | string |
| Attachment.metadata | string |
| Attachment.content | string |
| Attachment.status | string |
| Attachment.remove | action |
| AttachmentOptions.id | string |
| AttachmentOptions.name | string |
| AttachmentOptions.metadata | string |
| AttachmentOptions.content | string |
| AttachmentOptions.status | string |
| AttachmentOptions.remove | action |
| AttachmentOptions.size | string |
| AttachmentOptions.orientation | string |
| AttachmentOptions.imageSource | string |
| AttachmentOptions.cardWidth | string |
| AttachmentOptions.previewHref | string |
| AttachmentOptions.reduced | bool |
| AttachmentOptions.copyable | bool |
| AttachmentOptions.copyValue | string |

## Source

File: packages/ui/conversation.contract

```contract
use FontWeights from "./typography-context.contract"
use uiFontFamily from "./typography-context.contract"
use Control from "./styles.contract"
use AttachmentFrame, AttachmentMedia, AttachmentContent, AttachmentTitle, AttachmentDescription, AttachmentActions, AttachmentAction, AttachmentTrigger, AttachmentPreview from "./attachment-parts.contract"
use BubbleFrame from "./conversation-parts.contract"
use BubbleReactions from "./bubble-parts.contract"
use Avatar from "./display.contract"

component Attachment
  props
    id: string
    name: string
    metadata: string
    content: string
    status: string
    remove: action
  view
    AttachmentOptions(id=id, name=name, metadata=metadata, content=content, status=status, remove=remove, size="default", orientation="horizontal", imageSource="", cardWidth="", previewHref="", reduced=true, copyable=false, copyValue="")

component AttachmentOptions
  props
    id: string
    name: string
    metadata: string
    content: string
    status: string
    remove: action
    size: string
    orientation: string
    imageSource: string
    cardWidth: string
    previewHref: string
    reduced: bool
    copyable: bool
    copyValue: string
  inject
    uiFont: string
  state preview = false
  state copied = false
  action toggle
    preview = not preview
  action dismiss
    preview = false
    focus(id + "-preview")
  action copy
    copyText(copyValue == "" ? content : copyValue)
    copied = true
  view
    AttachmentFrame(id=id, status=status, size=size, orientation=orientation, cardWidth=cardWidth)
      AttachmentMedia(name=name, source=imageSource, status=status, size=size, orientation=orientation, reduced=reduced)
      AttachmentContent()
        AttachmentTitle(name=name, status=status, size=size, reduced=reduced)
        if metadata != ""
          AttachmentDescription(text=metadata, status=status)
      AttachmentActions(orientation=orientation)
        if copyable and (content != "" or copyValue != "")
          AttachmentAction(id=id + "-copy", label=(copied ? "Copied " : copyValue == "" ? "Copy " : "Copy link to ") + name, icon="copy", press=copy)
        AttachmentAction(id=id + "-remove", label="Remove " + name, icon="remove", press=remove)
      AttachmentTrigger(id=id + "-preview", label=(previewHref == "" ? "Preview " + name : "Open " + name + " (opens in a new tab)"), disabled=(status != "done"), expanded=preview, controls=id + "-dialog", href=(status == "done" ? previewHref : ""), press=toggle)
    if copied
      text ("Copied " + name) role="status" font-size="ui.text-xs" color="ui.muted-foreground" font-family=uiFontFamily(uiFont) data-rightui-font="body"
    AttachmentPreview(id=id + "-dialog", open=preview, name=name, metadata=metadata, content=content, contentId=id + "-content", imageSource=imageSource, reduced=reduced, dismiss=dismiss)

component Bubble
  props
    id: string
    body: string
    align: string
    variant: string
    collapsible: bool
  view
    BubbleOptions(id=id, body=body, align=align, variant=variant, collapsible=collapsible, reactions=true, reduced=true, initialCollapsed=false, previewLength=180)

component BubbleOptions
  props
    id: string
    body: string
    align: string
    variant: string
    collapsible: bool
    reactions: bool
    reduced: bool
    initialCollapsed: bool
    previewLength: number
  inject
    uiWeights: FontWeights
    uiFont: string
  state bubbleCollapsed: bool = initialCollapsed
  state bubbleReacted: bool = false
  derive shownBody = collapsible and bubbleCollapsed ? body.slice(0, previewLength) + (body.length > previewLength ? "…" : "") : body
  action toggle
    bubbleCollapsed = not bubbleCollapsed
  action react
    bubbleReacted = not bubbleReacted
  view
    BubbleFrame(id=id, align=align, variant=variant)
      column gap="ui.space-6" min-width="0px"
        text shownBody id=(id + "-body") testId=(id + "-body") font-size="ui.text-sm" line-height="ui.leading-code" white-space="pre-wrap" overflow-wrap="break-word" font-family=uiFontFamily(uiFont) data-rightui-font="body"
        if collapsible
          button id=(id + "-collapse") testId=(id + "-collapse") class=Control font-weight=uiWeights.medium press=toggle aria-expanded=(not bubbleCollapsed) aria-controls=(id + "-body") display="flex" align-items="center" gap="ui.space-4" padding="0px" min-height="ui.space-24" border="none" background-color="transparent" color="inherit" align-self="flex-start"
            text (bubbleCollapsed ? "Show more" : "Show less") font-size="ui.text-xs" font-family=uiFontFamily(uiFont) data-rightui-font="body"
            svg width="ui.space-14" height="ui.space-14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="ui.stroke-standard" rotate=(bubbleCollapsed ? "0deg" : "180deg") transition=(reduced ? "none" : "rotate ui.duration-fast ui.easing") aria-hidden=true
              path d="m6 9 6 6 6-6"
      if reactions
        BubbleReactions(id=id + "-reactions", label="Message reactions", side="bottom", align="end", interactive=true)
          button id=(id + "-reaction") testId=(id + "-reaction") class=Control font-weight=uiWeights.medium press=react aria-pressed=bubbleReacted aria-label="Helpful reaction" min-height="ui.space-24" padding="ui.space-2 ui.space-8" border="none" border-radius="ui.radius-full" background-color="transparent" color="ui.foreground"
            text (bubbleReacted ? "Helpful · 1" : "Helpful") font-size="ui.text-xs" font-family=uiFontFamily(uiFont) data-rightui-font="body"

component Marker
  props
    id: string
    label: string
    variant: string
  inject
    uiFont: string
  view
    row id=id testId=id gap="ui.space-8" align-items="center" min-height="ui.space-16" padding-bottom=(variant == "border" ? "ui.space-8" : "0px") border-bottom-width=(variant == "border" ? "ui.border-width" : "0px") border-bottom-style="solid" border-bottom-color="ui.border"
      if variant == "separator"
        view flex=1 height="ui.border-width" background-color="ui.border" aria-hidden=true
      text label font-size="ui.text-sm" color="ui.muted-foreground" overflow-wrap="break-word" font-family=uiFontFamily(uiFont) data-rightui-font="body"
      if variant == "separator"
        view flex=1 height="ui.border-width" background-color="ui.border" aria-hidden=true

component Message
  props
    id: string
    author: string
    initials: string
    time: string
    align: string
  slot
  view
    MessageRow(id=id, align=align)
      MessageAvatar()
        Avatar(id=id + "-avatar", src="", name=author, fallback=initials)
      MessageBody(align=align)
        if author != ""
          MessageHeader(label=author)
        children
        if time != ""
          MessageMeta(label=time, align=align)

component MessageGroup
  props
    id: string
  slot
  view
    column id=id testId=id gap="ui.space-8" width="100%" min-width="0px" max-width="100%"
      children

component MessageRow
  props
    id: string
    align: string
  slot
  view
    row id=id testId=id gap="ui.space-8" width="100%" min-width="0px" flex-direction=(align == "end" ? "row-reverse" : "row")
      children

component MessageAvatar
  slot
  view
    view flex-shrink=0 align-self="flex-end" width="ui.avatar-size" min-width="ui.avatar-size" display="flex" align-items="center" justify-content="center"
      children

component MessageBody
  props
    align: string
  slot
  view
    column gap="ui.space-10" flex=1 min-width="0px" align-items=(align == "end" ? "flex-end" : "flex-start") overflow-wrap="break-word"
      children

component MessageHeader
  props
    label: string
  inject
    uiWeights: FontWeights
    uiFont: string
  slot
  view
    row gap="ui.space-8" align-items="center" max-width="100%" min-width="0px" padding="0px ui.space-12"
      if label != ""
        text label font-size="ui.text-xs" font-weight=uiWeights.medium color="ui.muted-foreground" font-family=uiFontFamily(uiFont) data-rightui-font="body"
      children

component MessageMeta
  props
    label: string
    align: string
  inject
    uiFont: string
  slot
  view
    row gap="ui.space-8" align-items="center" justify-content=(align == "end" ? "flex-end" : "flex-start") align-self=(align == "end" ? "flex-end" : "flex-start") flex-wrap="wrap" max-width="100%" min-width="0px" padding="0px ui.space-12"
      if label != ""
        text label font-size="ui.text-xs" color="ui.muted-foreground" font-family=uiFontFamily(uiFont) data-rightui-font="body"
      children

keyframes uiTypingWave
  from translate="0px 0px"
  25% translate="0px -4px"
  50% translate="0px 0px"
  to translate="0px 0px"

component MessageTyping
  props
    id: string
    label: string
    reduced: bool
  inject
    uiFont: string
  view
    row id=id testId=id role="status" aria-label=label align-items="center" gap="ui.space-8" color="ui.muted-foreground"
      row aria-hidden=true gap="ui.space-4" align-items="center" height="ui.space-16"
        for dot in [0, 1, 2] key=dot
          view testId=(id + "-dot-" + dot.toString()) width="ui.space-4" height="ui.space-4" border-radius="ui.radius-full" background-color="currentColor" animation=(reduced ? "none" : ("uiTypingWave 1s ease-in-out " + (dot * 0.15).toString() + "s infinite"))
      text label font-size="ui.text-xs" font-family=uiFontFamily(uiFont) data-rightui-font="body"

```
