React 19

The React component ImageEditor renders the image editor inside your React application.

InstallationCopy Anchor Link

npm install @layermetry/media-editor

Import the component from @layermetry/media-editor/react.

RequirementsCopy Anchor Link

• React 19.2 or 19.3. The component uses the React of your application to place the editor. The editor itself runs on its own copy of React, which the package carries.
• A bundler that reads the exports field of package.json, such as Vite. The examples on this page run with Vite 8.3.
• A license key. See License keys.

UsageCopy Anchor Link

Render ImageEditor inside an element that has a size. The editor fills that element.

import { ImageEditor } from '@layermetry/media-editor/react';

export default function App() {
  return (
    <div style={{ position: 'fixed', inset: 0 }}>
      <ImageEditor
        licenseKey="YOUR_LICENSE_KEY"
        onExport={(file) => console.log(`Exported ${file.name}`)}
        onClose={() => console.log('The editor was closed')}
      />
    </div>
  );
}

For each complete App.tsx on this page, use a Vite React 19 TypeScript project. Install the package above, replace your main App.tsx with one complete example at a time, and replace YOUR_LICENSE_KEY with a key valid for your origin. Start the development server:

npm run dev

Open the address printed by Vite. The editor fills the browser window in the Usage example; its export and close callbacks log to the browser console. Later JSX excerpts show only the setting or callback being discussed; they are fragments, not standalone components. Keep the required props, imports, helpers, and surrounding UI from the complete file below each excerpt.

The examples that call your backend need the routes and response formats named beside their complete files. Relative routes need your application server or a Vite proxy; npm run dev does not create those routes. Addresses on example.com and provider-key placeholders must be replaced. For content and export examples, supply a small image or create a multi-page design as indicated. These files and servers are not bundled with this page.

licenseKey and onClose are required. The component works inside React's StrictMode.

The component creates the editor once, when it first renders. Later changes to the props reach the running editor without a restart, so the user's work stays on the page. darkMode is the exception: see Light and dark mode.

Launch from a buttonCopy Anchor Link

Show the editor when the user asks for it, and hide it when onClose runs.

import { useState } from 'react';
import { ImageEditor } from '@layermetry/media-editor/react';

async function uploadDesign(file: File) {
  const body = new FormData();
  body.append('design', file);
  const response = await fetch('/api/designs', { method: 'POST', body });
  if (!response.ok) throw new Error(`Upload failed: ${response.status}`);
  console.log(`Uploaded ${file.name}`);
}

export default function App() {
  const [isOpen, setIsOpen] = useState(false);

  if (!isOpen) {
    return <button onClick={() => setIsOpen(true)}>Create a design</button>;
  }

  return (
    <div style={{ position: 'fixed', inset: 0 }}>
      <ImageEditor
        licenseKey="YOUR_LICENSE_KEY"
        onExport={(file) => {
          uploadDesign(file).catch((error) => console.error(error));
        }}
        onClose={() => setIsOpen(false)}
      />
    </div>
  );
}

The editor calls onClose when the user presses the close button, and after Save & Exit. When the component is removed from the page, the editor is removed with it.

For this launch example, provide a POST /api/designs route that accepts the exported file in the multipart design field, or route it to your application server. After Save & Exit, the page removes the editor and the upload runs in your application.

ConfigurationCopy Anchor Link

Pass configuration options as props. Options lists every prop.

Layout and sizingCopy Anchor Link

width and height size the editor's container; omitted values fill its parent.

Use numeric values for pixels, such as width={390}, or CSS strings, such as height="80vh". The complete example below switches between narrow and wide containers and adds a fullscreen button.

Container sizingCopy Anchor Link

A numeric size is in pixels. A string accepts any CSS size, such as '80vh' or 'calc(100vh - 64px)'. Both props default to '100%'. Give the parent a height when you use these defaults. The editor measures its container continuously and adjusts when that container changes size.

Compact layoutCopy Anchor Link

The editor uses the compact layout below 960 pixels and the regular layout from 960 pixels. The container determines the layout, including in a narrow desktop side panel.

The top bar contains Close, Undo, Redo, zoom, and Export. The page list sits below the canvas. The bottom dock contains Media, Text, Elements, Shapes, Stickers, Background, Effects, Resize, and Templates. When the container is narrow, the nine tools do not all fit, and the dock scrolls sideways to show the rest. Tools open in a panel above the dock; drag the bar at the top of a panel up to expand it, or down to close it. Selecting an element replaces the tools with selection actions.

Fullscreen modeCopy Anchor Link

The editor has no fullscreen button. Call requestFullscreen() on its container after a user click or key press. Exit fullscreen before removing that container. To fill the browser window without fullscreen, use position: fixed and inset: 0 on the parent.

Editing outside canvasCopy Anchor Link

Selected or dragged items remain visible in the gray area outside the canvas, with their outside parts dimmed. Resize and rotation handles remain usable. Deselecting an item clips it at the canvas edge. The export contains only the canvas.

Snapping aligns with the canvas, not with other items. Move into canvas is in the right-click menu, respects position locks and takes one undo step. Markers do not appear in exported files.

See Canvas editing for the recovery steps.

ThemingCopy Anchor Link

Theming changes the editor's colors, control fonts, corners, and logo. Canvas content keeps its own styling.

View full size

Apply these settings to match the screenshot:

<ImageEditor
  theme={{
    primary: '#7c3aed',
    secondary: '#7c3aed',
    surface: '#f5f3ff',
    border: '#ddd6fe',
    textPrimary: '#1e1b4b',
  }}
  typography={{
    heading: 'Georgia, serif',
    body: 'Georgia, serif',
    mono: 'Menlo, monospace',
  }}
  radii={{ sm: '2px', md: '4px', lg: '6px', full: '9999px' }}
  logo={LOGO}
/>

ColorsCopy Anchor Link

theme sets the colors of the editor. Name only the roles you want to change. Every other role keeps its default.

<ImageEditor
  theme={{ primary: '#7c3aed', secondary: '#7c3aed' }}
/>

Default: the Layermetry palette in the table below. A value is a CSS hex color, or a color name from the table, such as gray.200.

The video editor accepts the same names and one more, mediaSelected. The image editor ignores mediaSelected, so one color object can serve both editors.

Customization StudioCopy Anchor Link

With showThemeCreator set to true, the palette button opens the Customization Studio. Choose colors, fonts, corners, icons and tool visibility there. Copy settings copies one JSON object. Download .json saves it as editor-settings.json.

The Settings tab starts from your supplied theme, logo, data icons and UI settings. It includes your edits. The file contains no license key or callbacks. React component icons are omitted because the file stores data only. Closing the Studio restores your supplied settings. Copy or download changes before closing it.

Logo edits appear immediately in the editor’s top bar while the Studio is open. Clearing the field removes the logo from the preview. Closing the Studio restores your supplied logo.

The Bar tab previews the real toolbar for each item type. Nothing selected previews the page bar. For a selected-item control, change its label, choose Default, Icon only, Words only or Both, move it up or down, or hide it. These settings are saved in ui.selection.

Tools marked (off by default) enter the rail order only when you enable them. Reordering the rail does not enable those tools. Reset restores the settings you supplied when the Studio opened.

Apply the settings fileCopy Anchor Link

Import the downloaded JSON and spread the whole settings object into the options from your existing host.

import settings from './editor-settings.json';

// Add this spread to the existing editor component.
<ImageEditor {...settings} licenseKey="YOUR_LICENSE_KEY"
  onClose={handleClose} />

The image settings file does not contain enableThemeToggle; the image editor has no user-facing light/dark switch. darkMode selects the base palette for any omitted theme roles.

icons accepts IconData: { svg: '<svg …></svg>' } or { url: '/icons/plus.svg' }. SVG text is limited to 8,192 UTF-8 bytes and cannot contain a script tag, JavaScript URL or event-handler attribute. Icon addresses use HTTPS, image data URLs, relative paths or HTTP on localhost, 127.0.0.1 or [::1]. A refused standard icon keeps the built-in icon with one warning. Custom actions accept icon data only; the standard icon map also accepts React components.

The JSON file contains icon data. It contains no React components. Your page loads the font files named by typography. See Editor settings for complete files and the settings table.

The Studio is a tool for you, the developer. Its button is hidden by default. Show it in your development build only. Only the value true shows it. Default: false.

<ImageEditor
  showThemeCreator={true}
/>

The Studio starts from your supplied settings. Hidden tools are written into ui.toolRail.hidden or ui.dock.hidden. A dark base writes darkMode: true. Reset returns to your supplied theme.

FontsCopy Anchor Link

typography sets the fonts of the editor's buttons, panels, and menus. Each value is a CSS font-family. Your page must load the font files.

<ImageEditor
  typography={{ heading: 'Georgia, serif', body: 'Georgia, serif', mono: 'Menlo, monospace' }}
/>

Default: the editor's own fonts. A key that you leave out keeps its default.

This does not change the fonts that users can pick for text in their designs. See Text.

