# ImageCropper

Headless, unstyled square image cropper. The user pans by dragging or with the arrow keys, zooms with the wheel, a pinch, the keyboard, a slider or step buttons, turns the image a quarter at a time, and resets it. The crop is a `Crop` (`{ x, y, zoom, rotation }`), with zoom clamped between the zoom where the whole image fits in the frame and `maxZoom`. At zoom `1` and above the image covers the frame. Below `1` the frame shows empty space along the short side of the image, and the long side stays cropped until the minimum zoom, where the whole image fits. `cropImage(src, crop, { type, size })` draws the chosen square into a `Blob`. Every control stays disabled until the image has loaded.

## Use for

- cropping a picked image to a square before upload
- pan, zoom and rotate controls for an image
- drawing a cropped image to a blob

## Practices

- Don't: Build an avatar or logo crop dialog from it. Use `AvatarUpload`, which already wraps the cropper.
- Do: Give `Viewport` an `aria-label` that names the keys. It has `role="application"` and the image has an empty `alt`.
- Do: Give icon-only `ZoomIn`, `ZoomOut`, `Rotate` and `Reset` buttons an `aria-label`.
- Do: Size the frame, any mask and the controls yourself. The primitive emits no styles apart from placing the image.
- Do: Read the output type from the blob `cropImage` returns. A browser that cannot encode `type` returns `image/png`.

## API reference

### ImageCropper.Root

Owns the crop and the image size and provides them to the parts. Renders no element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `src` | `string` |  | The image to crop, such as an object URL for a picked file. |
| `value` | `Crop` |  | The crop, when controlled. |
| `defaultValue` | `Crop` | `` `INITIAL_CROP` `` | The crop on mount, when uncontrolled. |
| `onValueChange` | `(crop: Crop) => void` |  | Called with the next crop on every pan, zoom, turn and reset. |
| `maxZoom` | `number` | `4` | Largest zoom, as a multiple of the scale that covers the frame. |
| `disabled` | `boolean` | `false` | Ignores every gesture and disables the controls. |

### ImageCropper.Viewport

The frame, a `div` with `role="application"`. Pans on drag and arrow keys (Shift for more), zooms on wheel, pinch and `+`/`-`, resets on `0`. Leaves the tab order until the image loads. Carries `data-dragging` and `data-disabled`.

### ImageCropper.Area

Optional `div` marking the square that is cropped when it is smaller than the frame. Drags are measured against it, and the `Viewport` around it shows the rest of the image.

### ImageCropper.Image

The `img`, placed by the crop and hidden until loaded. Reports its size on load and carries `data-loaded`.

### ImageCropper.Zoom

An `input type="range"` from the zoom where the whole image fits to `maxZoom`. Carries `data-disabled`.

### ImageCropper.ZoomIn

A `button` that zooms in one `ZOOM_STEP`. Disabled at `maxZoom`. Carries `data-disabled`.

### ImageCropper.ZoomOut

A `button` that zooms out one `ZOOM_STEP`. Disabled once the whole image fits in the frame. Carries `data-disabled`.

### ImageCropper.Rotate

A `button` that turns the image a quarter clockwise. Carries `data-disabled`.

### ImageCropper.Reset

A `button` that returns to `INITIAL_CROP`. Carries `data-disabled`.

## Examples

### Crop and save

```tsx
const [crop, setCrop] = useState<Crop>(INITIAL_CROP);

<ImageCropper.Root src={src} value={crop} onValueChange={setCrop}>
  <ImageCropper.Viewport aria-label='Crop. Drag or use the arrow keys to move, plus and minus to zoom.'>
    <ImageCropper.Area>
      <ImageCropper.Image />
    </ImageCropper.Area>
  </ImageCropper.Viewport>
  <ImageCropper.ZoomOut aria-label='Zoom out'>−</ImageCropper.ZoomOut>
  <ImageCropper.Zoom aria-label='Zoom' />
  <ImageCropper.ZoomIn aria-label='Zoom in'>+</ImageCropper.ZoomIn>
  <ImageCropper.Rotate>Rotate</ImageCropper.Rotate>
  <ImageCropper.Reset>Reset</ImageCropper.Reset>
  <button onClick={async () => onSave(await cropImage(src, crop, { type: 'image/png' }))}>Save</button>
</ImageCropper.Root>
```

## Related

- `AvatarUpload`
- [FileUpload](/docs/primitives/file-upload.md)
