Media

Cropper

A crop rectangle over an image, with no dependency: lock a ratio, mask a circle, rotate and flip, and crop on a server or in the browser.

WAI-ARIA tested

Import

main.ts

import { Cropper } from '@vitral/vue';

Avatar

A circle locks the ratio to one and drops the handles: drag the crop, or zoom it. The preview beside it is the same picture under a smaller box, not a second render.

1<script setup lang="ts">2import { Button, Cropper, type CropValue, StackPanel } from '@vitral/vue';3import { ref, useTemplateRef } from 'vue';4 5const portrait = 'https://picsum.photos/id/1027/900/1200';6const avatar = ref<CropValue>({ x: 0, y: 0, width: 0, height: 0, rotate: 0, flipX: false, flipY: false });7 8// The file, when the file is what you want: a canvas, then a Blob to upload.9const cropper = useTemplateRef<InstanceType<typeof Cropper>>('avatarCropper');10const saved = ref<string | null>(null);11const savedSize = ref(0);12 13async function save() {14    const blob = await cropper.value?.toBlob('image/png', { width: 256 });15    if (!blob) return;16    if (saved.value) URL.revokeObjectURL(saved.value);17    saved.value = URL.createObjectURL(blob);18    savedSize.value = blob.size;19}20</script>21 22<template>23    <StackPanel spacing="1rem" style="flex: 1 1 100%; min-width: 0">24        <Cropper ref="avatarCropper" v-model="avatar" :src="portrait" shape="circle" alt="A portrait" height="18rem" :preview-size="96" />25        <StackPanel orientation="horizontal" spacing="0.625rem" align="center" wrap>26            <Button label="Crop to a 256px PNG" size="small" @click="save" />27            <small v-if="saved" style="color: var(--vt-text-muted-color)">{{ Math.round(savedSize / 1024) }} kB</small>28            <img v-if="saved" :src="saved" alt="The cropped avatar" width="48" height="48" style="border-radius: 50%" />29        </StackPanel>30    </StackPanel>31</template>

A ratio, with handles

Eight handles for the pointer, hidden from assistive technology: the rectangle itself is the one tab stop.

{ x: 0, y: 0, width: 0, height: 0, rotate: 0 }

1<script setup lang="ts">2import { Cropper, type CropValue } from '@vitral/vue';3import { ref } from 'vue';4 5const photo = 'https://picsum.photos/id/1015/1600/900';6const banner = ref<CropValue>({ x: 0, y: 0, width: 0, height: 0, rotate: 0, flipX: false, flipY: false });7 8const rounded = (value: CropValue) => `{ x: ${Math.round(value.x)}, y: ${Math.round(value.y)}, width: ${Math.round(value.width)}, height: ${Math.round(value.height)}, rotate: ${value.rotate} }`;9</script>10 11<template>12    <Cropper v-model="banner" :src="photo" aspect="16:9" alt="A landscape" height="18rem" />13    <small style="color: var(--vt-text-muted-color)">{{ rounded(banner) }}</small>14</template>

Without the thirds

The guide is on for a rectangle and off for a circle, where a rule of thirds means nothing. `grid` overrules either way.

1<script setup lang="ts">2import { Cropper, type CropValue } from '@vitral/vue';3import { ref } from 'vue';4 5const photo = 'https://picsum.photos/id/1015/1600/900';6const plain = ref<CropValue>({ x: 0, y: 0, width: 0, height: 0, rotate: 0, flipX: false, flipY: false });7</script>8 9<template>10    <Cropper v-model="plain" :src="photo" aspect="4:3" :grid="false" alt="A landscape" height="16rem" />11</template>

Free, with ratios and turns

A chooser locks the ratio; the quarter turns and the flips travel with the crop, so it keeps pointing at the same part of the picture.

const crop = ref<CropValue>({ x: 0, y: 0, width: 0, height: 0, rotate: 0 });

1<script setup lang="ts">2import { Cropper, type CropValue } from '@vitral/vue';3import { computed, ref } from 'vue';4 5const photo = 'https://picsum.photos/id/1015/1600/900';6const free = ref<CropValue>({ x: 0, y: 0, width: 0, height: 0, rotate: 0, flipX: false, flipY: false });7 8const aspects = [9    { label: 'Free', value: 'free' },10    { label: '1:1', value: '1:1' },11    { label: '4:3', value: '4:3' },12    { label: '16:9', value: '16:9' }13];14 15const model = computed(() => {16    const { x, y, width, height, rotate } = free.value;17    return `const crop = ref<CropValue>({ x: ${Math.round(x)}, y: ${Math.round(y)}, width: ${Math.round(width)}, height: ${Math.round(height)}, rotate: ${rotate} });`;18});19</script>20 21<template>22    <Cropper v-model="free" :src="photo" :aspects="aspects" rotatable alt="A landscape" height="20rem" />23    <code style="font-size: 0.75rem; color: var(--vt-text-muted-color)">{{ model }}</code>24</template>