radii sets the corner rounding of the editor, in any CSS length. Each key is used by one kind of control. sm is for input boxes, such as the Zoom box. md is for the buttons in the top bar and the zoom menu, such as Undo, Redo, Zoom in, Export, and Close. lg is for cards inside a panel, such as the Add Text card. full is for round buttons, such as the template category buttons in the Text panel. A key that you leave out keeps its default. Defaults: sm is '2px', md is '6px', lg is '8px', and full is '9999px'.

<ImageEditor
  radii={{ sm: '2px', md: '4px', lg: '6px', full: '9999px' }}
/>

Light and dark modeCopy Anchor Link

darkMode selects the dark palette. Default: false, the light palette.

<ImageEditor
  darkMode
/>

With theme, darkMode decides which palette your colors change: roles that you do not name come from the dark palette. The editor has no switch for the user. Your application decides the mode. Choose it when the component first renders. If you change darkMode while the editor is open, the editor does not follow completely. When the editor started light, a change to dark updates the colors, and a change back to light updates them again, but the CSS color-scheme of the editor stays light. When the editor started dark, a change to light changes nothing: the colors and the color-scheme stay dark. To change the mode, remove the component and render it again, for example with a key prop that changes with the mode. The editor then starts again.

LogoCopy Anchor Link

logo shows your logo in the top bar. The value is the address of an image: a URL, or a data: URL.

<ImageEditor
  logo="https://example.com/logo.svg"
/>

The logo is drawn at 32 × 32 pixels at the left of the top bar, before the title. In the compact layout it is 24 × 24 pixels, between the zoom buttons and Export. Default: no logo.

UI customizationCopy Anchor Link

Use HTTPS for endpointUrl. HTTP is allowed only on your own computer at the loopback addresses.

The ui prop changes which tools the editor shows, in what order, and with which names. It also controls where AI features appear. Without ui, the editor shows its standard tools.

Apply these settings to match the screenshot:

<ImageEditor
  ai={{ endpointUrl: 'https://api.example.com/ai' }}
  ui={{
    toolRail: {
      // Templates first, then the rest in their usual order. No stickers.
      order: ['templates'],
      hidden: ['stickers'],
      labels: { upload: 'Photos' },
    },
    generative: {
      actions: {
        image: {
          label: 'Create a picture',
          presets: [
            { id: 'product', label: 'Product photo', prompt: 'A product photo on a white table, soft light' },
          ],
        },
        // No AI rewriting of text.
        textRewrite: { enabled: false },
      },
    },
  }}
/>

PanelsCopy Anchor Link

ui.toolRail changes the tool rail on the left, in the desktop layout. ui.dock changes the tool dock at the bottom, in the compact layout. Both take the same three keys:

Default: every tool in the order of the tables below, except the two that are off the rail. See Tools that are off the rail by default.

With createAutomatedContent, the tool rail also has Generate, with the id automated. Hide it with ui.features.automatedContent: false.

An id that the editor does not know is ignored, and the console lists the valid ids. The Stickers tool also disappears when you pass stickers={{ sources: [] }}. See Stickers and GIFs.

To hide the pages strip, the list of pages with Add page, Duplicate page, and Delete page, set ui.chrome.pages to false. It is hidden in the desktop and the compact layout. Use it for an editor that edits one picture.

<ImageEditor
  ui={{ chrome: { pages: false } }}
/>

One ui object fits both editors: ui.chrome accepts timeline, which the video editor reads, and pages, which the image editor reads. Each editor ignores the other key.

Toolbar buttonsCopy Anchor Link

The buttons in the top bar and above the page follow the features that you set up. There is no list to change them one by one:

The Export and Close buttons are always there.

AI featuresCopy Anchor Link

ui.generative decides where each AI feature appears. An AI feature appears only when you pass ai. See AI providers.

<ImageEditor
  ui={{ generative: { actions: { textRewrite: { enabled: false } } } }}
/>

The features of the image editor, and the places where each one appears by default:

ui.features switches all AI generation off with one key: ui={{ features: { 'ai.generate': false } }}.

ui can only remove AI controls. To stop the editor from sending a feature's requests at all, set it to false in ai, for example ai={{ endpointUrl: '/api/ai', imageEdit: false }}. See Per-feature options.

Built-in control listsCopy Anchor Link

On a desktop, one bar above the canvas shows the controls of the selected item, for text, shapes, pictures, stickers, GIFs, labels and several items together. The phone's selection bar uses the same settings. A button shows its current value, for example opacity or font size. When the bar is too narrow, the controls at the end of the default list move into a More menu. Colour, volume, effects and the other value controls open in a panel on the left side. With nothing selected, the bar becomes a page bar with the canvas size, Background, the Save template button when the editor can save templates, the Default locks… button, and a More menu with the lines of the empty-canvas right-click menu.

ui.selection changes the controls of the selected item. The editor has a default list of controls for each type of item. That list is only the starting view. ui.selection is applied after it, so your choice wins. Merge this section into the existing host's ui option.

import type { ImageUiConfig } from '@layermetry/media-editor';

const uiControls: ImageUiConfig = {
  selection: {
    order: ['replace', 'crop'],           // these come first
    hidden: ['delete'],                   // no Delete button
    labels: { replace: 'Swap picture' },  // a new name
    display: { effects: 'icon' },         // a picture only
  },
};

Listed ids come first, in your order, even a control that would wait behind More. The other controls keep their default order. Hidden buttons leave shortcuts and editing actions available. labels renames a control, and the new name is also its tooltip and accessible name. display: 'icon' draws a picture only and keeps the label as the tooltip and accessible name. The desktop bar draws Bold, Italic, Underline, Bring forward, Send backward, Delete as a picture only by default. Set display to 'label' or 'both' to bring the words back. The right-click menu keeps words. Unknown ids are ignored with one warning.

The new ids are replace (a picture), copyStyle and pasteStyle, and group and ungroup for several selected items.

ui.toolbar is still accepted. The bar has no groups now, so the editor translates each group id into the controls that the group held. The group text held font, textAlign and rewriteWithAi. A labels setting for a group has no heading to change, and the order, labels and display of actions (your own buttons) are not applied. The editor prints one console warning that starts with [MediaEditor] ui.toolbar:. Use ui.selection instead.

See Default lists for the real default list of every type of item, and Control ids for the typed id unions.

Tools that are off the rail by defaultCopy Anchor Link

Effects and Background are not on the left rail by default. Reach them from the bar above the canvas: Effects from the bar of the selected item, and Background from the page bar. To put a tool back on the rail, list its id in ui.toolRail.order. A host that already lists every tool sees no change. The phone's dock is not changed by this.

import type { ImageUiConfig } from '@layermetry/media-editor';

const uiRail: ImageUiConfig = {
  toolRail: { order: ['templates', 'effects', 'background'] },
};

Color controlsCopy Anchor Link

Color controls show the current color, your brand colors and 16 default colors. Use the same control for text and label colors, shape fill and stroke, text outline and shadow, text gradients and picture outlines. Open Custom color for the color square, hue strip and HEX, R, G and B fields. The control stays inside the panel or phone sheet.

A steady 3 px line under a toolbar color icon shows its stored color. Mixed colors show a gray dashed line. Your icon, label and display settings still apply. Dragging an item color previews it live. Releasing it saves one change, so one Undo restores the previous color. Escape cancels an unfinished item preview. Selected words in an open text box receive colors through the text editor.

The desktop image color control also has an opacity strip and an A % field. Transparent colors are stored as rgba(…). Opaque colors and controls without opacity use hex.

Generate from the barCopy Anchor Link

With nothing selected, open More and choose Generate text… or Generate image here…. These open the Text panel or Upload Images, with its Generate form already open. With an item selected, Rewrite with AI and Edit with AI open the form in the left panel. For Rewrite with AI and Edit with AI, the selected suggestion previews on the existing item; closing the box keeps it. New-item operations add a separate item through their add action.

For an existing-item edit, closing with ✕ or Escape keeps the selected card. Selecting another item or opening another panel also ends the edit and keeps that choice as one Undo step. Choose Original first to keep the current item unchanged. A new result needs Add to canvas or Set as background. Only one panel is open at a time.

When the required panel is unavailable or hidden by ui.panels, ui.toolRail or ui.dock, the form opens under the bar. Panel placement also respects ui.generative. The floating pill, Cmd+K and the panels’ own Generate buttons keep their existing behavior.

Copy style and paste styleCopy Anchor Link

Copy style takes the look of one item. Paste style gives that look to one or more other items. Both are in the More menu of the bar above the canvas, in the right-click menu, and on the keyboard: Cmd + Option + C and Cmd + Option + V on a Mac, Ctrl + Alt + C and Ctrl + Alt + V on Windows and Linux. The editor matches the physical key, AltGr on Windows still types its character, and holding the keys pastes once. The ids are copyStyle and pasteStyle, so ui.selection can hide, move or rename them.

