Documentation

Configuration

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

Limiting CropGuide to a subset of fields

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

<script>
    window.$cropguide = window.$cropguide || {
        fields: [
            /* Active fields here */
        ],
    };
</script>
<script defer src="https://cdn.crop.guide/loader/l.js?c=123ABC"></script>

One field

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" accept="image/*" />
    </fieldset>
</form>

This tells CropGuide to only intercept files that are added to the fields in the fields array, #profile-picture matches the id attribute of our file input.

<script>
    window.$cropguide = window.$cropguide || {
        fields: ['#profile-picture'],
    };
</script>
<script defer src="https://cdn.crop.guide/loader/l.js?c=123ABC"></script>

Multiple fields

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

<script>
    window.$cropguide = window.$cropguide || {
        fields: ['#profile-picture', '#document-photo'],
    };
</script>
<script defer src="https://cdn.crop.guide/loader/l.js?c=123ABC"></script>

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

<script>
    window.$cropguide = window.$cropguide || {
        fields: ['fieldset'],
    };
</script>
<script defer src="https://cdn.crop.guide/loader/l.js?c=123ABC"></script>

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

Overriding field properties

We can further adjust the fields property to pass custom editor properties to the fields.

Setting a different crop aspect ratio

Suppose one or more of our file input fields need a different crop aspect ratio.

We can achieve this by adjusting our settings object like shown below.

The #profile-picture field still receives the configuration we defined in the CropGuide admin, for the #document-photo field we overwrite the crop aspect ratio setting it to 3:4.

<script>
    window.$cropguide = window.$cropguide || {
        fields: [
            // Pass default configuration to profile picture
            '#profile-picture',

            // Override crop aspect for document photo
            {
                selector: '#document-photo',
                editor: {
                    imageCropAspectRatio: 3 / 4,
                },
            },
        ],
    };
</script>
<script defer src="https://cdn.crop.guide/loader/l.js?c=123ABC"></script>

The following properties are available for configuration.

<script>
    window.$cropguide = window.$cropguide || {
        fields: [
            // Pass default configuration to profile picture
            '#profile-picture',

            // Override crop aspect for document photo
            {
                selector: '#document-photo',

                // Field configuration
                field: {
                    // 'circle', defaults to undefined
                    guide: 'circle',

                    // 'circle', defaults to undefined
                    mask: 'circle',

                    // convert HEIC images to JPEGs, defaults to undefined
                    convertHeic: true,

                    // don't set file if user closed the editor window
                    discardOnCancel: true,

                    // don't set file if user aborted load
                    discardOnAbort: true,
                },

                // Editor configuration
                editor: {
                    // A Number, defaults to undefined
                    imageCropAspectRatio: 3 / 4,

                    // A Size, defaults to { width: 1, height: 1 }
                    imageCropMinSize: {
                        width: 100,
                        height: 100,
                    },

                    // An image writer configuration, defaults to undefined
                    imageWriter: {
                        // 'image/jpeg', 'image/png', or 'image/webp' or don't set
                        mimeType: 'image/jpeg',

                        // number between 0 and 1, or don't set
                        quality: 1

                        // a TargetSize or don't set
                        targetSize: {

                            // a number, or don't set
                            width: 100,

                            // a number, or don't set
                            height: 100,

                            // 'contain', 'cover', or 'force', or don't set
                            fit: 'contain',

                            // a boolean or don't set
                            upscale: false
                        }
                    }
                },
            },
        ],
    };
</script>
<script defer src="https://cdn.crop.guide/loader/l.js?c=123ABC"></script>

Dynamically updating field properties

If we want to dynamically change a field property we can use the updateConfig method.

<select id="print-size">
    <option value="1">Square</option>
    <option value="3/4">Portrait</option>
    <option value="4/3">Landscape</option>
</select>

<input id="print-image" type="file" />

<script>
    // Function that updates syncs the CropGuide config with the dropdown
    function setCropAspectRatio(aspectRatio) {
        // Update cropguide configuration
        window.$cropguide.updateConfig('#print-image', {
            editor: {
                imageCropAspectRatio: aspectRatio,
            },
        });
    }

    // When CropGuide loads we listen for changes on the print size dropdown
    document.addEventListener('$cropguide:load', function (e) {
        // Get dropdown element
        const dropdown = document.getElementById('print-size');

        // Set CropGuide config with default dropdown value for print image
        setCropAspectRatio(dropdown.value);

        // When dropdown value changes, we update the CropGuide config
        dropdown.onchange = function () {
            setCropAspectRatio(dropdown.value);
        };
    });
</script>
<script defer src="https://cdn.crop.guide/loader/l.js?c=123ABC"></script>