@thm-health/vue-profile-image-cropper

Vue 3 Profile Image Cropper

Minimal unstyled, accessible profile-image cropper for Vue.js 3 with zero-runtime dependencies and small in size (< 12kB).

Install

npm install @thm-health/vue-profile-image-cropper

Peer dependency: vue@^3.4.

import { ProfileImageCropper, type CropResult } from '@thm-health/vue-profile-image-cropper';

Usage

Mount only when a File is available. Own zoom bounds and controls in the parent. Use v-model:zoom with optional minZoom / maxZoom / zoomStep for wheel and +/− zoom. The classes in this example are Tailwind CSS.

<script setup lang="ts">
import { ref } from 'vue';
import { ProfileImageCropper, type CropResult } from '@thm-health/vue-profile-image-cropper';

const MIN_ZOOM = 1;
const MAX_ZOOM = 3;
const cropperRef = ref<InstanceType<typeof ProfileImageCropper> | null>(null);
const selectedImage = ref<File | null>(null);
const zoom = ref(MIN_ZOOM);

function onFileChange(event: Event) {
  const input = event.target as HTMLInputElement;
  selectedImage.value = input.files?.[0] ?? null;
  zoom.value = MIN_ZOOM;
  input.value = '';
}

async function onCropClick() {
  const result = await cropperRef.value?.cropImage();
  if (result) {
    // result.blob
  }
}

function onLoading(loading: boolean) {
  // disable controls while loading
}
</script>

<template>
  <input type="file" accept="image/*" @change="onFileChange" />

  <ProfileImageCropper
    v-if="selectedImage"
    ref="cropperRef"
    v-model:zoom="zoom"
    :min-zoom="MIN_ZOOM"
    :max-zoom="MAX_ZOOM"
    :image="selectedImage"
    aria-label="Image crop area. Drag to reposition, scroll or press +/− to zoom, arrow keys to move the image."
    class="h-[200px] w-full max-h-[200px] max-w-md rounded-xl border bg-slate-100"
    mask-class="rounded-full shadow-[0_0_0_9999px_rgb(17_24_39_/_0.55)]"
    ring-class="rounded-full border-2 border-white"
    @loading="onLoading"
  />

  <input
    type="range"
    :min="MIN_ZOOM"
    :max="MAX_ZOOM"
    step="0.1"
    v-model.number="zoom"
    :disabled="!selectedImage"
  />

  <button type="button" :disabled="!selectedImage" @click="onCropClick">Crop</button>
</template>

Props

Events

Exposed methods

Styling

The cropper has no size of its own. Set a height and width with class, or it is not visible. mask-class dims the area outside the crop square, and ring-class draws its edge. Without those classes, the crop area is visually unrecognizable.

Example

<ProfileImageCropper
  class="profile-image-cropper"
  mask-class="profile-image-cropper__mask"
  ring-class="profile-image-cropper__ring"
/>
<style>
  .profile-image-cropper {
    height: 200px;
    width: 100%;
    max-height: 200px;
    border: 1px solid;
  }

  .profile-image-cropper__mask {
    box-shadow: 0 0 0 9999px rgb(0 0 0 / 0.55);
  }

  .profile-image-cropper__ring {
    border: 2px solid white;
  }
</style>

Example with Tailwind CSS

<ProfileImageCropper
  class="h-[200px] w-full max-h-[200px] border"
  mask-class="shadow-[0_0_0_9999px_rgb(0_0_0_/_0.55)]"
  ring-class="border-2 border-white"
/>

Circle

cropImage() always exports a square image. To show the crop square as a circle, set border-radius: 50% on the mask and ring (Tailwind: rounded-full). That CSS changes only the overlay.

<ProfileImageCropper
  class="h-[200px] w-full max-h-[200px] border"
  mask-class="rounded-full shadow-[0_0_0_9999px_rgb(0_0_0_/_0.55)]"
  ring-class="rounded-full border-2 border-white"
/>

Accessibility

The viewport has role="application" and is in the tab order unless disabled is true. With focus on the viewport, + and − change zoom by zoomStep, and the arrow keys moves the image under that square by keyboardStep pixels.

Set aria-label so screen reader users know how to control the cropper.

<ProfileImageCropper
  aria-label="Image crop area. Drag to reposition, scroll or press +/− to zoom, arrow keys to move the image."
/>

You can also announce the crop position and zoom in a live region. position is a CropSquarePosition: x and y are 0–100, or null when that axis cannot move.

<script setup lang="ts">
import { computed, ref } from 'vue';
import { type CropSquarePosition } from '@thm-health/vue-profile-image-cropper';

const zoom = ref(1);
const position = ref<CropSquarePosition>({ x: null, y: null });

const ariaPosition = computed(() => {
  const zoomText = `Zoom ${Math.round(zoom.value * 100)} percent.`;
  if (position.value.x === null && position.value.y === null) {
    return `Crop fills the image. ${zoomText} Zoom in to reposition.`;
  }
  const x =
    position.value.x != null
      ? `Horizontal position ${Math.round(position.value.x)} percent.`
      : 'Horizontal position fixed.';
  const y =
    position.value.y != null
      ? `Vertical position ${Math.round(position.value.y)} percent.`
      : 'Vertical position fixed.';
  return `${x} ${y} ${zoomText}`;
});
</script>

<template>
  <ProfileImageCropper v-model:zoom="zoom" @position="position = $event" />
  <span aria-live="polite" aria-atomic="true" class="sr-only">{{ ariaPosition }}</span>
</template>

Development

pnpm install
pnpm dev         # demo app
pnpm build       # library bundle + types → dist/
pnpm build:demo  # demo production build
pnpm lint
pnpm format
pnpm test        # Vitest unit tests
pnpm test:e2e    # Cypress against the demo (upload, zoom, pan, crop, debug)
pnpm check       # typecheck + lint + format + unit + lib build

License

MIT