Skip to main content
Unlayer Docs
Version: Latest

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. The editor logs a warning when AI is available without an end-user ID.

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. Editor-specific keys use the image_editor.* prefix. Shared host-credit notices use labels.credits.* keys.

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…',
      'labels.credits.exhausted': 'Vous n’avez plus de {unitLabel}.',
    },
  },
});

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