CropperSelection

The CropperSelection interface provides properties and methods for manipulating the layout and presentation of <cropper-selection> elements.

Examples

Basic

TIP

The default width and height of this element is 0.

Customize Initial Selection Coverage

Customize Position and Size

With Handles

Dynamic

Set the dynamic property to true to change as the image changes.

Multiple

Set the multiple property to true to support multiple selections on the same image.

Resize Around Center

Set resizeAroundCenter property to true to keep the selection centered while resizing.

Zoom Around Center

Set zoomAroundCenter property to true to zoom from the center of the selection instead of the pointer.

Fixed Selection

Keep the selection fixed while moving or scaling the image underneath it. Drag the image to reposition it, or use the mouse wheel to scale it.

Border Radius

Set the border-radius attribute to round the selection. It supports the CSS border-radius syntax and is also applied to the canvas generated by $toCanvas().

Limit Boundaries

Details

vue

<template>
  <div class="cropper-container">
    <form>
      <fieldset>
        <legend>Within:</legend>
        <input
          id="withinCanvas"
          v-model="within"
          type="radio"
          name="within"
          value="canvas"
        >
        <label for="withinCanvas">canvas</label>
        <input
          id="withinImage"
          v-model="within"
          type="radio"
          name="within"
          value="image"
        >
        <label for="withinImage">image</label>
        <input
          id="withinNone"
          v-model="within"
          type="radio"
          name="within"
          value="none"
        >
        <label for="withinNone">none</label>
      </fieldset>
    </form>
    <cropper-canvas
      ref="cropperCanvas"
      :key="within"
      background
    >
      <cropper-image
        ref="cropperImage"
        :src="src"
        alt="Picture"
        :rotatable="within !== 'image'"
        :scalable="within !== 'image'"
        :skewable="within !== 'image'"
        :translatable="within !== 'image'"
      />
      <cropper-handle
        action="move"
        plain
      />
      <cropper-selection
        initial-coverage="0.5"
        :min-inset="minInset"
        movable
        resizable
        outlined
      >
        <cropper-grid
          role="grid"
          covered
        />
        <cropper-crosshair centered />
        <cropper-handle
          action="move"
          theme-color="rgba(255, 255, 255, 0.35)"
        />
        <cropper-handle action="n-resize" />
        <cropper-handle action="e-resize" />
        <cropper-handle action="s-resize" />
        <cropper-handle action="w-resize" />
        <cropper-handle action="ne-resize" />
        <cropper-handle action="nw-resize" />
        <cropper-handle action="se-resize" />
        <cropper-handle action="sw-resize" />
      </cropper-selection>
    </cropper-canvas>
  </div>
</template>

<script lang="ts">
import type CropperCanvas from '@cropper/element-canvas';
import type CropperImage from '@cropper/element-image';

const { BASE_URL } = import.meta.env;

export default {
  name: 'CropperSelectionExample',
  data() {
    return {
      src: `${BASE_URL}picture.jpg`,
      within: 'canvas',
      minInset: '0',
    };
  },
  watch: {
    within: 'updateMinInset',
  },
  methods: {
    async updateMinInset() {
      const { within } = this;

      this.minInset = within === 'canvas' ? '0' : 'auto';

      if (within !== 'image') {
        return;
      }

      // Waits for the canvas to be re-created by the `key` change.
      await this.$nextTick();

      const cropperCanvas = this.$refs.cropperCanvas as CropperCanvas;
      const cropperImage = this.$refs.cropperImage as CropperImage;

      await cropperImage.$ready();

      if (this.within !== within) {
        return;
      }

      const canvasRect = cropperCanvas.getBoundingClientRect();
      const imageRect = cropperImage.getBoundingClientRect();

      this.minInset = [
        imageRect.top - canvasRect.top,
        canvasRect.right - imageRect.right,
        canvasRect.bottom - imageRect.bottom,
        imageRect.left - canvasRect.left,
      ].map((value) => `${value}px`).join(' ');
    },
  },
};
</script>

<style lang="scss" scoped>
.cropper-container {
  border: 1px solid var(--vp-c-divider);
  border-radius: 0.375rem;
  margin-bottom: 1rem;
  margin-top: 1rem;
  padding: 1.25rem 1.5rem;

  fieldset {
    border: 1px solid var(--vp-c-divider);
    border-radius: 0.375rem;
    margin-bottom: 1rem;
    padding: 0.25rem 0.75rem 0.75rem 0.75rem;

    > input {
      margin: 0 0.25rem 0 0;
      transform: translateY(-0.5px);
      vertical-align: middle;
    }

    > label {
      margin-right: 0.5rem;
    }
  }

  cropper-canvas {
    height: 320px;
  }
}
</style>

