Configuration

Complete reference for all Imigi configuration options.

Basic Options

Top-level properties that control core editor behaviour.

Option	Type	Default	Description
selector Required	string | HTMLElement	—	CSS selector (e.g. '#editor') or DOM element where the editor mounts.
image	string	undefined	URL or data URL of the image to load on initialization. Supports absolute URLs, relative paths, and base64 data URLs.
state	string	undefined	JSON string of a previously saved editor state. Restores all objects, filters, and transformations. Takes precedence over image.
blankCanvasSize	{width, height}	undefined	Creates a blank canvas with the given pixel dimensions instead of loading an image. Useful for creating graphics from scratch.
crossOrigin	boolean	false	Sets crossOrigin="anonymous" on loaded images. Required for exporting cross-domain images. The server must send CORS headers.
watermarkText	string	undefined	Text rendered as a watermark on export only (not visible while editing).
textureSize	number	4096	Maximum WebGL texture size in pixels. Lower on weak devices to prevent memory issues. Common: 2048, 4096, 8192.
baseUrl	string	''	Base URL prepended to all asset paths (filters, stickers, frames). Set when assets live on a CDN or subdirectory.
saveUrl	string	undefined	Endpoint that receives a POST with the exported image data (base64) when the user clicks Save.
activeLanguage	string	'en'	BCP 47 language code for the UI. See Translations for available languages.

const editor = await Imigi.init({
  selector: '#editor',
  image: 'https://example.com/photo.jpg',
  crossOrigin: true,
  watermarkText: 'Draft',
  textureSize: 4096,
  baseUrl: '/assets/imigi/',
  activeLanguage: 'en',
});

UI Configuration

The ui object controls the editor's user interface: display mode, theme, visibility, and default tool.

ui: {
  visible: true,
  mode: 'overlay',
  forceOverlayModeOnMobile: true,
  allowEditorClose: true,
  showExportPanel: true,
  defaultTool: 'crop',
  activeTheme: 'dark',
}

Navigation Configuration

The ui.nav object controls the main tool navigation bar.

ui: {
  nav: {
    position: 'left',
    replaceDefault: true,
    items: [
      { name: 'crop',   icon: 'crop-icon',   label: 'Crop',    action: 'crop' },
      { name: 'filter', icon: 'filter-icon', label: 'Filters', action: 'filter' },
      { name: 'draw',   icon: 'draw-icon',   label: 'Draw',    action: 'draw' },
      { name: 'text',   icon: 'text-icon',   label: 'Text',    action: 'text' },
      {
        name: 'custom',
        icon: '<svg ...>...</svg>',
        label: 'My Action',
        action: () => { console.log('Custom!'); }
      },
    ],
  },
}

Menubar Configuration

The ui.menubar object controls the secondary toolbar (undo, redo, zoom, save).

ui: {
  menubar: {
    position: 'top',
    items: [
      { type: 'button', icon: 'undo',     label: 'Undo',     action: 'undo' },
      { type: 'button', icon: 'redo',     label: 'Redo',     action: 'redo' },
      { type: 'separator' },
      { type: 'button', icon: 'zoom-in',  label: 'Zoom In',  action: 'zoomIn' },
      { type: 'button', icon: 'zoom-out', label: 'Zoom Out', action: 'zoomOut' },
      { type: 'spacer' },
      { type: 'button', icon: 'save',     label: 'Save',     action: 'save' },
    ],
  },
}

Open Image Dialog

The ui.openImageDialog object configures the dialog shown when no image is preloaded.

ui: {
  openImageDialog: {
    show: true,
    replaceDefaultSampleImages: true,
    sampleImages: [
      { url: '/samples/nature.jpg',   thumbnail: '/samples/nature-sm.jpg',   label: 'Nature' },
      { url: '/samples/portrait.jpg', thumbnail: '/samples/portrait-sm.jpg', label: 'Portrait' },
      { url: '/samples/city.jpg',     thumbnail: '/samples/city-sm.jpg',     label: 'City' },
    ],
  },
}

Color Presets

The ui.colorPresets object defines color swatches in color pickers throughout the editor.

ui: {
  colorPresets: {
    replaceDefault: true,
    items: [
      '#000000', '#ffffff', '#f44336', '#e91e63',
      '#9c27b0', '#3f51b5', '#2196f3', '#00bcd4',
      '#4caf50', '#ffeb3b', '#ff9800', '#795548',
      'rgba(0,0,0,0)', // transparent
    ],
  },
}

Tool Configuration

The tools object lets you configure every individual tool with presets, defaults, and constraints.

Filter Tool

Image filter presets (grayscale, sepia, vintage, etc.).

Finetune Tool

Fine-tuning sliders for image adjustments.

Crop Tool

Aspect ratio presets and crop zone behaviour.

Resize Tool

Image resize constraints.