In a dialog

Where a cropper usually lives: a photograph is chosen, cropped over the page, and the profile changes only once it is accepted. The dialog gives the stage its width, so the crop is measured against what it is actually shown at.

1<script setup lang="ts">2import { Avatar, Button, Cropper, Dialog, StackPanel, type CropValue } from '@vitral/vue';3import { ref, useTemplateRef } from 'vue';4 5// The whole flow, which is where a cropper usually lives: a picture is6// chosen, cropped in a dialog, and only then does the profile change.7const portrait = 'https://picsum.photos/id/1027/900/1200';8const dialog = ref(false);9const pending = ref<CropValue>({ x: 0, y: 0, width: 0, height: 0, rotate: 0, flipX: false, flipY: false });10const profile = ref<string | null>(null);11const modalCropper = useTemplateRef<InstanceType<typeof Cropper>>('modalCropper');12 13async function apply() {14    const blob = await modalCropper.value?.toBlob('image/png', { width: 192 });15    dialog.value = false;16    if (!blob) return;17    if (profile.value) URL.revokeObjectURL(profile.value);18    profile.value = URL.createObjectURL(blob);19}20</script>21 22<template>23    <StackPanel orientation="horizontal" spacing="0.625rem" align="center" wrap>24        <Avatar :image="profile ?? undefined" :label="profile ? undefined : 'AF'" shape="circle" size="large" :alt="profile ? 'Your photo' : undefined" />25        <Button :label="profile ? 'Change the photo' : 'Upload a photo'" severity="secondary" variant="outlined" size="small" @click="dialog = true" />26        <small v-if="profile" style="color: var(--vt-text-muted-color)">Cropped to a 192px PNG</small>27    </StackPanel>28 29    <Dialog v-model:visible="dialog" modal header="Crop your photo" :style="{ width: 'min(30rem, 92vw)' }">30        <Cropper ref="modalCropper" v-model="pending" :src="portrait" shape="circle" alt="The photograph being cropped" height="16rem" />31        <template #footer>32            <Button label="Cancel" severity="secondary" variant="text" @click="dialog = false" />33            <Button label="Use this photo" @click="apply" />34        </template>35    </Dialog>36</template>

The shape of it

1<script setup lang="ts">2import { Button, Cropper, type CropValue } from '@vitral/vue';3import { ref, useTemplateRef } from 'vue';4 5const src = 'https://picsum.photos/id/1027/900/1200';6const crop = ref<CropValue>({ x: 0, y: 0, width: 0, height: 0, rotate: 0, flipX: false, flipY: false });7const cropper = useTemplateRef<InstanceType<typeof Cropper>>('cropper');8 9// The file, when you want the file rather than the numbers.10async function upload() {11    const blob = await cropper.value?.toBlob('image/png', { width: 256 });12    if (blob) console.log(blob);13}14</script>15 16<template>17    <Cropper ref="cropper" v-model="crop" :src="src" shape="circle" :preview-size="96" alt="A portrait" />18    <Button label="Get the file" size="small" @click="upload" />19</template>

API

Read from packages/vue/src/components/Cropper/types.ts, so it says what the component actually accepts.

Props

Name	Type	Description
src	string	The image. Anything an `<img>` takes; a data or object URL included.
alt	string	Describes the picture, not the control. Without one the image is decorative.
aspect	number \| string \| null	Lock the crop to a ratio: `1`, `'16:9'`, or null to leave it free.
aspects	readonly CropAspect[]	Ratios to offer in the toolbar. Omit it and no chooser is drawn.
shape	'rect' \| 'circle'	`'circle'` masks the crop and the preview, and locks the ratio to 1.
handles	boolean	Draw the eight resize handles. Defaults to true for a rectangle, false for a circle.
rotatable	boolean	Offer the quarter turns and the flips.
zoomable	boolean	Offer a zoom slider.
grid	boolean	Draw the thirds over the crop while it is being moved. On by default for a rectangle and off for a circle, where a rule of thirds means nothing: the guide is for composing a frame, and a round crop has no corners to compose towards.
minWidth	number	The smallest crop, in the image's own pixels.
minHeight	number	—
height	number \| string	The stage's height: a number is pixels.
previewSize	number	The live preview's size, in pixels. Zero draws none.
disabled	boolean	—

Plus pt, dt and unstyled from BaseProps, see pass-through and unstyled mode.

Emits

Event	Payload	Description
update:modelValue	value: CropValue	The crop, as it changes.
load	event: { width: number; height: number }	The image has loaded and its natural size is known.
change	value: CropValue	A drag of the crop or a handle has finished.

Slots

Name	Slot props	Description
toolbar	(props: { value: CropValue; reset: () => void })	Replaces the toolbar.
preview	(props: { value: CropValue })	Beside the preview, or in place of it.

Cropper

Import

API

Props

Emits

Slots

Related components