Properties

Inherits properties from its parent, CropperElement, and implements the following properties:

Name	Type	Default	Options	Description
x	`number`	`0`	-	Indicates the x-axis coordinate of the selection.
y	`number`	`0`	-	Indicates the y-axis coordinate of the selection.
width	`number`	`0`	-	Indicates the width of the selection.
height	`number`	`0`	-	Indicates the height of the selection.
aspectRatio	`number`	`NaN`	-	Indicates the aspect ratio of the selection, must a positive number.
initialAspectRatio	`number`	`NaN`	-	Indicates the initial aspect ratio of the selection, must a positive number.
borderRadius ^2.3.0	`string`	`''`	-	Defines the border radius of the selection and the exported canvas. Supports the CSS `border-radius` syntax (e.g. `10px`, `25%`, `10% 20% 30% 40%`, `10% 20% / 30% 40%`). Pixel values are scaled proportionally when the output canvas size changes.
initialCoverage	`number`	`NaN`	-	Indicates the initial coverage of the selection, must a positive number between `0` (0%) and `1` (100%).
dynamic	`boolean`	`false`	-	Indicates whether this selection is dynamic and changes as the image changes.
movable	`boolean`	`false`	-	Indicates whether this element is movable.
maxInset ^2.3.0	`string`	`"auto"`	`"auto"`, or 1 to 4 values of `<length>` / `<percentage>` / `calc()`, like the CSS `inset` property	Indicates the max distances from the selection edges to the matching edges of its parent element, in the order of top, right, bottom, and left. `auto` means unlimited. A change that breaks the limits is rejected.
minInset ^2.3.0	`string`	`"auto"`	Same as `maxInset`	Indicates the min distances from the selection edges to the matching edges of its parent element, in the order of top, right, bottom, and left. `auto` means unlimited. A change that breaks the limits is rejected.
resizable	`boolean`	`false`	-	Indicates whether this element is resizable.
resizeAroundCenter ^2.3.0	`boolean`	`false`	-	Indicates whether to keep the selection centered when resizing.
zoomable	`boolean`	`false`	-	Indicates whether this element is zoomable.
zoomAroundCenter ^2.3.0	`boolean`	`false`	-	Indicates whether to use the selection center as the zoom origin.
multiple	`boolean`	`false`	-	Indicates whether multiple selections is supported.
keyboard	`boolean`	`false`	-	Indicates whether keyboard control is supported.
outlined	`boolean`	`false`	-	Indicates whether show the outlined or not.
precise	`boolean`	`false`	-	Indicates whether reserve the precise of the `x`, `y`, `width`, and `height` properties or not.

The supported keyboard keys:

Delete or Command + Backspace: Removes the active selection.
ArrowLeft: Moves the active selection to the left by 1 pixel.
ArrowRight: Moves the active selection to the right by 1 pixel.
ArrowUp: Moves the active selection to the top by 1 pixel.
ArrowDown: Moves the active selection to the bottom by 1 pixel.
+: Zooms in the active selection by 10%.
-: Zooms out the active selection by 10%.

Methods

$center

Syntax: $center()
Returns:
- Type: CropperSelection
- The element instance for chaining.

Aligns the selection to the center of its parent element.

$move

Syntax:
- $move(x)
- $move(x, y)
Alternatives:
- $moveTo(selection.x + x)
- $moveTo(selection.x + x, selection.y + y)
Arguments:
- x:
  - Type: number
  - The moving distance in the horizontal direction.
- y:
  - Type: number
  - Default: x
  - The moving distance in the vertical direction.
Returns:
- Type: CropperSelection
- The element instance for chaining.

Moves the selection.

$moveTo

Syntax:
- $moveTo(x)
- $moveTo(x, y)
Arguments:
- x:
  - Type: number
  - The new position in the horizontal direction.
- y:
  - Type: number
  - Default: x
  - The new position in the vertical direction.
Returns:
- Type: CropperSelection
- The element instance for chaining.

Moves the selection to a specific position.

$resize

Syntax:
- $resize(action)
- $resize(action, offsetX)
- $resize(action, offsetX, offsetY)
- $resize(action, offsetX, offsetY, aspectRatio)
Arguments:
- action:
  - Type: string
  - Options: "n-resize", "e-resize", "s-resize", "w-resize", "ne-resize", "nw-resize", "se-resize", and "sw-resize".
  - Indicates the side or corner to resize.
