Vue Avatar cropper component

This is Vue Avatar cropper component to crop Avatar before going to upload

Follow these steps to use vue Avatar cropper component

Basic usage

<button @click="() => { trigger = true }">Pick avatar</button>




  • Include the link to AvatarCropper in <head> alongside Vue.js, Cropper.js and Mime:
<link rel="stylesheet" href="">
<script src=""></script>
<script src=""></script>
<script src=""></script>
<script src=""></script>
  • AvatarCropper will auto-install upon detecting the global Vue instance. You can use it right away

Node environment

  • Install the AvatarCropper package:
npm install vue-avatar-cropper
# or
yarn add vue-avatar-cropper
  • Register it as you usually would:
import AvatarCropper from 'vue-avatar-cropper'

// or
const AvatarCropper = require('vue-avatar-cropper');

Vue.component('AvatarCropper', AvatarCropper);

// or

// or
new Vue({
    components: { AvatarCropper },
    // ...


Property NameTypeDescription
triggerBooleanSet to true to trigger the avatar cropper, this prop is used for v-model. Default: false
fileFileFile to use instead of prompting the user to upload one
upload-urlStringURL to upload the file to
upload-file-fieldStringFormData field to use for the file. Default: 'file'
upload-file-nameString/FunctionFile name to use for the FormData field. Can be String or Function({ filename, mime, extension }) => String. Default: Automatically determined from the uploaded File‘s name property and the extension of the output MIME.
upload-form-dataFormDataAdditional FormData. Default: new FormData()
upload-handlerFunctionHandler to replace default upload handler, the argument is cropperJS instance.
request-optionsObjectOptions passed to the init parameter of the Request() constructor. Use this to set the method, headers, etc. Default: { method: 'POST' }
cropper-optionsObjectOptions passed to the cropperJS instance.
Default: {
    aspectRatio: 1,
    autoCropArea: 1,
    viewMode: 1,
    movable: false,
    zoomable: false
output-optionsObjectOptions passed to the cropper.getCroppedCanvas() method.
Default: {}. Recommended use-case is specifying an output size, for instance: { width: 512, height: 512 }
output-mimeStringThe resulting avatar image MIME type, if invalid image/png will be used. Default: null
output-qualityNumberThe resulting avatar image quality [0 – 1]. Default: 0.9
(if the output-mime property is 'image/jpeg' or 'image/webp')
mimesStringAllowed image formats. Default:
'image/png, image/gif, image/jpeg, image/bmp, image/x-icon'
captureStringCapture attribute for the file input. Forces mobile users to take a new picture with the back(Use value 'environment') or front(Use value 'user') camera
labelsObjectLabel for buttons. Default: { submit: 'Ok', cancel: 'Cancel' }
inlineBooleanIf true component will be displayed as inline elemenet. Default: false


  • triggered trigger prop changed, used for v-model, parameter:
    • value boolean.
  • changed user picked a file, parameter is an object containing:
  • submit right after a click on the submit button
  • cancel when user decides to cancel the upload
  • uploading before submit upload request, parameter is an object containing:
  • uploaded after request is successful, parameter is an object containing:
  • completed after request has completed, parameter is an object containing:
  • error something went wrong, parameter is an object containing:
    • message error message.
    • type error type, example: 'load'/'upload'/'user'.
    • context context data.

You can listen for these events like this:

export default {
  methods: {
    handleUploading({ form, request, response }) {
      // show a loader

    handleUploaded({ form, request, response }) {
      // update user avatar attribute

    handleCompleted({ form, request, response }) {
      // close the loader

    handleError({ message, type, context}) {
      if (type === 'upload') {
        const { request, response } = context

Leave a Comment