# Image Cropper

URL: https://ark-ui.com/docs/components/image-cropper
Source: https://raw.githubusercontent.com/chakra-ui/ark/refs/heads/main/website/src/content/pages/components/image-cropper.mdx

Crop and transform images with zoom, rotation, and aspect ratio controls.

---

<ComponentPreview id="ImageCropper" />

## Anatomy

<Anatomy id="image-cropper" />

```tsx
<ImageCropper.Root>
  <ImageCropper.Viewport>
    <ImageCropper.Image />
    <ImageCropper.Selection>
      <ImageCropper.Handle />
      <ImageCropper.Grid />
    </ImageCropper.Selection>
  </ImageCropper.Viewport>
</ImageCropper.Root>
```

## Examples

### Basic

Set up a basic image cropper. Drag the handles to resize the selection, or drag inside to pan the image.

**Example: basic**

```ripple
import { ImageCropper } from 'ark-ripple/image-cropper';
import styles from 'styles/image-cropper.module.css';

export component Basic() {
  <div class={styles.Layout}>
    <ImageCropper.Root class={styles.Root}>
      <ImageCropper.Viewport class={styles.Viewport}>
        <ImageCropper.Image
          class={styles.Image}
          src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800"
          alt="Sample"
        />
        <ImageCropper.Selection class={styles.Selection}>
          for (const position of ImageCropper.handles; key position) {
            <ImageCropper.Handle class={styles.Handle} {position}>
              <div />
            </ImageCropper.Handle>
          }
          <ImageCropper.Grid class={styles.Grid} axis="horizontal" />
          <ImageCropper.Grid class={styles.Grid} axis="vertical" />
        </ImageCropper.Selection>
      </ImageCropper.Viewport>
    </ImageCropper.Root>
  </div>
}

```

### Aspect Ratio

Lock the crop area to a specific aspect ratio. Use the `aspectRatio` prop—pass a number like `16/9` for widescreen or
`1` for square.

**Example: aspect-ratio**

```ripple
import { ImageCropper } from 'ark-ripple/image-cropper';
import { RectangleHorizontal, Square, RectangleVertical } from 'lucide-ripple';
import { track } from 'ripple';
import button from 'styles/button.module.css';
import styles from 'styles/image-cropper.module.css';

const aspects = [
  { label: '16:9', value: 16 / 9 },
  { label: '1:1', value: 1 },
  { label: '9:16', value: 9 / 16 },
];

const icons = [RectangleHorizontal, Square, RectangleVertical];

export component AspectRatio() {
  let aspectRatio = track(16 / 9);

  <div class={styles.Layout}>
    <div class={button.Group}>
      for (const aspect of aspects; key aspect.label) {
        <button
          type="button"
          class={button.Root}
          data-variant={@aspectRatio === aspect.value ? 'solid' : undefined}
          onClick={() => {
            @aspectRatio = aspect.value;
          }}
        >
          {aspect.label}
        </button>
      }
    </div>

    <ImageCropper.Root class={styles.Root} {@aspectRatio}>
      <ImageCropper.Viewport class={styles.Viewport}>
        <ImageCropper.Image
          class={styles.Image}
          src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800"
          alt="Sample"
        />
        <ImageCropper.Selection class={styles.Selection}>
          for (const position of ImageCropper.handles; key position) {
            <ImageCropper.Handle class={styles.Handle} {position}>
              <div />
            </ImageCropper.Handle>
          }
          <ImageCropper.Grid class={styles.Grid} axis="horizontal" />
          <ImageCropper.Grid class={styles.Grid} axis="vertical" />
        </ImageCropper.Selection>
      </ImageCropper.Viewport>
    </ImageCropper.Root>
  </div>
}

```

### Circle Crop

Use `cropShape="circle"` for profile pictures or avatars. The selection becomes a circle instead of a rectangle.

**Example: circle**

