Docs
Media

Photo Cropper

A crop step for profile photos and posts with pinch, pan and aspect presets, rendering the crop off the main thread at full size.

$npx swiftpieces add PhotoCropper
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 Glasscropphotoavatarpinch-zoomrotateaspect-ratioimageeditor
Type
PhotoCropper
Files
PhotoCropper.swift
Depends on
Nothing (Apple frameworks only)
Version
1.2.0

A crop step for a picked photo: the photo under a frame of the chosen aspect, with pinch, pan, rotate and aspect chips. The photo is content; the controls around it are liquid glass. The aspect chips sit on one glass track, with a red puck under the selected one that stretches between picks. Rotate and Reset rest joined as one pair of tools, apart from Cancel and the red Choose capsule, and the zoom level floats over the photo on glass while you pinch. The photo always covers the frame. It can't be zoomed out or dragged so far that an empty edge stays in the frame: past a limit it resists and springs back on release. The framing is stored relative to the photo (zoom relative to the smallest scale that fills the frame, and the photo point at the frame's centre), so rotating, switching aspect and size changes keep the same subject in frame. Choose renders the crop from the original, off the main actor, and hands you a Crop. A drag that starts on the photo pans it; it never scrolls an enclosing scroll view or pulls a sheet down. swift @State private var photo: UIImage // keep it in state, never create it in `body` PhotoCropper(image: photo, aspect: .circle, onCancel: { dismiss() }) { crop in avatar = crop.image dismiss() }

Notes

  • The photo is content; the controls around it are liquid glass. The aspect chips sit on one glass track with a red puck under the selected chip. Rotate and Reset rest joined, one pair of tools for the crop, apart from Cancel and the red Choose capsule. The zoom level and any notice float over the photo on dark glass, since the well is dark in both appearances. On iOS 26 this is Liquid Glass; before that, a frosted material; under Reduce Transparency, solid fills.
  • Put it after a PhotosPicker (or the camera) in a .fullScreenCover, a pushed screen or a sheet. Keep the photo in state, for example @State private var photo: UIImage?, never created in body: a new image starts the cropper over.
  • The photo always covers the frame. Zoom is relative to the smallest scale that fills the frame (1 to 5, less for very small photos so a crop never drops below 32 pixels), and the framing is stored as that zoom plus the photo point at the frame's centre. Rotating, switching aspect, rotating the device and resizing all keep the same subject in frame.
  • Pinch zooms about the fingers while they pan, both at once, and the photo stays exactly under them. Past the edges of the photo, or past 1x and the maximum zoom, it follows with a scroll view's resistance. Let go and it lands: a flick carries on at the photo's own speed into a short coast, a pull past an edge springs back from where the band left it, and a pinch past a limit comes back from rest. None of it bounces or runs past its stop: a coast stops where it's going, and a hard flick into an edge arrives fast and stops at the edge. Touch the photo before it has landed, or while a double tap, a key step or Reset is still zooming or moving it, and it stops where it is, under the finger, the way a scroll view does; a change of aspect or a turn always runs to its end. At a zoom limit the frame's edge and corner marks flash red for an instant with a rigid tick. Double-tap toggles between filling the frame and 2.5x about the tapped point.
  • A rule-of-thirds grid fades in the moment a finger touches the photo and out half a second after the last one lifts. The zoom level settles in above the frame on a glass capsule while pinching and lifts away with the grid.
  • The aspect chips default to circle, square, 4:5, 16:9 and the photo's own shape; pass your own list ([.square, .portrait, .ratio(3, 2)]), retitle one with .titled("Post"), or pass a single aspect (or none) for a fixed frame. The red puck travels to the chip you pick as two tinted shapes, one landing with a little give and the other a beat behind, so it stretches along the track like a drop of liquid and gathers as it lands; the chip's picture turns solid ink on it. Meanwhile the frame and the photo morph to the new shape together without overshoot, so the photo never leaves part of the frame uncovered. .circle shows a round frame but the crop is square: clip it when you draw it.
  • Rotate turns the photo a quarter to the left each tap; quick taps keep turning the same way. The turn never swings past its stop, and mid-turn the photo grows just enough that the frame's corners never leave it. .original turns with the photo.
  • Chips, Rotate, Reset, Cancel and Choose sink a little under the finger and spring back. Reset's label dims while there is nothing to reset.
  • Choose renders from the original, off the main actor, in the photo's own color space (Display P3 stays P3), upright, at up to maxOutputDimension (4096) on the longer side and never scaled up. onCrop gets a Crop with the image, the rect in pixels of the upright original and quarterTurns (to the left, applied after the rect), so a server can repeat the crop on the original, plus the framing. Choose spins until your onCrop returns, so you can await an upload there, then a check blurs in, and a beat later the label blurs back. The capsule holds its width throughout. If the cropper goes away mid-render the render is dropped; an onCrop that has started is never cut off.
  • framing: binds the aspect, zoom, centre and rotation instead of aspect:. Store crop.framing (it is Codable) and pass it back to reopen a crop where it was left, or drive the cropper from your own controls. Reset returns to the photo filling the starting aspect and is enabled only once something changed.
  • EXIF orientation is respected on screen and in the output. A photo that is much larger than the screen is shown from a copy cut once, off the main actor, so a 48 MP photo never decodes on the main thread; a quiet placeholder holds the frame meanwhile. A photo that can't be drawn shows "Couldn't open this photo" in the frame, and Choose and the puck drain to neutral glass. A failed render shows a short notice, rising in on glass at the bottom of the well, with an error haptic.
  • A drag on the photo pans it: it never scrolls an enclosing scroll view or pulls a sheet down, because those pans wait for the cropper's own. Pinch and pan come from UIKit's recognizers, which report the fingers' moving centre.
  • Haptics: a selection tick when the aspect changes, a light impact on rotate, a rigid tick at a zoom limit or an edge (once for a held key, not on every repeat), a soft tick on Reset, success when the crop is delivered, an error if rendering fails.
  • VoiceOver: the photo is one adjustable element, "Crop area", with a value such as "2.5×, 4:5, Rotated left 90°". Swipe up and down to zoom, and use the Move up, down, left and right actions (a fifth of the frame each), Rotate left and Reset. Aspect chips are buttons with the selected trait ("4 to 5"), and rotations, resets and the finished crop are announced.
  • Hardware keyboard: the arrow keys move and + and - zoom when the photo is focused, Return chooses, Escape cancels and Command-R rotates.
  • Reduce Motion: the photo lands, zooms and changes aspect on a short spring with no overshoot, a quarter turn crossfades to the turned photo and frame instead of swinging round, and the puck fades over to the chip you pick instead of travelling. The grid, the zoom level, the photo appearing and the red limit flash still fade, so you can follow what changed, and pressed buttons dim instead of sinking.
  • Dynamic Type: chips and buttons scale (chips stop at the second accessibility size so the photo keeps its room). When the buttons no longer fit on one line, Choose moves to its own full-width row, and at the largest sizes Cancel does too; separate actions never come closer than the merge distance, so their glass never necks. Right to left mirrors the toolbar; the photo is never mirrored. All text is one weight, semibold.
  • Style sets the toolbar ground, the photo's well (dark in both appearances so the photo, scrim and frame read the same), the scrim, the frame's edge, the red accent (Choose, the puck and the limit flash) and the ink on it, labels, the well's corner radius (0 runs the photo edge to edge) and the frame inset. control and selectedControl are no longer used: the controls are neutral glass and the puck takes accent. Messages replaces any of the copy, such as choose: "Use photo".

