{"id":12545,"library":"vue-picture-cropper","title":"Vue Picture Cropper","description":"Vue Picture Cropper is a lightweight and easy-to-use image cropping component specifically designed for Vue 3 applications. It leverages the popular Cropper.js library internally, providing a robust set of cropping functionalities. The current stable version is `v1.0.0`, which introduced significant breaking changes and new features, most notably the `useCropper` composable for enhanced programmatic control. The project maintains an active release cadence, with a focus on Vue 3 Composition API, TypeScript support, and features like multiple cropper instances on a single page, preset cropping modes (fixed size, circular), and direct output as Blob, File, or Base64. It differentiates itself through its tight integration with the Vue 3 ecosystem and a streamlined API for common cropping tasks.","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/chengpeiquan/vue-picture-cropper","tags":["javascript","picture cropper","image cropper","photo cropper","vue3 cropper","vue3 cropperjs","typescript"],"install":[{"cmd":"npm install vue-picture-cropper","lang":"bash","label":"npm"},{"cmd":"yarn add vue-picture-cropper","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-picture-cropper","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core image cropping logic; peer dependency.","package":"cropperjs","optional":false},{"reason":"Vue 3 framework dependency; peer dependency.","package":"vue","optional":false}],"imports":[{"note":"The main component is exported as a default export, as shown in official examples.","wrong":"import { PictureCropper } from 'vue-picture-cropper'","symbol":"PictureCropper","correct":"import PictureCropper from 'vue-picture-cropper'"},{"note":"The `useCropper` composable was introduced in v1.0.0 and is a named export. Ensure you are on v1.0.0 or later.","wrong":"import useCropper from 'vue-picture-cropper'","symbol":"useCropper","correct":"import { useCropper } from 'vue-picture-cropper'"},{"note":"Import types using `import type` for better tree-shaking and clarity in TypeScript projects. Type definitions were refined in v0.6.0 and enhanced in v1.0.0.","wrong":"import { CropperResult } from 'vue-picture-cropper'","symbol":"CropperResult","correct":"import type { CropperResult } from 'vue-picture-cropper'"}],"quickstart":{"code":"<!-- App.vue -->\n<template>\n  <div class=\"container\">\n    <h1>Image Cropper</h1>\n    <input type=\"file\" accept=\"image/*\" @change=\"selectFile\" />\n    <div v-if=\"imageSrc\">\n      <PictureCropper\n        :boxStyle=\"{ width: '100%', height: '300px', backgroundColor: '#f8f8f8', margin: 'auto' }\"\n        :img=\"imageSrc\"\n        :options=\"{ \n          viewMode: 1, \n          dragMode: 'move', \n          aspectRatio: 1 / 1,\n          cropBoxResizable: true\n        }\"\n        @ready=\"cropperReady\"\n      />\n      <button @click=\"cropImage\">Crop Image</button>\n      <div v-if=\"croppedImageBlob\">\n        <h2>Cropped Image Preview</h2>\n        <img :src=\"croppedImageBlob\" alt=\"Cropped\" style=\"max-width: 100%;\" />\n      </div>\n    </div>\n  </div>\n</template>\n\n<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport PictureCropper, { useCropper } from 'vue-picture-cropper';\n\nconst imageSrc = ref<string | null>(null);\nconst croppedImageBlob = ref<string | null>(null);\nconst { getCropperRef, getCropper, setCropper } = useCropper();\n\nconst selectFile = (e: Event) => {\n  const target = e.target as HTMLInputElement;\n  if (target.files && target.files.length) {\n    const file = target.files[0];\n    imageSrc.value = URL.createObjectURL(file);\n  }\n};\n\nconst cropperReady = () => {\n  console.log('Cropper is ready!');\n  // You can set options or perform actions when cropper is ready\n  // For example, setCropper(getCropperRef().value.cropperInstance); // If you need direct Cropper.js instance\n};\n\nconst cropImage = async () => {\n  const cropper = getCropper(); // Get the current cropper instance via composable\n  if (cropper) {\n    const blob = await cropper.getBlob();\n    if (blob) {\n      croppedImageBlob.value = URL.createObjectURL(blob);\n      console.log('Cropped image blob:', blob);\n    } else {\n      console.error('Failed to get cropped image blob.');\n    }\n  }\n};\n</script>\n\n<style>\n.container {\n  max-width: 600px;\n  margin: 20px auto;\n  padding: 20px;\n  border: 1px solid #eee;\n  border-radius: 8px;\n  font-family: sans-serif;\n}\nbutton {\n  margin-top: 20px;\n  padding: 10px 15px;\n  background-color: #3fb984;\n  color: white;\n  border: none;\n  border-radius: 4px;\n  cursor: pointer;\n}\n</style>","lang":"typescript","description":"This quickstart demonstrates how to install `vue-picture-cropper` and `cropperjs`, select an image, display the cropper component, and then use the `useCropper` composable to retrieve the cropped image as a Blob for preview."},"warnings":[{"fix":"Refer to the official 'Migrating from v0.x' guide and online examples for step-by-step migration instructions. Update import paths and usage of component properties/methods.","message":"Version 1.0.0 introduced significant breaking changes, including enhanced type constraints, unified public exports, component-scoped cropper instances replacing module-level ones, and the introduction of the `useCropper` composable. Direct access to the Cropper.js instance and event handling might have changed.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Ensure `cropperjs` is installed: `npm install vue-picture-cropper cropperjs@^1`.","message":"The `cropperjs` library is a peer dependency and must be installed separately alongside `vue-picture-cropper`. Forgetting to install it will lead to runtime errors.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Always `await` the calls to `cropper.getBlob()`, `cropper.getFile()`, and `cropper.getBase64()` to correctly handle the asynchronous nature and receive the result.","message":"The `getBlob`, `getFile`, and `getBase64` methods are asynchronous operations since v0.3.0 (for `getBlob`) due to their reliance on canvas processing to generate higher quality output and correctly handle large images, which was a fix for previous white-border issues.","severity":"gotcha","affected_versions":">=0.3.0"},{"fix":"Upgrade to `v0.1.11` or later. If on an older version, add explicit checks for `null` or empty results before further processing cropped data.","message":"Prior to v0.1.11, if cropping failed and `base64` was empty, converting it to a `blob` could lead to application crashes. This was fixed to return `null` instead.","severity":"gotcha","affected_versions":"<0.1.11"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install `cropperjs`: `npm install cropperjs@^1` or `yarn add cropperjs@^1`.","cause":"The `cropperjs` library, a peer dependency, has not been installed.","error":"Cannot find module 'cropperjs' or its corresponding type declarations."},{"fix":"Upgrade `vue-picture-cropper` to `v1.0.0` or higher (`npm install vue-picture-cropper@^1`) and ensure it's imported correctly as a named export: `import { useCropper } from 'vue-picture-cropper'`.","cause":"Attempting to use the `useCropper` composable on a version of `vue-picture-cropper` prior to `v1.0.0`, or an incorrect named import.","error":"TypeError: (0, vue_picture_cropper__WEBPACK_IMPORTED_MODULE_0__.useCropper) is not a function"},{"fix":"Ensure you are awaiting `getBlob()` as it's an asynchronous operation. Also, make sure the `cropper` instance (e.g., obtained from `useCropper().getCropper()`) is valid before attempting to call methods on it.","cause":"This error often occurs when `getBlob()` is called synchronously or on an undefined cropper instance, or when the TypeScript context doesn't correctly infer the `CropperResult` type.","error":"Property 'getBlob' does not exist on type '(...)' (TypeScript error)"}],"ecosystem":"npm"}