<a href="https://github.com/scaleflex/filerobot-image-editor/blob/master/LICENSE"> <img src="https://img.shields.io/npm/l/filerobot-image-editor?style=for-the-badge" alt="License (MIT)" /> </a> <a href="#installation"> <img src="https://img.shields.io/npm/v/filerobot-image-editor/latest?label=Version&style=for-the-badge&logo=npm" alt="Version" /> </a> <a href="#"> <img alt="GitHub stars" src="https://img.shields.io/github/stars/scaleflex/filerobot-image-editor?style=for-the-badge&logo=github" /> </a> <a href="#installation"> <img src="https://img.shields.io/npm/dt/filerobot-image-editor?style=for-the-badge&logo=npm" alt="Downloads"/> </a> <a href="https://www.scaleflex.com/"> <img alt="Built with love by Scaleflex team" src="https://img.shields.io/badge/%3C%2F%3E%20w%2F%20%E2%99%A5%20by-the%20Scaleflex%20team-6986fa.svg?style=for-the-badge" /> </a> <a href="#installation"> <img alt="Typescript types" src="https://img.shields.io/badge/types-included-blue?style=for-the-badge&logo=typescript" /> </a> <a href="https://github.com/scaleflex/filerobot-image-editor/issues?q=is%3Aissue+is%3Aclosed"> <img alt="GitHub closed issues" src="https://img.shields.io/github/issues-closed-raw/scaleflex/filerobot-image-editor?style=for-the-badge&logo=github" /> </a> <a href="https://github.com/scaleflex/filerobot-image-editor/issues"> <img alt="GitHub open issues" src="https://img.shields.io/github/issues-raw/scaleflex/filerobot-image-editor?style=for-the-badge&color=red&logo=github" /> </a> <a href="https://www.filerobot.com/en/home#gh-dark-mode-only" /> <img src="https://assets.scaleflex.com/Marketing/Logos/Filerobot+Logos/Logo+with+Scaleflex/LOGO+WITH+SCALEFLEX+ON+BLACK+BG.png?vh=619469" alt="Filerobot dark mode Logo" width="300px" /> </a> <a href="https://www.filerobot.com/en/home#gh-light-mode-only"> <img src="https://assets.scaleflex.com/Marketing/Logos/Filerobot+Logos/Logo+with+Scaleflex/LOGO+WITH+SCALEFLEX+ON+WHITE+BG.png?vh=7ae33c" alt="Filerobot white mode Logo" width="300px"> </a> <a href="https://scaleflex.github.io/filerobot-image-editor/">Editor Preview</a> • <a href="https://www.filerobot.com/en/home">Learn more about Filerobot</a> • <a href="https://codesandbox.io/s/holy-resonance-j0n5z">CodeSandbox</a>

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

<a href="https://scaleflex.github.io/filerobot-image-editor/">🔗 DEMO/PREVIEW LINK</a>

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

<hr />

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

<hr />

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

react & react-dom versions	react-konva version
v17.x.x	>= v17.0.1-1 <= v17.0.2-6
v18.x.x	v18.x.x

<details> <summary>Prerequisites Installation (Click to show)</summary>

react, react-dom, react-konva & styled-components:

npm install --save react react-dom react-konva styled-components

</details> <hr />

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!

<hr />

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.

<hr />

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,