Skip to main content

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';
Loading…
<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.

Loading…
<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.

Loading…
<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.

Loading…
<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.

Loading…
<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​

PropTypeDefaultDescription
sourcestringrequiredThe photo's URI.
imageSize{ width, height }measuredIts pixel size, when you know it.
aspectnumber | null1Width 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:9The toolbar's choices; [] hides them.
shape'rect' | 'circle''rect'A round mask for avatars.
maxZoomnumber6How far past covering it zooms.
grid'auto' | 'always' | 'never''auto'Thirds lines while dragging, always or never.
toolbarbooleantrueRotate, flip, zoom slider, reset and aspects.
initialCropCropRect—Open on a saved crop.
onCropChange(crop: CropRect) => void—The crop in source pixels, each time it settles.
heightnumber360The viewport's height.
labelsPartial<CropperLabels>EnglishFor 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.

  • File upload: the avatar and gallery uploaders that crop and send photos.
  • Image viewer: look at a photo full screen, with zoom.