Copy style needs exactly one selected item that has a style. Text copies its font, size, weight, italic, underline, color, alignment, outline, shadow, color gradient, letter spacing and line height. A shape copies its fill, outline color, outline width and corner rounding. A picture copies the values of the Effects panel, its mask and its outline. Every item copies its transparency. A plain source clears italic, underline, shadow, filters and the mask instead of keeping the target’s old style. A paste is one Undo step. An item of another type gets only the transparency, and locked items are skipped. The editor then shows one short message that says what was left out. The colored plate behind text is not copied. If every selected item is locked, the message is "The selected items are locked."

Custom actionsCopy Anchor Link

customActions adds your own buttons after the built-in controls. Define this complete configuration module, then import customActions and onCustomAction into the host from the UI customization example above.

import type { ImageCustomAction, ImageCustomActionEvent } from '@layermetry/media-editor';

export const customActions: ImageCustomAction[] = [{
  id: 'inspect-selection',
  label: 'Inspect selection',
  placements: ['selection', 'contextMenu'],
  when: { selection: 'any' },
  run(ctx) {
    console.log('Selected items', ctx.items);
    ctx.notify(`${ctx.items.length} item(s) selected.`, 'info');
  },
}];

export function onCustomAction(event: ImageCustomActionEvent) {
  console.log(event.actionId, event.status);
}

Options excerpt: keep the existing host's license key, required callbacks and lifecycle.

<ImageEditor customActions={customActions} onCustomAction={onCustomAction} />

Select at least one item to see Inspect selection. Image custom actions receive ctx.verbs === null in 1.0.0. They can call your services and show notices, but cannot edit through that handle. The undo field is ignored. The list accepts at most 24 actions. Only one custom action runs at a time. A viewer sees none. The customaction DOM event carries the same status payload as the callback. Pass the action list as a property, not an attribute. See Custom actions for the fields, overflow counts and cancellation rules.

Saving and loadingCopy Anchor Link

Your application stores designs as template records. Pass save and list callbacks to connect your storage to the editor.

Pass save and list callbacks to connect the editor to your server:

<ImageEditor
  onSaveTemplate={saveTemplate}
  onGetTemplates={getTemplates}
  templateMetadata={{ metadata: { brand: 'acme' } }}
/>

Saving designsCopy Anchor Link

onSaveTemplate receives { ...metadata, template } when the user saves. Return a promise. When it resolves, the user sees "Template saved". When it rejects, the user sees "Template wasn't saved" and can try again.

<ImageEditor
  onSaveTemplate={saveTemplate}
/>

Default: none. Without onSaveTemplate, the editor hides every save button, and the console says why.

The user saves with the Save template button in the toolbar above the page, or with Save this page as a template in the Templates panel. The editor waits 30 seconds for your promise. After that, it tells the user that it cannot say whether the design was saved.

The value that your promise resolves with is ignored. Only success or failure counts.

templateMetadata.metadata adds your own fields to every save. They arrive next to template, at the top level: { brand: 'acme', template }.

Loading designsCopy Anchor Link

onGetTemplates returns the list of templates. The editor calls it each time the user opens the Templates panel, and when the user presses Refresh. A click on a template loads it onto the page.

<ImageEditor
  onGetTemplates={getTemplates}
/>

Default: none. Without it, the Templates panel says "Template loading is not configured".

A template is one page. Save template keeps the page that is open, and a click on a template in the panel replaces the page that is open. The panel shows a template only when it has scene, a thumbUri, and sceneMode: 'image'. Return the objects that onSaveTemplate received, and they meet these rules.

To open the editor with a design already on the page, pass the template as defaultTemplate. The editor reads it once, when it starts.

<ImageEditor
  defaultTemplate={template}
/>

A template keeps the page size it was made with. templateCanvasPolicy decides what happens when that size differs from the current page:

DraftsCopy Anchor Link

A draft is a design that the user has not finished. Save draft in the export panel saves it through the same onSaveTemplate, with draft: true in the template. The Templates panel then shows a Drafts filter with the number of drafts.

Saving a draft again updates the same record. The first draft save of a design makes a new template.id, and every later draft save of that design sends the same id, from the button or from automatic saving. There is no keyboard shortcut for it. Opening a draft from the Templates panel continues that draft under its own id. Opening another template, the defaultTemplate, or a new blank design starts a new record. A finished template save gets a new id every time. Store drafts by template.id, and replace a record that has the same id.

To save drafts while the user works, set ui.drafts.autosave. Default: false.

<ImageEditor
  ui={{ drafts: { autosave: true } }}
  onSaveTemplate={saveTemplate}
  onGetTemplates={getTemplates}
/>

Autosave starts after the user presses Save draft once. Then each change starts a 30-second wait, and each further change starts the wait again. So a user who keeps working is saved once, 30 seconds after the last change.

Server-side handlingCopy Anchor Link

Store each template as the editor gives it to you, and return the same objects from your list. This Node.js server stores each record as a file:

import { createServer } from 'node:http';
import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';

const FOLDER = './templates';
await mkdir(FOLDER, { recursive: true });

async function readBody(request) {
  const chunks = [];
  for await (const chunk of request) chunks.push(chunk);
  return JSON.parse(Buffer.concat(chunks).toString('utf8'));
}

createServer(async (request, response) => {
  if (request.url !== '/api/templates') {
    response.writeHead(404).end();
    return;
  }
  if (request.method === 'POST') {
    const payload = await readBody(request);
    const template = payload.template ? { ...payload, ...payload.template } : payload;
    if (payload.template) delete template.template;
    if (!/^[\w-]+$/.test(String(template.id))) {
      response.writeHead(400).end();
      return;
    }
    // Store the record exactly as the editor sent it, including fields you do not use.
    await writeFile(`${FOLDER}/${template.id}.json`, JSON.stringify(template));
    response.writeHead(201).end();
    return;
  }
  const files = await readdir(FOLDER);
  const templates = await Promise.all(
    files.map(async (file) => JSON.parse(await readFile(`${FOLDER}/${file}`, 'utf8'))),
  );
  response.writeHead(200, { 'Content-Type': 'application/json' });
  response.end(JSON.stringify(templates));
}).listen(3001);

A template has these fields:

The Template type also declares voiceoverScript. Only the video editor writes it.

The pictures in a design are stored inside scene, unless you pass onUploadAsset. See Asset storage.

Each save also sends a templatesave DOM event, with detail: { template, saved }. Use it to log saves in code that does not do the saving. See Events.

Item lockingCopy Anchor Link

A lock stops some kinds of change to one item. For example, a person can change the words of a headline but cannot move the logo. The person who made the design sets the locks. Your application tells the editor who is editing, and the editor obeys the locks for that person.

Lock rolesCopy Anchor Link

The role prop says who is editing. You choose it for each person. The editor never decides it.

When you pass no role, the role is 'adopter'. A value that is not one of the three names is also read as 'adopter'.

Lock propsCopy Anchor Link

Pass the four lock props to the editor. This example opens the editor for an adopter. It lets that person ask to unlock, records each unlock in your audit log, and locks the position of every item that has no lock of its own:

<ImageEditor
  role="adopter"
  allowUnlock
  onUnlock={handleUnlock}
  defaultLocks={{ move: true }}
/>

When a prop changes while the editor is open, the editor uses the new value at once.

TypeScript names the types ImageEditorRole, ImageLockScopes, ImageUnlockHandler, ImageUnlockEvent and ImageUnlockAnswer. The package also exports ImageLockScope, ImageUnlockRecord and ImageLockManifest. They come from @layermetry/media-editor, @layermetry/media-editor/embed and @layermetry/media-editor/react.

Lock scopesCopy Anchor Link

Each kind of change that a lock can stop has a name, called a scope. A lock is a list of scopes.

add is a lock on the whole design, not on one item. The editor reads it only from the design's default locks. The item lock panel does not show it. The Default locks… panel does.

There are three more scopes: timing, animate and audio. They belong to the video editor. A still design has no timeline, no animation and no sound, so these scopes change nothing in the image editor, and the lock panel does not show them. The image editor keeps them in a design, so a design that the video editor locked keeps its locks after a save here.

Lock fieldsCopy Anchor Link

The locks are stored in the design, so every save carries them:

The editor decides the locked scopes of one item in this order:

1. When isLocked is true, every scope is locked.
2. Otherwise, when the item has a locks object, the scopes in it are locked. An empty object, {}, locks nothing, and the default locks do not apply to that item.
3. Otherwise, the design's default locks apply.

Only the lock menus change these fields. When any other change writes locks, isLocked or unlocks, the editor restores the old value.

Unlocking itemsCopy Anchor Link

An unlock removes scopes from the lock of one or more items. A creator may always unlock. An adopter may unlock only when you pass allowUnlock. A viewer never may. Every unlock follows these steps:

