Skip to content
Back

Attachments

Files and context in the draft: upload rings, ready, reading and failed states with retry, too-large rejections, context chips for files, repos, selections and URLs, and drop zones.

oxyn add attachments
MCP
PNG
64%
PDF
RS
CSV
Dioxus
let items = vec![
    AttachmentItem::file(1, "login-flow.png", 1_400_000, AttachmentState::Uploading { progress: Some(0.64) }),
    AttachmentItem::file(2, "spec.pdf", 812_000, AttachmentState::Ready { meta: "PDF · 12 pages".into() }),
];

rsx! {
    AttachmentRow {
        items: items,
        now: clock.now(),
        on_remove: move |id: u64| remove(id),
        on_retry: move |id: u64| retry(id),
    }
}

Rendered from Rust at build time · goes live when visible

When to use

  • Agents work on material: screenshots of a bug, a CSV to analyse, a PDF contract, a folder, a URL, the repo itself, a 300-line log pasted from the terminal.
  • The attachment row is where that material waits before it is sent, and where the user learns whether the agent can actually use it (uploaded? read? too big? wrong type?).
  • Most kits show a filename and a spinner.
  • We show every step from queued to ready, make failure recoverable in place, and keep context chips (files, URLs, repo) visually distinct from uploaded files so the user knows what will be *sent* versus *referenced*.

When not to use

  • Prompt composer with model picker, voice input, app connections and approval request: use Chat Composer instead.
  • The model menu of an AI chat: use Model Picker instead.
  • The prompt box for an agent, in six layouts: use Composer instead.

Installation

Attachments is free and MIT. The oxyn CLI copies its code, and the components it needs, into src/oxyn/ of your Dioxus or GPUI project, so it is yours to change.

Terminal
cargo install --git https://github.com/ismailqureshi72/Oxyn oxyn-cli
oxyn init
oxyn add attachments
Rust
use crate::oxyn::{AttachmentRow, DropZone, COMPOSER_CSS};

Rather depend on the crate? cargo add oxyn-dioxus oxyn-core --git https://github.com/ismailqureshi72/Oxyn, then use oxyn_dioxus::{AttachmentRow, DropZone, COMPOSER_CSS};

Usage

Dioxus · rust
let items = vec![
    AttachmentItem::file(1, "login-flow.png", 1_400_000, AttachmentState::Uploading { progress: Some(0.64) }),
    AttachmentItem::file(2, "spec.pdf", 812_000, AttachmentState::Ready { meta: "PDF · 12 pages".into() }),
];

rsx! {
    AttachmentRow {
        items: items,
        now: clock.now(),
        on_remove: move |id: u64| remove(id),
        on_retry: move |id: u64| retry(id),
    }
}

Examples

Tile ring

Tiles with upload rings.

PNG
64%
PDF
RS
CSV
Code
let items = vec![
    AttachmentItem::file(1, "login-flow.png", 1_400_000, AttachmentState::Uploading { progress: Some(0.64) }),
    AttachmentItem::file(2, "spec.pdf", 812_000, AttachmentState::Ready { meta: "PDF · 12 pages".into() }),
];

rsx! {
    AttachmentRow {
        items: items,
        now: clock.now(),
        on_remove: move |id: u64| remove(id),
        on_retry: move |id: u64| retry(id),
    }
}

Chip

Compact chips.

login-flow.png64 %
spec.pdfPDF · 12 pages
auth.rsRS · 18 KB
q3-revenue.csvUpload failed
Code
let items = vec![
    AttachmentItem::file(1, "login-flow.png", 1_400_000, AttachmentState::Uploading { progress: Some(0.64) }),
    AttachmentItem::file(2, "spec.pdf", 812_000, AttachmentState::Ready { meta: "PDF · 12 pages".into() }),
];

rsx! {
    AttachmentRow {
        items: items,
        now: clock.now(),
        variant: "chip",
        on_remove: move |id: u64| remove(id),
        on_retry: move |id: u64| retry(id),
    }
}

List

A list with sizes.

login-flow.png1.4 MB64 %
spec.pdf812 KBPDF · 12 pages
auth.rs18 KBRS · 18 KB
q3-revenue.csv2.4 MBUpload failed
Code
let items = vec![
    AttachmentItem::file(1, "login-flow.png", 1_400_000, AttachmentState::Uploading { progress: Some(0.64) }),
    AttachmentItem::file(2, "spec.pdf", 812_000, AttachmentState::Ready { meta: "PDF · 12 pages".into() }),
];

rsx! {
    AttachmentRow {
        items: items,
        now: clock.now(),
        variant: "list",
        on_remove: move |id: u64| remove(id),
        on_retry: move |id: u64| retry(id),
    }
}

Context chip

Files, repo, selection and URL.

auth.rssrc/middleware
main3 changes
token.rslines 12–40
docs.rs
Code
let items = vec![
    AttachmentItem::file(1, "login-flow.png", 1_400_000, AttachmentState::Uploading { progress: Some(0.64) }),
    AttachmentItem::file(2, "spec.pdf", 812_000, AttachmentState::Ready { meta: "PDF · 12 pages".into() }),
];

