simple-react-app-kit/packages/cropper/docs/en-US/advanced/geometry-and-export.mdx

---
title: Geometry and export
description: Work with source coordinates, pure functions, and Canvas output.
order: 20
toc:
  - id: controlled-state
    title: Controlled state
  - id: geometry
    title: Geometry functions
  - id: export
    title: Exporting an image
  - id: api
    title: API
  - id: cross-origin
    title: Cross-origin images
---

## Controlled state {#controlled-state}

```tsx
const [value, setValue] = React.useState({ x: 0, y: 0, zoom: 1 })

<Cropper
  src={src}
  value={value}
  onValueChange={setValue}
  onCropComplete={(area) => saveDraft(area)}
/>
```

`onCropAreaChange` runs whenever a valid crop changes. `onCropComplete` runs after drag or wheel interaction and after discrete keyboard operations, making it a better persistence boundary.

## Geometry functions {#geometry}

`getCoverScale`, `getCropperBounds`, `constrainCropperValue`, `getCropArea`, and `zoomCropperValueAtPoint` are DOM-independent pure functions that can be reused in custom interfaces and tests.

## Exporting an image {#export}

The shortest path exports the current result through the component ref:

```tsx
import { Cropper, type CropperHandle } from "@workspace/cropper"

const cropperRef = React.useRef<CropperHandle>(null)

const result = await cropperRef.current?.getCropImage({
  outputType: "base64",
  type: "image/jpeg",
  quality: 0.9,
  width: 1200,
})

<Cropper ref={cropperRef} src={src} />
```

`getCropImage()` returns `undefined` until the image is ready. `outputType` defaults to `"blob"`; `"base64"` returns a data URL suitable for previews or form values. Quality must be between `0` and `1`.

Use the pure function when no component instance is available:

```tsx
const blob = await cropImage(src, area, {
  type: "image/webp",
  quality: 0.9,
  width: 1200,
})
```

Supplying only `width` or `height` preserves the crop aspect ratio. `shape: "circle"` clips through an ellipse; provide `background` when an opaque JPEG background is required. `getCropImage(source, area, options)` is the corresponding pure function for Blob/base64 output.

## API {#api}

| Prop                           | Type                                | Description                                      |
| ------------------------------ | ----------------------------------- | ------------------------------------------------ |
| `src`                          | `string \| Blob`                    | An image URL, Blob, or File.                     |
| `aspectRatio`                  | `number \| \`${number}:${number}\`` | Crop viewport ratio; defaults to `1`.            |
| `width` / `height`             | matching `CSSProperties` value      | Optional inline container dimensions.            |
| `value` / `defaultValue`       | `CropperValue`                      | Controlled or uncontrolled translation and zoom. |
| `minZoom` / `maxZoom`          | `number`                            | Zoom range; defaults to `1` through `4`.         |
| `shape`                        | `"rectangle" \| "circle"`           | Viewport shape.                                  |
| `showGrid`                     | `boolean`                           | Whether to render the rule-of-thirds grid.       |
| `onCropAreaChange`             | `(area) => void`                    | Runs when the valid source-image crop changes.   |
| `onCropComplete`               | `(area, value) => void`             | Runs after an interaction or reset completes.    |
| `onImageLoad` / `onImageError` | callbacks                           | Observe image loading state.                     |

`CropperHandle` exposes `element`, `getCropArea()`, `getCropImage(options)`, and `reset()`. Use `rootRef` when a raw DOM ref is needed; the component `ref` is reserved for the imperative handle.

## Cross-origin images {#cross-origin}

A remote image server must return CORS headers that permit Canvas use. Pass `crossOrigin="anonymous"` to `Cropper` and the matching `crossOrigin` option to `cropImage`; otherwise the browser may taint the Canvas and prevent Blob encoding.