```ripple
import { ImageCropper } from 'ark-ripple/image-cropper';
import styles from 'styles/image-cropper.module.css';

export component Circle() {
  <div class={styles.Layout}>
    <ImageCropper.Root class={styles.Root} cropShape="circle">
      <ImageCropper.Viewport class={styles.Viewport}>
        <ImageCropper.Image
          class={styles.Image}
          src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800"
          alt="Sample"
        />
        <ImageCropper.Selection class={styles.Selection}>
          for (const position of ImageCropper.handles; key position) {
            <ImageCropper.Handle class={styles.Handle} {position}>
              <div />
            </ImageCropper.Handle>
          }
          <ImageCropper.Grid class={styles.Grid} axis="horizontal" />
          <ImageCropper.Grid class={styles.Grid} axis="vertical" />
        </ImageCropper.Selection>
      </ImageCropper.Viewport>
    </ImageCropper.Root>
  </div>
}

```

### Initial Crop

Start with a pre-defined crop area using the `initialCrop` prop. Pass an object with `x`, `y`, `width`, and `height` in
pixels.

**Example: initial-crop**

```ripple
import { ImageCropper } from 'ark-ripple/image-cropper';
import styles from 'styles/image-cropper.module.css';

export component InitialCrop() {
  <div class={styles.Layout}>
    <p class={styles.Description}>{'Starts with a pre-defined crop area'}</p>

    <ImageCropper.Root class={styles.Root} initialCrop={{ x: 50, y: 30, width: 200, height: 120 }}>
      <ImageCropper.Viewport class={styles.Viewport}>
        <ImageCropper.Image
          class={styles.Image}
          src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800"
          alt="Sample"
        />
        <ImageCropper.Selection class={styles.Selection}>
          for (const position of ImageCropper.handles; key position) {
            <ImageCropper.Handle class={styles.Handle} {position}>
              <div />
            </ImageCropper.Handle>
          }
          <ImageCropper.Grid class={styles.Grid} axis="horizontal" />
          <ImageCropper.Grid class={styles.Grid} axis="vertical" />
        </ImageCropper.Selection>
      </ImageCropper.Viewport>
    </ImageCropper.Root>
  </div>
}

```

### Controlled Zoom

Control zoom programmatically with the `zoom` and `onZoomChange` props. Useful when you want external buttons to zoom in
and out.

**Example: controlled-zoom**

```ripple
import { ImageCropper } from 'ark-ripple/image-cropper';
import { ZoomIn, ZoomOut } from 'lucide-ripple';
import { track } from 'ripple';
import button from 'styles/button.module.css';
import styles from 'styles/image-cropper.module.css';

export component ControlledZoom() {
  let zoom = track(1);

  <div class={styles.Layout}>
    <div class={button.Group}>
      <button
        type="button"
        class={button.Root}
        onClick={() => {
          @zoom = @zoom - 0.1;
        }}
      >
        <ZoomOut />
      </button>
      <span style={{ fontSize: '0.875rem', minWidth: '3rem', textAlign: 'center' }}>
        {@zoom.toFixed(1)}
        {'x'}
      </span>
      <button
        type="button"
        class={button.Root}
        onClick={() => {
          @zoom = @zoom + 0.1;
        }}
      >
        <ZoomIn />
      </button>
    </div>

    <ImageCropper.Root
      class={styles.Root}
      {zoom}
      onZoomChange={(e) => {
        @zoom = e.zoom;
      }}
    >
      <ImageCropper.Viewport class={styles.Viewport}>
        <ImageCropper.Image
          class={styles.Image}
          src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800"
          alt="Sample"
        />
        <ImageCropper.Selection class={styles.Selection}>
          for (const position of ImageCropper.handles; key position) {
            <ImageCropper.Handle class={styles.Handle} {position}>
              <div />
            </ImageCropper.Handle>
          }
          <ImageCropper.Grid class={styles.Grid} axis="horizontal" />
          <ImageCropper.Grid class={styles.Grid} axis="vertical" />
        </ImageCropper.Selection>
      </ImageCropper.Viewport>
    </ImageCropper.Root>
  </div>
}

```

### Zoom Limits

Set `minZoom` and `maxZoom` to constrain how far users can zoom. Prevents over-zooming or zooming out past the image
bounds.

**Example: zoom-limits**