1. The editor checks the role and allowUnlock. When they do not allow the unlock, it is refused, and your onUnlock is not called.
2. The editor calls your onUnlock and waits for its answer. It does this before every unlock, a creator's too.
3. When you allow the unlock, the editor removes the scopes. For an adopter, it also adds an unlock record to each item that lost a scope. An item that had none of the asked scopes locked stays as it is and gets no record. A creator's unlock adds no record.
4. Without onUnlock, the editor unlocks the items when step 1 allows it, and still adds the adopter's record.

Your onUnlock receives one event:

Your answer decides what happens:

Use ref for the id of the entry in your own audit log. The editor keeps a ref only when it is text that is not empty.

An unlock record looks like this:

{ "scopes": ["move"], "at": "2026-10-05T09:30:00.000Z", "role": "adopter", "ref": "audit-1" }

scopes lists the scopes that the unlock removed from this item. at is the time, as a date and time text such as 2026-10-05T09:30:00.000Z. role is the role of the person. ref is present only when your onUnlock gave one.

Saving locksCopy Anchor Link

Each save gives onSaveTemplate two lock fields, next to scene:

A lockManifest looks like this:

{
  "version": 1,
  "defaultLocks": { "move": true },
  "items": {
    "logo-1": { "locks": ["move", "resize", "delete"] },
    "photo-1": { "locks": ["move"] },
    "headline-1": {
      "locks": [],
      "unlocks": [{ "scopes": ["style"], "at": "2026-10-05T09:30:00.000Z", "role": "adopter", "ref": "audit-1" }]
    }
  }
}

items lists only the items that have a locked scope or an unlock record. Each item's locks is the list of scopes that are locked for it, with the design's own default locks applied, never your defaultLocks prop. In this example, photo-1 has no lock of its own, so it shows the default lock move. headline-1 has no locked scope left, but it is listed because of its unlock record. add never appears in an item's list.

When the editor opens a design, it reads defaultLocks back from the record. The locks inside scene are the ones that count.

Checking locks on your serverCopy Anchor Link

The editor runs in the person's browser. A person who controls the browser can change a record before it reaches your server. The lock is protection against mistakes, not security.

Your server can still find a lock that was removed without permission. Keep the lockManifest of the template that a design came from. When an adopter saves the design, compare the two manifests. Accept a lock that disappeared only when the item carries an unlock record for that scope, and the record's ref is in your own audit log. A creator's save is a new version of the template, and a creator's unlock leaves no record, so do not run this check for a creator.

This Node.js route writes each unlock to an audit log, and returns the id that your onUnlock returns as ref:

import { createServer } from 'node:http';
import { appendFile } from 'node:fs/promises';
import { randomUUID } from 'node:crypto';

async function readBody(request) {
  const chunks = [];
  for await (const chunk of request) chunks.push(chunk);
  return JSON.parse(Buffer.concat(chunks).toString('utf8'));
}

createServer(async (request, response) => {
  if (request.method !== 'POST' || request.url !== '/api/unlocks') {
    response.writeHead(404).end();
    return;
  }
  const event = await readBody(request);
  const id = randomUUID();
  // One line per unlock: the id, the time, and the event from onUnlock.
  await appendFile('./unlock-audit.jsonl', JSON.stringify({ id, at: new Date().toISOString(), event }) + '\n');
  response.writeHead(201, { 'Content-Type': 'application/json' });
  response.end(JSON.stringify({ id }));
}).listen(3002);

Your page reaches it at /api/unlocks, for example through the proxy of your development server. Add your own sign-in check, so that only a person who may unlock gets an id.

This function compares the two manifests. It returns one line for each lock that disappeared without an approved unlock:

export function findUnapprovedUnlocks(sourceManifest, savedManifest, auditIds) {
  const problems = [];
  for (const [id, before] of Object.entries(sourceManifest.items)) {
    const after = savedManifest.items[id];
    if (!after) {
      // The item was deleted, or it lost every lock without an unlock record. See the note below.
      if (before.locks.length > 0) problems.push(`${id}: the item or its locks are gone`);
      continue;
    }
    for (const scope of before.locks) {
      if (after.locks.includes(scope)) continue;
      const approved = (after.unlocks ?? []).some(
        (record) => record.scopes.includes(scope) && auditIds.has(record.ref),
      );
      if (!approved) problems.push(`${id}: '${scope}' was unlocked without an approved ref`);
    }
  }
  return problems;
}

For example, the template's manifest has "headline-1": { "locks": ["style"] }. The saved design has the manifest shown in Saving locks, where headline-1 has "locks": [] and an unlock record with "ref": "audit-1". Your audit log holds audit-1, so findUnapprovedUnlocks(source, saved, new Set(['audit-1'])) returns [], and you accept the save. With an empty audit log, it returns ["headline-1: 'style' was unlocked without an approved ref"], and you refuse the save. auditIds.has(record.ref) is false for a record without ref, so such a record never approves an unlock.

An item that is missing from the saved manifest was deleted, or lost every lock without an unlock record. The manifest alone cannot tell these two apart, so the function reports both. When delete was not locked on that item, read scene to see whether the item is still there before you refuse the save.

Lock controlsCopy Anchor Link

A locked item shows a small lock badge at its top-right corner. The badge has the same size at every zoom, and every role sees it. It never appears in an exported picture, a template preview or a page thumbnail. An item whose select scope is locked cannot be selected by an adopter or a viewer.

A creator finds Lock… on the lock button of the canvas toolbar when items are selected, and Default locks… when nothing is selected. An adopter finds Unlock there when you pass allowUnlock and a locked item is selected. On a phone, the same entries are on the selection bar. The right-click menu has no lock entries. A person who may not use an entry does not see it. The lock panel has one switch per scope, and the buttons Lock everything and Unlock everything. Lock everything leaves select unlocked, so that an adopter can still select the item and ask to unlock it. Turn on the Selecting switch to lock select too.

The image editor has no editor API. The menu entries above are its only way to lock and unlock.

When the editor refuses a change, it shows a short notice with the title "Locked":

Asset storageCopy Anchor Link

The pictures in a design can live in your own storage. You pass onUploadAsset, the editor gives it each picture as a File, and your code returns the permanent address. The design then refers to that address.

Without onUploadAsset, the pictures are saved inside the design as data: URLs. This works, but it makes each saved template large.

UploadsCopy Anchor Link

onUploadAsset(file, ctx) returns a promise of { url }. The editor calls it when the user saves a template or a draft: once for each picture in the design, and once for the small preview picture of the template.

<ImageEditor
  onSaveTemplate={async ({ template }) => console.log(`Saved template ${template.id}`)}
  onUploadAsset={uploadAsset}
  assetMetadata={{ workspace: 'marketing' }}
/>

Default: none. A rejected promise stops the save, and the user sees "We couldn't store this design's media, so nothing was saved."

ctx describes the file:

The context type is the same in both editors, so one onUploadAsset function fits both. It also declares source: 'recorded', take, and punchIn, which only the video editor's voiceover recorder sends. The image editor never sends them.

assetMetadata adds your own text fields to every ctx, for example a workspace or a customer id. The editor's own fields win if a name is the same.

<ImageEditor
  assetMetadata={{ workspace: 'marketing' }}
/>

A picture that your storage returns must allow cross-origin requests, because the editor draws it on a canvas.

Loading stored picturesCopy Anchor Link

When a template is loaded, an address that starts with http is used as it is. For other stored values, the editor asks resolveAssetUrl, then tries assetBaseUrl:

<ImageEditor
  resolveAssetUrl={async (stored) => {
    const response = await fetch(`/api/signed-url?key=${encodeURIComponent(stored)}`);
    return (await response.json()).url;
  }}
/>

When onUploadAsset returns a storage key instead of a web address, the picture keeps your key in the design, and the design holds no picture bytes. A generated picture added to the canvas, from Edit with AI, or from Generate background holds the key at once, so the save that follows sends nothing to onUploadAsset for it. A picture the user added from the computer is different: while the design stays open, each save sends it to onUploadAsset again, also when your code returned a web address for it. When the design opens again, the editor loads the picture from the key through resolveAssetUrl, or assetBaseUrl.

Keeping pictures inside the designCopy Anchor Link

inlineTemplateMedia saves every picture inside the design, even when you pass onUploadAsset. Default: false.

<ImageEditor
  inlineTemplateMedia
/>

Generated mediaCopy Anchor Link

AI services may return temporary picture URLs. Generated pictures pass through onUploadAsset with source: 'generated'; the design uses the reference your host returns.

For these uploads, ctx also has:

If onUploadAsset is missing or fails, the picture keeps the address of the AI service until the next save. Then the editor stores it like any other picture.

Temporary assetsCopy Anchor Link

A picture that the user uploads stays inside the browser as a data: URL until the design is saved. Nothing is sent to your server when the user adds a picture.

When the user saves, each temporary picture, and each picture from an AI service, goes to onUploadAsset. Without onUploadAsset, it is saved inside the design. Pictures that already have an http address from your storage are not uploaded again.

The exported file that onExport receives is separate from these assets. See Export.

Stock mediaCopy Anchor Link

