Docs
API Docs

Transform

Our transform tool unifies cropping, flipping and rotation operations in one feature. The PhotoEditor SDK holds various preset crop ratios (e.g. 16:9) that can easily be complemented by any crop ratio you deem necessary.

Adding custom crop ratios

To add custom crop ratios, pass them using the ratios option. Ratios can be grouped in arrays, which will be displayed using separators.

If replaceRatios is set to true, all default ratios are removed. If it is set to false, your additional ratios are appended.

const editor = new PhotoEditorSDK.UI.DesktopUI({
  editor: {
    controlsOptions: {
      transform: {
        categories: [
          {
            identifier: 'my_custom_category',
            defaultName: 'My Custom Ratios',
            ratios: [
              {
                identifier: 'my_custom_ratio', // A unique identifier for this ratio
                defaultName: 'Custom Ratio', // The default translation for this ratio
                ratio: 5 / 4, // The image ratio (a floating point number)
                dimensions: new PhotoEditorSDK.Math.Vector2(50, 40) // Optional fixed
              }
            ]
          }
        ],
        replaceCategories: false
      }
    }
  }
})
const editor = new PhotoEditorSDK.UI.ReactUI({
  editor: {
    controlsOptions: {
      transform: {
        ratios: [
          {
            identifier: 'my_custom_ratio', // A unique identifier for this ratio
            defaultName: 'Custom Ratio', // The default translation for this ratio
            ratio: 5 / 4, // The image ratio (a floating point number)
            dimensions: new PhotoEditorSDK.Math.Vector2(50, 40) // Optional fixed
          }
        ],
        replaceRatios: false
      }
    }
  }
})

You will also need to add an icon to the assets/ui/desktop-ui/controls/transform directory with the same identifier (my_custom_ratio) and a @2x.png suffix.

Specifying the available ratios

Per default, all existing ratios (including your own) are available to the user. To make only specific ratios available to the user, use the availableRatios option.

The default ratio identifiers are imgly_transform_common_custom, imgly_transform_common_square, imgly_transform_common_4-3, imgly_transform_common_16-9, imgly_transform_facebook_profile, imgly_transform_facebook_ad, imgly_transform_facebook_post and imgly_transform_facebook_cover

const editor = new PhotoEditorSDK.UI.DesktopUI({
  editor: {
    controlsOptions: {
      transform: {
        availableRatios: ['imgly_transform_common_custom', 'my_custom_ratio']
      }
    }
  }
})
const editor = new PhotoEditorSDK.UI.ReactUI({
  editor: {
    controlsOptions: {
      transform: {
        availableRatios: ['imgly_transform_common_custom', 'my_custom_ratio']
      }
    }
  }
})

Localization

By default, our UI displays each ratio’s defaultName as the ratio label. You can override this value for each ratio by overriding or adding new keys to the controls.transform.ratios object in the Localization JSON file:

{
  "editor": {
    "controls": {
      // ...
      "transform": {
        // ...
        "ratios": {
          // ...
          "my_custom_category": {
            "name": "My Category Name",
            "ratios": {
              "my_custom_ratio": "Customly localized ratio name"
            }
          },
          "my_other_custom_category": {
            "name": "My Other Category Name",
            "ratios": {
              "my_other_custom_ratio": "Other Customly localized ratio name"
            }
          }
          // ...
        }
        // ...
      }
      // ...
    }
  }
}
{
  "editor": {
    "controls": {
      // ...
      "transform": {
        // ...
        "ratios": {
          // ...
          "my_custom_ratio": "Customly localized ratio name"
          // ...
        }
        // ...
      }
      // ...
    }
  }
}