UI customization

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.

This example produces the editor in the picture:

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

export default function App() {
  return (
    <div style={{ position: 'fixed', inset: 0 }}>
      <ImageEditor
        licenseKey="YOUR_LICENSE_KEY"
        onClose={() => console.log('The editor was closed')}
        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 },
            },
          },
        }}
      />
    </div>
  );
}

Selection and toolbarCopy Anchor Link

On a desktop, one bar above the canvas shows the controls of the selected item. It appears for text, shapes, pictures, stickers, GIFs, labels, and several items selected together. On a phone, the selection bar shows the same controls. Since 1.0.0 it also appears when you select several items, with Delete, layer order, Transparency, Group, Ungroup and Lock.

The bar works like this:

• Values on the buttons. A button shows the current value, for example opacity, font size and line width. The phone's selection bar shows the same values.
• More. When the bar is too narrow, the controls at the end of the list move into a short More menu. The editor measures the real width of each button. Copy style and Paste style are always in More.
• Value controls open in the side panel. Colour, effects and the other value controls open in a panel on the left side, not in a menu that hangs from the bar. The phone uses the same control. One panel is open at a time. It closes when the selection changes, when you press Escape, with its close button, or when a tool from the rail opens in its place. Small controls stay in the bar: the font size field with − and +, the three alignment buttons, the line width field and Transparency.
• Your own buttons. customActions appear after the editor's controls. See Custom actions.

With nothing selected, the bar becomes a page bar. It shows the canvas size (it opens the Resize panel), Background (it opens the Background panel), the Save template button when the editor can save templates, the Default locks… button, and a More menu. More has the same lines as a right-click on the empty canvas, and Background settings…. A viewer sees no page bar.

Set ui.toolbar.hidden to ['controls'] to hide the page-bar extras: Insert Emoji and Save template in the video editor, or Save template and Default locks… in the image editor. The page controls and More remain available. This hides the buttons; it does not revoke editing permissions.

Default lists and ui.selectionCopy Anchor Link

The order of the controls for each type of item is a plain list in the editor. It is only the starting view. ui.selection is applied after it and always wins. ui.selection takes the same four fields as the tool rail: order, hidden, labels and display. It now drives the desktop bar as well as the phone's selection bar.

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

const ui: UiConfig = {
  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
  },
};

• order puts the listed ids first, in your order. This is true even for a control that would wait behind More. The other controls keep their default order after yours.
• hidden removes the button. The action, its keyboard shortcut and its editing action keep working.
• labels renames a control. The new name is also the tooltip and the accessible name.
• display is 'icon', 'label' or 'both' for each id. By default the desktop bar draws Bold, Italic, Underline, Bring forward, Send backward and Delete as a picture only. Set display to 'label' or 'both' to bring the words back.

The new ids are replace (a picture), copyStyle, pasteStyle, and group and ungroup (several selected items). The lists for every type of item are in Default lists.

An id that the editor does not know is ignored, and the console prints one warning with the valid ids.

The old ui.toolbar settingCopy Anchor Link

ui.toolbar is still accepted, so a host that uses it keeps working. The bar has no groups any more, so each group id is translated into the controls that the group held, for the item types that showed the group. hidden and order are applied to those controls. Both ui.toolbar and ui.selection are applied. The hidden lists are added together.

A labels setting for a group, or a display of 'label' or 'both', has nothing to change, because there is no heading left. A display of 'icon' already meant "no heading", and it still holds. Your own buttons are the actions group. They always come after the editor's controls, with no heading, so the order, labels and display of actions are not applied. Hiding actions still works.

The editor prints one console warning that starts with [MediaEditor] ui.toolbar:. It names the group ids that were translated and the settings that have no effect, and it tells you to use ui.selection instead.

The text group held font, textAlign and rewriteWithAi. This example shows the old setting and the same choice written for ui.selection:

const ui: ImageUiConfig = {
  // Old: hides the Text group. Works, with one console warning.
  toolbar: { hidden: ['text'] },
};

const sameWithSelection: ImageUiConfig = {
  // New: names the controls. An id applies to every type of item that has it.
  selection: { hidden: ['font', 'textAlign', 'rewriteWithAi'] },
};

The right-click menu keeps its words. See Control customization for all ids and the default lists.

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. The ids are copyStyle and pasteStyle, so ui.selection can hide, move or rename them.

The editor matches the physical key, because Option + C types the character "ç" on a Mac. On Windows, AltGr is not treated as a shortcut, so it still types its character. If you hold the keys, the style is pasted once. The keys work only while this editor is the active one, and never while you type in a text field.

Copy style needs exactly one selected item that has a style. Paste style needs a copied style and at least one selected item. The copied style stays while the editor is open.

What is copied depends on the type of the item:

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, even when it changes several items. Parts that do not apply to the target are skipped. The editor shows one short message for the paste. If every selected item is locked, it says "The selected items are locked." The colored plate behind text is not copied. An item of another type receives only transparency.

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.

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.

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.

Tools that are off the rail by defaultCopy Anchor Link

Effects and Background are not on the left rail by default. Effects does nothing useful when nothing is selected. You reach it from the bar of the selected item, and Background from the page bar. Their panels are the same as before.

To put a tool back on the rail, list its id in ui.toolRail.order. The tool then shows in the place where you listed it. A host that already lists every tool sees no change. The phone's dock is not changed by this.

<ImageEditor
  licenseKey="YOUR_LICENSE_KEY"
  onClose={() => console.log('The editor was closed')}
  ui={{ toolRail: { order: ['templates', 'effects', 'background'] } }}
/>

Brand panelCopy Anchor Link

ui.panels.brand hides the Brand entry, or gives it another name. It takes visible (default true) and label (default Brand):

ui={{ panels: { brand: { label: 'Company brand' } } }}

visible: false removes the entry from the rail and the dock. label changes the name in the rail, the dock, the panel heading, and the tooltip. The entry is shown only when a brand kit has a logo, a main color, or a text style. See Brand kits.

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.

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.