Customization

Vue Croppa v1 exposes two different kinds of customization:

1. Canvas-affecting props change the generated image.
2. CSS changes only the component's presentation in the page.

Keeping those separate avoids a common surprise: changing the component background with CSS does not change exported pixels.

Appearance playground

Appearance and behaviorChange placeholder text/colors, canvas color, remove control, and disabled state.

Open demo ↗

Canvas color

canvas-color is painted into the canvas, so it affects exported output.

<croppa
  v-model="croppa"
  canvas-color="#ffffff"
></croppa>

For transparent output, keep canvas-color="transparent" and use CSS for the visual background.

Placeholder

<croppa
  v-model="croppa"
  placeholder="Drop a profile photo"
  placeholder-color="#0f766e"
  :placeholder-font-size="16"
></croppa>

An image can also be used as the placeholder:

Image placeholderA first-party slot demo that renders the local logo into the empty canvas.

Open demo ↗

Initial image layout

initial-size behaves similarly to CSS background sizing:

• cover fills the crop viewport.
• contain keeps the whole image visible.
• natural starts at the source image's natural size.

prevent-white-space forces cover-like behavior because the viewport may not expose empty canvas.

initial-position accepts center, edges such as top left, or percentage values such as 30% 40%.

Responsive / auto sizing

v1 can size itself from the rendered component instead of the numeric width/height props.

Responsive auto-sizingResize the first-party container and inspect the real component dimensions.

Open demo ↗

<croppa
  v-model="croppa"
  auto-sizing
  class="responsive-croppa"
></croppa>

In v1, auto-sizing reacts to the window resize event. v2 uses ResizeObserver; its quality prop scales the backing canvas and export pixels.

Zoom behavior

zoom-speed controls wheel sensitivity and reverse-scroll-to-zoom reverses the wheel direction.

For a custom control surface, you can drive the exposed v1 scale state directly:

Zoom sliderA local range control drives the same v1 scale used by wheel and pinch zoom.

Open demo ↗

Directly mutating internal state is a v1 escape hatch. Prefer documented methods for ordinary application code.

Disable built-in interactions

Use disabled to disable everything, or disable specific behaviors:

<croppa
  v-model="croppa"
  :disable-click-to-choose="true"
  :disable-drag-and-drop="true"
  :disable-drag-to-move="true"
  :disable-scroll-to-zoom="true"
  :disable-pinch-to-zoom="true"
  :disable-rotation="true"
></croppa>

This is useful when your own toolbar should be the only way to manipulate the crop.

Custom loading

The built-in spinner is optional. For a fully custom loading state, listen to the lifecycle events.

Custom loading overlayThe UI is driven by loading-start and loading-end while Croppa handles the real file.

Open demo ↗

Canvas attachments

The draw event runs after Croppa draws the image. Use it for watermarks, stickers, guides, or other output-visible canvas additions.

Watermark / attachmentA local logo is drawn into the real crop canvas and included in export.

Open demo ↗

Custom clipping

For rounded rectangles, image-border-radius is the simplest API. For arbitrary paths, use addClipPlugin().

Circle clip pluginThe test suite verifies the top-left output pixel is actually transparent.

Open demo ↗