Brand kits

A brand kit is the data of one brand: its name, logo, colors, text styles, and the way it writes. You pass one kit or many in templateMetadata. The editor then offers the brand's colors and text styles in the places where the user picks them, and it adds the brand to AI requests.

This page is about the brand of the design. Theme Studio has a different setting that is also called "Brand color". It sets the colors of the editor's own buttons and panels. See Theming. The two do not affect each other.

SetupCopy Anchor Link

Pass the kits in templateMetadata.brands. Pass activeBrandId to choose the kit that is active when the editor opens:

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

const brands: BrandKit[] = [
  {
    id: 'northwind',
    name: 'Northwind Studio',
    logoUrl: 'https://cdn.example.com/northwind-logo.png',
    description: 'Boat charters and harbour tours.',
    colors: {
      primary: '#1F4E79',
      secondary: '#F2B134',
      palette: { 'Harbour blue': '#1F4E79', 'Buoy yellow': '#F2B134' },
    },
    textStyles: {
      headline: {
        textStyleName: 'Headline',
        fontFamily: 'Georgia',
        fontSize: 96,
        fontWeight: 700,
        lineHeight: 1.1,
        fontStyle: 'normal',
        textDecoration: 'none',
      },
    },
    voice: 'warm, plain and precise',
    locale: 'en-GB',
  },
  { id: 'harbourbrew', name: 'Harbour Brew', colors: { primary: '#6B3E26' } },
];

export default function App() {
  return (
    <div style={{ position: 'fixed', inset: 0 }}>
      <ImageEditor
        licenseKey="YOUR_LICENSE_KEY"
        onClose={() => console.log('The editor was closed')}
        templateMetadata={{ metadata: {}, brands, activeBrandId: 'northwind' }}
        onBrandChange={(brandId) => console.log(`Brand: ${brandId}`)}
      />
    </div>
  );
}

Expected result: the tool rail has a Brand entry right after Text, with the name "Northwind Studio" under it. Because two kits are listed, the panel has a menu that switches the kit.

Default: no brand, no Brand entry, and every color picker looks as it did before.

The one-brand formCopy Anchor Link

The form that earlier versions used keeps working. The editor reads colors, textStyles, logoUrl, and description at the top of templateMetadata, the id from metadata.brandId, and the name from metadata.brandName. It treats them as a list of one kit.

templateMetadata={{
  metadata: { brandId: 'northwind', brandName: 'Northwind Studio' },
  colors: { primary: '#1F4E79', secondary: '#F2B134' },
  textStyles: { headline: { textStyleName: 'Headline', fontFamily: 'Georgia', fontSize: 96 } },
  logoUrl: 'https://cdn.example.com/northwind-logo.png',
}}

A list in brands with at least one entry wins. The one-brand fields next to it are then ignored. Without metadata.brandId, the kit has an empty id. An empty id is never saved with a design, and onBrandChange is not called for it.

Brand kit fieldsCopy Anchor Link

id and name are the only required fields. Every other field is optional.

A panel shows only the logo, the colors, the text styles, and the description. The writing fields are never shown. They go to the Generate boxes, so that people do not type them again.

Each color must be a hex color: #rgb, #rgba, #rrggbb, or #rrggbbaa. Any other value, such as navy or rgb(31, 78, 121), is left out. Every color action of the editor accepts only hex, so a swatch never offers a color that an action refuses.

Which kits are keptCopy Anchor Link

The editor keeps a kit that has an id and at least one thing it can use. That is a logo, a main color, a text style, or any writing field. A kit that has only a name is left out, and the console shows a warning that starts with [Brand]. A kit without an id, or with an id that is already listed, is left out with a warning too.

A kit that has only writing fields is kept, and it reaches the Generate boxes. It has no Brand entry, because its panel would be empty.

Names on screenCopy Anchor Link

With a name, the editor shows the name, such as "Brand: Northwind Studio". A kit without a name shows its id when two or more kits are listed, so that people can tell them apart. A single kit without a name shows only "Brand", and no id.

Choosing the active kitCopy Anchor Link

When the editor opens, it picks the active kit in this order:

1. The brandKitId saved in the design, if you still list that kit.
2. Your activeBrandId, if you list that kit.
3. The first kit in the list.

If you pass a different activeBrandId later, the editor switches to that kit, if it is listed. A new templateMetadata object with the same ids changes nothing, so a React page that writes templateMetadata={{ ... }} inline does not undo a switch that the user made.

When the user opens a saved design from the Templates panel, the design's kit becomes active, if it is listed.

Force one brandCopy Anchor Link

To make the editor use one brand and offer no choice, pass only that brand. The menu appears from two kits, so a list of one kit has no menu.

templateMetadata={{ metadata: {}, brands: brands.filter((kit) => kit.id === currentCustomerBrandId) }}

A saved design from another brand then does not change the kit, because the editor does not list that kit.

Brand change eventsCopy Anchor Link

onBrandChange(brandId) is called when the editor opens with a kit, and again on every switch. The argument is the id of the active kit. The custom element <media-editor-image> sends a brandchange event too, and its detail is the id.

const editor = document.querySelector('media-editor-image');
editor.addEventListener('brandchange', (event) => {
  console.log(`brandchange: ${event.detail}`);
});

A switch does not change the design. It is not an undo step, and it does not mark the design as unsaved. If your function throws an error, the console shows it and the editor continues.

Saved designsCopy Anchor Link

