@xcvzmoon/vue-cropperjs

@xcvzmoon/vue-cropperjs

Vue 3 wrapper for Cropper.js 2 with a Vue-native component and composable API.

• Vue 3 only
• Cropper.js 2 only

Install

pnpm add @xcvzmoon/vue-cropperjs cropperjs

Cropper.js 2 styles are bundled with its custom elements, so no separate CSS import is required:

// Cropper.js 2 styles are bundled with its custom elements.
// No separate CSS import is required.

Basic usage

<script setup lang="ts">
import { CropperImage } from '@xcvzmoon/vue-cropperjs';

const src = 'https://fengyuanchen.github.io/cropperjs/picture.jpg';
</script>

<template>
  <CropperImage
    :canvas-props="{ background: true }"
    :image-props="{ rotatable: true, scalable: true, translatable: true }"
    :selection-props="{ initialCoverage: 0.5, movable: true, resizable: true }"
    :src="src"
  />
</template>

Template ref usage

<script setup lang="ts">
import { useTemplateRef } from 'vue';
import { CropperImage, type CropperImageInstance } from '@xcvzmoon/vue-cropperjs';

const cropperRef = useTemplateRef<CropperImageInstance>('cropperRef');

async function exportSelection() {
  const canvas = await cropperRef.value?.toCanvas({ width: 320 });
  if (!canvas) return;

  const dataUrl = canvas.toDataURL('image/png');
  console.log(dataUrl);
}
</script>

<template>
  <CropperImage ref="cropperRef" :src="'/image.jpg'" />
  <button type="button" @click="exportSelection">Export</button>
</template>

v-model:data

<script setup lang="ts">
import { ref } from 'vue';
import { CropperImage, type CropperData } from '@xcvzmoon/vue-cropperjs';

const cropData = ref<CropperData | null>(null);
</script>

<template>
  <CropperImage
    v-model:data="cropData"
    :image-props="{ rotatable: true, scalable: true, translatable: true }"
    :selection-props="{ initialCoverage: 0.5, movable: true, resizable: true }"
    :src="'/image.jpg'"
  />

  <pre>{{ cropData }}</pre>
</template>

data: null resets the image transform and selection back to Cropper's default state.

useCropper

<script setup lang="ts">
import { onMounted, useTemplateRef } from 'vue';
import { useCropper } from '@xcvzmoon/vue-cropperjs';

const imageRef = useTemplateRef<HTMLImageElement | null>('imageRef');
const cropper = useCropper(imageRef, { syncData: 'events' });

onMounted(async () => {
  await cropper.init();
  cropper.zoomImage(0.1);
  console.log(cropper.data.value);
});
</script>

<template>
  <img ref="imageRef" alt="Example" src="https://raw.githubusercontent.com/xcvzmoon/vue-cropperjs/HEAD/image.jpg" />
</template>

The composable is useful when you want full control over markup and lifecycle while still getting typed state refs and action methods.

syncData: 'events' keeps the data and imageTransform refs updated from Cropper events. The default syncData: 'manual' avoids continuous syncing and lets you call refreshData() explicitly.

Public API

Component props

Props matrix

Prop object shapes

imageProps

• initialCenterSize
• rotatable
• scalable
• skewable
• slottable
• translatable

selectionProps

• x, y, width, height
• aspectRatio, initialAspectRatio, initialCoverage
• dynamic, movable, resizable, zoomable
• multiple, keyboard, outlined, precise

canvasProps

• background
• disabled
• scaleStep
• themeColor

Emits

Events matrix

Event detail types

Exposed component methods

Methods matrix

Composable return value

useCropper() returns the same typed action surface used by the component expose API, plus:

• cropper: ShallowRef<CropperInstance | null>
• canvas: ComputedRef<CropperCanvasElement | null>
• image: ComputedRef<CropperImageElementInstance | null>
• selection: ComputedRef<CropperSelectionElement | null>
• elementRef: Ref<HTMLImageElement | null>
• data: Ref<CropperData | null>
• imageTransform: Ref<CropperImageTransform | null>
• isReady: Ref<boolean>
• isInitializing: Ref<boolean>
• error: Ref<Error | null>
• refreshData(): CropperData | null
• applyData(data: CropperData | null): CropperData | null
• init(options?): Promise<CropperInstance | null>

Types

Useful exported types:

• CropperImageInstance
• CropperImageProps
• CropperImageEmits
• CropperData
• CropperInitOptions
• CropperSyncMode
• CropperCanvasOptions
• CropperImageTransform
• CropperCanvasElement
• CropperImageElementInstance
• CropperSelectionElement
• UseCropperOptions

Reactive behavior

These props are designed for live updates after mount:

• src
• alt
• crossorigin
• data
• imageProps
• selectionProps
• canvasProps

These values should be treated as init-time configuration:

• initOptions.container
• initOptions.template
• any setup that changes the internal Cropper element structure

If you need to change init-time structure, recreate the component instead of expecting a seamless hot update.

Error behavior

• the component emits error when Cropper initialization fails
• the component emits error when the source image fails to load
• setImageSource() throws if Cropper's internal image $ready() flow rejects

Nuxt 3

Use the component only on the client because Cropper depends on the DOM.

<template>
  <ClientOnly>
    <CropperImage
      v-model:data="cropData"
      :image-props="{ rotatable: true, scalable: true, translatable: true }"
      :selection-props="{ initialCoverage: 0.5, movable: true, resizable: true }"
      :src="src"
    />
  </ClientOnly>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { CropperImage, type CropperData } from '@xcvzmoon/vue-cropperjs';

const cropData = ref<CropperData | null>(null);
const src = '/images/example.jpg';
</script>

If you want Nuxt auto-imports without creating a Nuxt module, add app-level wrappers for both the component and composable:

// composables/useVueCropper.ts
export { useCropper as useVueCropper } from '@xcvzmoon/vue-cropperjs';

<!-- components/AppCropperImage.client.vue -->
<script setup lang="ts">
export { CropperImage as default } from '@xcvzmoon/vue-cropperjs';
</script>

That gives you Nuxt auto-imports for useVueCropper() and AppCropperImage while keeping the package itself framework-agnostic.

Migration notes

• Vue 3 only
• Cropper.js 2 only
• element-oriented API instead of a v1-style method proxy layer
• no Vue 2 compatibility layer
• no attempt to support Cropper.js v1 and v2 in one API
• v-model:data syncs image transform plus selection state instead of exposing old v1 getData() assumptions alone