- offsetX:
  - Type: number
  - Default: 0
  - The horizontal offset of the specific side or corner.
- offsetY:
  - Type: number
  - Default: 0
  - The vertical offset of the specific side or corner.
- aspectRatio:
  - Type: number
  - Default: this.aspectRatio
  - The aspect ratio for computing the new size if it is necessary.
Returns:
- Type: CropperSelection
- The element instance for chaining.

Adjusts the size of the selection on a specific side or corner.

$zoom

Syntax:
- $zoom(scale)
- $zoom(scale, x, y)
Arguments:
- scale:
  - Type: number
  - The zoom factor. Positive numbers for zooming in, and negative numbers for zooming out.
- x:
  - Type: number
  - Default: The center of the selection in the horizontal.
  - The zoom origin in the horizontal.
- y:
  - Type: number
  - Default: The center of the selection in the vertical.
  - The zoom origin in the vertical.
Returns:
- Type: CropperSelection
- The element instance for chaining.

Example:

cropperSelection.$zoom(0.1); // Zoom in 10%
cropperSelection.$zoom(-0.1); // Zoom out 10%

Zooms the selection. Changes the width and height of the selection in pixels directly at the same time.

$change

Syntax:
- $change(x, y)
- $change(x, y, width, height)
- $change(x, y, width, height, aspectRatio)
Arguments:
- x:
  - Type: number
  - The new position in the horizontal direction.
- y:
  - Type: number
  - The new position in the vertical direction.
- width:
  - Type: number
  - Default: this.width
  - The new width.
- height:
  - Type: number
  - Default: this.height
  - The new height.
- aspectRatio:
  - Type: number
  - Default: this.aspectRatio
  - The new aspect ratio for this change only.
Returns:
- Type: CropperSelection
- The element instance for chaining.

Changes the position and/or size of the selection.

$reset

Syntax: $reset()
Returns:
- Type: CropperSelection
- The element instance for chaining.

Resets the selection to its initial position and size.

$clear

Syntax: $clear()
Returns:
- Type: CropperSelection
- The element instance for chaining.

Clears the selection.

$render

Syntax: $render()
Returns:
- Type: CropperSelection
- The element instance for chaining.

Refreshes the position or size of the selection.

$toCanvas

Syntax:
- $toCanvas()
- $toCanvas(options)
Arguments:
- options:
  - Type: Object
  - The available options.
  - Properties:
    - width:
      - Type: number
      - The width of the canvas.
    - height:
      - Type: number
      - The height of the canvas.
    - beforeDraw:
      - Type: Function
      - The function called before drawing the image onto the canvas.
      - Syntax: beforeDraw(context, canvas)
      - Arguments:
        context:
        Type: CanvasRenderingContext2D
        The 2D rendering context of the canvas.
        canvas:
        Type: HTMLCanvasElement
        The canvas element itself.
      - Example: function (context) { context.filter = 'grayscale(100%)'; }
Returns:
- Type: Promise
- A promise that resolves to the generated canvas element.
Example:

Generates a real canvas element, with the image (selected area only) drawn into if there is one.

Events

change

The event is fired when the position or size of the selection is going to change.

Event:
- event.bubbles: true
- event.cancelable: true
- event.composed: true
- event.detail:
  - Type: Object
  - The position and size data of the selection.
- event.detail.x:
  - Type: number
  - The x-axis coordinate of the selection.
- event.detail.y:
  - Type: number
  - The y-axis coordinate of the selection.
- event.detail.width:
  - Type: number
  - The width of the selection.
- event.detail.height:
  - Type: number
  - The height of the selection.
Example:

html

<cropper-selection id="selection"></cropper-selection>

<script>
document.querySelector('#selection').addEventListener('change', function (event) {
  console.log(event);
});
</script>

Slots

There is only one default slot in this element.

You can disable it by setting the slottable property to false:
html
<cropper-selection slottable="false"></cropper-selection>

CropperSelection ​

Examples ​

Basic ​

Customize Initial Selection Coverage ​

Customize Position and Size ​

With Handles ​

Dynamic ​

Multiple ​

Resize Around Center ​

Zoom Around Center ​

Fixed Selection ​

Border Radius ​

Limit Boundaries ​

Properties ​

Methods ​

$center ​

$move ​

$moveTo ​

$resize ​

$zoom ​

$change ​

$reset ​

$clear ​

$render ​

$toCanvas ​

Events ​

change ​

Slots ​