Documentation

Configuration

Although CropGuide fields are meant to be configured using the customer dashboard we can also configure them with JavaScript.

The JavaScript API is only available on Pro and Unlimited subscriptions.

Setting the editor language

The editor supports the folowing locales.

Pick one of the default locales.

<script>
    $cropguide.push(['set', 'locale', 'en_GB']);
</script>

Set a custom label

<script>
    $cropguide.push([
        'set',
        'locale',
        {
            // the document lang to set
            lang: 'en_GB',

            // optional label overrides here, else uses default lang labels (if available, else falls back to English)
            close: 'Exit',
        },
    ]);
</script>

Override all labels.

<script>
    $cropguide.push([
        'set',
        'locale',
        {
            // the document lang to set
            lang: 'en_GB',

            // Overwrite all labels
            close: 'Close',
            export: 'Done',
            revert: 'Revert',
            recenter: 'Recenter',
            rotateLeft: 'Rotate left',
            rotateRight: 'Rotate right',
            flipHorizontal: 'Flip horizontal',
            flipVertical: 'Flip vertical',
            cropShape: 'Crop shape',
            cropBoundary: 'Crop boundary',
            cropBoundaryEdge: 'Edge of image',
            cropBoundaryNone: 'None',
            tabRotation: 'Rotation',
            tabZoom: 'Zoom',
            imageWaiting: 'Waiting for image',
            imageTooSmall: 'Minimum image size is {minWidth} × {minHeight}',
            imageLoadError: 'Error loading image',
            imagePreparing: 'Preparing image…',
            imageLoading: 'Loading image…',
            imageUploading: 'Uploading image…',
            imageUploadError: 'Error uploading image',
            imageProcessError: 'Error processing image',
            imageProcessing: 'Processing image…',
            supportError: 'CropGuide is not supported on this browser',
        },
    ]);
</script>

Excluding fields

By default CropGuide will intercept all image files added to the page. We can configure it to only target a subset of fields by setting the fields property on the $cropguide global object.

Let’s imagine we have the the following form and want to limit CropGuide to the profile picture field.

<form>
    <input type="file" />

    <fieldset>
        <input type="file" id="profile-picture" />
    </fieldset>
</form>

When we pass a selector to the 'fields' setter, only these fields will trigger CropGuide.

The fields array can have multiple field selectors, this will select the #profile-picture and the #document-photo field.

<script>
    $cropguide.push(['set', 'fields', ['#profile-picture', '#document-photo']]);
</script>

Instead of targetting specific fields we can also allow groups of fields.

<script>
    $cropguide.push(['set', 'fields', ['fieldset']]);
</script>

Here we tell CropGuide to only intercept files added to file inputs inside the <fieldset> element.

Setting field properties

The 'fields' setter also enables us to programmatically override settings on existing fields.

Field properties don’t have to all be set on page load, you can update the editor settings at any time.

<script>
    $cropguide.push([
        'set',
        'fields',
        [
            {
                // select the field we want to update
                selector: 'html',

                // override these settings
                settings: {
                    aspectRatio: 1,
                },
            },
        ],
    ]);
</script>

The following properties are available to control via the API, these are also available for configuration in the customer dashboard.

discardOnCancel

Set to true discard an image when the user doesn’t press the Done button.

accept

Set to array of accepted image formats.

{
    accept: ['image/jpeg', 'image/heic'],
}

If includes 'image/heic' the editor will automatically convert HEIC images to JPEGs.

minSize

Defaults to { width: 1, height: 1 }, set to a higher value to prevent users from submitting images smaller than the defined size.

aspectRatio

Set the aspect ratio to crop images to.

mask

Defaults to 'none', set to 'circle' to apply a circular mask to the output image.

Use with cropOverlay property to indicate the mask area in the editor.

fill

Fill the background of an image with a given color. Only works on transparent images.

{
    fill: '#fff',
}

quality

A value between 0 and 1 indicating the output image quality. 0 is max compression, ‘1’ is no compression. Please note that a value of 1 results in extremely large images.

Defaults to the browser image output quality which averages around 0.98

{
    quality: 0.5,
}

format

The format of the resulting image. Defaults to same format as input image.

Set to image/jpeg or image/webp to export to that image format.

resize

The size of the resulting image.

This will scale an image to fit in a 512 by 512 square, if the crop is smaller the image won’t be upscaled.

{
    resize: {
        width: 512,
        height: 512,
        upscale: false,
        fit: 'contain'
    }
}

headless

When set to true the editor doesn’t open and image processing happens in the background.

toolbarPosition

Defaults to 'top', can be set to 'bottom' to render the toolbar at the bottom of the editor.

cropOverlay

An overlay shape to render on top of the editor.

Set to 'circle' to render a circular overlay. Use with mask property to also mask the output image.

cropSelectionStyle

The style of the selection corners. Can be either 'invisible', 'hook', or 'circle', defaults to 'circle'

cropPresets

A list of crop aspect ratios to show in the editor.

{
    cropPresets: [
        [undefined, 'Free'],
        [1, 'Square'],
        [16 / 9, 'Widescreen'],
    ],
}

cropLimit

Set to false to allow the crop selection to exceed the image bounds, defaults to true

enableFlipHorizontal

Toggle the Flip Horizontal button. Defaults to true

enableFlipVertical

Toggle the Flip Vertical button. Defaults to false

enableRotateLeft

Toggle the Rotate Left button. Defaults to true

enableRotateRight

Toggle the Rotate Right button. Defaults to false

enableRevert

Toggle the revert button. Defaults to true, which allows the user to press the revert button to revert the image state to the initial editor state.

enableScale

Toggles the scale control at the bottom of the editor view. Enabled by default, set to false to disable.

enableRotate

Toggles the free rotation control at the bottom of the editor view. Enabled by default, set to false to disable.

theme

What theme to use for the editor. Defaults to 'auto', which will determine a bright or dark theme based on the website color scheme.

{
    theme: 'dark';
}

colorsLight

Only available on unlimited subscription level.

The colors to use in the light theme.

{
    colorsLight: {
        buttonPrimaryColor: '#fff';
        buttonPrimaryBackground: '#000';
    }
}

colorsDark

Only available on unlimited subscription level.

The colors to use in the dark theme.

{
    colorsDark: {
        buttonPrimaryColor: '#000';
        buttonPrimaryBackground: '#fff';
    }
}