Docs
Media

Attachment Tray

An attachment strip for composers: a glass add tile opens the photo picker and each pick lands as a tile with a live progress ring.

$npx swiftpieces add AttachmentTray
See it in a Pro app On a real screen in one of the Pro apps: open it with Pro, take it apart, remix it, and copy the SwiftUI.
Free · MIT + Commons ClauseiOS 17.0+Liquid Glassattachmentsphotosphotos-pickeruploadthumbnailsimageiocomposermedia
Type
AttachmentTray
Files
AttachmentTray.swift
Depends on
Nothing (Apple frameworks only)
Version
1.2.0

A strip of photo and video attachments with an add tile, per-item loading, retry, remove and a limit. Thumbnails are content; everything you press or read over them is liquid glass. A tile that is loading, failed or uploading carries a status bubble at its centre, joined to the remove badge in its corner. The badge buds out of that bubble when the tile drops onto the strip, and the bubble melts into the badge once the photo has developed. The caller owns the attachments. Picks from the built-in add tile are appended for you; anything else (a camera capture, a paste, a drop, a draft restored from disk, your own picker) is added by appending an Attachment to the binding, and the tray runs the same loading pipeline for it.

Notes

  • Thumbnails are content; everything you press or read over them is liquid glass. The add tile is a glass tile with a solid red plus disc. A tile that is loading, failed or uploading carries a glass status bubble at its centre, joined by a liquid neck to the remove badge in its corner: the badge buds out of the bubble a beat after the tile drops onto the strip, and once the photo has developed the bubble melts up into the badge. On iOS 26 this is Liquid Glass; before that, a frosted material; under Reduce Transparency, solid fills.
  • You own the attachments through a @Binding [AttachmentTray.Attachment]. Picks from the add tile are appended for you; the tray writes load progress, the thumbnail and the payload back by id, and removes an attachment when its badge is tapped.
  • Anything else goes through the same pipeline by appending an attachment: Attachment(image:) for a camera capture or paste, Attachment(data:) for a drop or a saved draft, Attachment(fileURL:) for a file, Attachment(item:) for your own PhotosPicker, and Attachment { progress in ... } for your own download. For drops, add .dropDestination(for: Data.self) { items, _ in attachments += items.map { .init(data: $0) }; return true }.
  • Each tile goes loading, then loaded or failed. The ring in the status bubble spins until the source reports progress (an iCloud download, or your loader setting totalUnitCount and completedUnitCount on the Progress it is given), then fills smoothly with no overshoot. When a load finishes the attachment is loaded at once: the payload is set and VoiceOver reads Loaded. A ring that was showing progress fills and holds full for a beat (about 150 ms), then the photo develops under the bubble, settling from a slight zoom inside the tile without ever showing the tile's edge, while the bubble melts into the remove badge on a spring with no bounce. A video's duration badge, a glass capsule, rises in a beat later, and an upload dim you start right away appears with the photo. A failed load floods the bubble red, blurs the ring into a retry arrow and hangs "Retry" under it; tapping the tile, or calling attachments[i].retry(), drains the red and swaps the ring back as it loads again.
  • Thumbnails are cut with ImageIO on a background task at the largest tile size times the screen scale, with orientation applied. The full-size image is never decoded, so a 48 MP photo costs a few hundred kilobytes, not a hundred megabytes. A text size change never triggers a reload.
  • Picked images keep their original bytes in data (HEIC stays HEIC, nothing is transcoded). jpegData(maxPixelSize:compressionQuality:) gives an upload-ready JPEG, downsampled, with location and other metadata removed.
  • Videos (with matching: .videos or .any(of: [.images, .videos])) are copied to the temporary directory, never loaded into memory. fileURL points at the copy, the tile shows a poster frame and a duration badge, and duration is set. Delete the copy after upload if you need the space sooner than the system does.
  • Removing a tile cancels its load, including the photo library transfer. A load that finishes after its tile was removed, or after a newer attempt started, is dropped.
  • The picker only allows the remaining count. Photos already in the tray (matched by library identifier, also within one pick) are skipped: the strip glides to their tile, which bumps once as it lands. Anything past the limit is left out with a warning haptic and one announcement. At the limit the add tile shows "6/6" and disables.
  • Set uploadProgress on an attachment to show your upload: the status bubble buds back out of the remove badge with the upload ring while the tile dims below 1, and once it reaches 1, a beat after the dim lifts, the bubble lands in the opposite corner as a sage check, whether or not you animate the write. Clearing uploadProgress melts the check back into the badge.
  • Empty, the add tile is wide and shows the title with "Up to 6". With attachments its glass narrows to a square with the count: the plus disc travels into place, the title clears out first and the count arrives after it, and later counts roll, never past the number they show. Picks drop onto the strip, settling from just above full size with a little give that dips just inside it (at most 5 pt past each edge, so larger tiles stay inside the strip), and every load starts at once. A first pick into an empty tray drops one after another in pick order, a beat apart (up to five beats, so a big pick never drags). Later picks, and tiles you append yourself, land together, and if the tray already had tiles the strip glides to the newest one. Removed tiles shrink away quickly with their glass and the rest close the gap. Tiles already in the tray when it appears (a restored draft) start with their badges in place.
  • Loaded tiles call onSelect when tapped, for example to open a full-screen viewer. Every tile has a context menu with Remove (and Retry when failed).
  • VoiceOver: each tile is one element read as "Photo 2 of 4" with a value such as "Loading, 40%", "Couldn't load", "Uploading, 62%" or "Loaded", and Remove and Retry actions. The add tile reads its title and "3 remaining" or "Limit reached". Adds, skipped picks, removals and failures are announced once, and "All attachments loaded" when the last load finishes.
  • Haptics: a soft impact when picks land, a rigid impact on remove, a warning for skipped picks, an error when a load fails (one for a batch that fails together, such as when offline), a selection tick on retry. Presses play none.
  • Dynamic Type grows tiles up to 1.5 times Style.tileSize; text inside tiles stops growing at the same point so it never outgrows its tile. Right to left, the add tile leads from the right and badges sit top left; thumbnails are never mirrored.
  • Tiles with a tap action, the add tile and the remove badge sink slightly on press and spring back, centered so scrolling the strip is never disturbed; a pressed tile's glass sinks with it. A tile with nothing to do on tap (still loading, or loaded with no onSelect) stays still.
  • Reduce Motion: tiles, the photo and the glass bubbles fade in place instead of budding and moving, picks arrive together, presses dim instead of sinking, a tile picked again flashes brighter instead of bumping, the add tile's plus disc and count crossfade instead of travelling and rolling, and the spinner is the system indicator. The progress ring still closes before the photo shows, and every haptic and announcement stays.
  • Horizontal inset: apply .contentMargins(.horizontal, 20, for: .scrollContent) to the tray so tiles line up with your content and still scroll to the screen edge.
  • Style sets the placeholder (tile), label and secondary colors, the badges' glass tint (badge, clear by default) and ink, the plus disc and retry tint (signal) and its ink, the uploaded check's tint, the corner radius, tile size and spacing. .disabled(true) dims the add tile, and the remove badges melt into their status bubbles (or thin away where there is none).