A saved design remembers its kit as template.brandKitId. Saving a template or a draft writes it. The editor gives it back when the design opens. It is never written into your metadata.

The editor leaves brandKitId out when the active kit has an empty id. It ignores a saved id that you no longer list.

Brand panelCopy Anchor Link

The Brand panel is in the tool rail right after Text. In the compact layout, the dock tile says "Brand", and the first line of the sheet names the brand. With two or more kits, the panel heading has a menu that switches the kit.

The panel shows these parts, in this order. It leaves out a part that the kit does not have.

A color click goes to every selected text and shape. Each click is one undo step. A picture or the background is not changed, and a message next to the colors says so.

A text style click sets the font, size, weight, italic, underline, and line height that the style names. It sets each value and never switches one. A bold text box stays bold when it gets a bold style. Each click is one undo step.

Your page must load the brand font, as for Brand text styles. The image editor does not wait for the font to load before it styles the text.

Brand styles in the Text panelCopy Anchor Link

The Text panel has a Brand styles card with the same text styles and, with two or more kits, the same menu. The card is not shown when the active kit has no text styles.

Brand colors in color pickersCopy Anchor Link

Every color picker has a Brand colors row with the name of the brand and one dot for each color of the kit. The row is not shown when the kit has no colors. The kit menu is not in the pickers. It is only in the panel heading, the first line of the compact sheet, and the Brand styles card.

Hide or rename the panelCopy Anchor Link

ui.panels.brand hides the Brand entry in the rail and the dock, or changes its name:

<ImageEditor
  licenseKey="YOUR_LICENSE_KEY"
  onClose={() => console.log('The editor was closed')}
  templateMetadata={{ metadata: {}, brands }}
  ui={{ panels: { brand: { label: 'Company brand' } } }}
/>

ui.toolRail.hidden and ui.dock.hidden with the id brand hide the entry as well. See UI customization.

Generate with brandCopy Anchor Link

When the editor has an active kit, each Generate box shows a Use brand switch. The switch adds a few brand words after the person's own words. Under the switch is one chip for each part of the brand that the request uses, such as Colors, Look, Voice, or Dos and don'ts. A chip that is turned off is missing from the prompt and from the data that goes to your server.

Above the Generate button, one line shows what will be added, for example "Added to your request: voice, tone, dos and don'ts, spelling (185 characters)". It opens to the exact words.

The row appears only when all four of these are true:

• The editor has an active kit.
• The editor has an AI service.
• You did not set ai.brand to false.
• The kit has something for this kind of request. If it has nothing, the row is hidden and the box is as it was before.

The switch and the chips are remembered for each kind and each kit while the editor is open. They are not saved in the design.

What each kind getsCopy Anchor Link

"Words" is the text added to the prompt. "Data" is what input.brand carries.

Rules that always holdCopy Anchor Link

• The brand words come after the person's own words, after one blank line. For a sticker, the words come after the filled sticker template, so they never land inside the subject.
• A picture prompt never carries the brand name or the dos and don'ts.
• A color is written as a name and a code, such as "Harbour blue (#1F4E79)". The name comes from colors.palette. Without a name, only the code is written.
• Every kit field is cleaned before use. Each line break and control character becomes a space, so a field cannot start a new paragraph in the prompt. A field is cut to 160 characters (the look) or 80 characters (voice, audience, a color name, and one rule).
• The whole addition has at most 300 characters for pictures and stickers, and at most 600 characters for text. A part that does not fit is left out, and so is every part after it. It is left out of the words and of the data, and the line above Generate names it.

Settings: ai.brandCopy Anchor Link

ai.brand changes how the feature works. Its value is false or an object:

<ImageEditor
  licenseKey="YOUR_LICENSE_KEY"
  onClose={() => console.log('The editor was closed')}
  templateMetadata={{ metadata: {}, brands }}
  ai={{
    endpointUrl: '/api/ai',
    brand: { addToPrompt: false, operations: { imageEdit: true, sticker: false } },
  }}
/>

The editor refuses these values and names the setting in the error: operations.soundEffect or operations.captions, because those never use a brand and the image editor has no such request; an unknown key, such as ai.brand.addToPrompts; true; and any other value that is not true or false.

Your own server: input.brandCopy Anchor Link

With a brand, the request to your server carries input.brand. A server that words its own prompts can read it and can remove the added words with an exact match on addedToPrompt:

{
  "type": "text",
  "prompt": "A headline\n\nWrite in a warm, plain and precise voice.",
  "input": {
    "operation": "text",
    "prompt": "A headline\n\nWrite in a warm, plain and precise voice.",
    "brand": {
      "kitId": "northwind",
      "name": "Northwind Studio",
      "addedToPrompt": "\n\nWrite in a warm, plain and precise voice.",
      "used": ["voice"],
      "voice": "warm, plain and precise"
    }
  }
}

The example is shortened, and the real words of addedToPrompt are longer. The fields of input.brand are:

input.brand is missing when no brand is active, when ai.brand is false, and for requests that never use a brand. A part that the person turned off is missing from input.brand too.

The name brand is reserved. A model field cannot use it, and a brand key that arrives with the model settings is removed before the editor adds its own. See Custom AI endpoint.

ConfigurationCopy Anchor Link

TroubleshootingCopy Anchor Link

Additional resourcesCopy Anchor Link

• Brand text styles
• AI providers
• UI customization
• Saving and loading
• Events