Home / API Reference

API Reference

Complete reference for all public methods, properties, and static members of the Imigi class.

Static Members

Imigi.init(config)

The primary way to create an editor instance. Returns a Promise that resolves to the initialized Imigi instance.

JavaScript

const editor = await Imigi.init({
  selector: '#editor',
  image: 'photo.jpg',
});

config ImigiConfig required

Configuration object. See Configuration for all options.

Returns Promise<Imigi>

Resolves to the editor instance once the editor is fully loaded and the image (if any) is rendered.

Imigi.version

Static property containing the library version string.

JavaScript

console.log(Imigi.version); // "3.0.5"

Imigi.defaultConfig

Static property containing the default configuration object. Useful for inspecting defaults or extending them.

JavaScript

const config = {
  ...Imigi.defaultConfig,
  image: 'photo.jpg',
};
const editor = await Imigi.init(config);

Instance Properties

Property	Type	Description
`editor.tools`	Tools	Access all tool instances (filter, crop, draw, text, export, history, zoom, objects, etc.).
`editor.fabric`	Canvas \| null	Direct reference to the underlying Fabric.js canvas instance.
`editor.state`	ImigiState	The Zustand state store. Access current zoom, active tool, loading state, and more.
`editor.defaultConfig`	ImigiConfig	The resolved configuration used during initialization.

Editor Control

editor.open(config?)

Opens the editor. In overlay mode, this shows the modal. Optionally pass a partial config to override settings.

JavaScript

// Open with current config
await editor.open();

// Open with a new image
await editor.open({ image: 'new-photo.jpg' });

config Partial<ImigiConfig> optional

Partial configuration to merge with the existing config.

Returns Promise<void>

editor.close()

Closes the editor. In overlay mode, hides the modal. Triggers the onClose callback.

JavaScript

editor.close();

editor.setConfig(config)

Update the editor configuration at runtime without reinitializing.

JavaScript

// Switch to dark theme at runtime
editor.setConfig({
  ui: { activeTheme: 'dark' },
});

// Change language at runtime
editor.setConfig({
  activeLanguage: 'fr',
});

config Partial<ImigiConfig> required

Partial configuration to merge into the current config.

editor.resetEditor(config?)

Fully reset the editor to its initial state. Optionally pass a new configuration.

JavaScript

await editor.resetEditor();

// Reset with a new image
await editor.resetEditor({ image: 'new-image.jpg' });

State Management

editor.getState(customProps?)

Serialize the current editor state to a JSON string. This includes all objects, filters, transforms, and the background image.

JavaScript

const stateJson = editor.getState();

// Save to localStorage
localStorage.setItem('editor-state', stateJson);

// Include custom Fabric.js properties
const stateJson = editor.getState(['myCustomProp']);

customProps string[] optional

Array of additional Fabric.js object property names to include in the serialized state.

Returns string

JSON string representing the complete editor state.

editor.setState(data)

Restore the editor from a previously saved state.

JavaScript

const saved = localStorage.getItem('editor-state');
if (saved) {
  await editor.setState(saved);
}

data string | object required

JSON string or parsed object representing the editor state.

Returns Promise<void>

editor.setStateFromUrl(url)

Load a state file from a remote URL.

JavaScript

await editor.setStateFromUrl('/api/states/draft-1.json');

File Operations

editor.newCanvas(width, height, bgColor?)

Create a new blank canvas, replacing the current content.

JavaScript

await editor.newCanvas(1920, 1080);

// With a custom background color
await editor.newCanvas(800, 600, '#f0f0f0');

editor.uploadAndAddImage()

Opens a file picker and adds the selected image as an overlay object on the canvas (does not replace the background).

JavaScript

await editor.uploadAndAddImage();

editor.uploadAndReplaceMainImage()

Opens a file picker and replaces the main background image with the selected file.

editor.uploadAndOpenStateFile()

Opens a file picker for .json state files and restores the editor to that state.

