Editor Preview • Learn more about Filerobot • CodeSandbox

Filerobot Image Editor (FIE)

The Filerobot Image Editor is the easiest way to integrate an easy-to-use image editor in your web application. Integrated with few lines of code, your users will be able to apply basic transformations like resize, crop, flip, finetune, annotate, watermark and various filters to any image.

Demo

🔗 DEMO/PREVIEW LINK

Features

• 📱 Touch, Mobile & Desktop Friendly.
• ⏭️ Live Comparison (Applied Operations & original).
• ⏳ History management (Undo/Redo/Reset).
• ✂️ Image Adjustment.
• 🔂 Export current design state & load it whenever you want to continue past edits Experimental
• 🎨 Image Annotating & Drawing.
• 🖼️ Watermarking & positioning.
• 🪟 Image Resizing.
• 🧊 A lot of Image Filters.
• 🌉 VanillaJS + Bridged to frameworks (React & More to support...).
• 🏗️ Easy, Focused & Simple UI for better UX.
• ➕ Ability to customize.
• 🔢 Multiple annotations selections & transformation
• 🚀 Image file on save customization.
• 🧩 ES6 library supports tree-shaking for eliminating dead code.
• 🤹🏼 And more to discover by yourself...

Contents

• Prerequisites
• Installation
  • React
  • NPM
  • VanillaJS
  • NPM
  • CDN
• Usage/Examples
  • React Example
  • VanillaJS Example
• Config
  • Properties
  • Callbacks
• Bridges
• Bridges docs
  • VanillaJS
• Used by
• Feedback
• Contributing
• License

Prerequisites

Following prerequisites are required only in React Component installation, but they're included in CDN bundle installation and added as dependencies of other bridges/adapters packages.

All of the following libraries are required, as the plugin is depending on them in the implementation.

• react, react-dom: >= v17.0.0
• react-konva >= v17.0.1-1
• styled-components: >= v5.3.5

Compatability table (installed version of react should meet the opposite react-konva version in the table).

Installation

NPM

React component

npm install --save react-filerobot-image-editor

VanillaJS

npm install --save filerobot-image-editor react-filerobot-image-editor

NOTE: if your npm version < 7 you don't need to install react-filerobot-image-editor .

CDN

VanillaJS only

// latest => last production version of the plugin, possible to replace with some earlier version (ex. 3.17.0) & if available will be requested
<script src="https://scaleflex.cloudimg.io/v7/plugins/filerobot-image-editor/latest/filerobot-image-editor.min.js"></script>

IMPORTANT NOTE: In all installation cases you must import the font family that will be used from your side as it is not included in the library by default, the default font family used is Roboto in 2 font-weight (normal === 400 & medium === 500) which fall-backs to Arial if not found.

Just import the font in your HTML/JS file before loading the plugin whether it's Roboto or you have provided another fontFamily from theme property and that's all!

Usage/Examples

React Example

import React, { useState } from 'react';
import FilerobotImageEditor, {
  TABS,
  TOOLS,
} from 'react-filerobot-image-editor';

function App() {
  const [isImgEditorShown, setIsImgEditorShown] = useState(false);

  const openImgEditor = () => {
    setIsImgEditorShown(true);
  };

  const closeImgEditor = () => {
    setIsImgEditorShown(false);
  };

  return (
    <div>
      <button onClick={openImgEditor}>Open Filerobot image editor</button>
      {isImgEditorShown && (
        <FilerobotImageEditor
          source="https://scaleflex.airstore.io/demo/stephen-walker-unsplash.jpg"
          onSave={(editedImageObject, designState) =>
            console.log('saved', editedImageObject, designState)
          }
          onClose={closeImgEditor}
          annotationsCommon={{
            fill: '#ff0000',
          }}
          Text={{ text: 'Filerobot...' }}
          Rotate={{ angle: 90, componentType: 'slider' }}
          Crop={{
            presetsItems: [
              {
                titleKey: 'classicTv',
                descriptionKey: '4:3',
                ratio: 4 / 3,
                // icon: CropClassicTv, // optional, CropClassicTv is a React Function component. Possible (React Function component, string or HTML Element)
              },
              {
                titleKey: 'cinemascope',
                descriptionKey: '21:9',
                ratio: 21 / 9,
                // icon: CropCinemaScope, // optional, CropCinemaScope is a React Function component.  Possible (React Function component, string or HTML Element)
              },
            ],
            presetsFolders: [
              {
                titleKey: 'socialMedia', // will be translated into Social Media as backend contains this translation key
                // icon: Social, // optional, Social is a React Function component. Possible (React Function component, string or HTML Element)
                groups: [
                  {
                    titleKey: 'facebook',
                    items: [
                      {
                        titleKey: 'profile',
                        width: 180,
                        height: 180,
                        descriptionKey: 'fbProfileSize',
                      },
                      {
                        titleKey: 'coverPhoto',
                        width: 820,
                        height: 312,
                        descriptionKey: 'fbCoverPhotoSize',
                      },
                    ],
                  },
                ],
              },
            ],
          }}
          tabsIds={[TABS.ADJUST, TABS.ANNOTATE, TABS.WATERMARK]} // or {['Adjust', 'Annotate', 'Watermark']}
          defaultTabId={TABS.ANNOTATE} // or 'Annotate'
          defaultToolId={TOOLS.TEXT} // or 'Text'
        />
      )}
    </div>
  );
}

VanillaJS Example

import FilerobotImageEditor from 'filerobot-image-editor'; // Load library from NPM
// or load from CDN as following and use (window.FilerobotImageEditor):
// <script src="https://scaleflex.cloudimg.io/v7/plugins/filerobot-image-editor/latest/filerobot-image-editor.min.js"></script>

