Attachment

Displays a file or image attachment with media, metadata, upload state, and actions.

❯buridan add attachment

Component Guide

Use the following to build the Attachment component.

from components.ui.attachment import attachment

attachment.root(
    attachment.media(),
    attachment.content(
        attachment.title(),
        attachment.description(),
    ),
    attachment.actions(
        attachment.action()
    ),
)

Source Code & Dependencies

For manual installation, copy each of the source codes below in their respective locations.

components/core/core.py

components/ui/button.py

components/ui/attachment.py

Features

Icon and image media through attachment.media
Upload states: idle, uploading, processing, error, and done with built-in styling and a shimmer while in progress
Three sizes and horizontal or vertical orientation
A full-card attachment.trigger that opens a link or dialog while the actions stay independently clickable
Scrollable, snapping attachment.group with an edge fade
Customizable styling through the class_name prop on every part

Examples

Image

Set variant="image" on attachment.media and render an rx.el.img() inside it. Use orientation="vertical" to stack the media above the content.

Props used: variant on attachment.media; orientation on attachment.root.

workspace.pngPNG · 820 KB

desk-reference.jpgJPG · 1.1 MB

office-reference.jpgJPG · 940 KB

import reflex as rx

from components.core.hugeicon import hi
from components.ui.attachment import attachment

images = [
    {
        "name": "workspace.png",
        "meta": "PNG · 820 KB",
        "src": "https://images.unsplash.com/photo-1497366754035-f200968a6e72?w=900&auto=format&fit=crop&q=80",
        "alt": "Workspace",
    },
    {
        "name": "desk-reference.jpg",
        "meta": "JPG · 1.1 MB",
        "src": "https://images.unsplash.com/photo-1497215728101-856f4ea42174?w=900&auto=format&fit=crop&q=80",
        "alt": "Desk",
    },
    {
        "name": "office-reference.jpg",
        "meta": "JPG · 940 KB",
        "src": "https://images.unsplash.com/photo-1497366811353-6870744d04b2?w=900&auto=format&fit=crop&q=80",
        "alt": "Office",
    },
]


def attachment_image_demo():
    return rx.el.div(
        attachment.group(
            # rx.foreach(
            #     images,
            #     lambda image: attachment.root(
            #         attachment.trigger(
            #             link=True,
            #             href=image["src"],
            #             target="_blank",
            #             rel="noreferrer",
            #             aria_label=f"Open {image['name']}",
            #         ),
            #         attachment.media(
            #             rx.el.img(src=image["src"], alt=image["alt"]),
            #             variant="image",
            #         ),
            #         attachment.content(
            #             attachment.title(image["name"]),
            #             attachment.description(image["meta"]),
            #         ),
            #         attachment.actions(
            #             attachment.action(
            #                 hi("Cancel01Icon"),
            #                 aria_label=f"Remove {image['name']}",
            #             )
            #         ),
            #         orientation="vertical",
            #     ),
            # ),
            [
                attachment.root(
                    attachment.trigger(
                        link=True,
                        href=image["src"],
                        target="_blank",
                        rel="noreferrer",
                        aria_label=f"Open {image['name']}",
                    ),
                    attachment.media(
                        rx.el.img(src=image["src"], alt=image["alt"]),
                        variant="image",
                    ),
                    attachment.content(
                        attachment.title(image["name"]),
                        attachment.description(image["meta"]),
                    ),
                    attachment.actions(
                        attachment.action(
                            hi("Cancel01Icon"),
                            aria_label=f"Remove {image['name']}",
                        )
                    ),
                    orientation="vertical",
                )
                for image in images
            ],
            class_name="w-full",
        ),
        class_name="mx-auto w-full max-w-sm py-12",
    )

States

Set state to reflect the upload lifecycle. uploading and processing shimmer the title, and error switches to a destructive treatment.

Props used: state on attachment.root.

selected-file.pdfReady to upload

design-system.zipUploading · 64%

market-research.pdfProcessing document

financial-model.xlsxUpload failed. Try again.

uploaded-report.pdfUploaded · 1.8 MB

import reflex as rx

from components.core.hugeicon import hi
from components.ui.attachment import attachment
from components.ui.spinner import spinner