Tool Access

editor.openTool(name)

Programmatically open a tool panel.

JavaScript

editor.openTool('filter');
editor.openTool('crop');
editor.openTool('draw');

Valid tool names: filter, finetune, crop, resize, draw, text, shapes, stickers, frame, corners, fill, redact.

editor.applyChanges()

Apply the pending changes from the currently open tool (equivalent to clicking the "Apply" button).

editor.cancelChanges()

Cancel the pending changes and close the current tool panel.

editor.togglePanel(name, isOpen?)

Toggle a floating panel (history, objects, export, newImage).

JavaScript

editor.togglePanel('history', true);  // Open history panel
editor.togglePanel('objects');          // Toggle objects panel
editor.togglePanel('export', true);   // Open export panel

Export API

Access export methods through editor.tools.export.

editor.tools.export.save(name?, format?, quality?)

Trigger the save flow. Calls the onSave callback with the exported data.

JavaScript

// Save with defaults
editor.tools.export.save();

// Save as JPEG with custom quality
editor.tools.export.save('my-photo', 'jpeg', 0.85);

name string optional

Filename without extension.

format string optional

'png', 'jpeg', 'json', or 'svg'.

quality number optional

Quality from 0 to 1 (only applies to lossy formats).

editor.tools.export.getDataUrl(format?, quality?)

Get the current canvas content as a base64 data URL string without triggering onSave.

JavaScript

const dataUrl = editor.tools.export.getDataUrl('png');

// Use the data URL
document.getElementById('preview').src = dataUrl;

editor.tools.export.getCanvasBlob(format, data)

Convert the canvas content to a Blob object, useful for uploading to servers.

JavaScript

const dataUrl = editor.tools.export.getDataUrl('png');
const blob = editor.tools.export.getCanvasBlob('png', dataUrl);

// Upload blob to server
const formData = new FormData();
formData.append('file', blob, 'image.png');
await fetch('/api/upload', { method: 'POST', body: formData });

History API

Access undo/redo through editor.tools.history.

Method	Returns	Description
`undo()`	`void`	Undo the last action.
`redo()`	`void`	Redo a previously undone action.
`canUndo()`	`boolean`	Whether undo is available.
`canRedo()`	`boolean`	Whether redo is available.
`getItems()`	`HistoryItem[]`	Get all history entries.
`clear()`	`void`	Clear all history.

JavaScript

// Undo/redo
editor.tools.history.undo();
editor.tools.history.redo();

// Check availability
if (editor.tools.history.canUndo()) {
  editor.tools.history.undo();
}

Zoom API

Access zoom controls through editor.tools.zoom.

Method	Returns	Description
`zoomIn(amount?)`	`void`	Zoom in by `amount` (default: `0.05`).
`zoomOut(amount?)`	`void`	Zoom out by `amount` (default: `0.05`).
`set(level, resize?)`	`void`	Set zoom to a specific level (1 = 100%). Optionally force resize mode.
`fitToScreen()`	`void`	Fit the image to the available screen space.
`canZoomIn()`	`boolean`	Whether further zoom-in is possible (max: 2x).
`canZoomOut()`	`boolean`	Whether further zoom-out is possible.
`currentZoom`	`number`	Property returning the current zoom level.

JavaScript

// Zoom to 150%
editor.tools.zoom.set(1.5);

// Fit to screen
editor.tools.zoom.fitToScreen();

// Read current level
console.log(editor.tools.zoom.currentZoom); // 1.5

Objects API

Manage canvas objects through editor.tools.objects.

Method	Returns	Description
`getAll()`	`FabricObject[]`	Get all objects on the canvas.
`getActive()`	`FabricObject \| null`	Get the currently selected object.
`delete()`	`void`	Delete the currently selected object(s).
`duplicate()`	`void`	Duplicate the currently selected object(s).
`bringForward()`	`void`	Move the selected object up one layer.
`sendBackward()`	`void`	Move the selected object down one layer.
`bringToFront()`	`void`	Move the selected object to the top layer.
`sendToBack()`	`void`	Move the selected object to the bottom layer.
`deselectAll()`	`void`	Clear the current selection.

