ImageCropper Pro
ImageCropper crops a photo the way the Photos app does. Drag to move it, pinch (or scroll, or a trackpad pinch on the web) to zoom, double-tap to zoom in and back. The photo always covers the crop: pull it past an edge and it follows only partly, then springs back. Pick an aspect, mask a circle for an avatar, rotate in quarter turns, flip, and on a free crop drag the corners. A rule-of-thirds grid shows while you move it.
It reports the crop in the source image's pixels, { x, y, width, height, rotation, flipX, flipY }, so you can cut the full-resolution file: with a canvas on the web (cropToDataUrl), with expo-image-manipulator on iOS and Android, or on your server. React Native core only. AvatarUploader uses it for profile photos.
import { ImageCropper, cropToDataUrl } from '@patine-ui/pro';
<VStack gap="sm" style={{ width: '100%', maxWidth: 560 }}> <ImageCropper source={PHOTO} aspect={4 / 5} onCropChange={setCrop} /> <Text size="xs" color="textSecondary" style={{ fontFamily: 'monospace' }}> {crop ? JSON.stringify(crop) : 'Move the photo'} </Text> </VStack>
Example: a product photo
A store's product editor: the photo is cropped square for the catalog grid, and Use photo cuts it out and shows the card exactly as shoppers will see it.
<VStack gap="md" style={{ width: '100%', maxWidth: 560 }}> <ImageCropper source={PHOTO} aspect={1} onCropChange={(c) => (crop.current = c)} height={300} /> <HStack gap="md" align="center" wrap> <Button onPress={async () => setResult(await cropToDataUrl(PHOTO, crop.current, { maxSize: 600 }))}>Use photo</Button> {result ? ( <Card style={{ width: 160, padding: 0, overflow: 'hidden' }}> <Image source={{ uri: result }} style={{ width: 160, height: 160 }} accessibilityLabel="The cropped product photo" /> <VStack padding="sm"> <Text weight="medium">Runner 2, red</Text> <Text size="sm" color="textSecondary">€129.00</Text> </VStack> </Card> ) : ( <Text size="sm" color="textSecondary">Drag and zoom to frame the shoe.</Text> )} </HStack> </VStack>
Avatars: a circle
shape="circle" masks a round crop (the output is the square around it) and fixes the aspect at 1:1. aspects={[]} hides the aspect choices.
<ImageCropper source="https://images.unsplash.com/photo-1544005313-94ddf0286df2?w=1200&q=80" shape="circle" aspects={[]} height={320} style={{ width: '100%', maxWidth: 420 }} />
Free crop with handles
aspect={null} lets people size the crop by its corners; it stays on the photo. The toolbar's Free does the same. Choose your own presets with aspects, such as a store's product ratios.
<ImageCropper source="https://images.unsplash.com/photo-1600585154340-be6161a56a0c?w=1600&q=80" aspect={null} aspects={ASPECTS} grid="always" style={{ width: '100%', maxWidth: 640 }} />
Get the cropped image
On the web, cropToDataUrl(uri, crop, { maxSize, type, quality }) cuts the crop out with a canvas, mirrored and turned as shown, and resolves with a data URL. A photo from another site needs CORS headers (Unsplash, S3 and most CDNs send them). Turn it into a Blob with fetch(dataUrl).then((r) => r.blob()) to upload it.
<VStack gap="md" style={{ width: '100%', maxWidth: 560 }}> <ImageCropper source={PHOTO} aspect={16 / 9} onCropChange={(c) => (crop.current = c)} height={300} /> <HStack gap="md" align="center"> <Button onPress={async () => setResult(await cropToDataUrl(PHOTO, crop.current, { maxSize: 800 }))}>Crop</Button> {result && <Image source={{ uri: result }} style={{ width: 160, height: 90, borderRadius: 8 }} />} </HStack> </VStack>
On iOS and Android, give the crop to expo-image-manipulator. The order matters: crop, then flip, then rotate.
import { manipulateAsync, FlipType, SaveFormat } from 'expo-image-manipulator';
const result = await manipulateAsync(
uri,
[
{ crop: { originX: crop.x, originY: crop.y, width: crop.width, height: crop.height } },
...(crop.flipX ? [{ flip: FlipType.Horizontal }] : []),
...(crop.flipY ? [{ flip: FlipType.Vertical }] : []),
...(crop.rotation ? [{ rotate: crop.rotation }] : []),
],
{ compress: 0.9, format: SaveFormat.JPEG }
);
Edit a saved crop
Keep the CropRect you got and pass it back as initialCrop: the photo opens zoomed, turned and placed exactly as it was. imageSize skips measuring the photo when you already know its pixels.
Designs
- Brand and iOS: bold white corner brackets, as the Photos app draws them.
- Material: shorter, thicker corners.
- Web: a plain frame with no brackets.
Accessibility
- The viewport is an adjustable control named "Crop photo": screen readers zoom it with the increment and decrement actions, and read the zoom.
- On the web it takes focus: arrow keys move the photo (Shift for bigger steps), + and − zoom, R rotates and 0 resets. Wheel and trackpad pinch zoom around the pointer.
- Every toolbar control has a name; the aspect choices are a radio group. The corner handles are 44pt targets.
- The spring back, rotate and flip animate through Patine's motion, which reduce motion turns into jumps.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
source | string | required | The photo's URI. |
imageSize | { width, height } | measured | Its pixel size, when you know it. |
aspect | number | null | 1 | Width over height; null for a free crop with handles. Controlled with onAspectChange. |
onAspectChange | (aspect) => void | — | The toolbar changed the aspect. |
aspects | { label, value }[] | Free, 1:1, 4:5, 16:9 | The toolbar's choices; [] hides them. |
shape | 'rect' | 'circle' | 'rect' | A round mask for avatars. |
maxZoom | number | 6 | How far past covering it zooms. |
grid | 'auto' | 'always' | 'never' | 'auto' | Thirds lines while dragging, always or never. |
toolbar | boolean | true | Rotate, flip, zoom slider, reset and aspects. |
initialCrop | CropRect | — | Open on a saved crop. |
onCropChange | (crop: CropRect) => void | — | The crop in source pixels, each time it settles. |
height | number | 360 | The viewport's height. |
labels | Partial<CropperLabels> | English | For translation. |
style, theme, design |
CropRect is { x, y, width, height, rotation: 0 | 90 | 180 | 270, flipX, flipY }. Also exported: cropToDataUrl, toSourceRect, fromSourceRect, fitBox, coverScale, aspectLabel.
Related
- File upload: the avatar and gallery uploaders that crop and send photos.
- Image viewer: look at a photo full screen, with zoom.