Home / Getting Started

Getting Started

Everything you need to start using Imigi in your project.

Requirements

Before installing Imigi, make sure your environment meets the following requirements:

Requirement	Minimum Version
Chrome	80+
Firefox	78+
Safari	14+
Edge	80+
Node.js (for npm installation)	16+

Info

Imigi relies on the Canvas API and modern JavaScript features such as async/await and ES modules. Internet Explorer is not supported.

Installation

Choose your preferred package manager or load Imigi directly from a CDN.

Terminal

npm install imigi

Terminal

yarn add imigi

Terminal

pnpm add imigi

Include the UMD bundle directly in your HTML. No build step required.

HTML

<script src="https://unpkg.com/imigi/dist-umd/imigi.umd.js"></script>

Info

When using the CDN, the Imigi object is available globally on window.Imigi.

Quick Start (ES Module)

If you are using a bundler such as Vite, Webpack, or Rollup, import Imigi as an ES module:

JavaScript

import { Imigi } from 'imigi';

const editor = await Imigi.init({
  selector: '#editor-container',
  image: 'path/to/image.jpg',
});

That's it. Imigi will render the editor inside the element matching #editor-container and load the specified image.

Info

Imigi.init() returns a Promise that resolves to the editor instance. Always await it (or use .then()) before interacting with the editor API.

Quick Start (UMD / Script Tag)

If you prefer a zero-build setup, include the UMD bundle via a <script> tag:

HTML

<!-- Container for the editor -->
<div id="editor-container" style="width:100%;height:600px;"></div>

<!-- Load Imigi -->
<script src="imigi.umd.js"></script>
<script>
  Imigi.init({
    selector: '#editor-container',
    image: 'photo.jpg',
  });
</script>

HTML Setup

Below is a complete HTML boilerplate you can copy and paste to get started immediately:

index.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Imigi Editor</title>
  <style>
    body { margin: 0; font-family: sans-serif; }
    #editor-container { width: 100vw; height: 100vh; }
  </style>
</head>
<body>

  <div id="editor-container"></div>

  <script src="https://unpkg.com/imigi/dist-umd/imigi.umd.js"></script>
  <script>
    Imigi.init({
      selector: '#editor-container',
      image: 'https://picsum.photos/800/600',
    });
  </script>

</body>
</html>

Warning

The container element must have explicit dimensions (width and height). If the container has zero height, the editor canvas will not be visible.

Loading an Image

Imigi supports multiple ways to load an image into the editor. Choose the approach that fits your use case.

From a URL

Pass the image URL directly in the configuration:

JavaScript

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

Warning

When loading images from a different origin, you may encounter CORS restrictions. Set crossOrigin: 'anonymous' in your configuration and ensure the server sends the appropriate Access-Control-Allow-Origin headers. See the Security section for details.

From a File Input

Let users pick an image from their device using a standard file input:

JavaScript

const fileInput = document.getElementById('file-input');

fileInput.addEventListener('change', async (e) => {
  const file = e.target.files[0];
  if (!file) return;

  const url = URL.createObjectURL(file);

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

From a Data URL / Base64

You can also load images from a base64-encoded data URL string:

JavaScript

const base64Image = 'data:image/png;base64,iVBORw0KGgo...';

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

Info

Data URLs can be very large. For better performance with large images, prefer loading from a URL or object URL whenever possible.

Creating a Blank Canvas

To start with an empty canvas instead of an existing image, use the blankCanvasSize option:

JavaScript

const editor = await Imigi.init({
  selector: '#editor',
  blankCanvasSize: { width: 800, height: 600 },
});

This creates an 800×600 pixel white canvas. You can then use the drawing tools, add text, shapes, or stickers to build a design from scratch.

Info

When blankCanvasSize is set, the image option is ignored. You can change the canvas background color later using the Fill Tool.

Handling Save

Use the onSave callback to handle the edited image when the user clicks Save:

JavaScript

const editor = await Imigi.init({
  selector: '#editor',
  image: 'photo.jpg',
  onSave: (data, filename, format) => {
    // data is a base64 string or JSON (depending on format)
    console.log('Saved:', filename, format);

    // Example: download the file
    const link = document.createElement('a');
    link.href = data;
    link.download = filename;
    link.click();
  },
});

The onSave callback receives three arguments:

data string

The exported image as a base64-encoded data URL, or a JSON string if the export format is set to 'json'.

filename string

The suggested filename including the file extension (e.g. 'photo.png').

format string

The export format: 'png', 'jpeg', 'webp', 'svg', or 'json'.

Example: Upload to a Server

JavaScript

onSave: async (data, filename, format) => {
  const blob = await fetch(data).then(r => r.blob());
  const formData = new FormData();
  formData.append('image', blob, filename);

  await fetch('/api/upload', {
    method: 'POST',
    body: formData,
  });

  alert('Image uploaded successfully!');
}

Inline vs Overlay Mode

Imigi supports two display modes that control how the editor is rendered on your page.

Inline Mode (default)

In inline mode, the editor renders directly inside the target container as part of the page flow. This is the default behavior.

JavaScript

const editor = await Imigi.init({
  selector: '#editor',
  image: 'photo.jpg',
  ui: {
    mode: 'inline', // This is the default
  },
});

Use inline mode when the editor is a permanent part of the page layout, such as in a dedicated editing view or an admin panel.

Overlay Mode

In overlay mode, the editor appears as a fullscreen modal on top of your page. The user can open it, edit, and then close it.

JavaScript

const editor = await Imigi.init({
  selector: '#editor',
  image: 'photo.jpg',
  ui: {
    mode: 'overlay',
  },
  onClose: () => {
    console.log('Editor closed');
  },
});

// Open the editor later
editor.open();

// Close it programmatically
editor.close();

Overlay mode is ideal when you want users to edit images on demand without leaving the current page, for example when clicking an "Edit" button on a thumbnail.

Feature	Inline	Overlay
Renders inside container	Yes	No (fullscreen modal)
Visible on load	Yes	No (call `editor.open()`)
Close button	No	Yes
Best for	Dedicated editing pages	On-demand editing flows

Info

In overlay mode, the onClose callback fires when the user dismisses the editor. Use it to clean up resources or update your UI.

Next Steps

Now that you have Imigi up and running, explore these guides to unlock its full potential:

Getting Started

Requirements

Installation

Quick Start (ES Module)

Quick Start (UMD / Script Tag)

HTML Setup

Loading an Image

From a URL

From a File Input

From a Data URL / Base64

Creating a Blank Canvas

Handling Save

Inline vs Overlay Mode

Inline Mode (default)

Overlay Mode

Next Steps

Configuration

API Reference

Tools Guide

Integrations