Usage

AttachmentTrayExample()

Parameters

ParameterDescription
titleLabel of the add tile while the tray is empty, and its VoiceOver label. Once there are attachments the tile shrinks to a square showing the count.
attachmentsBound attachments, in display order. The tray appends picks, writes load progress, thumbnails and payloads back by id, and removes an attachment when its remove badge is tapped. Loads for attachments you remove are cancelled and their results ignored.
limitMost attachments the tray lets people pick (at least 1). The picker only allows the remaining count; at the limit the add tile shows "6/6" and disables. Extra picks and picks already in the tray are not added.
matchingWhat the picker offers, such as .images, .videos or .any(of: [.images, .videos]). Videos load as a file copied to the temporary directory with a poster frame thumbnail and a duration badge.
styleColors and tile metrics. Defaults to the SwiftPieces house palette, adapting to light and dark.
onSelectCalled when a loaded tile is tapped, for example to open it full screen. When nil, loaded tiles have no tap action.

Install

Pick one. Run it from the folder that contains your .xcodeproj and the files land inside your app.

Terminal

$npx swiftpieces add AttachmentTray

Or ask your coding agent · Claude Code, Cursor or Xcode, once the MCP server is connected

>Add the SwiftPieces "Attachment Tray" piece to my app

Or copy the source above into your app.

New to SwiftUI?If you know React, CSS or Tailwind, SwiftUI is easier to pick up than it looks.Try real app patterns first

Building a whole app? See SwiftPieces Pro →

All media →

Build it yourself: SwiftUI animations guide

On this page

SwiftPiecesPro

Build the whole app with one library.

Production-ready screens, whole flows, complete app templates, a Build Kit your agent follows and Pro remixing.

Explore Pro