const { TABS, TOOLS } = FilerobotImageEditor;
const config = {
  source: 'https://scaleflex.airstore.io/demo/stephen-walker-unsplash.jpg',
  onSave: (editedImageObject, designState) =>
    console.log('saved', editedImageObject, designState),
  annotationsCommon: {
    fill: '#ff0000',
  },
  Text: { text: 'Filerobot...' },
  Rotate: { angle: 90, componentType: 'slider' },
  translations: {
    profile: 'Profile',
    coverPhoto: 'Cover photo',
    facebook: 'Facebook',
    socialMedia: 'Social Media',
    fbProfileSize: '180x180px',
    fbCoverPhotoSize: '820x312px',
  },
  Crop: {
    presetsItems: [
      {
        titleKey: 'classicTv',
        descriptionKey: '4:3',
        ratio: 4 / 3,
        // icon: CropClassicTv, // optional, CropClassicTv is a React Function component. Possible (React Function component, string or HTML Element)
      },
      {
        titleKey: 'cinemascope',
        descriptionKey: '21:9',
        ratio: 21 / 9,
        // icon: CropCinemaScope, // optional, CropCinemaScope is a React Function component.  Possible (React Function component, string or HTML Element)
      },
    ],
    presetsFolders: [
      {
        titleKey: 'socialMedia', // will be translated into Social Media as backend contains this translation key
        // icon: Social, // optional, Social is a React Function component. Possible (React Function component, string or HTML Element)
        groups: [
          {
            titleKey: 'facebook',
            items: [
              {
                titleKey: 'profile',
                width: 180,
                height: 180,
                descriptionKey: 'fbProfileSize',
              },
              {
                titleKey: 'coverPhoto',
                width: 820,
                height: 312,
                descriptionKey: 'fbCoverPhotoSize',
              },
            ],
          },
        ],
      },
    ],
  },
  tabsIds: [TABS.ADJUST, TABS.ANNOTATE, TABS.WATERMARK], // or ['Adjust', 'Annotate', 'Watermark']
  defaultTabId: TABS.ANNOTATE, // or 'Annotate'
  defaultToolId: TOOLS.TEXT, // or 'Text'
};

// Assuming we have a div with id="editor_container"
const filerobotImageEditor = new FilerobotImageEditor(
  document.querySelector('#editor_container'),
  config,
);

filerobotImageEditor.render({
  onClose: (closingReason) => {
    console.log('Closing reason', closingReason);
    filerobotImageEditor.terminate();
  },
});

NOTE: if you are importing the library from CDN then you could access it using window.FilerobotImageEditor and access both TABS & TOOLS from window.FilerobotImageEditor.TABS & window.FilerobotImageEditor.TOOLS, see tabsIds.

Config

NOTE: The plugin respects the container/wrapper HTML element through CSS by having both width & height set 100% so you could change the width/height of the plugin through adding/changing width/height of the wrapper HTML element.

Properties

source

Type: string | HTMLImageElement Required.

Supported version: +v4.0.0

Default: undefined.

The image url or an HTMLImageElement for the image which the operations/edits will be applied on.

theme

Type: object

Supported version: +v4.0.0

Default:

Theme from @scaleflex/ui deep merged with following overrides

// Overrides
{
  palette: {
    'bg-primary-active': '#ECF3FF',
  },
  typography: {
    fontFamily: 'Roboto, Arial',
  },
}

// Used properties in case you need to provide your custom colors/theme, you should customize those properties (all or any of them) with your color hex/name string values.
{
  palette: {
    'bg-secondary': '....',
    'bg-primary': : '....',
    'bg-primary-active': : '....',
    'accent-primary': : '....',
    'accent-primary-active': : '....',
    'icons-primary': : '....',
    'icons-secondary': : '....',
    'borders-secondary': : '....',
    'borders-primary': : '....',
    'borders-strong': : '....',
    'light-shadow': : '....',
    'warning': : '....',

  },
  typography: {
    fontFamily: : '....', // Font family string value, you should import this font in your app.
  },
}

Almost you would need those 2 objects (palette values are the possible keys for palette object & typograpghy) to have the proper theme you want.

As the colors of the plugin are retrieved dynamically from the theme object, it gives you the possibility to customize the colors and font-family to yours.

NOTE: You must import the font family from your side in 2 weights (Normal === 400, Medium === 500) to have fonts work properly and show text as expected, which means Roboto is not included in the plugin by default so you must import it from your side too if you have provided another font family value through theme don't forget to import it from your side too.

tabsIds

Type: string[]

Supported version: +v4.0.0

Default: []

the tabs will be shown to the user, if empty array provided or left by default all tabs will be used otherwise the provided tabs ids would be shown.

Access the available Tabs ids & tools ids through anyway of the following

// Accessing from the CDN bundle
const { TABS, TOOLS } = window.FilerobotImageEditor;

// Accessing from React Function component lib. NPM
import ReactFilerobotImageEditor, {
  TABS,
  TOOLS,
} from 'react-filerobot-image-editor';

// Access from VanillaJS lib. NPM
import VanillaFilerobotImageEditor from 'filerobot-image-editor';
const { TABS, TOOLS } = VanillaFilerobotImageEditor;

defaultTabId

Type: string

Supported version: +v4.0.0

Default: Adjust

The default opened tab once the user opens the plugin.

defaultToolId

Type: string

Supported version: +v4.0.0

Default: first tool of the default opened tab.

The default opened tool once the user opens the plugin, and must be one of the tools related to the opened tab.

useBackendTranslations

Type: boolean

Supported version: +v4.0.0

Default: true

A backend service that hosts the translations of the plugin to be able to change the translations without making a new build once the translations changed, and gives the chance to support more languages too, if true the service would be used and the next language property used in determining which language to show, false means avoid using this service in that case default translations and provided translations property will be used.

language

Type: string

Supported version: +v4.0.0

Default: en

The 2 letters shorthand used for the language/translations, would be used in case useBackendTranslations is true.

translations

Type: object

Supported version: +v4.0.0

Default: null

If provided will be used in overriding the default translations arrived locally with the plugin & backend's translations.

All the translation keys could be found here.

avoidChangesNotSavedAlertOnLeave

Type: boolean

Supported version: +v4.0.0

Default: false

By default once the user makes any change/edit on the image and hasn't saved the image yet and tried to leave the page before saving then a browser's confirmation would be shown asking him if he really wants to leave before saving, true means it won't be shown.