The editor can search Pexels and Unsplash for photos, and GIPHY for stickers. You connect each service with your own account. Each one is off until you configure it.

This example connects all three through your own server, so that your keys stay on the server:

<ImageEditor
  stockMediaApis={{
    pexels: { endpointUrl: 'https://api.example.com/pexels' },
    unsplash: { endpointUrl: 'https://api.example.com/unsplash', showAttribution: true },
  }}
  stickers={{
    sources: [builtInStickers(), giphyStickers({ endpointUrl: 'https://api.example.com/giphy' })],
  }}
/>

Each service takes exactly one of three connections:

A searchFn receives search parameters such as query, page, and perPage. It also gets mediaType (always "image" here), and orientation when the editor asks for one. When the panel first opens, query is an empty string for Pexels and "nature" for Unsplash. Return { results, total, total_pages }, using the exported StockPhoto type:

Unmodified Pexels and Unsplash responses are also accepted. The editor validates each page: it skips an item missing id or url and logs the omission. A response without a result list appears as a service error.

A setting that names none, or more than one, of apiKey, endpointUrl, and searchFn turns off only that service. Its panel says, for example, "Unsplash photos are not available.", and the console says which setting is wrong.

PexelsCopy Anchor Link

stockMediaApis.pexels connects Pexels. Default: none, and the Pexels tab does not appear.

<ImageEditor
  stockMediaApis={{ pexels: { endpointUrl: 'https://api.example.com/pexels' } }}
/>

UnsplashCopy Anchor Link

stockMediaApis.unsplash connects Unsplash. Unsplash requires that the photographer's name is shown, so showAttribution: true is required. Default: none, and the Unsplash tab does not appear.

<ImageEditor
  stockMediaApis={{ unsplash: { endpointUrl: 'https://api.example.com/unsplash', showAttribution: true } }}
/>

Photo creditsCopy Anchor Link

A stock photo keeps its photographer's credit after the user places it. The placed item carries attribution, which is saved with templates and drafts.

When the design holds a stock photo with a credit, the Export panel shows two switches:

The user's choice is saved with the design, and it can be undone. showAttributionOverlay and includeAttributionInExport set the starting value of each switch. Both are false by default.

To show credits your own way, hide a switch. A hidden switch always follows your prop:

<ImageEditor
  ui={{ exportOptions: { hidden: ['photoCreditsOverlay', 'photoCreditsInExport'] } }}
/>

stockMediaApis.pexels.showAttribution: false hides the photographer's name on the Pexels photo tiles. Unsplash tiles always show the name, because Unsplash requires it.

GIPHYCopy Anchor Link

GIPHY is a source of stickers. You connect it in the stickers prop with giphyStickers, not in stockMediaApis. Default: the built-in stickers only.

<ImageEditor
  stickers={{ sources: [builtInStickers(), giphyStickers({ endpointUrl: 'https://api.example.com/giphy' })] }}
/>

See Stickers and GIFs for what the user sees.

Where providers appearCopy Anchor Link

View full size

A search shows 15 photos at a time, and Load More shows the next 15. The editor asks for photos in the shape of the page: landscape, portrait, or square.

AI providersCopy Anchor Link

The ai prop switches on the AI features of the image editor and says where their requests go. Without ai, the editor shows no AI control and sends no AI request.

The image editor has five AI features: text generation (text), text rewriting (textRewrite), image generation (image), AI image editing (imageEdit), and shape generation (svgPath). See UI customization for where each appears.

ai takes exactly one of three connections: endpointUrl, requestFn, or hosted. With none, or with more than one, AI stays off and the console says why. Hosted AI is coming soon and available only with an enterprise licence from Layermetry.

Hosted serviceCopy Anchor Link

Use your own endpointUrl or requestFn for generation. hosted: true sends AI requests to Layermetry. Hosted AI is coming soon. Available only with an enterprise licence from Layermetry.

<ImageEditor
  ai={{ hosted: true }}
/>

With an enterprise licence from Layermetry, hosted: true sends POST https://api.layermetry.com/kloudleadsai/ai/proxy with your license key in the x-license-key header. Hosted AI is coming soon. Use your own endpointUrl or requestFn for generation and your own mediaApiUrl for background removal; eligible hosted setups use Layermetry’s background-removal service when no media address is set.

When the account that pays for AI has no credits left, a request is refused with ai-credits-exhausted. When the plan does not include a kind of AI work, it is refused with meter-off. Both can carry a top-up address for your own interface. See Top-up address.

Proxy URLCopy Anchor Link

endpointUrl sends AI requests to your own server. Your server calls the AI provider with your provider key, so the key never reaches the browser.

<ImageEditor
  ai={{ endpointUrl: 'https://api.example.com/ai' }}
/>

The editor sends POST with a JSON body, and does not send your license key. See Custom AI endpoint for the request and the response your server returns.

Request functionCopy Anchor Link

requestFn passes the initial generation request and an AbortSignal to your function. Return the response, or a job handle whose status URL the SDK polls. Use your function to add headers, such as a sign-in token, or to call your own SDK.

<ImageEditor
  ai={{ requestFn: requestAI, limits: { maxPerSession: 20 }, image: { maxPerSession: 2 } }}
/>

The request and the response are the same as for endpointUrl. Pass signal to fetch: the editor aborts the request when the user closes the box.

When your function throws, the user sees "Generation failed" and can try again.

Session limitsCopy Anchor Link

limits.maxPerSession sets how many AI requests one editor may send while the page is open, for all features together. Default: no limit.

<ImageEditor
  ai={{ endpointUrl: 'https://api.example.com/ai', limits: { maxPerSession: 20 } }}
/>

A feature can have its own limit, in the same way: image: { maxPerSession: 2 }. The box shows how many requests are left. When none are left, it says "Generation limit reached", and no request is sent. Every request that the editor sends counts, also one that fails, because a failed request can still cost money.

The editor counts in the browser, and a new page starts again at zero. A user can change the count in their own browser, so this limit protects against mistakes, not against abuse. Enforce your real limits on your server.

Per-feature optionsCopy Anchor Link

Each feature takes false, true, or an object. false switches the feature off. true, or leaving the feature out, switches it on.

<ImageEditor
  ai={{
    endpointUrl: 'https://api.example.com/ai',
    textRewrite: false,
    image: { maxPerSession: 5 },
    svgPath: { transport: { endpointUrl: 'https://shapes.example.com/ai' } },
  }}
/>

An object for one feature can have:

A key that the editor does not know turns AI off, and the console names the key: "ai.<key> is not a setting this version knows."

Saving generated resultsCopy Anchor Link

ai.generatedStore.onSave receives text results when they are generated. File results use saveFiles: 'all' by default; when you provide onUploadAsset, the file uploads before its record is pushed. Set saveFiles: 'used' to wait until a file is placed. The list matches records by userId and brandId; other scope fields are carried but not compared. See Save generated results for the details, flow diagram, defaults and host checklist.

Generation resultsCopy Anchor Link

The first returned suggestion is selected automatically. For Rewrite with AI and Edit with AI, it appears on the existing item. Click a different card to compare it. Leaving the box keeps the selected card as one editing action and one Undo step. This includes ✕, Escape, Enter from the results, changing selection or opening another panel. Choose Original before leaving to make no change.

The text card says Original (your text now). A returned wording identical to it says Same as your text. Picture edits label the source Original. If the target was deleted, the editor says That item was deleted, so the change was not kept.

Generate more appends suggestions using the previous request. Try again replaces the current choices. The count excludes Original and states the number actually returned. The SDK sends the selected field values to your host through the configured schema, including any sendAs names. If your service returns fewer suggestions than requested, handling that count belongs to your service; the editor does not create extra answers.

For a new result shown in the box, the add action depends on its destination:

In the Text panel, Generated uses the same list as Elements. With no text selected, selecting a text result adds it. With editable text selected, choose Replace selected to keep its font family, font size and position, or Add as new. Replacement is one Undo step. Rewriting clears per-letter style ranges; the font family, font size and position remain. Locked text has no Replace selected action.

The toolbar action Rewrite with AI opens the Text panel form in rewrite mode. With selected text, the form can change the words or put them in a template; + New starts a separate text item.

Custom AI endpointCopy Anchor Link

With ai={{ endpointUrl }} or ai={{ requestFn }}, your code handles the image editor's AI requests. The following contract describes the request that the editor sends, the response it reads, and the errors it understands. See AI providers for the connection itself.

Pass the endpoint URL as ai.endpointUrl. Route /ai to the Node.js server below, or deploy it on your origin:

<ImageEditor
  ai={{ endpointUrl: '/ai' }}
/>

Request formatCopy Anchor Link

The editor sends POST to your endpointUrl, with Content-Type: application/json. It does not send your license key. With requestFn, your function receives the same object.

{
  "type": "image",
  "prompt": "A paper kite over a green hill",
  "input": { "operation": "image", "prompt": "A paper kite over a green hill" },
  "options": { "action": "create", "provider": "…", "count": 1 }
}

