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'],
    ],
});