vue-croppa

library1.3.8jsnpmunverified

Vue-croppa is a straightforward, highly customizable, and mobile-friendly image cropping component specifically designed for Vue 2.0 applications. It enables users to select an image, move, zoom, and crop it directly within the browser, supporting touch gestures for mobile devices and handling EXIF orientation. The current stable version is 1.3.8. While the package has seen consistent bug fixes and minor feature additions (like `auto-sizing` and `passive` mode) in its 1.x series, its focus on Vue 2.0 suggests a maintenance cadence rather than active feature development for newer Vue versions. Its key differentiators include simplicity of use, extensive customization options via props, and built-in mobile support for common cropping interactions.

web-framework

npm install vue-croppa

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VUE-CROPPA

vue-croppa

web-frameworkjavascriptv1.3.8

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Croppa

✓ import Croppa from 'vue-croppa';

✗ import { Croppa } from 'vue-croppa';

Croppa is a default export, used for installing the plugin and accessing the component object.

Croppa styles

✓ import 'vue-croppa/dist/vue-croppa.css';

The CSS must be imported separately for styling the cropper component.

Vue.use(Croppa)

✓ Vue.use(Croppa);

Registers the cropper component globally. By default, it registers as `<croppa>`. You can customize the component name via `Vue.use(Croppa, { componentName: 'my-cropper' })`.

This quickstart initializes a Vue application with the croppa component. It demonstrates how to integrate the component, bind it with `v-model`, and programmatically access its API to generate and upload a cropped image as a Blob.

import Vue from 'vue'; import Croppa from 'vue-croppa'; import 'vue-croppa/dist/vue-croppa.css'; Vue.use(Croppa); new Vue({ el: '#app', template: ` <div> <croppa v-model="myCroppa" :width="400" :height="400" :placeholder="'Drag & Drop or Click to Choose'" :quality="2"></croppa> <button @click="uploadCroppedImage">Upload Cropped Image</button> </div> `, data: { myCroppa: {} }, methods: { uploadCroppedImage() { if (!this.myCroppa.hasImage()) { alert('Please choose an image first!'); return; } this.myCroppa.generateBlob( blob => { // In a real application, you'd upload this blob to a server. // For demonstration, we'll just log its size and type. console.log('Generated Blob:', blob); console.log(`Type: ${blob.type}, Size: ${blob.size} bytes`); // Example: const formData = new FormData(); // formData.append('image', blob, 'cropped-image.jpeg'); // fetch('/upload', { method: 'POST', body: formData }); alert('Image blob generated and logged to console!'); }, 'image/jpeg', 0.8 ); // 80% compressed jpeg file } } });

Debug

Known issues

breakingThe `v-model` behavior for the cropper component has undergone changes. Prior to v1.0.0, the `v-model` prop might have behaved differently or had different expectations regarding the component's internal state binding.

fix

Ensure `v-model` is correctly bound to an empty object, e.g., `data: { myCroppa: {} }`, to correctly access the component's API methods.

affects: <1.0.0

gotchaThe `replace-drop` prop, which controls whether dropping a new image replaces the current one without explicit removal, defaults to `false` for backward compatibility. This might lead to unexpected behavior for users expecting the new image to automatically replace the old one.

fix

To enable automatic replacement on drag and drop, explicitly set `:replace-drop="true"` on the `<croppa>` component.

affects: <1.1.4

gotchaWhen using `Vue.use(Croppa)`, the component is globally registered under the name `<croppa>`. If this name conflicts with existing components or you prefer a custom name, you need to specify it during plugin installation.

fix

Use `Vue.use(Croppa, { componentName: 'my-custom-cropper' });` to register the component with a different name.

affects: >=0.1.0

gotchaThe `width` and `height` props are ignored if `auto-sizing` is set to `true`. In this mode, the cropper will adjust to its container's size, which can be useful for responsive layouts but might override explicit dimensions.

fix

If you need fixed dimensions, ensure `auto-sizing` is `false` (its default). For responsive behavior, set `:auto-sizing="true"` and manage the container's dimensions via CSS.

affects: >=1.3.0

gotchaThe component is primarily designed for Vue 2.0. While it might work in a compatibility layer for Vue 3, official support for Vue 3 or Composition API is not explicitly stated, potentially leading to integration issues.

fix

Consider using alternative image cropper libraries that are explicitly built for Vue 3 if you are working on a Vue 3 project.

affects: All versions

Errors

Common errors & fixes

ReferenceError: window is not defined

The package attempts to access the `window` object during server-side rendering (SSR), which is only available in a browser environment.

fix

Implement SSR-specific checks or dynamically import the component only on the client-side. For Nuxt.js, use `<client-only><croppa ...></client-only>` or register the component as a client-side plugin.

TypeError: Cannot read properties of undefined (reading 'hasImage')

This usually occurs when the `v-model` bound `croppa` object has not been properly initialized or the component hasn't rendered yet, meaning the API methods are not available.

fix

Ensure `myCroppa: {}` is defined in your component's `data` property, and any calls to `myCroppa` methods are made after the component is mounted or after an image has been loaded (e.g., in a method triggered by user interaction).

Error: Component name "croppa" has already been registered.

Attempting to call `Vue.use(Croppa)` or `Vue.component('croppa', Croppa.component)` multiple times or in different modules within the same Vue instance.

fix

Ensure `Vue.use(Croppa)` is called only once, typically in your main `main.js` or `app.js` file. If using multiple Vue apps, register it separately for each, or customize the component name to avoid clashes.

Upgrade

Version history

1.3.8latest on npm

Audit

Dependencies

vuerequiredRuntime peer dependency for Vue 2.0 applications.

Agent activity

12 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/zhanziyang/vue-croppa ↗

packagehttps://www.npmjs.com/package/vue-croppa ↗

homepagehttps://zhanziyang.github.io/vue-croppa/ ↗