# CropperImage The `CropperImage` interface provides properties and methods for manipulating the layout and presentation of `` elements. ## Examples ### Basic :::live-demo ```html ``` ::: :::tip The default width and height of this element is `0`. ::: ### With Image Source :::live-demo ```html ``` ::: ### Zoom Around Center Set `zoomAroundCenter` to `true` to zoom from the center of the image instead of the pointer. :::live-demo ```html ``` ::: ### Set Initial Fit ::: details <<< @/.vitepress/components/CropperImageInitialFitExample.vue ::: ### Set Max Fit and/or Min Fit ::: details <<< @/.vitepress/components/CropperImageMaxFitAndMinFitExample.vue ::: ### Set Max Inset and/or Min Inset The insets are the distances from the image edges to the matching canvas edges (top, right, bottom, and left). Negative distances mean the image extends beyond the canvas. A transform that breaks the limits is rejected. ::: details <<< @/.vitepress/components/CropperImageMaxInsetAndMinInsetExample.vue ::: ### Limit Boundaries ::: details <<< @/.vitepress/components/CropperImageExample.vue ::: ## Properties Inherits properties from its parent, [`CropperElement`](cropper-element.html), and implements the following properties: | Name | Type | Default | Options | Description | | --- | --- | --- | --- | --- | | initialFit | `string` | `"contain"` | `"cover"` \| `"fill"` \| `"contain"` \| `"scale-down"` \| `"none"` | Indicates the initial size of the image when aligned with the center of its parent element. | | maxFit | `string` | `""` | `"cover"` \| `"fill"` \| `"contain"` \| `"scale-down"` \| `"none"` | Indicates the max size of this element relative to its parent element. | | minFit | `string` | `""` | `"cover"` \| `"fill"` \| `"contain"` \| `"scale-down"` \| `"none"` | Indicates the min size of this element relative to its parent element. | | maxInset | `string` | `"auto"` | `"auto"`, or 1 to 4 values of [``](https://developer.mozilla.org/en-US/docs/Web/CSS/length) / [``](https://developer.mozilla.org/en-US/docs/Web/CSS/percentage) / [`calc()`](https://developer.mozilla.org/en-US/docs/Web/CSS/calc), like the CSS [`inset`](https://developer.mozilla.org/en-US/docs/Web/CSS/inset) property | Indicates the max distances from the image edges to the matching edges of its parent element, in the order of top, right, bottom, and left. `auto` means unlimited. | | minInset | `string` | `"auto"` | Same as `maxInset` | Indicates the min distances from the image edges to the matching edges of its parent element, in the order of top, right, bottom, and left. `auto` means unlimited. | | rotatable | `boolean` | `false` | - | Indicates whether this element is rotatable. | | scalable | `boolean` | `false` | - | Indicates whether this element is scalable. | | skewable | `boolean` | `false` | - | Indicates whether this element is skewable. | | slottable | `boolean` | `false` | - | Indicates whether this element is slottable. | | translatable | `boolean` | `false` | - | Indicates whether this element is translatable. | | zoomAroundCenter | `boolean` | `false` | - | Indicates whether to use the image center as the zoom origin. | | initialCenterSize | `string` | `"contain"` | `"contain"`, `"cover"` | Indicates the initial size of this element when aligned with the center of its parent element. | The built-in `` element will inherit the following attributes by default: - `alt` - `crossorigin` - `decoding` - `elementtiming` - `fetchpriority` - `loading` - `referrerpolicy` - `sizes` - `src` - `srcset` ## Methods ### $ready - **Syntax**: - `$ready()` - `$ready(callback)` - **Arguments**: - `callback`: - Type: `Function` - The callback to execute after successfully loading the image. - **Returns**: - Type: `Promise` - A promise that resolves to the image element. - **Example**: ```js const cropperImage = new CropperImage(); cropperImage.$ready((image) => { console.log(image.naturalWidth, image.naturalHeight); }); cropperImage.src = '/cropperjs/picture.jpg'; ``` Defers the callback to execute after successfully loading the image. ### $center - **Syntax**: - `$center()` - `$center(size)` - **Arguments**: - `size`: - Type: `string` - Options: `"cover"`, `"fill"`, `"contain"`, `"scale-down"`, and `"none"`. - The size of the image. - **Returns**: - Type: `CropperImage` - The element instance for chaining. Aligns the image to the center of its parent element. ### $move - **Syntax**: - `$move(x)` - `$move(x, 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: `CropperImage` - The element instance for chaining. Moves the image. ### $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: `CropperImage` - The element instance for chaining. Moves the image to a specific position. ### $rotate - **Syntax**: `$rotate(angle)` - **Arguments**: - `angle`: - Type: `number | string` - The rotation angle (in radians). The default unit is `rad`. - `x`: - Type: `number` - Default: The center of the image in the horizontal. - The rotation origin in the horizontal. - `y`: - Type: `number` - Default: The center of the image in the vertical. - The rotation origin in the vertical. - **Returns**: - Type: `CropperImage` - The element instance for chaining. - **Examples**: - `$rotate(0.8)` - `$rotate('0.8rad')` - `$rotate('45deg')` - `$rotate('50grad')` - `$rotate('0.1turn')` - `$rotate('90deg', 0, 0)` Rotates the image. It is similar to CSS function [rotate()](https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/rotate()) or [CanvasRenderingContext2D.rotate()](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/rotate). ### $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 image in the horizontal. - The zoom origin in the horizontal. - `y`: - Type: `number` - Default: The center of the image in the vertical. - The zoom origin in the vertical. - **Returns**: - Type: `CropperImage` - The element instance for chaining. - **Examples**: ```js cropperImage.$zoom(0.1); // Zoom in 10% cropperImage.$zoom(-0.1); // Zoom out 10% cropperImage.$zoom(0.1, 0, 0); // Zoom in from the top-left corner cropperImage.$zoom(-0.1, 0, 0); // Zoom out from the top-left corner ``` Zooms the image. ### $scale - **Syntax**: - `$scale(x)` - `$scale(x, y)` - **Arguments**: - `x`: - Type: `number` - The scaling factor in the horizontal direction. - `y`: - Type: `number` - Default: `x` - The scaling factor in the vertical direction. - **Returns**: - Type: `CropperImage` - The element instance for chaining. - **Examples**: ```js cropperImage.$scale(1.1); // Zoom in 10% cropperImage.$scale(0.9); // Zoom out 10% cropperImage.$scale(-1); // Flip both the horizontal and vertical directions cropperImage.$scale(-1, 1); // Flip the horizontal direction cropperImage.$scale(1, -1); // Flip the vertical direction ``` Scales the image. It is similar to CSS function [scale()](https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/scale()) or [CanvasRenderingContext2D.scale()](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/scale). ### $skew - **Syntax**: - `$skew(x)` - `$skew(x, y)` - **Arguments**: - `x`: - Type: `number | string` - The skewing angle in the horizontal direction. The default unit is `rad`. - `y`: - Type: `number | string` - Default: `x` - The skewing angle in the vertical direction. The default unit is `rad`. - **Returns**: - Type: `CropperImage` - The element instance for chaining. - **Examples**: - `$skew(0.8)` - `$skew('0.8rad')` - `$skew('45deg')` - `$skew('50grad')` - `$skew('0.1turn')` - `$skew(0, 0.8)` Skews the image. It is similar to CSS function [skew()](https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/skew()). ### $translate - **Syntax**: - `$translate(x)` - `$translate(x, y)` - **Arguments**: - `x`: - Type: `number` - The translating distance in the horizontal direction. - `y`: - Type: `number` - Default: `x` - The translating distance in the vertical direction. - **Returns**: - Type: `CropperImage` - The element instance for chaining. Translates the image. It is similar to CSS function [translate()](https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/translate()) or [CanvasRenderingContext2D.translate()](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/translate). ### $transform - **Syntax**: `$transform(a, b, c, d, e, f)` - **Arguments**: - `a`: - Type: `number` - The scaling factor in the horizontal direction. - `b`: - Type: `number` - The skewing angle in the vertical direction. - `c`: - Type: `number` - The skewing angle in the horizontal direction. - `d`: - Type: `number` - The scaling factor in the vertical direction. - `e`: - Type: `number` - The translating distance in the horizontal direction. - `f`: - Type: `number` - The translating distance in the vertical direction. - **Returns**: - Type: `CropperImage` - The element instance for chaining. Transforms the image. It is similar to CSS function [matrix()](https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/matrix()) or [CanvasRenderingContext2D.transform()](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/transform). ### $setTransform - **Syntax**: - `$setTransform(a, b, c, d, e, f)` - `$setTransform(a)` - **Arguments**: - `a`: - Type: `number | Array` - The scaling factor in the horizontal direction, or the transformation matrix. - `b`: - Type: `number` - The skewing angle in the vertical direction. - `c`: - Type: `number` - The skewing angle in the horizontal direction. - `d`: - Type: `number` - The scaling factor in the vertical direction. - `e`: - Type: `number` - The translating distance in the horizontal direction. - `f`: - Type: `number` - The translating distance in the vertical direction. - **Returns**: - Type: `CropperImage` - The element instance for chaining. Resets (overrides) the current transform to the specific identity matrix, and then invokes a transform described by the arguments of this method. This lets you scale, rotate, translate (move), and skew the context. It is similar to [CanvasRenderingContext2D.setTransform()](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setTransform). ### $getTransform - **Syntax**: `$getTransform()` - **Returns**: - Type: `Array` - The current transformation matrix of the element. Retrieves the current transformation matrix being applied to the element. It is similar to [CanvasRenderingContext2D.getTransform()](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/getTransform). ### $resetTransform - **Syntax**: - `$resetTransform()` - **Alternatives**: - `$setTransform(1, 0, 0, 1, 0, 0)` - `$setTransform([1, 0, 0, 1, 0, 0])` - **Returns**: - Type: `CropperImage` - The element instance for chaining. Resets the current transform to the initial identity matrix. It is similar to [CanvasRenderingContext2D.resetTransform()](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/resetTransform). ## Events ### transform - Event: - **event.bubbles**: `true` - **event.cancelable**: `true` - **event.composed**: `true` - **event.detail**: - Type: `Object` - The transform information of the image. - **event.detail.matrix**: - Type: `Array` - The new (next) matrix object. - **event.detail.oldMatrix**: - Type: `Array` - The old (current) matrix object. The event is fired when the [`transform`](https://developer.mozilla.org/en-US/docs/Web/CSS/transform) CSS property of the element is going to change. ### change The event is fired when the position or size of the image 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 image. - **event.detail.x**: - Type: `number` - The x-axis coordinate of the image. - **event.detail.y**: - Type: `number` - The y-axis coordinate of the image. - **event.detail.width**: - Type: `number` - The width of the image. - **event.detail.height**: - Type: `number` - The height of the image. - Example: ```html ``` ## Slots There are no available slots in this element. > You can enable the default slot by setting the `slottable` property to `true`: > > ```html > > ```