Every request of the image editor carries options.provider, the name of a vendor. The editor names that vendor for the reference backend, which reads it. Your server can ignore provider and choose its own vendor and model. The examples on this page show its value as "…".

input.operation is one of five values in the image editor:

Response formatCopy Anchor Link

Answer with status 200 and { items: [...] }. Each item’s fields depend on input.operation:

Return each suggestion as an object with a nonempty text field inside items. This shape works with both built-in providers and custom models.

Each url in items is an https address that allows cross-origin requests, or a data: URL. The editor downloads the picture.

Each pathData in items is the d attribute of an SVG path, in a box of about 100 by 100 units. The SDK refuses path data that does not start with M or m. The editor leaves out an outline that the browser cannot draw.

A complete endpointCopy Anchor Link

This endpoint handles every image editor request. It runs on port 5178. Its small functions return fixed results. Replace them with calls to your AI vendor. Serve the endpoint from the same site as the editor, or add CORS headers.

import http from 'node:http';

// Replace these functions with calls to your AI vendor. Keep the vendor key on this server.
async function writeSuggestions(prompt, count) {
  return Array.from({ length: count }, (_, i) => `${prompt} (${i + 1})`);
}
async function makePicture(prompt, sourceDataUrl) {
  return 'https://cdn.example.com/pictures/sample.png';
}
async function makeShapeOutline(prompt) {
  return 'M 50 5 L 95 95 L 5 95 Z';
}

// Turns one request of the editor into the answer the editor reads.
async function answer({ prompt, input, options = {} }) {
  switch (input.operation) {
    case 'text':
    case 'textRewrite': {
      const texts = await writeSuggestions(prompt, options.count ?? 3);
      return { items: texts.map((text) => ({ text })) };
    }
    case 'image':
    case 'imageEdit':
      return { items: [{ url: await makePicture(prompt, input.source?.dataUrl) }] };
    case 'svgPath':
      return { items: [{ pathData: await makeShapeOutline(prompt) }] };
    default:
      return null;
  }
}

function send(response, status, body) {
  response.writeHead(status, { 'Content-Type': 'application/json' });
  response.end(JSON.stringify(body));
}

http
  .createServer(async (request, response) => {
    if (request.method !== 'POST' || request.url !== '/ai') return send(response, 404, {});
    // Check the user's session here, before you spend money on a request.
    let raw = '';
    for await (const chunk of request) raw += chunk;
    const aiRequest = JSON.parse(raw);
    try {
      const result = await answer(aiRequest);
      if (!result) {
        const message = `This server does not handle ${aiRequest.input.operation}.`;
        return send(response, 400, { error: { code: 'invalid-input', message } });
      }
      send(response, 200, result);
    } catch (error) {
      send(response, 502, { error: { code: 'transport-failed', message: error.message } });
    }
  })
  .listen(5178);

Run it with Node.js 18 or later: node server.mjs.

For imageEdit, the editor reads the picture itself and sends it as input.source.dataUrl, a data: text such as data:image/png;base64,… (a JPEG picture keeps its own type), so your server does not have to fetch an address. options.image holds the same text, and options.size is the size that is nearest to the shape of the picture: 1024x1024, 1536x1024, or 1024x1536. Send the picture and prompt to your vendor's picture editing service, and respond with { items: [{ url }] }, as for image.

Error codesCopy Anchor Link

To refuse a request, respond with a status of 400 or higher and this JSON body:

{ "error": { "code": "limit-reached", "message": "You have made 20 pictures today. Try again tomorrow." } }

The editor shows a title for the code, and your message under it. A code that is not in the table below, or an answer without a JSON body, shows "Generation failed" and "AI request failed (HTTP 502)." with the status. For ai-quota-exceeded, ai-credits-exhausted, and meter-off, the editor shows fixed words instead of your message, and writes your message to the browser console. See AI errors.

Send ai-credits-exhausted with HTTP 402 when the account that pays for AI has no credits left, and meter-off with HTTP 403 when the plan does not include this kind of AI work. With either, you can add topUpUrl to error: the https address where the account buys more credits. The editor passes it to your code as error.topUpUrl and shows no link itself. See Top-up address.

See Error codes for every code, including the ones that the editor and the Layermetry service produce.

An answer with status 200 that is not JSON shows "The answer could not be read as JSON." A request that cannot reach your server shows "Generation failed". The user can press Try again.

EventsCopy Anchor Link

The editor tells your code about four moments: a design is saved, a design is exported, the editor closes, and something goes wrong. You receive them as callback props. The custom element also sends them as DOM events. The React component does not: see the note under the table.

Pass callbacks directly to ImageEditor:

<ImageEditor
  onSaveTemplate={saveTemplate}
  onLicenseState={(report) => console.log(report.state.status, report.reference)}
/>

The DOM events bubble, and they cross shadow DOM boundaries, so a listener on document also receives them.

Use the callback props in React. The React component does not send the export event or the close event. The one exception is templatesave, which also reaches document. See Save.

SaveCopy Anchor Link

onSaveTemplate({ ...metadata, template }) saves the design. The editor waits for the promise that it returns, so a DOM event cannot replace it. See Saving and loading.

After each save, the element also sends templatesave, with detail: { template, saved }. saved is false when the save failed or took more than 30 seconds. template is null when the editor could not prepare the design.

ExportCopy Anchor Link

onExport(file, extras) receives the finished design as a File. Its name looks like exported-image- followed by an id, and its extension follows the format. See Export for the formats.

<ImageEditor
  onExport={(file) => console.log(`${file.name}: ${file.size} bytes, ${file.type}`)}
/>

extras is present when the user presses Share, or when the editor was opened with a defaultTemplate. extras.email is { to, name }: the address and the name that the user typed. extras.templateID is the id of the defaultTemplate. Read each field with a check, such as extras?.email?.to.

callback is an older name for onExport. The editor calls both, so use only one of them.

The custom element sends one export event for each export. event.detail is the File. The extras object is not in the event: read it from the second argument of onExport.

The Download button in the export panel saves the file on the user's computer and calls no callback.

CloseCopy Anchor Link

onClose() is required. The editor calls it when the user presses the close button in the top bar, and after Save & Exit or Share. Remove or hide the editor when it runs.

<ImageEditor
  onClose={() => setIsOpen(false)}
/>

The custom element also sends a close event. Do not read its detail: after Save & Exit it is empty, and after the close button it is the editor's own click event.

The close button does not ask the user to save first. Use the draft controls and Saving and loading to preserve unfinished designs.

ErrorsCopy Anchor Link

The editor has no single error callback. Each kind of problem reaches you in its own way:

<ImageEditor
  onLicenseState={(report) => {
    if (report.state.status === 'blocked') {
      console.error(`License blocked (${report.state.reason}): ${report.reference}`);
    }
  }}
/>

report.reference is a short line for your support team. It never contains the license key. See Error codes for every reason.

Handling the exportCopy Anchor Link

The editor calls onExport with the finished design as a File, when the user presses Save & Exit in the export panel. The file has the format that the user selected there.

<ImageEditor
  onExport={handleExport}
/>

The Download button in the export panel saves the file on the user's computer instead, and does not call onExport. See Export.

ContentCopy Anchor Link

TextCopy Anchor Link

Text boxes hold the words of a design. The user picks the font, size, color, and alignment, styles single words, and adds outline, shadow, and gradient. Ready-made text templates and AI help write the words.

Text works with no setup. Three props add more:

<ImageEditor
  googleFonts={{ endpointUrl: '/api/fonts' }}
  templateMetadata={{
    metadata: {},
    textStyles: {
      headline: {
        textStyleName: 'Brand headline',
        fontFamily: 'Montserrat',
        fontSize: 64,
        fontWeight: 700,
        lineHeight: 1.1,
        fontStyle: 'normal',
        textDecoration: 'none',
      },
    },
  }}
  ai={{ endpointUrl: 'https://api.example.com/ai' }}
/>

Text panelCopy Anchor Link

The Text panel is ordered as follows: a selected-text strip when one item is selected; the AI control (Generate with AI, or Rewrite with AI and + New with text selected); Brand styles when a brand is active; Add text (Heading, Subheading and Body text); Styles (four previews and See all); and Generated. Sections fold. The Text styles toolbar control opens this panel at Brand styles.

Text boxesCopy Anchor Link

Press Add text in the toolbar above the page. This opens the Text panel, and it does not add a text box by itself. In the panel, press Add Text. The Text panel offers Heading (48 px), Subheading (28 px) and Body text (18 px). When a brand is active, the tiles use its Title, Subtitle and Body styles.

Double-click a text box to type in it. Enter ends the editing, and Shift+Enter starts a new line. Esc, or a click outside the box, also ends the editing.

When a text box is selected, the toolbar above the page shows:

FontsCopy Anchor Link

Select a text box and press the font button in the toolbar. The Font panel lists font families by category, with a search field. Open a family to choose a weight or italic.

View full size

