Filerobot Image Editor Documentation

You can define custom crop presets and organize them into folders using the presetsItems and presetsFolders configuration properties.

CropPresetItem Configuration

Each item in presetsItems or within a folder's groups must have a unique titleKey.

• titleKey (string, Required): Translation key for the item title.
• descriptionKey (string): Translation key for the description (e.g., showing the ratio or size).
• ratio (string, Required if width/height are missing): The aspect ratio (e.g., 4/3, 'original', 'ellipse', 'custom').
• width / height (number, Required if ratio is missing): Specific dimensions used to calculate the ratio.
• icon (HTML Element | string | React Component): An icon displayed before the title.
• disableManualResize (boolean): If true, disables resize inputs when this preset is selected (requires autoResize: true).
• noEffect (boolean): If true, the crop is only a selection on the canvas and does not affect the image; you must handle the resulting crop manually.

Presets Folders Structure

Folders are organized via presetsFolders, which contain groups. Each group contains a titleKey and an array of items (which are CropPresetItem objects).

{
  autoResize: true,
  presetsItems: [
    {
      titleKey: 'classicTv',
      descriptionKey: '4:3',
      ratio: 4 / 3,
      icon: CropClassicTv,
    },
    {
      titleKey: 'cinemascope',
      descriptionKey: '21:9',
      ratio: 21 / 9,
      icon: CropCinemaScope,
    },
  ],
  presetsFolders: [
    {
      titleKey: 'socialMedia',
      icon: Social,
      groups: [
        {
          titleKey: 'facebook',
          items: [
            {
              titleKey: 'profile',
              width: 180,
              height: 180,
              descriptionKey: 'fbProfilePhotoSize',
            },
            {
              titleKey: 'coverPhoto',
              width: 820,
              height: 312,
              descriptionKey: 'fbCoverPhotoSize',
            },
          ],
        },
      ],
    },
  ],
}

Customize how watermarks behave in the editor using the following configuration properties:

• gallery: An array of strings or objects ({ url: string, previewUrl: string }) representing watermark image URLs. These appear in the watermark tab for users to select.
• textScalingRatio: A number (default 0.33) that controls the scaling ratio for text watermarks.
• hideTextWatermark: A boolean (default false) to disable the ability to add text watermarks.
• onUploadWatermarkImgClick: A callback function triggered when the 'add image watermark' button is clicked. It receives a function loadAndSetWatermarkImgFn and returns a Promise<{ url: string, revokeObjectUrl?: boolean }> or void. This allows you to handle custom watermark uploads.

Note on CloudImage mode: Text watermark width and multi-line support are not available in cloudimage mode. Text watermarks will always be a single line in the generated URL. Supported fonts for cloudimage mode must be provided via the Text property.

Use moreSaveOptions to add an overlay menu next to the save button. This allows you to provide additional saving workflows (e.g., 'Save as new version').

Each object in the array must contain:

• label (string, Required): The text shown to the user.
• onClick (function, Required): A function receiving (triggerSaveModal, triggerSave).
  • triggerSaveModal opens the saving modal.
  • triggerSave saves directly.
  • Note: You must pass an onSave callback to either of these functions to handle the result.
• icon (HTML Element | string | React Component): The icon displayed before the label.

[
  {
    label: 'Save as new version',
    onClick: (triggerSaveModal, triggerSave) =>
      triggerSaveModal((...args) => {
        console.log('saved', args);
      }), // Required to pass the callback function
    icon: '<svg width="14" height="14" viewBox="0 0 14 14" fill="none" xmlns="http://www.w3.org/2000/svg">...</svg>', // HTML Element as string
  },
  {
    label: 'Save as new file',
    onClick: (triggerSaveModal, triggerSave) =>
      triggerSave((...args) => {
        console.log('saved', args);
      }), // Required to pass the callback function
    icon: () => (
      <svg
        width="14"
        height="14"
        viewBox="0 0 14 14"
        fill="none"
        xmlns="http://www.w3.org/2000/svg"
      >
        ...
      </svg>
    ), // React Function component
  },
];