def attachment_states_demo():
    return rx.el.div(
        attachment.root(
            attachment.media(hi("Clock01Icon")),
            attachment.content(
                attachment.title("selected-file.pdf"),
                attachment.description("Ready to upload"),
            ),
            attachment.actions(
                attachment.action(
                    hi("Cancel01Icon"), aria_label="Remove selected-file.pdf"
                )
            ),
            state="idle",
        ),
        attachment.root(
            attachment.media(spinner()),
            attachment.content(
                attachment.title(
                    "design-system.zip",
                    class_name="shimmer",
                ),
                attachment.description("Uploading · 64%"),
            ),
            attachment.actions(
                attachment.action(hi("Cancel01Icon"), aria_label="Cancel upload")
            ),
            state="uploading",
        ),
        attachment.root(
            attachment.media(hi("File02Icon")),
            attachment.content(
                attachment.title("market-research.pdf"),
                attachment.description("Processing document"),
            ),
            attachment.actions(
                attachment.action(
                    hi("Cancel01Icon"), aria_label="Remove market-research.pdf"
                )
            ),
            state="processing",
        ),
        attachment.root(
            attachment.media(hi("FileExclamationPointIcon")),
            attachment.content(
                attachment.title("financial-model.xlsx"),
                attachment.description("Upload failed. Try again."),
            ),
            attachment.actions(
                attachment.action(hi("RefreshIcon"), aria_label="Retry upload"),
                attachment.action(
                    hi("Cancel01Icon"), aria_label="Remove financial-model.xlsx"
                ),
            ),
            state="error",
        ),
        attachment.root(
            attachment.media(hi("Tick02Icon")),
            attachment.content(
                attachment.title("uploaded-report.pdf"),
                attachment.description("Uploaded · 1.8 MB"),
            ),
            attachment.actions(
                attachment.action(
                    hi("Cancel01Icon"), aria_label="Remove uploaded-report.pdf"
                )
            ),
            state="done",
        ),
        class_name="w-full mx-auto max-w-sm py-12 flex flex-col gap-y-4",
    )

Sizes

Use size to switch between default, sm, and xs.

Props used: size on attachment.root.

Default attachmentPDF · 2.4 MB

Small attachmentPDF · 2.4 MB

Extra small attachment

import reflex as rx

from components.core.hugeicon import hi
from components.ui.attachment import attachment


def attachment_sizes_demo():
    return rx.el.div(
        attachment.root(
            attachment.media(hi("File02Icon")),
            attachment.content(
                attachment.title("Default attachment"),
                attachment.description("PDF · 2.4 MB"),
            ),
            size="default",
        ),
        attachment.root(
            attachment.media(hi("File02Icon")),
            attachment.content(
                attachment.title("Small attachment"),
                attachment.description("PDF · 2.4 MB"),
            ),
            size="sm",
        ),
        attachment.root(
            attachment.media(hi("File02Icon")),
            attachment.content(
                attachment.title("Extra small attachment"),
            ),
            size="xs",
        ),
        class_name="mx-auto w-full max-w-sm py-12 flex flex-col gap-y-4",
    )

Group

Wrap attachments in attachment.group to lay them out in a horizontally scrollable, snapping row with an edge fade.

Props used: none required beyond default attachment.group composition.

briefing-notes.pdfPDF · 1.4 MB

workspace.pngPNG · 820 KB

customers.csvCSV · 18 KB

renderer.tsxTSX · 12 KB

import reflex as rx

from components.core.hugeicon import hi
from components.ui.attachment import attachment

items = [
    {"name": "briefing-notes.pdf", "meta": "PDF · 1.4 MB", "type": "file"},
    {
        "name": "workspace.png",
        "meta": "PNG · 820 KB",
        "src": "https://images.unsplash.com/photo-1497366754035-f200968a6e72?w=900&auto=format&fit=crop&q=80",
        "type": "image",
    },
    {"name": "customers.csv", "meta": "CSV · 18 KB", "type": "file"},
    {"name": "renderer.tsx", "meta": "TSX · 12 KB", "type": "file"},
]


def attachment_group_demo():
    return rx.el.div(
        attachment.group(
            # rx.foreach(
            #     items,
            #     lambda item: attachment.root(
            #         rx.cond(
            #             item["type"] == "image",
            #             attachment.media(
            #                 rx.el.img(src=item["src"], alt=item["name"]),
            #                 variant="image",
            #             ),
            #             attachment.media(hi("File02Icon")),
            #         ),
            #         attachment.content(
            #             attachment.title(item["name"]),
            #             attachment.description(item["meta"]),
            #         ),
            #         attachment.actions(
            #             attachment.action(
            #                 hi("Cancel01Icon"), aria_label=f"Remove {item['name']}"
            #             )
            #         ),
            #         class_name="w-64",
            #     ),
            # ),
            [
                attachment.root(
                    attachment.media(
                        rx.el.img(src=item["src"], alt=item["name"]),
                        variant="image",
                    )
                    if item["type"] == "image"
                    else attachment.media(hi("File02Icon")),
                    attachment.content(
                        attachment.title(item["name"]),
                        attachment.description(item["meta"]),
                    ),
                    attachment.actions(
                        attachment.action(
                            hi("Cancel01Icon"),
                            aria_label=f"Remove {item['name']}"
                        )
                    ),
                    class_name="w-64",
                )
                for item in items
            ],
            class_name="full",
        ),
        class_name="mx-auto w-full max-w-sm py-12",
    )

Trigger

Add an attachment.trigger to make the whole card open a link or dialog. It fills the card behind the actions, so the actions stay clickable.