showBackButton

Type: boolean

Supported version: +v4.0.0

Default: false

If true Close button on the top right will be hidden and back button will be shown on the top left (with replacing positions of save & history buttons).

defaultSavedImageName

Type: string

Supported version: +v4.0.0

Default: undefined

The image file name used as default name for the image's file that will be saved if not provided the name will be extracted from provided image's src.

defaultSavedImageType

Type: string

Supported version: +v4.0.0

Default: png

Possible values: 'png' | 'jpeg' | 'jpg' | 'webp'

The default type used and selected in saving the image (the user has the possibility to change it from the saving modal).

NOTE: Quality modification will be applied to jpeg, jpg and webp types in returned base64 format only while saving the image by the default behavior.

defaultSavedImageQuality

Type: number

Supported version: +v4.4.0

Default: 0.92

Possible values: [0.1 - 1]

The default value used for quality property used in the final saving of the canvas. the higher value used (Min: 0.1, Max: 1) the higher generated image's resolution the higher generated image file's size and vice-versa.

NOTE: Quality modification will be applied to jpeg, jpg and webp types in returned base64 format only.

NOTE: The value of this property will reflect the quality option found in the default save behavior's UI (if default save behavior used otherwise UI only is not affected).

forceToPngInEllipticalCrop

Type: boolean

Supported version: +v4.0.0

Default: false

If true then the saved image's type will always be png type if the user made an elliptical crop for preserving the transparency even if the user chose another extension in the saving modal, otherwise the familiar behavior (defaultSavedImageType or user's selected types) wins.

closeAfterSave

Type: boolean

Supported version: +v4.0.0

Default: false

Fires onClose callback after handling save & triggering onSave if true.

loadableDesignState

Type: object

Supported version: +v4.0.0

Default: null

If provided the plugin will load this design state at the initial load to give the possibility to get back to that design in another time and continue editing it, it accepts the same object as provided in the onSave callback's designState parameter.

annotationsCommon

Type: object

Supported version: +v4.0.0

Default:

{
    fill: '#000000',
    stroke: '#000000',
    strokeWidth: 0,
    shadowOffsetX: 0,
    shadowOffsetY: 0,
    shadowBlur: 0,
    shadowColor: '#000000',
    shadowOpacity: 1,
    opacity: 1,
}

The common options existed in all the annotations tools and used as default values.

Text

Type: object

Supported version: +v4.0.0

Default:

{
    ...annotationsCommon,
    text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
    fontFamily: 'Arial',
    fonts: [
      { label: 'Arial', value: 'Arial' },
      'Tahoma',
      'Sans-serif',
      { label: 'Comic Sans', value: 'Comic-sans' },
    ],
    fontSize: 14,
    letterSpacing: 0,
    lineHeight: 1,
    align: 'left',
    fontStyle: 'normal',
    onFontChange: (newFontFamily, reRenderCanvasFn) => undefined,
}

The options available for the text annotation tool in additon to the annotationsCommon property,

If you are lazy loading the font then you must re-render the canvas manually after the font is loaded (if the font wasn't loaded and user changed the font then font won't be applied) you could call the 2nd paramter (reRenderCanvasFn) inside the onFontChange function to re-render the canvas manually whenever you want.

Fonts must be loaded from your side in implementation to take effect as it is not guaranteed that the user has the font on his OS.

Image

Type: object

Supported version: +v4.0.0

Default:

{
    ...annotationsCommon,
    fill: undefined,
    disableUpload: false,
    gallery: [{
      originalUrl: '...', // The url of the image in original size to be added in canvas
      previewUrl: '...', // The url of the image to be used as preview in gallery list (for less data consuming & better performance).
    }]
}

The options available for image annotation tool in additon to the annotationsCommon property,

Rect

Type: object

Supported version: +v4.0.0

Default:

{
    ...annotationsCommon,
    cornerRadius: 0,
}

The options available for Rect annotation tool in additon to the annotationsCommon property,

Ellipse

Type: object

Supported version: +v4.0.0

Default: annotationsCommon

No specific options available for ellipse only the annotationsCommon are used for ellipse and you could override any of them for ellipse only by passing them here.

Polygon

Type: object

Supported version: +v4.0.0

Default:

{
    ...annotationsCommon,
    sides: 3,
}

The available options for polygon annotation tool in additon to the annotationsCommon property,

Pen

Type: object

Supported version: +v4.0.0

Default:

{
    ...annotationsCommon,
    strokeWidth: 1,
    tension: 0.5,
    lineCap: 'round',
    selectAnnotationAfterDrawing: true,
}

The available options for pen annotation tool in additon to the annotationsCommon property,

Line

Type: object

Supported version: +v4.0.0

Default:

{
    ...annotationsCommon,
    lineCap: 'butt',
    strokeWidth: 1,
}

The available options for line annotation tool in additon to the annotationsCommon property,

Arrow

Type: object

Supported version: +v4.0.0

Default:

{
    ...annotationsCommon,
    strokeWidth: 6,
    lineCap: 'butt',
    pointerLength: undefined,
    pointerWidth: undefined,
}

The available options for arrow annotation tool in additon to the annotationsCommon property,

Watermark

Type: object

Supported version: +v4.0.0

Default:

{
    ...(config[TOOLS.TEXT || TOOLS.IMAGE]), // depends on the added watermark type the config will be used
    gallery: [],
    textScalingRatio: 0.33,
    imageScalingRatio: 0.33,
    hideTextWatermark: false,
    onUploadWatermarkImgClick: () => {},
}

The available options for watermark tool, the watermark is using the options of text and image annotation tools mentioned above depending on the watermark chosen,

Text watermark width/multi-lines are not supported in the cloudimage mode even if the transformation/resize frame is shown while selecting which means text watermark will always be 1 line in generated cloudimage's URL from the plugin

Supported fonts for text watermark in cloudimage mode only are found here you could provide them/any of them through Text property.

Rotate

Type: object

Supported version: +v4.3.2

Default:

{
    angle: 90,
    componentType: 'slider',
}

The available options for crop tool,

Crop