```ripple
import { ImageCropper } from 'ark-ripple/image-cropper';
import { ZoomIn, ZoomOut } from 'lucide-ripple';
import { track } from 'ripple';
import button from 'styles/button.module.css';
import styles from 'styles/image-cropper.module.css';

export component ZoomLimits() {
  let zoom = track(1);
  const minZoom = 0.5;
  const maxZoom = 2;

  <div class={styles.Layout}>
    <div class={button.Group}>
      <button
        type="button"
        class={button.Root}
        onClick={() => {
          @zoom = Math.max(minZoom, @zoom - 0.1);
        }}
      >
        <ZoomOut />
      </button>
      <span
        style={{ fontSize: '0.875rem', padding: '0 0.5rem', minWidth: '3rem', textAlign: 'center' }}
      >
        {@zoom.toFixed(1)}
        {'x'}
      </span>
      <button
        type="button"
        class={button.Root}
        onClick={() => {
          @zoom = Math.min(maxZoom, @zoom + 0.1);
        }}
      >
        <ZoomIn />
      </button>
    </div>

    <p class={styles.Description}>
      {'Zoom constrained between '}
      {minZoom}
      {'x and '}
      {maxZoom}
      {'x'}
    </p>

    <ImageCropper.Root
      class={styles.Root}
      {zoom}
      onZoomChange={(e) => {
        @zoom = e.zoom;
      }}
      {minZoom}
      {maxZoom}
    >
      <ImageCropper.Viewport class={styles.Viewport}>
        <ImageCropper.Image
          class={styles.Image}
          src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800"
          alt="Sample"
        />
        <ImageCropper.Selection class={styles.Selection}>
          for (const position of ImageCropper.handles; key position) {
            <ImageCropper.Handle class={styles.Handle} {position}>
              <div />
            </ImageCropper.Handle>
          }
          <ImageCropper.Grid class={styles.Grid} axis="horizontal" />
          <ImageCropper.Grid class={styles.Grid} axis="vertical" />
        </ImageCropper.Selection>
      </ImageCropper.Viewport>
    </ImageCropper.Root>
  </div>
}

```

### Rotation

Rotate the image with the `rotation` and `onRotationChange` props. Values are in degrees—common increments are 90
or 180.

**Example: rotation**

```ripple
import { ImageCropper } from 'ark-ripple/image-cropper';
import { RotateCcw, RotateCw } from 'lucide-ripple';
import { track } from 'ripple';
import button from 'styles/button.module.css';
import styles from 'styles/image-cropper.module.css';

export component Rotation() {
  let rotation = track(0);

  <div class={styles.Layout}>
    <div class={button.Group}>
      <button
        type="button"
        class={button.Root}
        onClick={() => {
          @rotation = @rotation - 90;
        }}
      >
        <RotateCcw />
      </button>
      <button
        type="button"
        class={button.Root}
        onClick={() => {
          @rotation = @rotation + 90;
        }}
      >
        <RotateCw />
      </button>
      <span style={{ fontSize: '0.875rem', padding: '0 0.5rem' }}>
        {@rotation}
        {'°'}
      </span>
    </div>

    <ImageCropper.Root
      class={styles.Root}
      {rotation}
      onRotationChange={(e) => {
        @rotation = e.rotation;
      }}
    >
      <ImageCropper.Viewport class={styles.Viewport}>
        <ImageCropper.Image
          class={styles.Image}
          src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800"
          alt="Sample"
        />
        <ImageCropper.Selection class={styles.Selection}>
          for (const position of ImageCropper.handles; key position) {
            <ImageCropper.Handle class={styles.Handle} {position}>
              <div />
            </ImageCropper.Handle>
          }
          <ImageCropper.Grid class={styles.Grid} axis="horizontal" />
          <ImageCropper.Grid class={styles.Grid} axis="vertical" />
        </ImageCropper.Selection>
      </ImageCropper.Viewport>
    </ImageCropper.Root>
  </div>
}

```

### Flip

Flip the image horizontally or vertically using the `flip` prop. Pass an object with `horizontal` and `vertical`
booleans.

**Example: flip**