JavaScript

// Get all objects
const objects = editor.tools.objects.getAll();
console.log(`Canvas has ${objects.length} objects`);

// Delete selected object
if (editor.tools.objects.getActive()) {
  editor.tools.objects.delete();
}

// Layer ordering
editor.tools.objects.bringToFront();

Text & Shapes API

editor.tools.text.add(text, options?)

Add a text object to the canvas.

JavaScript

editor.tools.text.add('Hello World', {
  fontFamily: 'Arial',
  fontSize: 48,
  fill: '#ffffff',
  textAlign: 'center',
});

editor.tools.shape.addBasicShape(name)

Add a shape to the canvas.

JavaScript

// Available shapes
editor.tools.shape.addBasicShape('circle');
editor.tools.shape.addBasicShape('rectangle');
editor.tools.shape.addBasicShape('triangle');
editor.tools.shape.addBasicShape('star');
editor.tools.shape.addBasicShape('arrow');
editor.tools.shape.addBasicShape('line');
editor.tools.shape.addBasicShape('polygon');
editor.tools.shape.addBasicShape('ellipse');

Canvas API

Access core canvas operations through editor.tools.canvas.

Method	Returns	Description
`getMainImage()`	`FabricImage`	Get the main background image object.
`clear()`	`void`	Clear all objects from the canvas.
`getSize()`	`{width, height}`	Get the current canvas dimensions in pixels.

Utility Methods

editor.isDirty()

Returns true if the editor has unsaved changes.

JavaScript

if (editor.isDirty()) {
  const leave = confirm('You have unsaved changes. Leave anyway?');
  if (!leave) return;
}

editor.notify(message)

Show a toast notification inside the editor.

JavaScript

editor.notify('Image saved successfully!');

editor.on(event, handler)

Listen to canvas-level events. See Events for all available event names.

JavaScript

editor.on('object:added', (e) => {
  console.log('Object added:', e.target.type);
});

editor.on('mouse:down', (e) => {
  console.log('Canvas clicked at', e.pointer);
});

editor.get(toolName)

Get a tool instance by name. Alternative to accessing editor.tools[name] directly.

JavaScript

const zoomTool = editor.get('zoom');
zoomTool.zoomIn();

State Store

The editor.state property provides access to the internal Zustand store. Useful for reading reactive state values.

Property	Type	Description
`state.zoom`	number	Current zoom level.
`state.dirty`	boolean	Whether there are unsaved changes.
`state.activeTool`	string \| null	Name of the currently active tool, or `null`.
`state.original`	{width, height}	Original image dimensions.
`state.config`	ImigiConfig	Current configuration.
`state.loading`	boolean	Whether the editor is currently loading.
`state.openPanels`	object	Which panels are open: `{history, objects, export, newImage}`.

State Actions

Method	Description
`state.setZoom(level)`	Update the zoom level in the store.
`state.setDirty(isDirty)`	Mark the editor as having unsaved changes.
`state.toggleLoading(isLoading)`	Toggle the loading state.
`state.setActiveTool(name)`	Set the active tool by name.
`state.togglePanel(name, isOpen)`	Toggle a floating panel.

Keyboard Shortcuts

Shortcut	Action
`Ctrl/Cmd + Z`	Undo
`Ctrl/Cmd + Shift + Z`	Redo
`Ctrl/Cmd + C`	Copy selected object
`Ctrl/Cmd + V`	Paste copied object
`Ctrl/Cmd + D`	Duplicate selected object
`Delete / Backspace`	Delete selected object
`Escape`	Deselect / Cancel current tool
`Arrow keys`	Move selected object by 1px
`Shift + Arrow keys`	Move selected object by 10px