# React Native Image Cropper (Pro)

> A React Native image cropper for iOS, Android and the web: pan, pinch, wheel and double-tap zoom with bounds that keep the photo covering the crop, aspect presets (free, 1:1, 4:5, 16:9), a circle mask for avatars, rotate 90°, flip, a rule-of-thirds grid while dragging, resizable corners for a free crop, and the crop in source pixels for expo-image-manipulator, or a cropped data URL from a canvas on the web. Part of Patine Pro, no native modules.

# 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](./file-upload#profile-photo) uses it for profile photos.

```tsx
import { ImageCropper, cropToDataUrl } from '@patine-ui/pro';
```

```tsx live
import { useState } from 'react';
import { Text, VStack } from 'patine-ui';
import { ImageCropper } from '@patine-ui/pro';

const PHOTO = 'https://images.unsplash.com/photo-1506744038136-46273834b3fb?w=1600&q=80';

export default function Example() {
  const [crop, setCrop] = useState(null);
  return (
    <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.

```tsx live
import { useRef, useState } from 'react';
import { Image } from 'react-native';
import { Button, Card, HStack, Text, VStack } from 'patine-ui';
import { ImageCropper, cropToDataUrl } from '@patine-ui/pro';

const PHOTO = 'https://images.unsplash.com/photo-1542291026-7eec264c27ff?w=1600&q=80';

export default function Example() {
  const crop = useRef(null);
  const [result, setResult] = useState<string | null>(null);
  return (
    <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.

```tsx live
import { ImageCropper } from '@patine-ui/pro';

export default function Example() {
  return (
    <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.

```tsx live
import { ImageCropper } from '@patine-ui/pro';

const ASPECTS = [
  { label: 'Free', value: null },
  { label: 'Square', value: 1 },
  { label: 'Story 9:16', value: 9 / 16 },
  { label: 'Banner 3:1', value: 3 },
];

export default function Example() {
  return (
    <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.

```tsx live
import { useRef, useState } from 'react';
import { Image } from 'react-native';
import { Button, HStack, VStack } from 'patine-ui';
import { ImageCropper, cropToDataUrl } from '@patine-ui/pro';

const PHOTO = 'https://images.unsplash.com/photo-1519681393784-d120267933ba?w=1600&q=80';

export default function Example() {
  const crop = useRef(null);
  const [result, setResult] = useState(null);
  return (
    <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.

```tsx
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](./file-upload): the avatar and gallery uploaders that crop and send photos.
- [Image viewer](./image-viewer): look at a photo full screen, with zoom.