```ripple
import { ImageCropper } from 'ark-ripple/image-cropper';
import { FlipHorizontal, FlipVertical } from 'lucide-ripple';
import { track } from 'ripple';
import button from 'styles/button.module.css';
import styles from 'styles/image-cropper.module.css';

export component Flip() {
  let flip = track({ horizontal: false, vertical: false });

  <div class={styles.Layout}>
    <div class={button.Group}>
      <button
        type="button"
        class={button.Root}
        data-variant={@flip.horizontal ? 'solid' : undefined}
        onClick={() => {
          @flip = { ...@flip, horizontal: !@flip.horizontal };
        }}
      >
        <FlipHorizontal />
        {'Horizontal'}
      </button>
      <button
        type="button"
        class={button.Root}
        data-variant={@flip.vertical ? 'solid' : undefined}
        onClick={() => {
          @flip = { ...@flip, vertical: !@flip.vertical };
        }}
      >
        <FlipVertical />
        {'Vertical'}
      </button>
    </div>

    <ImageCropper.Root
      class={styles.Root}
      {flip}
      onFlipChange={(e) => {
        @flip = e.flip;
      }}
    >
      <ImageCropper.Viewport class={styles.Viewport}>
        <ImageCropper.Image
          class={styles.Image}
          src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800"
          alt="Sample"
        />
        <ImageCropper.Selection class={styles.Selection}>
          for (const position of ImageCropper.handles; key position) {
            <ImageCropper.Handle class={styles.Handle} {position}>
              <div />
            </ImageCropper.Handle>
          }
          <ImageCropper.Grid class={styles.Grid} axis="horizontal" />
          <ImageCropper.Grid class={styles.Grid} axis="vertical" />
        </ImageCropper.Selection>
      </ImageCropper.Viewport>
    </ImageCropper.Root>
  </div>
}

```

### Min and Max Size

Constrain the crop area size with `minWidth`, `minHeight`, `maxWidth`, and `maxHeight`. Keeps the selection within
sensible bounds.

**Example: min-max-size**

```ripple
import { ImageCropper } from 'ark-ripple/image-cropper';
import styles from 'styles/image-cropper.module.css';

export component MinMaxSize() {
  <div class={styles.Layout}>
    <p class={styles.Description}>{'Crop area constrained to min 80px and max 200px'}</p>

    <ImageCropper.Root
      class={styles.Root}
      minWidth={80}
      minHeight={80}
      maxWidth={200}
      maxHeight={200}
    >
      <ImageCropper.Viewport class={styles.Viewport}>
        <ImageCropper.Image
          class={styles.Image}
          src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800"
          alt="Sample"
        />
        <ImageCropper.Selection class={styles.Selection}>
          for (const position of ImageCropper.handles; key position) {
            <ImageCropper.Handle class={styles.Handle} {position}>
              <div />
            </ImageCropper.Handle>
          }
          <ImageCropper.Grid class={styles.Grid} axis="horizontal" />
          <ImageCropper.Grid class={styles.Grid} axis="vertical" />
        </ImageCropper.Selection>
      </ImageCropper.Viewport>
    </ImageCropper.Root>
  </div>
}

```

### Fixed Crop Area

Set `fixedCropArea` to `true` when the crop area should stay fixed while the image moves underneath. Useful for
overlay-style cropping.

**Example: fixed**

```ripple
import { ImageCropper } from 'ark-ripple/image-cropper';
import styles from 'styles/image-cropper.module.css';

export component Fixed() {
  <div class={styles.Layout}>
    <ImageCropper.Root class={styles.Root} fixedCropArea>
      <ImageCropper.Viewport class={styles.Viewport}>
        <ImageCropper.Image
          class={styles.Image}
          src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800"
          alt="Sample"
        />
        <ImageCropper.Selection class={styles.Selection}>
          <ImageCropper.Grid class={styles.Grid} axis="horizontal" />
          <ImageCropper.Grid class={styles.Grid} axis="vertical" />
        </ImageCropper.Selection>
      </ImageCropper.Viewport>
    </ImageCropper.Root>
  </div>
}

```

### Crop Preview