Type: object

Supported version: +v4.0.0

Default:

{
    minWidth: 14,
    minHeight: 14,
    maxWidth: null,
    maxHeight: null,
    ratio: 'original',
    ratioTitleKey: 'original',
    noPresets: false,
    autoResize: false,
    presetsItems: [],
    presetsFolders: [],
    lockCropAreaAt: null, // 'top-left'
}

The available options for crop tool,

CropPresetFolder:

Type: object

Supported version: +v4.0.0

CropPresetGroup:

Type: object

Supported version: +v4.0.0

CropPresetItem:

Type: object

Supported version: +v4.0.0

NOTE: titleKey of each object must be unique between the other objects in the same array.

Example,

{
  autoResize: true,
  presetsItems: [
    {
      titleKey: 'classicTv',
      descriptionKey: '4:3',
      ratio: 4 / 3,
      icon: CropClassicTv,
    },
    {
      titleKey: 'cinemascope',
      descriptionKey: '21:9',
      ratio: 21 / 9,
      icon: CropCinemaScope, // optional
    },
  ],
  presetsFolders: [
    {
      titleKey: 'socialMedia', // will be translated into Social Media as backend contains this translation key
      icon: Social, // React Function component, string or HTML Element
      groups: [
        {
          titleKey: 'facebook',
          items: [
            {
              titleKey: 'profile',
              width: 180,
              height: 180,
              descriptionKey: 'fbProfilePhotoSize',
            },
            {
              titleKey: 'coverPhoto',
              width: 820,
              height: 312,
              descriptionKey: 'fbCoverPhotoSize',
            },
          ],
        },
      ],
    },
  ],
}

Please note the letters-case of the above properties..

useCloudimage

Type: boolean

Supported version: +v4.0.0

Default: false

If true the plugin will work in cloudimage mode means you will receive a cloudimage's URL contains the transformations/operations on saving not the image itself and some of tabs, tools and options are not supported in this mode, otherwise the default mode is used.

To use the Cloudimage mode, you will need a Cloudimage token to deliver your images over CDN. Don't worry, it only takes seconds to get one by registering here. Once your token is created, you can configure it as described in cloudimage property. This token allows you to use 25GB of image cache and 25GB of worldwide CDN traffic per month for free.

cloudimage

Type: object

Supported version: +v4.0.0

Default:

{
  token: '',
  dontPrefixUrl: false,
  domain: 'cloudimg.io',
  version: '',
  secureProtocol: true,
  imageSealing: {
    enable: false,
    salt: '',
    charCount: 10,
    includeParams: [],
  }
}

The options available for cloudimage mode,

savingPixelRatio

Type: number

Supported version: +v4.0.0

Default: 4

The pixel ratio used in saving the image (higher the ratio, higher the resolution of the saved image till reaching the possible max. resolution for the image, higher the memory used & processing time of saving).

High pixel ratio might cause some device crashes/slowness or showing stack error in some browsers while saving so consider choosing an appropriate ratio for your use case.

previewPixelRatio

Type: number

Supported version: +v4.0.0

Default: window.devicePixelRatio

The pixel ratio used in previewing the image while doing the operations (higher the ratio, higher the resolution of the drawn/previewed image in the plugin till reaching the possible max. resolution for the image, higher the processing time of drawing the image & more memory used).

High pixel ratio might cause some device crashes/slowness while drawing/previewing and doing operations so consider choosing an appropriate ratio for your use case.

moreSaveOptions

Type: array of objects

Supported version: +v4.0.0

default: []

Used in case you want to show more saving options to the user besides the current save button as overlay menu opened through arrow next to save button.

If left provided [] or left default value the arrow button that would open the menu will be hidden, otherwise it'll be shown

Option's object to be provided,

NOTE: you must provide an onSave callback function on using any of the passed functions to the option's onClick function. example,

[
  {
    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
  },
];

observePluginContainerSize

Type: boolean

Supported version: +v4.0.0

Default: false

By default the plugin's root HTML Element is set with 100% for both height & width to respect the plugin's container HTML element size using CSS, If provided true to this property then that root element will always be the same absolute width & height values of the plugin's container HTML Element through JS observable not CSS.