rsx! {
    AttachmentRow {
        items: items,
        now: clock.now(),
        variant: "context-chip",
        on_remove: move |id: u64| remove(id),
        on_retry: move |id: u64| retry(id),
    }
}

Drop

Drop target over the row.

PNG
64%
PDF
RS
CSV
Drop to attach · 3 files
Code
let items = vec![
    AttachmentItem::file(1, "login-flow.png", 1_400_000, AttachmentState::Uploading { progress: Some(0.64) }),
    AttachmentItem::file(2, "spec.pdf", 812_000, AttachmentState::Ready { meta: "PDF · 12 pages".into() }),
];

rsx! {
    AttachmentRow {
        items: items,
        now: clock.now(),
        on_remove: move |id: u64| remove(id),
        on_retry: move |id: u64| retry(id),
    }
}

API reference

AttachmentRow

PropTypeDefaultDescription
itemsrequiredVec<AttachmentItem>—Items in the draft.
nowrequiredClockMs—Shared clock time.
variantString"tile-ring"`tile-ring` · `chip` · `chip-bar` · `thumb-strip` · `context-chip` · `paste-chip` · `list` · `terminal` (the two drop variants are [`DropZone`]).
max_visibleusize6Slots before "+k more".
reducedboolDefault::default()Reduced motion: static % label instead of the ring.
on_removeEventHandler<u64>—× pressed.
on_retryEventHandler<u64>—⟲ pressed.

DropZone

PropTypeDefaultDescription
staterequiredString—`armed` · `valid` · `invalid`.
labelrequiredString—`Drop to attach · 3 files`, `2 of 3 files can't be attached`.
variantString"inline"`inline` or `overlay`.

Read from the Rust signature and doc comments.

Keyboard interactions

KeyAction
TabTo each attachment and its remove button
EnterRetry a failed upload

Accessibility

  • A list labelled "Attachments, 4 items"; each item reads its name, type, size and state.
  • Progress is announced at 25 % steps at most; errors once, assertively.
  • Drag and drop always has an alternative (attach button, paste).
From the spec
  • The row is a list labelled "Attachments, 3 items"; each tile is a list item containing a button (preview) and a remove button.
  • Accessible names per state: "report.pdf, PDF, 2.4 megabytes, uploading 64 percent"; "…, reading"; "…, ready"; "…, upload failed, press Enter to retry"; "…, too large, maximum 20 megabytes".
  • Progress is announced politely at 25 % steps at most (not every tick) and on completion; errors are announced assertively once.
  • Remove: "Removed report.pdf. Press Control Z to undo." Undo: "Restored report.pdf."
  • Drop zone: drag-and-drop always has an alternative (+ → Upload file, paste). Drop results are announced ("2 files attached, 1 file can't be attached: setup.exe").
  • Reorder by keyboard: Alt+←/→ with announcement "Moved to position 2 of 4".
  • Focus order: tiles in visual order, then the text area. Removing a focused tile moves focus to the next tile, or to the text area if none remain.
  • Contrast: meta text 4.5:1; ring ≥ 3:1 against tile and background; error state uses icon + text.
  • Image thumbnails take alt text from the filename unless the app provides a description.