Use `getCroppedImage()` from the context to get the cropped result. Call it with `{ output: 'dataUrl' }` for a base64
string you can use in an `img` src.

**Example: crop-preview**

```ripple
import { ImageCropper, useImageCropper } from 'ark-ripple/image-cropper';
import { Crop } from 'lucide-ripple';
import { track } from 'ripple';
import button from 'styles/button.module.css';
import styles from 'styles/image-cropper.module.css';

export component CropPreview() {
  const imageCropper = useImageCropper();
  let preview = track<string | null>(null);

  const handleCrop = async () => {
    const result = await @imageCropper.getCroppedImage({ output: 'dataUrl' });
    if (typeof result === 'string') {
      @preview = result;
    }
  };

  <div class={styles.Layout}>
    <div class={button.Group}>
      <button type="button" class={button.Root} data-variant="solid" onClick={handleCrop}>
        <Crop />
        {'Crop Image'}
      </button>
    </div>

    <ImageCropper.RootProvider class={styles.Root} value={imageCropper}>
      <ImageCropper.Viewport class={styles.Viewport}>
        <ImageCropper.Image
          class={styles.Image}
          src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800"
          alt="Sample"
          crossOrigin="anonymous"
        />
        <ImageCropper.Selection class={styles.Selection}>
          for (const position of ImageCropper.handles; key position) {
            <ImageCropper.Handle class={styles.Handle} {position}>
              <div />
            </ImageCropper.Handle>
          }
          <ImageCropper.Grid class={styles.Grid} axis="horizontal" />
          <ImageCropper.Grid class={styles.Grid} axis="vertical" />
        </ImageCropper.Selection>
      </ImageCropper.Viewport>
    </ImageCropper.RootProvider>

    <div class={styles.Preview}>
      <span class={styles.PreviewLabel}>{'Preview'}</span>
      if (@preview) {
        <img src={@preview} alt="Cropped preview" class={styles.PreviewImage} />
      }
    </div>
  </div>
}

```

### Reset

The context exposes a `reset()` method that restores the image to its initial state. Handy for an "undo" or "start over"
button.

**Example: reset**

```ripple
import { ImageCropper, useImageCropper } from 'ark-ripple/image-cropper';
import { FlipHorizontal, RotateCw, RotateCcw, RefreshCw, ZoomIn, ZoomOut } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/image-cropper.module.css';

export component Reset() {
  const imageCropper = useImageCropper();

  <div class={styles.Layout}>
    <div class={button.Group}>
      <button type="button" class={button.Root} onClick={() => @imageCropper.zoomBy(-0.1)}>
        <ZoomOut />
      </button>
      <button type="button" class={button.Root} onClick={() => @imageCropper.zoomBy(0.1)}>
        <ZoomIn />
      </button>
      <button type="button" class={button.Root} onClick={() => @imageCropper.rotateBy(-90)}>
        <RotateCcw />
      </button>
      <button type="button" class={button.Root} onClick={() => @imageCropper.rotateBy(90)}>
        <RotateCw />
      </button>
      <button type="button" class={button.Root} onClick={() => @imageCropper.flipHorizontally()}>
        <FlipHorizontal />
      </button>
      <button
        type="button"
        class={button.Root}
        data-variant="surface"
        onClick={() => @imageCropper.reset()}
      >
        <RefreshCw />
        {'Reset'}
      </button>
    </div>

    <ImageCropper.RootProvider class={styles.Root} value={imageCropper}>
      <ImageCropper.Viewport class={styles.Viewport}>
        <ImageCropper.Image
          class={styles.Image}
          src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800"
          alt="Sample"
        />
        <ImageCropper.Selection class={styles.Selection}>
          for (const position of ImageCropper.handles; key position) {
            <ImageCropper.Handle class={styles.Handle} {position}>
              <div />
            </ImageCropper.Handle>
          }
          <ImageCropper.Grid class={styles.Grid} axis="horizontal" />
          <ImageCropper.Grid class={styles.Grid} axis="vertical" />
        </ImageCropper.Selection>
      </ImageCropper.Viewport>
    </ImageCropper.RootProvider>
  </div>
}

```

### Events