Without the whole catalog, the panel lists 25 popular families: Roboto, Open Sans, Lato, Montserrat, Poppins, Inter, Nunito, Work Sans, Oswald, Merriweather, Playfair Display, Lora, PT Serif, Libre Baskerville, Bebas Neue, Anton, Righteous, Alfa Slab One, Pacifico, Satisfy, Dancing Script, Caveat, Roboto Mono, Source Code Pro, and JetBrains Mono.

The panel can also list the whole Google Fonts catalog, about 1,500 families, which the user can search. You choose where that list comes from with googleFonts. It takes exactly one of three ways, and none of them puts a Google key in the page:

Without googleFonts, the panel uses its built-in families. If you provide both licenseKey and mediaApiUrl, it requests the font list from your media server and falls back to built-in families if that request fails. A setting that names two ways, or none, prints one console line and uses the built-in families.

Your server or your function answers with the same JSON as the Google Fonts Developer API: an items list in which each entry has family, variants, and category. Other fields are ignored. Your function receives an AbortSignal, which fires when the panel closes before the answer arrives:

<ImageEditor
  googleFonts={{ requestFn: loadFonts }}
/>

With hosted, endpointUrl, or the old key, the editor keeps a good answer for as long as the page is open, so opening the panel again makes no second request. With requestFn, the editor calls your function again each time the Font panel opens. The browser downloads each chosen font from Google Fonts, which needs no key.

googleFontsApiKey is deprecated. It still works, but it sends your Google key in a request from the browser, where anyone who opens the page can copy it. When you pass both, googleFonts wins and the key is not sent. On a page that is not on localhost, the editor prints one console warning about the key. If you keep the key, restrict it by HTTP referrer in Google Cloud Console.

Text style controlsCopy Anchor Link

The Text styles control in the canvas toolbar opens the Text panel at Brand styles. There is no separate Text Styles panel. When text is selected, the Styles section also offers size presets (H1 32 px, H2 28 px, H3 24 px, H4 20 px, H5 18 px, Normal 16 px) and case controls (ABC, abc, Abc). See Text for the current panel flow.

Brand text stylesCopy Anchor Link

templateMetadata.textStyles appears in Brand styles in the Text panel when a brand is active. A click applies the style to the selected text, or adds text in that style when nothing is selected.

<ImageEditor
  templateMetadata={{
    metadata: {},
    textStyles: {
      headline: {
        textStyleName: 'Brand headline',
        fontFamily: 'Montserrat',
        fontSize: 64,
        fontWeight: 700,
        lineHeight: 1.1,
        fontStyle: 'normal',
        textDecoration: 'none',
      },
    },
  }}
/>

metadata is required in templateMetadata. It adds your own fields to saved templates. See Saving and loading.

Letter caseCopy Anchor Link

With text selected, the Text panel’s Styles section includes Size presets and Case controls: ABC for uppercase, abc for lowercase, and Abc for capitalizing each word.

Rich textCopy Anchor Link

A single word or letter can have its own style. Double-click a text box, select part of the text, and press Bold, Italic, Underline, or the text color, or change the font size.

View full size

When part of the text is selected, the tooltips of these buttons end in "selected text". The font, the alignment, and the text styles always apply to the whole text box. A new font size applies to whole lines, so that each line has one size.

When the whole selection already has a style, the button removes it. Otherwise, it adds the style to all of the selection.

Outline and shadowCopy Anchor Link

Select a text box and open the Effects panel. Outline draws a line around the letters. Shadow / Glow draws a soft color behind them.

The presets at the top set several values at once:

View full size

The same panel sets Letter Spacing, from -5 to 40, and Line Height, from 0.5 to 3.

Gradient textCopy Anchor Link

The Gradient switch in the Effects panel fills the letters with a color gradient, from the Start color at the top to the End color at the bottom. The default colors are #fbbf24 and #f97316.

The gradient is linear and runs from top to bottom, over the height of one line.

Text templatesCopy Anchor Link

The Text panel’s Styles section shows four templates and a See all view. The full view has search, purpose categories (Title, Button, Call to action, Sale, Price, Lower third, Quote, Testimonial, Social handle, Announcement, Countdown and Caption), then style categories (Bold, Elegant, Script, Neon, Outline and More for Gradient, Shadow and Minimal). Brand styles appear first when a brand is active. AI-made templates appear first with an AI badge. There is no Label category.

A template is a group of text and simple shapes. With one text selected, choosing a template replaces it, puts its words in the template’s main line and keeps its size. With several texts selected, each becomes its own group. A style-locked text cannot be put into a template. With no text selected, choosing a template adds the group. See Text templates for the host setting and AI format.

AI text generationCopy Anchor Link

The Text panel has one AI form. Generate with AI opens it for new wording. With text selected, the button is Rewrite with AI and + New starts a new item. In the form, choose Words or Text template; with a selection the choices read Change the words and Put it in a template. The single prompt is kept when you switch. Results preview on the canvas when selected. Generate more appends results; Try again replaces them. Add to canvas keeps the form open. See AI providers and Text templates.

AI rewriteCopy Anchor Link

The toolbar action Rewrite with AI opens the Text panel’s AI form in rewrite mode. The right-click action opens the same form. Selecting a result previews it on the existing text; closing with ✕, pressing Escape, or changing selection keeps the chosen result as one undoable edit. + New switches to a new text item. The prompt is shared with text-template generation and stays when the operation changes.

ConfigurationCopy Anchor Link

EventsCopy Anchor Link

Text has no events of its own. The words are part of the design, and they reach you in the exported file through onExport. See Events.

TroubleshootingCopy Anchor Link

ImagesCopy Anchor Link

Use HTTPS for mediaApiUrl. HTTP is allowed only on your own computer at the loopback addresses.

Pictures come from the user's computer, from stock photo services, or from an AI model. On the page, the user can crop, fit, and filter a picture, and remove its background.

Upload, crop, fit modes, and filters work with no setup. The other options need a key, a server, or an AI provider, which you pass as props.

<ImageEditor
  mediaApiUrl="https://media.example.com"
  stockMediaApis={{
    pexels: { apiKey: 'YOUR_PEXELS_KEY' },
    unsplash: { apiKey: 'YOUR_UNSPLASH_ACCESS_KEY', showAttribution: true },
  }}
  ai={{ endpointUrl: 'https://api.example.com/ai' }}
/>

UploadCopy Anchor Link

The Upload Images button in the upload panel opens the file picker. The user can choose several files at once.

The panel lists JPG, PNG, GIF, and WebP. A file that is not an image is refused with the message "Invalid file type".

A new picture is placed with the Fit mode, so the whole picture shows on the page.

View full size

Stock photosCopy Anchor Link

With stockMediaApis set, the upload panel shows a Stock Images tab, with one tab for each service. A search asks for pictures in the orientation of the page: landscape, portrait, or square.

<ImageEditor
  stockMediaApis={{
    pexels: { apiKey: 'YOUR_PEXELS_KEY' },
    unsplash: { apiKey: 'YOUR_UNSPLASH_ACCESS_KEY', showAttribution: true },
  }}
/>

Unsplash requires showAttribution: true, so the photographer's name is shown with each picture.

CropCopy Anchor Link

Crop shows part of a picture. Select a picture and press Crop in the toolbar above the page, or choose Crop in the right-click menu. In the compact layout, Crop is a chip under the picture. A frame opens over the picture. Drag the frame or its handles to choose the part that shows.

Press Done, press Enter, or click outside the frame to apply the crop. Press Cancel or Esc to leave the picture as it was. Clear crop shows the whole picture again. A crop is one step to undo, and the exported file shows exactly the same part of the picture.

A saved design keeps the crop in a crop field on the picture, { x, y, width, height }, counted in the picture's own pixels, not in page pixels. Store it with the rest of the record.

Fit modesCopy Anchor Link

A fit mode decides how a picture fills the page. Select a picture and press Image Fitting Options in the toolbar above the page.

View full size

Filters and adjustmentsCopy Anchor Link

Select a picture and open the Effects panel. Four filters switch on and off: Grayscale, Sepia, Invert, and Emboss.

Eleven adjustments take a number:

Filters and adjustments appear in the exported file.

View full size

Background removalCopy Anchor Link

Select a picture and press Remove Background in the toolbar, or choose Remove background in the right-click menu. The editor replaces the picture with the one your server returns, at the same place and size.

Image generationCopy Anchor Link

With ai set, the upload panel shows Generate image. The user describes the picture and presses Generate.

The results appear in the box. Choose a picture and select Add to canvas to place it. Generate more appends results; Try again replaces the current choices. Every picture made in the session stays in the Generated tab.

<ImageEditor
  ai={{ endpointUrl: 'https://api.example.com/ai' }}
/>

AI image editingCopy Anchor Link

Select a picture and press Edit with AI in the toolbar, or choose Edit with AI… in the right-click menu. The user describes the change, for example "put two passengers in the boat", and presses Generate.

