This is the archived documentation for Doka Image Editor v7.

Please visit pqina.nl/pintura/docs/ to see documentation for the latest version of Pintura Image Editor.

Crop

The crop plugin handles the following functionality:

Manipulating the crop selection
Free rotating the image
Exposing crop selection presets
Zooming the image
Turning the image left and right
Flipping the image
Showing current crop size

All functionality can be toggled and configured with the properties below:

Property	Default value	Description
`cropSelectPresetOptions`	`[]`	A list of crop presets.
`cropImageSelectionCornerStyle`	`'circle'`	Determines style of crop selection corners, either `'circle'`, `'hook'`, or `'invisible'`, defaults to `'circle'`.
`cropWillRenderImageSelectionGuides`	`undefined`	Determines if and how many image selection guides are rendered.
`cropEnableButtonFlipHorizontal`	`true`	Toggle flip horizontal button.
`cropEnableButtonFlipVertical`	`false`	Toggle flip vertical button.
`cropEnableButtonRotateLeft`	`true`	Toggle rotate left button.
`cropEnableButtonRotateRight`	`false`	Toggle Rotate right button.
`cropEnableButtonToggleCropLimit`	`false`	Toggle crop limit button.
`cropEnableImageSelection`	`true`	Enable or disable the crop selection controls.
`cropEnableInfoIndicator`	`false`	Show image size indicator.
`cropEnableLimitWheelInputToCropSelection`	`true`	Only captures mouse wheel interactions when the mouse is inside the crop selection.
`cropEnableRotationInput`	`true`	Toggle the image rotation input on and off.
`cropEnableSelectPreset`	`true`	If crop presets have been defined this will show the preset dropdown in the toolbar.
`cropEnableZoom`	`true`	Enable generic zooming of the image. If set to `false` all zoom related input will be disabled.
`cropEnableZoomInput`	`true`	Enable the zoom input control at the bottom of the crop tool. This control will automatically hide if there's not enough vertical space.
`cropEnableZoomMatchImageAspectRatio`	`true`	Will automatically adjust the crop aspect ratio when zooming out, only works if aspect ratio is set to `undefined`
`cropEnableRotateMatchImageAspectRatio`	`'never'`	Will automatically rotate the crop rectangle with the image if set to `'custom'`, or `'always'`.
`cropEnableZoomTowardsWheelPosition`	`true`	Will zoom in towards the mouse position within the crop.
`cropEnableCenterImageSelection`	`true`	Toggle the center selection button on and off.
`cropAutoCenterImageSelectionTimeout`	`undefined`	Timeout in milliseconds after which the crop automatically re-centers.

cropSelectPresetOptions

A flat or a grouped array of crop presets.

An example of a flat list of crop aspect ratio presets.

[
    [undefined, 'Custom'],
    [1, 'Square'],
    [4 / 3, 'Landscape'],
    [3 / 4, 'Portrait'],
];

If we don't supply the 'Custom' crop options with value undefined we have to make sure we set the imageCropAspectRatio property to one of the values in the list otherwise the editor won't know which value to select.

An example of a grouped list of presets.

[
    [
        'Crop Aspect Ratios',
        [
            [undefined, 'Custom'],
            [1, 'Square'],
            [4 / 3, 'Landscape'],
            [3 / 4, 'Portrait'],
        ],
    ],
    [
        'Crop sizes',
        [
            [[180, 180], 'Profile Picture'],
            [[1200, 600], 'Header Image'],
            [[800, 400], 'Timeline Photo'],
        ],
    ],
];

As we could see in the previous code snippets we can describe a crop with [aspectRatio, 'label'] and a size preset with [[width, height], 'label'].

Doka will apply the aspectRatio value to the imageCropAspectRatio prop. When a size is selected it will apply the matching aspect ratio and apply the size to the imageTargetSize prop.

import { openEditor } from './doka.js';

openEditor({
    cropSelectPresetOptions: [
        [
            'Crop',
            [
                [undefined, 'Custom'],
                [1, 'Square'],
                [4 / 3, 'Landscape'],
                [3 / 4, 'Portrait'],
            ],
        ],
        [
            'Size',
            [
                [[180, 180], 'Profile Picture'],
                [[1200, 600], 'Header Image'],
                [[800, 400], 'Timeline Photo'],
            ],
        ],
    ],
});

cropWillRenderImageSelectionGuides

Set opacity to .25 to always render the image selection guides.

interactionFraction tweens from 0 to 1 when the user interacts with the editor UI this allows us to fade in and out the image selection guides.

import { openEditor } from './doka.js';

openEditor({
    cropWillRenderImageSelectionGuides: (interaction, interactionFraction) => {
        const isRotating = interaction === 'rotate';
        return {
            rows: isRotating ? 5 : 3,
            cols: isRotating ? 5 : 3,
            opacity: interactionFraction * 0.25,
        };
    },
});

cropEnableRotateMatchImageAspectRatio

When set to 'always' or 'custom' this will automatically rotate the crop rectangle with the image is the crop rectangle is fully zoomed out and centered.

Value	Description
`'never'`	Don't rotate the crop when the image is rotated.
`'custom'`	Only rotate the crop with the image if the crop aspect ratio is set to custom `imageCropAspectRatio === undefined`
`'always'`	Rotate the crop rectangle with the image if the crop aspect ratio is custom or a rotated crop aspect ratio can be found in the preset list. For example `4:3` to `3:4`.

In this example the crop will automatically switch between 4:3 and 3:4 when the image is rotated while fully zoomed out.

import { openEditor } from './doka.js';

openEditor({
    cropEnableRotateMatchImageAspectRatio: 'always',
    cropSelectPresetOptions: [
        [undefined, 'Custom'],
        [1, 'Square'],
        [4 / 3, 'Landscape'],
        [3 / 4, 'Portrait'],
    ],
});