Listen to `onCropChange` and `onZoomChange` to track crop position and zoom level. Use these to sync with external state
or show live previews.

**Example: events**

```ripple
import { ImageCropper } from 'ark-ripple/image-cropper';
import { track } from 'ripple';
import styles from 'styles/image-cropper.module.css';

export component Events() {
  let cropData = track({ x: 0, y: 0, width: 0, height: 0 });
  let zoom = track(1);

  <div class={styles.Layout}>
    <ImageCropper.Root
      class={styles.Root}
      onCropChange={(e) => {
        @cropData = e.crop;
      }}
      onZoomChange={(e) => {
        @zoom = e.zoom;
      }}
    >
      <ImageCropper.Viewport class={styles.Viewport}>
        <ImageCropper.Image
          class={styles.Image}
          src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800"
          alt="Sample"
        />
        <ImageCropper.Selection class={styles.Selection}>
          for (const position of ImageCropper.handles; key position) {
            <ImageCropper.Handle class={styles.Handle} {position}>
              <div />
            </ImageCropper.Handle>
          }
          <ImageCropper.Grid class={styles.Grid} axis="horizontal" />
          <ImageCropper.Grid class={styles.Grid} axis="vertical" />
        </ImageCropper.Selection>
      </ImageCropper.Viewport>
    </ImageCropper.Root>

    <div class={styles.DataDisplay}>
      <div class={styles.DataItem}>
        <span class={styles.DataLabel}>{'Zoom'}</span>
        <span class={styles.DataValue}>
          {@zoom.toFixed(2)}
          {'x'}
        </span>
      </div>
      <div class={styles.DataItem}>
        <span class={styles.DataLabel}>{'Position'}</span>
        <span class={styles.DataValue}>
          {Math.round(@cropData.x)}
          {', '}
          {Math.round(@cropData.y)}
        </span>
      </div>
      <div class={styles.DataItem}>
        <span class={styles.DataLabel}>{'Size'}</span>
        <span class={styles.DataValue}>
          {Math.round(@cropData.width)}
          {' × '}
          {Math.round(@cropData.height)}
        </span>
      </div>
    </div>
  </div>
}

```

### Context

Use `ImageCropper.Context` to access the cropper API from anywhere inside the root. You get methods like `zoomBy`,
`rotateBy`, and `setZoom`.

**Example: context**

```ripple
import { ImageCropper } from 'ark-ripple/image-cropper';
import { ZoomIn, ZoomOut } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/image-cropper.module.css';

export component Context() {
  <div class={styles.Layout}>
    <ImageCropper.Root class={styles.Root}>
      <ImageCropper.Context>
        component children({ context }) {
          <div class={button.Group}>
            <button type="button" class={button.Root} onClick={() => @context.zoomBy(-0.1)}>
              <ZoomOut />
            </button>
            <span
              style={{
                fontSize: '0.875rem',
                padding: '0 0.5rem',
                minWidth: '3rem',
                textAlign: 'center',
              }}
            >
              {@context.zoom.toFixed(1)}
              {'x'}
            </span>
            <button type="button" class={button.Root} onClick={() => @context.zoomBy(0.1)}>
              <ZoomIn />
            </button>
          </div>
        }
      </ImageCropper.Context>

      <ImageCropper.Viewport class={styles.Viewport}>
        <ImageCropper.Image
          class={styles.Image}
          src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800"
          alt="Sample"
        />
        <ImageCropper.Selection class={styles.Selection}>
          for (const position of ImageCropper.handles; key position) {
            <ImageCropper.Handle class={styles.Handle} {position}>
              <div />
            </ImageCropper.Handle>
          }
          <ImageCropper.Grid class={styles.Grid} axis="horizontal" />
          <ImageCropper.Grid class={styles.Grid} axis="vertical" />
        </ImageCropper.Selection>
      </ImageCropper.Viewport>
    </ImageCropper.Root>
  </div>
}

```

### Root Provider

Use `RootProvider` with `useImageCropper` when you need to control the cropper from outside the component tree. Build
custom toolbars or integrate with form state.

**Example: root-provider**

