# Documentation

## Configuration

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

Customizing CropGuide using the JavaScript API instead of the customer portal is **only available on Pro and Unlimited subscriptions**. 

### Environments

#### Web

After you’ve added the CropGuide `<script>` snippet to before the document `</head>` you can run API commands like this.

```html
<script>
    // Set other locale
    $cropguide.push(['set', 'locale', 'nl_NL']);
</script>
```

#### App

When you’re using the `'@cropguide/browser'` package you can run API commands like this.

```js
import { $cropguide } from '@cropguide/browser';

// Set other locale
$cropguide.push(['set', 'locale', 'nl_NL']);
```

### API

See below for the list of commands.

* [Setting the editor language](#setting-the-editor-language)
* [Excluding fields](#excluding-fields)
* [Setting field properties](#setting-field-properties)  
  * [discardOnCancel](#discardoncancel)
  * [accept](#accept)
  * [minSize](#minsize)
  * [aspectRatio](#aspectratio)
  * [mask](#mask)
  * [fill](#fill)
  * [quality](#quality)
  * [format](#format)
  * [resize](#resize)
  * [headless](#headless)
  * [toolbarPosition](#toolbarposition)
  * [cropOverlay](#cropoverlay)
  * [cropSelectionStyle](#cropselectionstyle)
  * [cropPresets](#croppresets)
  * [cropLimit](#croplimit)
  * [enableFlipHorizontal](#enablefliphorizontal)
  * [enableFlipVertical](#enableflipvertical)
  * [enableRotateLeft](#enablerotateleft)
  * [enableRotateRight](#enablerotateright)
  * [enableRevert](#enablerevert)
  * [enableScale](#enablescale)
  * [enableRotate](#enablerotate)
  * [theme](#theme)
  * [colorsLight](#colorslight)
  * [colorsDark](#colorsdark)

### Setting the editor language

The editor supports the folowing locales.

* Deutsch `de_DR`
* English `en_GB`
* Español `es_ES`
* Français `fr_FR`
* हिन्दी `hi_IN`
* Italiano `it_IT`
* 日本語 `ja_JP`
* 한국어 `ko_KR`
* Norwegian `nb_NO`
* Nederlands `nl_NL`
* Português `pt_PT`
* Русский `ru_RU`
* Svenska `sv_SE`
* 筒体中文 `zh_CN`

Pick one of the default locales.

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

Set custom labels.

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

            // Overwrite all labels
            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>
```

You can optionally pass only a label if you just want to change one.

```html
<script>
    $cropguide.push([
        'set',
        'locale',
        {
            // optional label overrides here, else uses default lang labels (if available, else falls back to English)
            close: 'Exit',
        },
    ]);
</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.

```html
<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.

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

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

```html
<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.

```html
<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.

```js
{
    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.

* `1` will result in a square image.
* `16/9` results in a 16:9 image.

#### 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.

```js
{
    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`

```js
{
    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.

```js
{
    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.

```js
{
    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.

* Set to `'dark'` to force dark mode.
* Set to `'bright'` to force bright mode.
* Set to `'user'` to use system settings.

```js
{
    theme: 'dark';
}
```

#### colorsLight

Only available on unlimited subscription level.

The colors to use in the light theme.

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

#### colorsDark

Only available on unlimited subscription level.

The colors to use in the dark theme.

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