Option	Type	Default	Description
tools.resize.minWidth	number	1	Minimum width in px.
tools.resize.maxWidth	number	10000	Maximum width in px.
tools.resize.minHeight	number	1	Minimum height in px.
tools.resize.maxHeight	number	10000	Maximum height in px.

Draw Tool

Freehand drawing brushes and settings.

Text Tool

Text tool fonts, defaults, and presets.

tools: {
  text: {
    replaceDefaultItems: true,
    defaultText: 'Type something...',
    items: [
      { family: 'Inter',       label: 'Inter',    url: 'https://fonts.googleapis.com/css2?family=Inter' },
      { family: 'Playfair Display', label: 'Playfair', url: 'https://fonts.googleapis.com/css2?family=Playfair+Display' },
      { family: 'Arial',       label: 'Arial' },
      { family: 'Georgia',     label: 'Georgia' },
    ],
  },
}

Shapes Tool

Geometric shapes available in the shapes tool.

Stickers Tool

Sticker categories and images.

tools: {
  stickers: {
    replaceDefault: true,
    items: [
      {
        name: 'brand-logos',
        label: 'Brand Logos',
        icon: '<svg ...>...</svg>',
        items: [
          { url: '/stickers/logo-dark.svg',  label: 'Dark Logo' },
          { url: '/stickers/logo-light.svg', label: 'Light Logo' },
        ],
      },
      {
        name: 'badges',
        label: 'Badges',
        icon: '<svg ...>...</svg>',
        items: [
          { url: '/stickers/sale.png' },
          { url: '/stickers/new.png' },
        ],
      },
    ],
  },
}

Frame Tool

Decorative frames applied around the image.

Fill Tool

Canvas background fill defaults.

Redact Tool

Censoring tool for hiding sensitive areas.

Decorate Tool

Decoration overlay tool for custom images on the canvas.

Import Tool

File import behaviour, allowed types, and size limits.

Export Tool

Default export format, quality, and filename.

Option	Type	Default	Description
tools.export.defaultFormat	'png'|'jpeg'|'json'|'svg'	'png'	Output format. 'json' exports state for restoration.
tools.export.defaultQuality	number	0.92	JPEG quality (0–1). Ignored for PNG.
tools.export.defaultName	string	'image'	Filename (without extension) for download.

Zoom Tool

Canvas zoom behaviour.

Object Defaults

The objectDefaults object sets default properties for newly created objects. Supports global, shape, sticker, and text scopes.

objectDefaults.global

Property	Type	Default	Description
fill	string	'#000000'	Default fill color.
stroke	string	''	Default stroke color. Empty = no stroke.
erasable	boolean	true	Can be erased with eraser brush.
width	number	200	Default width (px).
height	number	200	Default height (px).

objectDefaults.shape

Property	Type	Default	Description
fill	string	'#2196f3'	Shape fill color.
stroke	string	''	Shape border color.
erasable	boolean	true	Can be erased.
width	number	200	Default width.
height	number	200	Default height.

objectDefaults.sticker

Property	Type	Default	Description
erasable	boolean	true	Can be erased.
width	number	150	Default width.
height	number	150	Default height.

objectDefaults.text

Property	Type	Default	Description
fill	string	'#000000'	Text color.
textAlign	'left'|'center'|'right'	'left'	Horizontal alignment.
underline	boolean	false	Underlined by default.
linethrough	boolean	false	Strikethrough by default.
fontStyle	'normal'|'italic'	'normal'	Font style.
fontFamily	string	'Arial'	Font family.
fontSize	number	24	Font size (px).
fontWeight	string|number	'normal'	Weight: 'normal', 'bold', or 100–900.
stroke	string	''	Text outline color.
erasable	boolean	true	Can be erased.

objectDefaults: {
  global: {
    fill: '#333333',
    erasable: false,
  },
  shape: {
    fill: 'rgba(33,150,243,0.5)',
    stroke: '#1976d2',
    width: 300,
    height: 200,
  },
  sticker: { width: 100, height: 100 },
  text: {
    fill: '#ffffff',
    fontFamily: 'Inter',
    fontSize: 32,
    fontWeight: 'bold',
    textAlign: 'center',
  },
}

Object Controls

The objectControls object determines which interactive handles appear on selected objects. Supports global, shape, sticker, and text scopes.

Property	Type	Default	Description
hideTopLeft	boolean	false	Hide top-left resize handle.
hideTopRight	boolean	false	Hide top-right resize handle.
hideBottomRight	boolean	false	Hide bottom-right resize handle.
hideBottomLeft	boolean	false	Hide bottom-left resize handle.
hideRotatingPoint	boolean	false	Hide rotation handle.
hideFloatingControls	boolean	false	Hide floating toolbar (delete, duplicate).
unlockAspectRatio	boolean	false	Allow free resize without preserving aspect ratio.
lockMovement	boolean	false	Prevent dragging. Can still resize/rotate.

