Image Cropper

Headless image cropper: aspect-locked crop box, zoom, rotation, keyboard nudging, canvas export.

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/ui

Add the public import below to <script setup lang="ts">. Components provide behavior without styles; the preview uses optional Paper styles.

import { ImageCropperArea, ImageCropperGrid, ImageCropperHandle, ImageCropperImage, ImageCropper, ImageCropperRoot, ImageCropperViewport } from "@vizejs/ui/image-cropper";

Or copy the source into your project with vize lib pull image-cropper (see Source Distribution).

Try it

This is the basic example maintained with the component source, using the public package imports. The preview adds the optional Paper styles.

Open the interactive example · Styling these components

Copy the example

<!-- Square avatar cropper with a rule-of-thirds grid, corner handles, and controlled zoom and rotation. -->
<script setup lang="ts">
import { ref, useId } from "vue";

import {
  ImageCropper,
  ImageCropperArea,
  ImageCropperGrid,
  ImageCropperHandle,
  ImageCropperImage,
  ImageCropperViewport,
} from "@vizejs/ui/image-cropper";

const zoom = ref(1);
const rotation = ref(0);
const zoomId = useId();
// The viewport needs a size to fit the image into.
const viewportSize = { inlineSize: "320px", blockSize: "240px" };

function rotate(): void {
  rotation.value = (rotation.value + 90) % 360;
}
</script>

<template>
  <ImageCropper
    v-slot="{ crop }"
    v-model:zoom="zoom"
    v-model:rotation="rotation"
    :aspect-ratio="1"
    :max-zoom="3"
  >
    <ImageCropperViewport :style="viewportSize">
      <ImageCropperImage src="/media/profile-photo.jpg" alt="Profile photo to crop" />
      <ImageCropperArea>
        <ImageCropperGrid />
        <ImageCropperHandle position="nw" />
        <ImageCropperHandle position="ne" />
        <ImageCropperHandle position="sw" />
        <ImageCropperHandle position="se" />
      </ImageCropperArea>
    </ImageCropperViewport>
    <label :for="zoomId">Zoom</label>
    <input :id="zoomId" v-model.number="zoom" type="range" min="1" max="3" step="0.1" />
    <button type="button" @click="rotate">Rotate 90°</button>
    <output>{{
      crop ? `${Math.round(crop.width)} × ${Math.round(crop.height)} px` : "Loading image"
    }}</output>
  </ImageCropper>
</template>

API

ImageCropperArea

Source: src/families/media/image-cropper/image-cropper-area.vue

Slots

Exposed

ImageCropperGrid

Source: src/families/media/image-cropper/image-cropper-grid.vue

Props

Slots

Exposed

ImageCropperHandle

Source: src/families/media/image-cropper/image-cropper-handle.vue

Props

Slots

Exposed

ImageCropperImage

Source: src/families/media/image-cropper/image-cropper-image.vue

Props

Events

Exposed

ImageCropper

Source: src/families/media/image-cropper/image-cropper-root.vue

Props

Events

Slots

Exposed

ImageCropperRoot

Source: src/families/media/image-cropper/image-cropper-root.vue

Props

Events

Slots

Exposed

ImageCropperViewport

Source: src/families/media/image-cropper/image-cropper-viewport.vue

Props

Slots

Exposed

Behavior

Normative state x input -> outcome table for image-cropper-root.vue, image-cropper-viewport.vue, image-cropper-image.vue, image-cropper-area.vue, image-cropper-handle.vue, and image-cropper-grid.vue (@vizejs/ui/image-cropper). Every row is proven by the named test.

Crops are { x, y, width, height } in the rotated image's bounding box, measured in natural image pixels, so cropImage and server-side croppers can reproduce the result. The viewport shows the bounds with contain scale times zoom; geometry is published only after the image and viewport are measured, so server and hydration markup agree.

Pinch-to-zoom gestures are not interpreted; touch users zoom with the consumer's controls (setZoom) or the keyboard.