GitHub55X

Image Cropper

Vue image cropper to pan, zoom, and crop photos before upload or avatar updates.

API Reference
PreviousNext

Installation

Install from the Vuzeno registry:

      
      bunx --bun shadcn-vue@latest add https://vuzeno.com/r/image-cropper.json

Usage

      
      <script setup lang="ts">
import { ImageCropper } from "@/components/ui/image-cropper";
</script>

<template>
  <ImageCropper.Root>
    <!-- … -->
  </ImageCropper.Root>
</template>

Composition

      
      ImageCropper.Root
├── ImageCropper.Context
├── ImageCropper.Grid
├── ImageCropper.Handle
├── ImageCropper.Image
├── ImageCropper.RootProvider
├── ImageCropper.Selection
└── ImageCropper.Viewport

Examples

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.

Circle Crop

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

Initial Crop

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

Controlled Zoom

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

Zoom Limits

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

Rotation

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

Flip

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

Min and Max Size

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

Fixed Crop Area

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

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.

Reset

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

Events

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

Context

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

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.

API

See Ark UI Image Cropper docs for full props and examples.

ImageInput