NOTE: This property might be useful in some cases (one of them if you leave height of the container element to auto or didn't set it) in those cases the root element will be the same current size values of the container by JS.

showCanvasOnly

Type: boolean

Supported version: +v4.0.0

Default: false

Hides all the UI of the plugin including (save & close buttons, tabs & tools bars...etc.) except the canvas only if true, otherwise the whole UI will be shown as normal.

This prop might be useful if are using the editor in different ways in the same project, (ex. using the editor in doing different transformations for quick photo editing & using the editor after uploading some profile photo to crop the photo only and dismiss other transformations).

getCurrentImgDataFnRef

Type: React Ref | Object

Supported version: +v4.0.0

Default: undefined

If provided the canvas processing/saving/manipulating function will be assigned as .current property to this passed Object | React Ref to be used/called somewhere else other than the default save button and returns both the final transformed image data object & current design state which are same as params as onSave callback,

The passed object/ref becomes with the following syntax after assigning internally

{
  current: (
    imageFileInfo = {},
    pixelRatio = false,
    keepLoadingSpinnerShown = false,
  ) => ({
    imageData, // An object has the current image data & info
    designState, // An object contains the current design state of the image's editor
    hideLoadingSpinner, // A function hides the loading spinner on calling if not already hidden (useful in case you have provided `keepLoadingSpinnerShown` param with `true` and wants to hide the spinner after finishing some operation from ur side)
  });
}

The function has the following params:

• imageFIleInfo: An object, defines the info of the file to be considered while saving, and contains the following properties:

  {
    name,
    extension,
    quality, // applied in JPEG/JPG/WEBP formats only
    size: { // used in resizing
      width, height
    },
  }

• pixelRatio: A number, that defines the pixel ratio used in transforming/saving the image (higher the ratio, higher the resolution of the saved image till reaching the possible max. resolution for the image, higher the memory used & processing time of saving/transforming).

NOTE: Calling the assigned function will be UI blocker so take care where & when you are calling the function.

updateStateFnRef

Type: React Ref | Object

Supported version: +v4.0.0

Default: undefined

Assigns the update state main function of the plugin inside .current property of the passed object/ref to be used in changing the main state of the application, the function has 1 paramter that could be either (function | object) the function receives the current state object as argument. The object is the new state part, in both types not required to return/pass the whole state object as it gets deep merged with the current state.

NOTE: Be-aware while using this function as it might cause an un-expected behavior and we don't recommend to use it unless you know what you are doing.

useZoomPresetsMenu

Type: Boolean

Supported version: +v4.1.0

Default: true

On clicking on the zoom percentage and having this property set true some zoom presets percentages will be shown for the user to quickly choose some zoom percentage, if set to false the zoom presets won't be shown and only fit percentage will be used as default.

Note: If disableZooming property is true then this property won't have any effect.

disableZooming

Type: Boolean

Supported version: +v4.2.0

Default: false

If true, there will be no zooming functionality available in the plugin & UI related to zooming will be removed.

noCrossOrigin

Type: Boolean

Supported version: +v4.5.0

Default: false

If true, crossOrigin=Anonymous property with its value won't be used in the original image (image to be edited) loading request -- not recommended --.

Disabling the usage of crossOrigin might cause some issues with applying filters or saving the image so it is not recommended to provide it true unless you know what you are doing.

If u face strange behavior with CORS on chromium based browser, please check this issue #319 might be useful for you.

disableSaveIfNoChanges

Type: Boolean

Supported version: +v4.6.0

Default: false

If true, the save button will be disabled till the user does a change on the image, otherwise on loading the editor without having any user's functionality then it will be disabled and user won't be able to save.

Disabling the usage of crossOrigin might cause some issues with applying filters or saving the image so it is not recommended to provide it true unless you know what you are doing.

If u face strange behavior with CORS on chromium based browser, please check this issue #319 might be useful for you.

removeSaveButton

Type: Boolean

Supported version: +v4.7.1

Default: false

If true, the save button get removed from the editor.

resetOnImageSourceChange

Type: Boolean

Supported version: +v4.8.0

Default: false

If true, the editor will reset its design state & saved data on providing a new original image source.

backgroundColor

Type: String

Supported version: +vx.x.x

Default: undefined

The color used as background for the canvas while the image is being edited and won't be considered in the final saved image.

backgroundImage

Type: HTMLImageElement

Supported version: +vx.x.x

Default: undefined

An image that will be shown as background image of the canvas and will be repeated (x & y) and it will be disregarded on saving.

Note: if provided both backgroundImage & backgroundColor, the priority will be for backgroundColor.

Callbacks

onBeforeSave

Type: function(imageFileInfo) {}

Supported version: +v4.0.0

Default: undefined

This function will be fired once the user clicks save button and before triggering the default saving behavior...

If the function returned false then the default saving behavior implemented in the plugin won't be triggered.

This function doesn't work in (cloudimage mode & moreSaveOptions) and the onSave is fired directly.

onSave

Type: function(imageData, imageDesignState) {}

Supported version: +v4.0.0

Default: undefined

it's used for handling the save functionality which is triggered once the user clicks on save button of the saving modal or once clicking the save button if the default behavior is prevented from onBeforeSave function, If you need to keep showing the loading spinner (shown on start saving) till you finish some functionality/operation from your project's side (ex. async uploading file to your server) then you must return a Promise otherwise returning nothing/void is fine.

In imageData parameter you have 2 formats (Base64 string & Canvas HTML element) of saved image, the Canvas HTML element format doesn't support quality chosen while saving from default behavior.

onModify

Type: function(currentImageDesignState)

Supported version: +v4.0.0

Default: undefined

Called after any operation/transformation is applied on the image (ex. Add/change filter, resize the image...etc.).

• currentImageDesignState: An object contains the latest design state of the current state of the plugin.

NOTE: This callback might be triggered multiple times at changing some properties related to same operation/functionality so please make sure you have checked when it's called to understand the behavior you'll have.

onClose

Type: function(closingReason, haveNotSavedChanges) {}

Supported version: +v4.0.0

Default: undefined

Triggered once the user clicks either close/cancel button or back button, if not provided then the closing button won't shown at all.

• closingReason: A string value showcases the place/reason the plugin closed.
• haveNotSavedChanges: A boolean value, true means the user has clicked the close button before saving latest changes otherwise he closed after saving.

Bridges

• Vanilla JS (done)
• React (done)
• Angular (no ETA)
• Vue (no ETA)
• React-native (no ETA)
• Flutter (no ETA)

NOTE: Currently additional docs of bridges are provided in the current page but on having more bridges docs will be moved to separate files.

Bridges docs

Vanilla Javascript

In addition to the main config mentioned above which works for all bridges, the following methods are specific for this bridge only:

render

Type: function render (additionalConfig)

Supported version: +v4.0.0

Initializes/rerenders the plugin with the possibility to provide an additional config properties to the previously provided properties to the same plugin's instance.

terminate

Type: function terminate ()

Supported version: +v4.0.0

Unmounts the plugin's container from the page to be removed.

getCurrentImgData

Type: function getCurrentImgData (imageFileInfo, pixelRatio, keepLoadingSpinnerShown)

Supported version: +v4.0.0

Calling the function will trigger the function responsible for handling/manipulating the current image operations and have the possible final results of the current image data besides the current design state, it's the bridge for the function mentioned here getCurrentImgDataFnRef.

Used By

This project is used by the following companies:

• Scaleflex
• Fast Image Resize

Fork the repoistory, append your company's name with the URL in above format inside the README.md file and make a PR! or create a GitHub issue mentioning (Site's name & domain).

Feedback

Create an issue on github repo. and mention the details there.

Contributing

All contributions are super welcomed!

License

Filerobot Image Editor is provided under MIT License

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Types of changes:

• Added for new features.
• Changed for changes in existing functionality.
• Deprecated for soon-to-be removed features.
• Removed for now removed features.
• Fixed for any bug fixes.
• Security in case of vulnerabilities.
• Improved for improvements done in existing functionality.

