Quick Start

This package is a Vue component wrapper for Cropper.js v1.

Note

It can only be used in Vue 3 projects, and the Vue version must be at least >=3.2.13. Vue 2 is not supported.

1.x is now ESM-only, with CJS/IIFE support removed. Please see the migration guide if you are upgrading from older versions.

To learn why we use Cropper.js 1.x instead of 2.x, see Design Philosophy.

Installation

To ensure the correct version of Cropper.js is installed, copy and run the following command.

npm

$ npm add vue-picture-cropper cropperjs@^1

pnpm

$ pnpm add vue-picture-cropper cropperjs@^1

yarn

$ yarn add vue-picture-cropper cropperjs@^1

bun

$ bun add vue-picture-cropper cropperjs@^1

Import styles

Import the styles in your project entry file (e.g. main.ts or main.js).

// Import Cropper.js styles and VuePictureCropper styles
import 'cropperjs/dist/cropper.css'
import 'vue-picture-cropper/style.css'

Usage

Starting from 1.x, this package provides two ways to render the cropper.

Using VuePictureCropper

This is the traditional approach, supported since 0.x, with some differences from 0.x. As of 1.x, the module-level cropper instance variable is deprecated. If you are upgrading, see Migration from v0.x.

We recommend using the script-setup syntax:

JavaScript

<!-- This is the script section of the Vue component -->
<script setup>
import VuePictureCropper from 'vue-picture-cropper'

// Bind a ref to the component
const vpcRef = ref(null)

// Derive the Cropper instance from the component ref
// to use getFile() etc. for the crop result
const cropper = computed(() => vpcRef.value?.cropper ?? null)
</script>

Template

<!-- This is the template section of the Vue component -->
<template>
  <!-- Render the imported VuePictureCropper component -->
  <VuePictureCropper
    ref="vpcRef"
    :img="pic"
    :options="{
      viewMode: 2,
    }"
  />
</template>

Prefer the standard component format?

If you are new to Vue 3, you can also use the standard component format (without script-setup):

JavaScript

<!-- This is the script section of the Vue component -->
<script>
import { useCropper } from 'vue-picture-cropper'

export default defineComponent({
  setup() {
    // Bind a ref to the component
    const vpcRef = ref(null)

    // Derive the Cropper instance from the component ref to use getFile() etc. for the crop result
    const cropper = computed(() => vpcRef.value?.cropper ?? null)

    // Return them so they can be used in the template
    return {
      vpcRef,
      cropper,
    }
  },
})
</script>

Template

<!-- This is the template section of the Vue component -->
<template>
  <!-- Render the imported VuePictureCropper component -->
  <VuePictureCropper
    ref="vpcRef"
    :img="pic"
    :options="{
      viewMode: 2,
    }"
  />
</template>

Full example: Basic usage of VuePictureCropper

Using useCropper

This API is available from 1.x. The composable makes it easier to work with the Cropper instance and is well-suited for managing multiple croppers in one component.

We recommend using the script-setup syntax:

JavaScript

<!-- This is the script section of the Vue component -->
<script setup>
import { useCropper } from 'vue-picture-cropper'

// Pass reactive data via computed props
const cropperProps = computed(() => ({
  img: pic.value ?? '',
  options: {
    viewMode: 2,
  },
}))

// CropperComponent and cropper are bound; you can use the cropper instance
const [CropperComponent, cropper] = useCropper(cropperProps)
</script>

Template

<!-- This is the template section of the Vue component -->
<template>
  <CropperComponent />
</template>

Prefer the standard component format?

If you are new to Vue 3, you can also use the standard component format (without script-setup):

JavaScript

<!-- This is the script section of the Vue component -->
<script>
import { useCropper } from 'vue-picture-cropper'

export default defineComponent({
  setup() {
    const cropperProps = computed(() => ({
      img: pic.value ?? '',
      options: {
        viewMode: 2,
      },
    }))

    // CropperComponent is a runtime component;
    // render it with <component :is="CropperComponent" />
    const [CropperComponent, cropper] = useCropper(cropperProps)

    // Return them so they can be used in the template
    return {
      CropperComponent,
      cropper,
    }
  },
})
</script>

Template

<!-- This is the template section of the Vue component -->
<template>
  <!-- With the standard component format, use a dynamic component to render CropperComponent -->
  <component :is="CropperComponent" />
</template>

Full example: Basic usage of useCropper

Multiple Croppers

From 1.x, whether you use VuePictureCropper or useCropper, you can easily manage multiple instances in a single component.

See the examples:

• Multiple VuePictureCropper instances in one component
• Multiple useCropper instances in one component

License

MIT License © 2020 chengpeiquan