The box offers starts such as Change the background and Add something. The first suggestion previews on the picture. Click a card to compare it; choose Original to restore the source. Closing the box keeps the selected result as one editing action, with one Undo step.

The request has "operation": "imageEdit" and carries the picture in input.source. The answer has the same { items: [{ url }] } format as image generation.

When you pass onUploadAsset, the editor gives it the new picture before the picture is replaced, so the design keeps your own address. Without onUploadAsset, the picture's data is saved inside the design. See Asset storage.

UpscalingCopy Anchor Link

Upscaling will increase the resolution of a picture.

MasksCopy Anchor Link

Select a picture and press Mask beside Crop to hide part of it. Choose Rectangle, Rounded, Circle, Star, Polygon, Linear, or Shape…, then move, resize, or rotate the mask. Invert hides the inside instead, and Feather softens the edge. Press Enter or click outside to apply it, or press Esc to cancel. In compact layout, use Done or Cancel. Clear mask removes the mask without changing the crop.

Masks work on pictures and GIFs, including pictures used as stickers. Backgrounds cannot be masked. A new mask is rectangular, inset 10% on each side, with no feather or inversion. Rounded corners and feather range from 0–50%; stars and polygons accept 3–12 points or sides. Mask controls are enabled by default; set ui={{ features: { masks: false } }} to hide them.

When the user edits a masked picture with AI, the request includes input.mask alongside input.source. White pixels identify the editable area, black pixels protect the rest, and gray pixels describe the feathered edge. Your provider must support mask input to honor that region.

ConfigurationCopy Anchor Link

EventsCopy Anchor Link

Images have no events of their own. The editor calls onUploadAsset when the user keeps a picture changed with AI. The finished design reaches you through onExport. See Events.

TroubleshootingCopy Anchor Link

ShapesCopy Anchor Link

Shapes are vector elements: rectangles, circles, stars, arrows, lines, speech bubbles, and more. The user sets their fill color, outline color, and outline width. With an AI provider, the user can also describe a new shape.

Shapes work with no setup. AI shape generation needs an AI provider:

<ImageEditor
  ai={{ endpointUrl: 'https://api.example.com/ai' }}
/>

Shape libraryCopy Anchor Link

Open the Shapes panel in the tool rail, or press Add shape in the toolbar above the page. A click on a shape adds it to the page and selects it.

View full size

The panel has 43 shapes, in six categories:

All shows every shape. A new shape is light gray (#E5E5E5) with a black outline.

Fill and strokeCopy Anchor Link

Select a shape. The toolbar above the page shows:

The color pickers offer a color field, hex and RGB values, and a row of ready-made colors.

A stroke width of 0 removes the outline. Fill is a solid color. For effects such as a shadow or rounded corners, use the Effects panel. See Effects and filters.

Lines and arrowsCopy Anchor Link

The Lines category adds straight lines: a solid, dashed, or dotted line, a line with one arrowhead, or a line with two. A new line is 200 pixels long and horizontal.

Select a line to see a handle at each end. Drag a handle to change the length and the angle of the line. The color of a line is its stroke color, and its thickness is its stroke width.

The Arrows category adds filled arrow shapes, which resize like any other shape.

AI shape generationCopy Anchor Link

With ai set, the Shapes panel shows Generate shape at the top. The user describes the shape, for example "a simple triangle", and presses Generate. The count line shows the number of returned outlines. Add to canvas adds the chosen shape to the page.

View full size

A generated shape is a vector path. It has the same fill and stroke controls as the other shapes.

The request has "operation": "svgPath", and your AI server answers with { items: [{ pathData }] }, with SVG path data in each entry. See Custom AI endpoint.

ConfigurationCopy Anchor Link

EventsCopy Anchor Link

Shapes have no events of their own. They are part of the design, and they reach you in the exported file through onExport. See Events.

TroubleshootingCopy Anchor Link

StickersCopy Anchor Link

Stickers are small ready-made pictures. The editor has a built-in set, and you can add GIPHY, your own collections, or your own sticker service. Each collection is a source in the stickers prop.

The built-in stickers work with no setup. This example adds a collection of your own and GIPHY:

<ImageEditor
  stickers={{
    sources: [builtInStickers(), brandStickers, giphyStickers({ endpointUrl: 'https://api.example.com/giphy' })],
  }}
/>

Built-in stickersCopy Anchor Link

Open the Stickers panel in the tool rail. Without the stickers prop, it shows the built-in collection Essentials: Heart, Star, Sparkle, and Check mark. They are drawings inside the package, so they load with no network request.

View full size

A click on a sticker adds it to the page. When there is more than one source, a row of source names appears under the tabs. The search field searches the source that is selected.

When you pass stickers, list builtInStickers() yourself if you want to keep the built-in collection. stickers={{ sources: [] }} removes the Stickers tool from the editor.

GIPHYCopy Anchor Link

giphyStickers() adds the GIPHY sticker library as a source. Before the user types, it shows the trending stickers. Results arrive 24 at a time, and Load more shows the next 24.

<ImageEditor
  stickers={{ sources: [builtInStickers(), giphyStickers({ endpointUrl: 'https://api.example.com/giphy' })] }}
/>

View full size

GIPHY content is rated pg.

Animated GIFsCopy Anchor Link

The Animated tab shows the stickers that move. A sticker moves on the page when it comes from this tab.

A sticker from the Stickers tab is still. The editor adds the first frame of the picture.

For a GIPHY sticker to appear on the Animated tab, its moving version must be 4 MB or smaller. Larger stickers appear on the Stickers tab only.

PNG, JPEG, and PDF files cannot move. An export holds one frame of each moving sticker.

Custom sticker packsCopy Anchor Link

staticStickers() turns a list of pictures into a source:

<ImageEditor
  stickers={{ sources: [brandStickers] }}
/>

The search field finds a sticker by its title or its id. A .gif or .webp picture appears on the Animated tab too.

Each sticker item has these fields:

Your own sticker serviceCopy Anchor Link

A source is an object with id, label, and a search function. trending is optional: without it, the source shows nothing until the user types.

<ImageEditor
  stickers={{ sources: [companyStickers] }}
/>

search receives limit 24 and an offset that grows by 24 with each Load more. It returns { items, hasMore }. Each source keeps its own results. The editor never mixes the results of two sources.

ConfigurationCopy Anchor Link

The three functions are exported from both @layermetry/media-editor and @layermetry/media-editor/react.

EventsCopy Anchor Link

Stickers have no events of their own. They are part of the design, and they reach you in the exported file through onExport. See Events.

TroubleshootingCopy Anchor Link

BackgroundsCopy Anchor Link

The background fills the whole page, behind every other element. It is a solid color, a gradient, a photo, or a blurred copy of a picture on the page. Each page of a design has its own background. A new page is white.

Colors, gradients, uploaded photos and blurred copies work with no setup. The Unsplash photo search needs your Unsplash key, and Generate background needs an ai setting that serves pictures:

<ImageEditor
  stockMediaApis={{
    unsplash: { endpointUrl: 'https://api.example.com/unsplash', showAttribution: true },
  }}
/>

Open the Background panel in the tool rail. At the top is Generate background, when your ai setting serves pictures. Below it are three tabs: Solid Color, Gradient, and Image.

Solid colorCopy Anchor Link

On the Solid Color tab, a click on one of the 16 Preset Colors fills the page at once. For another color, choose it under Custom Color and press Apply Color.

The presets are white, black, two grays, and twelve bright colors, from red (#ef4444) to purple (#a855f7).

The color stays with the page when the user changes the background to a gradient, a photo, or a blurred copy. It is the fallback color: the page and the exported file show it whenever the background cannot be drawn. That happens while a photo has not loaded, when the colors of a gradient cannot be read, and when the picture of a blurred copy is deleted. A new page starts with white.

GradientCopy Anchor Link

On the Gradient tab, a click on one of the 8 Gradient Presets fills the page with a gradient. For your own gradient, choose the Start, Middle, and End colors under Custom Gradient, and press Apply Custom Gradient.

View full size

Under the colors, Direction says which way the gradient runs: → (left to right, the default), ↓ (top to bottom), ↘ and ↗ (the two diagonals). For any other direction, type a number of degrees from 0 to 359 and press Enter.

ImageCopy Anchor Link

The Image tab puts a picture behind the page. It has, from top to bottom:

• From this design: one tile for each picture on the page. Press a tile to make the background a blurred, darkened copy of that picture. See Blurred background.
• Upload a picture: choose a picture file from the computer.
• The Unsplash search, when Unsplash is connected. It starts with the search "backgrounds". The photographer's name is shown on each photo, as Unsplash requires. Load More shows the next 15 photos.
• Blur and Darken, whenever the background is a photo or a blurred copy.

A photo fills the whole page. It keeps its proportions, it is centered, and the parts that do not fit are cut off equally from both sides.

Blur softens the photo, from 0 (sharp) to 40 pixels. Darken puts black over it, from 0 to 100 %. Both help text on top stay readable. The page changes once, when the slider is let go.

View full size