```ripple
import { ImageCropper, useImageCropper } from 'ark-ripple/image-cropper';
import { ZoomIn, ZoomOut } from 'lucide-ripple';
import button from 'styles/button.module.css';
import styles from 'styles/image-cropper.module.css';

export component RootProvider() {
  const imageCropper = useImageCropper();

  <div class={styles.Layout}>
    <div class={button.Group}>
      <button
        type="button"
        class={button.Root}
        onClick={() => @imageCropper.setZoom(@imageCropper.zoom - 0.1)}
      >
        <ZoomOut />
      </button>
      <span style={{ fontSize: '0.875rem', minWidth: '3rem', textAlign: 'center' }}>
        {@imageCropper.zoom.toFixed(1)}
        {'x'}
      </span>
      <button
        type="button"
        class={button.Root}
        onClick={() => @imageCropper.setZoom(@imageCropper.zoom + 0.1)}
      >
        <ZoomIn />
      </button>
    </div>

    <ImageCropper.RootProvider class={styles.Root} value={imageCropper}>
      <ImageCropper.Viewport class={styles.Viewport}>
        <ImageCropper.Image
          class={styles.Image}
          src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800"
          alt="Sample"
        />
        <ImageCropper.Selection class={styles.Selection}>
          for (const position of ImageCropper.handles; key position) {
            <ImageCropper.Handle class={styles.Handle} {position}>
              <div />
            </ImageCropper.Handle>
          }
          <ImageCropper.Grid class={styles.Grid} axis="horizontal" />
          <ImageCropper.Grid class={styles.Grid} axis="vertical" />
        </ImageCropper.Selection>
      </ImageCropper.Viewport>
    </ImageCropper.RootProvider>
  </div>
}

```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `aspectRatio` | `number` | No | The aspect ratio to maintain for the crop area (width / height).
For example, an aspect ratio of 16 / 9 will maintain a width to height ratio of 16:9.
If not provided, the crop area can be freely resized. |
| `cropShape` | `'circle' | 'rectangle'` | No | The shape of the crop area. |
| `defaultFlip` | `FlipState` | No | The initial flip state to apply to the image. |
| `defaultRotation` | `number` | No | The initial rotation to apply to the image in degrees. |
| `defaultZoom` | `number` | No | The initial zoom factor to apply to the image. |
| `fixedCropArea` | `boolean` | No | Whether the crop area is fixed in size and position. |
| `flip` | `FlipState` | No | The controlled flip state of the image. |
| `ids` | `Partial<{
  root: string
  viewport: string
  image: string
  selection: string
  handle: (position: string) => string
}>` | No | The ids of the image cropper elements |
| `initialCrop` | `Rect` | No | The initial rectangle of the crop area.
If not provided, a smart default will be computed based on viewport size and aspect ratio. |
| `maxHeight` | `number` | No | The maximum height of the crop area |
| `maxWidth` | `number` | No | The maximum width of the crop area |
| `maxZoom` | `number` | No | The maximum zoom factor allowed. |
| `minHeight` | `number` | No | The minimum height of the crop area |
| `minWidth` | `number` | No | The minimum width of the crop area |
| `minZoom` | `number` | No | The minimum zoom factor allowed. |
| `nudgeStep` | `number` | No | The base nudge step for keyboard arrow keys (in pixels). |
| `nudgeStepCtrl` | `number` | No | The nudge step when Ctrl/Cmd key is held (in pixels). |
| `nudgeStepShift` | `number` | No | The nudge step when Shift key is held (in pixels). |
| `onCropChange` | `(details: CropChangeDetails) => void` | No | Callback fired when the crop area changes. |
| `onFlipChange` | `(details: FlipChangeDetails) => void` | No | Callback fired when the flip state changes. |
| `onRotationChange` | `(details: RotationChangeDetails) => void` | No | Callback fired when the rotation changes. |
| `onZoomChange` | `(details: ZoomChangeDetails) => void` | No | Callback fired when the zoom level changes. |
| `rotation` | `number` | No | The controlled rotation of the image in degrees (0 - 360). |
| `translations` | `IntlTranslations` | No | Specifies the localized strings that identify accessibility elements and their states. |
| `zoom` | `number` | No | The controlled zoom level of the image. |
| `zoomSensitivity` | `number` | No | Controls how responsive pinch-to-zoom is. |
| `zoomStep` | `number` | No | The amount of zoom applied per wheel step. |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | image-cropper |
| `[data-part]` | root |
| `[data-fixed]` |  |
| `[data-shape]` |  |
| `[data-pinch]` |  |
| `[data-dragging]` | Present when in the dragging state |
| `[data-panning]` |  |