Usage

PhotoCropperExample()

Parameters

ParameterDescription
imageThe photo to crop, at full size, such as one loaded from a PhotosPicker item. Its orientation is respected. An on-screen copy is cut from it once, off the main actor; the crop is always rendered from this original. Keep it in state rather than creating it in body, or every update starts over.
aspectThe frame to start with. Defaults to .square.
framingBound framing, instead of aspect: the aspect, zoom, centre and rotation, updated as people adjust them. Set it to reopen a crop where it was left (crop.framing from an earlier result) or to drive the cropper from your own controls. While a finger is down it can briefly sit past the limits (the rubber band); it settles inside them on release.
aspectsThe aspect chips under the photo, in order. Defaults to circle, square, 4:5, 16:9 and the photo's own shape. One aspect, or none, hides the chips for a fixed frame. An aspect that isn't listed is added at the front.
maxOutputDimensionThe longest side of the rendered crop, in pixels. Defaults to 4096. Larger crops are scaled down to it; smaller ones keep the original's pixels and are never scaled up.
messagesThe cropper's copy. Defaults are localizable through your String Catalog; replace any line, for example choose with "Use photo".
styleColors, the photo's well and the frame inset. Defaults to the SwiftPieces house palette, adapting to light and dark, with red for Choose, the selected aspect and the limit flash.
onCancelShows a Cancel button (and Escape on a hardware keyboard) that calls this. nil hides it.
onCropCalled on the main actor with the rendered Crop when Choose is tapped (or Return is pressed). Choose keeps spinning until this returns, so you can await an upload here.

Install

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

Terminal

$npx swiftpieces add PhotoCropper

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

>Add the SwiftPieces "Photo Cropper" 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