objectControls: {
  global: {
    hideRotatingPoint: false,
    hideFloatingControls: false,
  },
  shape: { unlockAspectRatio: true },
  sticker: {
    hideTopLeft: true,
    hideTopRight: true,
    hideBottomLeft: true,
  },
  text: {
    lockMovement: true,
    hideRotatingPoint: true,
  },
}

Callbacks

Callback functions invoked at key lifecycle moments. Passed at the top level of the config object.

const editor = await Imigi.init({
  selector: '#editor',
  image: '/photos/sample.jpg',

  onLoad(editor) {
    console.log('Editor ready!');
  },

  onSave(data, editor) {
    // Upload exported image
    fetch('/api/upload', {
      method: 'POST',
      body: JSON.stringify({ image: data.dataUrl, format: data.format }),
      headers: { 'Content-Type': 'application/json' },
    });
  },

  onClose(editor) {
    if (editor.isDirty()) {
      return confirm('You have unsaved changes. Close anyway?');
    }
  },

  onOpen(editor) {
    console.log('Editor opened');
  },

  onFileOpen(file, editor) {
    console.log('Opened:', file.name, file.size);
  },

  onMainImageLoaded(image, editor) {
    console.log('Image:', image.naturalWidth, 'x', image.naturalHeight);
  },
});

AI Configuration

The ai object configures AI-powered features (generative fill, background removal, smart selection).

// Dev only - never use tokens in production client code
ai: {
  replicateApiToken: 'r8_YOUR_DEV_TOKEN_HERE',
}

// Production - proxy through your backend
ai: {
  proxyUrl: 'https://api.yoursite.com/imigi-ai-proxy',
}

Complete Example

A comprehensive configuration demonstrating all major option groups together.

import Imigi from 'imigi';

const editor = await Imigi.init({

  // ---- Basic Options ----
  selector: '#image-editor',
  image: '/photos/landscape.jpg',
  crossOrigin: true,
  baseUrl: '/assets/imigi/',
  activeLanguage: 'en',
  textureSize: 4096,

  // ---- UI ----
  ui: {
    mode: 'overlay',
    activeTheme: 'dark',
    allowEditorClose: true,
    showExportPanel: true,
    defaultTool: 'crop',
    nav: { position: 'left' },
    menubar: {
      position: 'top',
      items: [
        { type: 'button', icon: 'undo', label: 'Undo', action: 'undo' },
        { type: 'button', icon: 'redo', label: 'Redo', action: 'redo' },
        { type: 'spacer' },
        { type: 'button', icon: 'save', label: 'Save', action: 'save' },
      ],
    },
    colorPresets: {
      replaceDefault: true,
      items: ['#000', '#fff', '#f44336', '#2196f3', '#4caf50', '#ff9800'],
    },
  },

  // ---- Tools ----
  tools: {
    crop: {
      defaultRatio: 16 / 9,
      allowCustomRatio: true,
    },
    resize: { maxWidth: 4000, maxHeight: 4000 },
    draw: { brushSizes: [2, 5, 10, 25, 50] },
    text: {
      defaultText: 'Add your text',
      items: [
        { family: 'Inter',    label: 'Inter' },
        { family: 'Georgia',  label: 'Georgia' },
        { family: 'Courier New', label: 'Courier' },
      ],
    },
    fill: {
      defaultMode: 'solid',
      defaultColor: '#f5f5f5',
    },
    redact: {
      defaultMode: 'blur',
      defaultBlurAmount: 25,
    },
    export: {
      defaultFormat: 'jpeg',
      defaultQuality: 0.85,
      defaultName: 'edited-photo',
    },
    zoom: {
      allowUserZoom: true,
      fitImageToScreen: true,
    },
    import: {
      maxFileSize: 10485760,
      openDroppedImageAsBackground: false,
    },
  },

  // ---- Object Defaults ----
  objectDefaults: {
    text: {
      fill: '#ffffff',
      fontFamily: 'Inter',
      fontSize: 28,
    },
    shape: {
      fill: 'rgba(33,150,243,0.4)',
      stroke: '#1976d2',
    },
  },

  // ---- Object Controls ----
  objectControls: {
    sticker: { unlockAspectRatio: false },
  },

  // ---- AI ----
  ai: {
    proxyUrl: 'https://api.yoursite.com/imigi-ai',
  },

  // ---- Callbacks ----
  onLoad(editor) {
    console.log('Imigi ready');
  },
  onSave(data) {
    fetch('/api/images', {
      method: 'POST',
      body: JSON.stringify({ image: data.dataUrl }),
      headers: { 'Content-Type': 'application/json' },
    });
  },
  onClose(editor) {
    if (editor.isDirty()) {
      return confirm('Discard unsaved changes?');
    }
  },
});