**Root CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--crop-width` | The width of the Root |
| `--crop-height` | The height of the Root |
| `--crop-x` | The crop x value for the Root |
| `--crop-y` | The crop y value for the Root |
| `--image-zoom` | The image zoom value for the Root |
| `--image-rotation` | The image rotation value for the Root |
| `--image-offset-x` | The offset position for image |
| `--image-offset-y` | The offset position for image |


**Grid Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `axis` | `'horizontal' | 'vertical'` | Yes | The axis of the grid lines to display |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Grid Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | image-cropper |
| `[data-part]` | grid |
| `[data-axis]` | The axis to resize |
| `[data-dragging]` | Present when in the dragging state |
| `[data-panning]` |  |


**Handle Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `position` | `HandlePosition` | Yes | The position of the handle |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Handle Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | image-cropper |
| `[data-part]` | handle |
| `[data-position]` |  |
| `[data-disabled]` | Present when disabled |


**Image Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Image Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | image-cropper |
| `[data-part]` | image |
| `[data-ready]` |  |
| `[data-flip-horizontal]` |  |
| `[data-flip-vertical]` |  |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseImageCropperReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Selection Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Selection Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | image-cropper |
| `[data-part]` | selection |
| `[data-disabled]` | Present when disabled |
| `[data-shape]` |  |
| `[data-measured]` |  |
| `[data-dragging]` | Present when in the dragging state |
| `[data-panning]` |  |


**Viewport Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Viewport Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | image-cropper |
| `[data-part]` | viewport |
| `[data-disabled]` | Present when disabled |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `zoom` | `number` | The current zoom level of the image. |
| `rotation` | `number` | The current rotation of the image in degrees. |
| `flip` | `FlipState` | The current flip state of the image. |
| `crop` | `Rect` | The current crop area rectangle in viewport coordinates. |
| `offset` | `Point` | The current offset (pan position) of the image. |
| `naturalSize` | `Size` | The natural (original) size of the image. |
| `viewportRect` | `BoundingRect` | The viewport rectangle dimensions and position. |
| `dragging` | `boolean` | Whether the crop area is currently being dragged. |
| `panning` | `boolean` | Whether the image is currently being panned. |
| `setZoom` | `(zoom: number) => void` | Function to set the zoom level of the image. |
| `zoomBy` | `(delta: number) => void` | Function to zoom the image by a relative amount. |
| `setRotation` | `(rotation: number) => void` | Function to set the rotation of the image. |
| `rotateBy` | `(degrees: number) => void` | Function to rotate the image by a relative amount in degrees. |
| `setFlip` | `(flip: Partial<FlipState>) => void` | Function to set the flip state of the image. |
| `flipHorizontally` | `(value?: boolean) => void` | Function to flip the image horizontally. Pass a boolean to set explicitly or omit to toggle. |
| `flipVertically` | `(value?: boolean) => void` | Function to flip the image vertically. Pass a boolean to set explicitly or omit to toggle. |
| `resize` | `(handlePosition: HandlePosition, delta: number) => void` | Function to resize the crop area from a handle programmatically. |
| `reset` | `() => void` | Function to reset the cropper to its initial state. |
| `getCroppedImage` | `(options?: GetCroppedImageOptions) => Promise<string | Blob>` | Function to get the cropped image with all transformations applied.
Returns a Promise that resolves to either a Blob or data URL. |
| `getCropData` | `() => CropData` | Function to get the crop data in natural image pixel coordinates.
These coordinates are relative to the original image dimensions,
accounting for zoom, rotation, and flip transformations.
Use this for server-side cropping or state persistence. |