Props used: link, href, aria_label on attachment.trigger.

research-summary.pdfOpen preview dialog

import reflex as rx

from components.core.hugeicon import hi
from components.ui.attachment import attachment
from components.ui.dialog import dialog


def attachment_trigger_dialog_demo():
    return rx.el.div(
        dialog.root(
            attachment.root(
                attachment.media(hi("File01Icon")),
                attachment.content(
                    attachment.title("research-summary.pdf"),
                    attachment.description("Open preview dialog"),
                ),
                attachment.actions(
                    attachment.action(hi("Copy01Icon"), aria_label="Copy link"),
                    attachment.action(
                        hi("Cancel01Icon"), aria_label="Remove research-summary.pdf"
                    ),
                ),
                dialog.trigger(attachment.trigger(link=False)),
                class_name="w-full",
            ),
            dialog.popup(
                dialog.title("research-summary.pdf"),
                dialog.description(
                    "The attachment trigger fills the card and opens the dialog, "
                    "while the actions stay independently clickable above it."
                ),
                class_name="max-w-md rounded-2xl",
            ),
        ),
        class_name="mx-auto w-full max-w-sm py-12",
    )

Accessibility

attachment.action renders a Button, and attachment.trigger renders either a real rx.el.button() or a rx.el.a() if the link prop is set to True. Follow the guidance below so both are operable and announced.

Label icon-only actions

attachment.action is usually icon-only, so give each one an aria-label describing the action and its target.

attachment.action(
    hi("Cancel01Icon"), aria_label="Remove market-research.pdf"
)

Label the trigger

attachment.trigger overlays the entire attachment with a clickable surface.

Use aria_label to describe what activating the attachment does. This is required when the trigger has no visible text.

Link trigger (opens a URL)

attachment.trigger(
    link=True,
    href=url,
    target="_blank",
    rel="noreferrer",
    aria_label="Open workspace.png",
)

Button trigger (interactive action)

attachment.trigger(
    on_click=handle_open,
    aria_label="Open attachment preview",
)

The trigger sits behind the actions in the stacking order, so an attachment.action and the attachment.trigger never trap each other — both remain separately focusable and clickable.

Keyboard scrolling

An attachment.group scrolls horizontally. When its attachments are interactive: a trigger or actions, keyboard users reach off-screen items by tabbing to them. For a row of presentational attachments, make the group itself focusable and scrollable by adding tabIndex={0}, role="group", and an aria-label.

Meaning beyond color

The error state uses a destructive color. Keep the failure reason in attachment.description so the state is not conveyed by color alone.

API Reference

attachment.root

The root attachment container.

Prop	Type	Default	Description
`state`	`Literal["idle", "uploading", "processing", "error", "done"]`	`"done"`	The upload state. Drives styling and the shimmer.
`size`	`Literal["default", "sm", "xs"]`	`"default"`	The attachment size.
`orientation`	`Literal["horizontal", "vertical"]`	`"horizontal"`	Lay the media beside or above the content.
`class_name`	`str`	-	Additional classes to apply to the root element.

attachment.media

The media slot for an icon or image preview.

Prop	Type	Default	Description
`variant`	`Literal["icon", "image"]`	`"icon"`	Whether the media holds an icon or an `<img>`.
`class_name`	`str`	-	Additional classes to apply to the media slot.

attachment.content

Wraps the title and description.

Prop	Type	Default	Description
`class_name`	`str`	-	Additional classes to apply to the content slot.

attachment.title

The attachment name. Shimmers while the attachment is uploading or processing.

Prop	Type	Default	Description
`class_name`	`str`	-	Additional classes to apply to the title.

attachment.description

Secondary metadata such as the file type, size, or upload status.

Prop	Type	Default	Description
`class_name`	`str`	-	Additional classes to apply to the description.

attachment.actions

A container for one or more actions, aligned to the end of the attachment.

Prop	Type	Default	Description
`class_name`	`str`	-	Additional classes to apply to the actions.

attachment.action

An action button. Renders a Button and accepts all of its props.

Prop	Type	Default	Description
`size`	`Literal["default", "xs", "sm", "lg", "icon", "icon-xs", "icon-sm", "icon-lg"]`	`"icon-xs"`	The button size.
`class_name`	`str`	-	Additional classes to apply to the actions.

attachment.trigger

A full-card overlay that activates the attachment. Renders a rx.el.button by default or a rx.el.a when link=True.

Prop	Type	Default	Description
`link`	`bool`	`False`	If set, renders an anchor (`rx.el.a`) instead of a button.
`aria_label`	`str \| None`	`None`	Accessibility label for screen readers. Required when no visible text exists.
`class_name`	`str`	`""`	Additional CSS classes applied to the trigger.

attachment.group

Lays out attachments in a horizontally scrollable, snapping row.

Prop	Type	Default	Description
`class_name`	`str`	-	Additional classes to apply to the group.