Date format: YYYY-MM-DD If we have some "Breaking changes" we can mark it in message by **BREAKING** prefix, like: - **BREAKING**: Some message

v4.9.1 - 2024-12-30

Fixed

• Watermark menu overlay was blocking the UI (#502 & (#514)).

v4.9.0 - 2024-10-27

Fixed

• Resize issue on unlocking ratio lock.
• Crop ratio wasn't considered in re-providing the whole editor's config by default (user had to interact with the canvas) (#493).
• Backend's translation service API.

Added

• Rotate anti-clockwise button in rotation.
• backgroundColor & backgroundImage params to be added as background for the canvas

Improved

• FlipX & FlipY behaviors, now the flip is only related to the edited image but everything else is keeping its state without flipping (#473).
• Update the design lib. (@scaleflex/ui & @scaleflex/icons) packages.

v4.8.1 - 2024-05-16

Fixed

• If crop area is changed on the canvas, and then resized again to the original image's dimensions doesn't consider the dimensions properly.
• Improving the getCurrentImgDataFnRef property by adding default values to some of the needed params inside to avoid rare issues.
• onModify fn. wasn't called on changing the crop to the original area.

v4.8.0 - 2024-05-14

Fixed

• An issue related to exported loadableDesignState which contained wrong finetune's names.
• Default save modal's resize inputs layout on Mozilla firefox browser (#446).
• HSV sliders go outside of the layout on small screens sometimes (#437).
• Cancel button for color picker doesn't revert to the proper color (#435).
• Issue related to zooming using touch screen that happens sometimes.
• Theme's typography issue related to @scaleflex/ui package.

Improved

• Update all the main dependencies (konva, scaleflex/ui & scaleflex/icons) (#461).
• Supporting the new state of undo/redo/reset operations in onModify callback (#444).
• Avoid applying the default value of the finetune's tools on moving to any of them as it is not needed since no difference in results (#445).
• Some UI improvements related to annotations tool (#426).
• Destroying the cloned canvas on saving the current one, expected to improve the repeated savings performance & avoid memory issues.
• Watermark images sizing and integration onto canvas in cloudimage mode.

Added

• resetOnImageSourceChange (#357) - for resetting the image editor design data on changing the current original image source to edit.

v4.7.1 - 2024-01-29

Fixed

• Save button menu options weren't open sometimes.

Added

• removeSaveButton used for showing/removing the save button.

v4.7.0 - 2023-12-28

Fixed

• Zooming behavior in some cases specially applying from zooming factors menu.
• Cropping area continually jumps on doing flip and then getting back to crop.
• some improper issue happen with zooming behavior on zooming-in from phone/touch screens.

Improved

• Resizing fields are more UX friendly.
• Auto fitting the image on resizing by auto zooming.
• Restrict the resizing expand to 10x.
• Avoid flipping watermarks if useCloudimage is true.
• Colorizing the ratio lock of resize tab to be more clear & visible to the user.
• Replace alt text of invalid loaded watermark image.

Added

• onUploadWatermarkImgClick used for customizing the image watermark adding.
• hideTextWatermark hides the add text watermark option and its possibility.
• Support for preview urls of watermark images to load faster and avoid loading images for previewing only.

v4.6.3 - 2023-11-30

Fixed

• Issue of React is undefined in some cases while opening the color picker.

v4.6.1 - 2023-11-30

Improved

• Top & Tools bars Design spaces polishing & improvements.
• enhancing the default label of save button to be save as if there are multiple/more save options, or save if no more saving options.

v4.6.0 - 2023-11-29

Improved

• major design improvements & changes that improves the user interface & experience.
• Save button is disabled till having first change.
• Reset button is available/enabled if any of config.loadableDesignState or config.cloudimage.loadableQuery has value.

Added

• disableSaveIfNoChanges property for disabling save button if no changes there yet.
• Crop.noEffect, Crop.lockCropAreaAt properties for giving more customization to crop functionality.

v4.5.2 - 2023-09-08

Fixed

• Docs. react-konva proper version that works with react 17.
• Can't draw an ellipse inside polygon or rectangle Issue #366
• changing save button label causing shifting problem

Added

• selectAnnotationAfterDrawing property that enables/disables auto selection of drawn annotation using the pen tool.

Improved

• If the watermark image is not loaded due to some reason and user tries to add it as watermark, feedback error will be shown.

v4.5.1 - 2023-06-26

Fixed

• Typescript theme types.

v4.5.0 - 2023-06-09

Fixed

• Crop doesn't work if no action with the canvas's UI (Issue #298).
• Bug of having error on unmounting the component with textarea opened while adding text (Issue #322).
• Resize isn't considered in developer's transform function getCurrentImgDataFnRef (Issue #344).

Added

• noCrossOrigin property changes the option while loading the original image (Issue #344).

Improved

• The add watermark button design & label
• Render function logic in JS version.
• Tabs labels become center aligned & space broken in-case of tab's label with multiple words.
• Typescript types (adding theme object into types & update the updateState function naming in VanillaJs version package's types)
• The loading of original image by waiting a tick for avoiding issues possible to happen with the whole plugin (PR #334).

v4.4.0 - 2023-03-30

Fixed

• Respect defaultSavedImageName in case of providing source property with HTMLImageElement
• Crop transformer is not updated on changing to (original) crop preset if no interaction happened with canvas (#291).

Added

• Backward compatability for react 17.
• defaultSavedImageQuality property for increasing/decreasing the saved image quality whether default save behavior used or not.
• Support adding gallery for image tool to enable possibility to add image from custom/preloaded images image.gallery.
• Support image.disableUpload which disables the possibility to upload image from local device.

Improved

• If image changed, re-extract its name & extension.
• Split react-konva library from dependencies and make it developer installable to determine the version to use.

v4.3.8 - 2023-02-10

Fixed

• Move crossOrigin = 'Anonymous' before .src for avoiding sometimes CORS issue (Issue #242).
• Some filters/finetunes names are changed on saving the image in prod (Issue #266).
• Issue of sometimes the canvas don't draw the main image (Issues #251 & #276).
• 50x50 image and smaller is not working (Issue #220).
• PEN as default TOOL don't work bug (Issue #288)
• Issue of button doesn't have a type (Issue #268).

Improved

• Filters' previews, Consider ratio in image filters preview by center cropping the image (Issue #253).
• If no Annotation component found avoid showing error (possible to happen if provided wrong annotation type from developer side).
• The behavior of color picker, by splitting the saved fill/stroke/shadow colors (Issue #285).
• Update TS types for defaultSavedImageType.
• Update @scaleflex/ui, @scaleflex/icons, konva & react-konva.

Security

• Apply Dependabot suggested fixes/improvements.

v4.3.7 - 2022-08-31

Added

• Multiple rotate option https://github.com/scaleflex/filerobot-image-editor#rotate
• new Watermark scaling options https://github.com/scaleflex/filerobot-image-editor#watermark

v4.3.6 - 2022-07-25

Chore

• Bump version

v4.3.5 - 2022-07-25

Chore

• Bump version

v4.3.4 - 2022-07-25

Chore

• Bump version

v4.3.3 - 2022-07-25

Chore

• Bump version

v4.3.0 - 2022-07-25

Chore

• Support React 18

Fixed

• Tab label text is not centered T7893
• Ellipse doesn't crop on first use in cloudimage T7490
• Topbar on small mobile screen

v4.2.1 - 2022-06-7

Fixed

• Npm versions with peer dependencies

Fixed

• Reset button disregards the default provided crop ratio and replaces with the original image's ratio.

Added

• disableZooming property for disabling zoom functionality & removing zoom-related UI.

Improved

• Changed default value of savingPixelRatio to 4 instead of 8 for avoiding errors in some browsers and faster saving.
• Plugin's styles by adding background for the whole editor & decreasing the bottom spacing of tabs bottom bar on phone screens.
• Keep showing the save loading spinner in case of returning a Promise from onSave and hide it after the promise's resolving/rejection
• Enabling Possibility in getCurrentImgDataFnRef function to keep save loading spinner shown and hide it manually through params.

v4.2.0 - 2022-04-26

Fixed

• Reset button disregards the default provided crop ratio and replaces with the original image's ratio.

Added

• disableZooming property for disabling zoom functionality & removing zoom-related UI.

Improved

• Changed default value of savingPixelRatio to 4 instead of 8 for avoiding errors in some browsers and faster saving.
• Plugin's styles by adding background for the whole editor & decreasing the bottom spacing of tabs bottom bar on phone screens.
• Keep showing the save loading spinner in case of returning a Promise from onSave and hide it after the promise's resolving/rejection
• Enabling Possibility in getCurrentImgDataFnRef function to keep save loading spinner shown and hide it manually through params.

v4.1.1 - 2022-03-29

Fixed

• Typescript types of the plugin react component.

v4.1.0 - 2022-03-28

Added

• Zoom presets menu and its visibility control property useZoomPresetsMenu.

Improved

• Zoom behavior to simulate the zooming percentage to the final image size.

Fixed

• Typescript types of the plugin react component.

v4.0.0 - 2022-03-17

Added

• New features (more annotations, finetunes, more filters) with options for customization.
• New customization properties for fitting different usecases.
• Static CSS class names for HTML elements for styles customization.
• Fully responsive functionality & UI with different screens including phones & touch screens.
• Changing default save behavior and ability to customize from UI, Exporting & loading current design state.

Improved

• Codebase is re-written with new structure.
• Performance & design UX.
• Rotation, crop & filter behaviors

Changed

• Internal canvas library replaced with another library (KonvaJS) which has more features & faster.

Fixed

• Different issues related to past version (v3).

v3.12.17 - 2021-3-19

Fixed

• Issue of cropping dimensions not accurate.

v3.12.16 - 2021-3-05

Added

• exitFullscreenModal callback function inside onSaveAs function for turning the fullscreen off in case it's opened.
• dontCleanQuery property inside cloudimage object to avoid cleaning the query of the passed image's URL and appending it to the cloudimage URL.

v3.12.15 - 2021-2-25

Improved

• The styles of footer for the editor with changing the full-screen icon.
• Moving react v17.0.1 & react-dom v17.0.1 from peerDependencies to dependencies for working with projects have lower versions of react.
• Improving full-screen logic.

Added

• finishButtonLabel for customizing the label of the finish button.
• imageName & imageMime to the returned object in the callbacks passed in default/download mode.

Fixed

• The icon of fullscreen at the footer wasn't shown for some OS users.
• The issue of not changing the width or height of the image before start editing.

v3.12.14 - 2021-2-20

Improved

• Update dependencies (styled-components v5.1.1, React v17.0.1, react-dom v17.0.1 & @babel).
• Switching to automatic runtime for JSX transformation.
• The styles of actions (save, save as, back, close, cancel & apply) buttons.

Added

• replaceCloseWithBackButton for replacing the close icon at the top right with a back button at the top left.

Removed

• closeButtonProps property from the config and replaced with the above replaceCloseWithBackButton.

v3.12.13 - 2021-2-18

Fixed

• The style of saveAs menu buttons.
• Text watermark is not applied in modify/cloudimage mode.
• Prohibit watermark positions square change if no watermark selected.
• Making text watermark default if no watermark images provided.
• Error while uploading the watermark image.
• Styles of un-selected watermark positions square.
• Resize tab's header style.

v3.12.12 - 2021-2-15

Added

• onSaveAs property to filerobot upload mode config for showing & handling Save As New Image Button as sliding item next to save button.
• keepPropsAndMeta property to uploadParams of filerobot upload mode config for keeping the provided imageProperties & imageMeta in the saved image.
• onError for handling the errors returned by the uploading process through filerobot or cloudimage.
• secondary property to theme's button object which is used in the background color of selectable button (ex. saveAs).

Removed

• saveMode property from the filerobot upload mode config.

Fixed

• Rarely happened issue of duplicated canvases when doing some operation.
• Warning of similar keys for canvases.

Improved

• Styles of resizing image before editing warning.
• Moving imageProperties, imageMeta & imageName to uploadParams object of filerobot upload mode.

v3.12.11 - 2021-1-6

Added

• closeButtonProps property to the config for customizing the top left corner close button (ex. label & styles).

Improved

• Plugin's container recognition (for being fullscreened) logic improved.
• Changed the place of fullscreen button to be bottom left corner besides undo/redo operations.

v3.12.10 - 2021-1-4

Added

• Close button (x) at the top left of the editor.

v3.12.9 - 2020-12-23

Fixed

• Watermark's text font selection is now updated with the chosen text font.

Added

• support custom theme's colors for more elements.

v3.12.8 - 2020-12-17

Fixed

• showing the appropriate styles for the plugin while being showing inside page not as modal.

v3.12.7 - 2020-11-23

Fixed

• Styling of adjust controls by having spaces between each control.

v3.12.6 - 2020-11-22

Added

• saveMode, imageProperties, imageMeta & imageName properties into filerobot object of upload mode to be used in determining the save/upload mode of filerobot whether to have a newly created image without the old image's properties & meta, duplicate the image data with the edits (different name with same old image's properties & meta with considering the new edits/design) or replacing the main image with the newly edited one.

v3.12.5 - 2020-11-22

Fixed

• Watermark scaling box stays in its place if watermark is positioned from watermark's positioning squares.
• Image's stroke width input issue of not changing.
• Issue of multiple canvases on saving image.
• Cloudimage's mode generated url.

Improved

• Improved the positioning of watermark in cloudimage mode.
• Adding selectors to the styled components.
• Applying watermark's default position when changing the watermark image.
• Scaling the watermark to 30% + 1.5% spacing when using watermark positioning sqaures and watermark's current size is bigger than 30% of edited image.
• Disabling scaling up the watermark image and allowing scaling down with scaling up to the max. size of the watermark image.

v3.12.4 - 2020-11-19

Improved

• Improved the positioning of watermark in cloudimage mode.
• Avoiding the overwriting of watermark's applying switcher styles.

v3.12.3 - 2020-11-14

Fixed

• Objects scaling on different image sizes issue.
• Canvas moving in while flipping issue.
• Text watermark position changing when undo then redo issue.
• Fixing issue of importing SVGs.

Added

• added lockScaleToPercentage property to watermark object in config for scaling the watermark image and preventing users from re-scaling/re-sizing it.

Improved

• Changing canvases selectors to be able to use multiple instances in same page.
• Using first url of watermark's urls array as the default watermark url if no string url property is provided.

v3.12.2 - 2020-10-22

Fixed

• Showing shapes borders in light color scheme.

Added

• Watermark fonts for using those fonts in text watermark fonts field.
• Theme fonts for supporting those fonts in text & text watermark fonts field (if no fonts provided for watermark object).

v3.12.1 - 2020-10-09

Fixed

• Removing hot loader build paths from the complied library files.

Improved

• Decreasing the library size a bit.

v3.12.0 - 2020-10-07

Fixed

• Watermark or added images quality is not destroyed and it would be relative to the edited image.
• The UI of font family field's dropdown while adding text through phone.
• Importing watermark/image through URL.

Added

• noCapitalStrs prop for disabling the capitalization of strings.
• minCropAreaWidth & minCropAreaHeight props for limiting/fixing the customized crop area with minimum values.

Improved

• Objects (Watermark/shapes...etc) on the image while editing became more accurate to the same positions & looking in produced/saved image which means after saving you will get the same looking (from position & quality of objects) as you are editing.
• Customizing the default element id regarding the used service by appending the used service to the id [|-cloudimage|-uploader].
• Replacing all used unsafe deprecated methods (UNSAFE_*).

v3.11.5 - 2020-10-05

Fixed

• bug with modal id. Added using modal id from config

v3.11.4 - 2020-10-02

Fixed

• Add classes for modal overlay and modal root container on purpose to manage plugin in external projects

v3.11.3 - 2020-09-22

Fixed

• Objects drag & drop error

v3.11.2 - 2020-09-21

Fixed

• Watermark issue when no urls provided in the configurations

Added

• Touch support for moving objects' places

v3.11.1 - 2020-09-16

Fixed

• Watermark spinner is always shown if no watermark urls provided
• Watermark image upload issue

v3.11.0 - 2020-09-03

Fixed

• Text watermark design
• Problem of image saving without adding watermark in upload & modify modes

Added

• showInModal & watermark.defaultText props
• onClose method's status

v3.10.1 - 2020-08-12

Changed

• update fonts

v3.10.0 - 2020-08-12

Added

• draw shapes, images, text with possibility to drag&drop and scale

v3.9.6 - 2020-07-28

Changed

• move back button into config

v3.9.5 - 2020-07-27

Fixed

• FocusPoint console error

Changed

/ FocusPointPreview improvements (sizes)

v3.9.4 - 2020-07-24

Fixed

• go back button visibility

v3.9.3 - 2020-06-18

Fixed

• image sealing
• fixed problem of canvas rendering on SSR

Added

• support for initial crop area (beginCropArea)

v3.9.2 - 2020-06-13

Fixed

• round the radius for cloudimage integration
• using blob as source

Added

• round crop
• SSR support

v3.9.1 - 2020-06-12

Fixed

• onComplete method doesn't call with new callback syntax

v3.9.0 - 2020-06-12

Fixed

• calculating final size when zooming was applied on download
• problem with query sting on generate cloudimage url
• configuration of tools
• fix canvas initilization error

Added

• image sealing
• support for onOpen & onClose methods
• fullscreen mode
• focus point

v3.7.6 - 2020-05-17

Fixed

• problem with localization
• mobile layout

v3.7.2

Added

• Add possibility to not prefix url when already using Filerobot URL

...
filerobot: {
    token: 'xxxx',
    doNotPrefixURL: true
},
...

v3.7.0

Deprecated

• fileUpload watermark param is deprecated. Now there is possibility to switch watermark input among url, gallery, file upload

Added

• possibility to change watermark input among url, gallery and file upload