Configuration

The Image Editor is configured through the options you pass to createEditor. This page covers the most common customizations — see the API Reference for the full list of options.

User

Pass user to identify the end user using the standalone Image Editor. It authenticates separately from the Email Builder, so unlayer.init({ user }) does not identify users in a standalone createEditor() instance.

window.ImageEditor.createEditor({
  container: '#editor-container',
  image: imageUrl,
  projectId: 123,
  user: { id: 'customer-42' },
  features: { ai: { enabled: true, assistant: true } },
});

Use a stable user.id from your application. AI edits are reported under that ID as end_user_id in the AI credits usage API. Without it, edits are still billed to the project but appear with end_user_id: null.

If your project enables identity verification, also provide the server-generated user.signature. Never expose your project's secret key in browser code. See AI Assistant for attribution and credit reporting details.

Tools

All eight tool tabs are enabled by default: Filter, Crop, Resize, Draw, Text, Shapes, Stickers, and Frame. Rounded corners are configured as corners, but the control appears inside Crop rather than as a separate tab. Flatten layers is a toolbar action, not a configurable tool.

You can disable any tool through features.imageEditor.tools.

Here's an example if you want to disable the Resize tool:

window.ImageEditor.createEditor({
  container: '#editor-container',
  image: imageUrl,
  features: {
    imageEditor: {
      tools: {
        resize: false,
      },
    },
  },
});

Customize Tool Icons

Each tool entry also accepts an object form so you can customize its icon while keeping the tool enabled. The icon field accepts a FontAwesome icon name (with or without the fa- prefix), an image URL (http(s):, data:, or absolute path), or inline SVG markup (must start with <svg). The object form also accepts enabled so you can mix-and-match tool visibility with icon overrides.

window.ImageEditor.createEditor({
  container: '#editor-container',
  image: imageUrl,
  features: {
    imageEditor: {
      tools: {
        filter: { icon: 'magic-wand-sparkles' },
        crop: { icon: 'https://example.com/icons/crop.svg' },
        draw: { icon: '<svg viewBox="0 0 24 24">…</svg>' },
        resize: { enabled: false },
      },
    },
  },
});

When the icon string cannot be resolved, the editor falls back to the default icon for that tool.

Tool Rail Position

The tool rail and its properties panel dock to the right by default. Set dock to move both to the left:

window.ImageEditor.createEditor({
  container: '#editor-container',
  image: imageUrl,
  features: {
    imageEditor: {
      dock: 'left', // 'left' | 'right'
    },
  },
});

Theme

The editor supports a light and a dark theme via the theme option:

const editor = await window.ImageEditor.createEditor({
  container: '#editor-container',
  image: imageUrl,
  theme: 'dark', // 'light' (default) or 'dark'
});

You can switch the theme at runtime — for example, to follow your application's appearance setting — with updateOptions:

editor.updateOptions({ theme: 'light' });

Localization

Set the editor language with the locale option. These locales ship bundled with the editor (no extra network requests): en, es, fr, de, it, pt, nl, ja, ko, zh. The editor falls back to English when a locale is not available.

window.ImageEditor.createEditor({
  container: '#editor-container',
  image: imageUrl,
  locale: 'fr',
});

Custom Translations

You can override any string — or supply translations for a new locale — through the translations option. All keys are grouped under the image_editor.* prefix.

window.ImageEditor.createEditor({
  container: '#editor-container',
  image: imageUrl,
  locale: 'fr',
  translations: {
    fr: {
      'image_editor.toolbar.save': 'Enregistrer',
      'image_editor.tools.filter': 'Effets',
      'image_editor.ai_assistant.placeholder':
        'Décrivez ce que vous souhaitez modifier…',
    },
  },
});

For the full list of translation keys, see the Translation Reference — the keys are shared with the in-builder image editor.