Motion & interaction

  • Add. Tiles grow in above the text from scale 0.85 to 1 with a fade (a thumbnail grow-in seen in Claude's GUI, reported at medium-low confidence in research notes 08); several files land one by one (40 ms stagger), "file tiles landing one by one above the prompt, each with its upload ring" [R095].
  • Upload ring. The ring draws clockwise; the % label counts up with tabular digits. At 100 % the % blurs out and the × blurs in at the same spot (blur-cross-fade in the same slot [R036]). The ring then fades as the tile moves to Reading.
  • Reading. A thin shimmer sweeps the label; images get a 1 px scan line travelling top to bottom. On ready, the thumbnail goes from 60 % to 100 % opacity and de-saturated to full colour.
  • Error. The ring's unfinished arc turns danger colour where it stopped (so you can see how far it got), the tile does a 2-cycle 4 px shake, ⟲ fades in. Retry restarts the ring from the stopped point if the transport supports resume.
  • Too large / unsupported. No ring ever draws. The tile lands, tints, and shows the reason; one shake.
  • Remove. Tile shrinks to 0.9 and fades; neighbours glide into the gap on a spring. Undo re-opens the gap and the tile grows back in place.
  • Reorder. Press-and-drag (or Alt+←/→) lifts the tile (scale 1.03, ≈3° tilt, shadow) and the gap opens where it will land, then it settles on a spring (lift pattern from [R040]).
  • Overflow. Beyond max_visible, the last slot becomes "+3 more"; expanding staggers the hidden Tiles in and morphs the row height (stagger capped at 300 ms total, the cap A chip group uses, research notes 12). Selected or erroring items always stay visible.
  • Drop zone. On window drag-enter, the composer outline appears; over the composer it heats up (tint + dashes march). Leaving the window clears it after a 50 ms delay (avoids flicker from child drag events).
  • Image preview. Click opens a lightbox that grows from the tile's rect (shared-element), closes back into it.
  • Pasted-text chip. Hover shows the first 3 lines in a popover after 300 ms; Expand unfolds the text back into the draft where the chip was.
  • Send. Ready tiles travel up with the message bubble and dock in it, in the same order.
Timing
TransitionDurationDelay / staggerEasing / springNotes
Tile grow-in (scale 0.85→1, fade)180 ms40 ms stagger, cap 6spring (stiffness 320, damping 28, proposed)
Upload ring progressfollows real progress, smoothedupdates ≤ 10 Hzlinear interpolation between updatesnever goes backward
Indeterminate arc1,000 ms per turn—linear90° arc
% → × blur swap160 msat 100 %ease-out, blur 4 px → 0same slot [R036]
Ring fade after 100 %160 ms120 msease-out
Reading shimmer1,800 ms per sweep—linearloop until ready
Image scan line1,200 ms top→bottom—ease-in-outloop
Ready (opacity + saturation)200 ms0ease-out
Error shake300 ms, 2 cycles, 4 px0linear
Remove (scale 0.9, fade)140 ms0ease-ingap closes 180 ms spring
Undo window6 spauses on hover/focus—Arc MCP uses about 6 s, research notes 12
Reorder lift / settle120 ms / 220 ms0ease-out / spring (stiffness 380, damping 30)1.03 scale, ≈3° tilt
Overflow expand160 ms row height30 ms stagger, cap 300 ms totalspring
Drop zone armed / hot120 ms / 100 msleave delay 50 msease-outdashes 60 ms per px, ≤ 30 fps
Hover preview popover140 ms300 msease-out
Lightbox open / close240 ms / 200 ms0spring / ease-inshared element
Minimum Uploading display300 ms——if the upload finishes faster, skip the ring entirely and go straight to Ready (no flash)
Reduced motion0–80 ms opacity cross-fadesno staggerlinearring is replaced by a static % text label (still updates); no shimmer, scan, shake, lift, tilt or marching dashes; every state label and announcement kept

Sizes (proposed): image/file tile 56 × 56 px (the BoardUI strip uses 56 px tiles [R036]), radius 10 px, gap 8 px; ring 2 px stroke inset 1 px; % label 9 px mono [R036]; chip height 28 px (24 px dense, 36 px touch), max chip width 220 px; × hit area 24 px (44 px on touch). Default max_visible = 6 tiles or 1 row of chips.

Responsive behaviour

  • max_visible slots, then "+k more"; chip and context-chip suit narrow composers.
Edge cases (spec)
  • Long filenames truncate in the middle so the extension stays visible ("quarterly-rep…final.pdf"). Full name in the accessible label and tooltip.
  • Many files. 50 files dropped at once: validate all, upload with a concurrency of 3 (proposed), Queued for the rest; the row shows 6 + "+44 more". Above max_files (default 10, proposed) the extra files are rejected with one summary line, not 40 error tiles.
  • Folders. Dropping a folder becomes one folder chip with a count; never 300 tiles.
  • Duplicates (same content hash): no second tile; the existing one pulses.
  • Huge images are downscaled client-side for the thumbnail only; the original is uploaded unless the app sets a resize policy.
  • HEIC / RAW / SVG. Thumbnails fall back to the type icon when the platform cannot decode; SVG thumbnails render sanitised (no scripts).
  • RTL. Row order follows reading direction (first attachment on the right); the ring still draws clockwise (a clock is not mirrored); Alt+←/→ reorder follows visual direction.
  • Tiny sizes / dense IDE. Below 40 px the ring becomes a 2 px bottom bar and % hides (shown in the tooltip); list is the default in IDE surfaces.
  • Touch. No hover: × is always visible on touch; long-press starts reorder; drag-from-other-apps is supported where the platform allows, otherwise the "+" picker is the path.
  • Slow networks. Ring smoothing hides jitter; if no progress event arrives for 10 s the label adds "Slow connection…" (proposed). Offline pauses uploads (Paused) and resumes automatically.
  • Very fast uploads (< 300 ms) skip the ring entirely. Very slow reading (> 20 s) shows elapsed time "Reading · 24 s".
  • Agent busy. Attachments added while busy belong to the draft (and therefore to the queued or steer message); they never change the running turn silently.
  • Model cannot read a type (e.g. images on a text-only model): tile lands as Unsupported("This model can't read images") with an action to switch model if the app provides one.
  • Privacy. Context chips that point to secrets-like files (.env, keys) show a warning line before send.

Notes for AI

  • Import AttachmentRow, DropZone from oxyn_dioxus and include COMPOSER_CSS plus the token stylesheet once.
  • A GPUI version exists: AttachmentRowEl in oxyn_gpui.
  • Props to set first: items, now, state, label.
  • It reads a clock (now) for live timers; pass one clock for the whole page rather than one per component.
  • Keep its states and timings as they ship; restyle it through the CSS variables rather than by hand.

Guides

Oxyn · 74 free components · 264 Pro components · 96 screens · 20 blocks · Dioxus and GPUI