Text templates

Text templates are editable groups made from text lines and simple filled rectangles. The image editor includes built-in templates and accepts your own through textTemplates. The same neutral template shape is used for host templates and AI results.

Add host templatesCopy Anchor Link

Pass textTemplates to ImageEditor. Its categories define gallery chips, and its templates appear in the Styles gallery. A category without type is a purpose category. Set type: 'style' for a visual style category. Host templates can also be used as examples for AI generation in their category.

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

const textTemplates: AITextTemplatesSettings = {
  categories: [
    { id: 'promotion', label: 'Promotion' },
    { id: 'brand-style', label: 'Brand style', type: 'style' },
  ],
  templates: [{
    id: 'summer-sale',
    name: 'Summer sale',
    category: 'promotion',
    w: 360,
    h: 120,
    backgrounds: [{ x: 0, y: 0, width: 360, height: 120, fillColor: '#123456', cornerRadius: 12 }],
    layers: [{ text: 'Summer sale', x: 20, y: 25, width: 320, fontFamily: 'Montserrat', fontSize: 42, fontWeight: 700, textColor: '#ffffff', align: 'center' }],
  }],
};

export function App() {
  return <ImageEditor licenseKey="YOUR_LICENSE_KEY" onClose={() => {}} textTemplates={textTemplates} />;
}

The gallery places AI-saved templates first with an AI badge, then host templates, then built-ins. replaceBuiltIns: true removes the built-in gallery templates; it does not remove AI-saved templates. Invalid host settings are ignored with a console warning. A template with an unknown category is dropped.

Template shapeCopy Anchor Link

All coordinates and sizes are pixels inside the template's w by h box. widthFraction makes the group scale to a fraction of the canvas width; anchor positions that scaled group at center, bottom or bottom-left.

Each text layer requires text, x, y, width, fontFamily and fontSize. Text is limited to 80 characters and font size to 8–400 pixels. Optional fields are fontWeight, fontStyle, textColor, align, letterSpacing, lineHeight, strokeColor, strokeWidth, shadowColor, shadowBlur, shadowOffsetX, shadowOffsetY, gradientStartColor and gradientEndColor. Letter spacing is limited to ±80; outline width to 40; shadow blur and offsets to 120. A gradient is used only when both colors are provided.

Each rectangle requires x, y, width, height and fillColor; cornerRadius is optional. Invalid templates are dropped and reported in one console warning. Values outside supported numeric ranges are clamped, and a font the editor cannot load is replaced with Montserrat.

Place a templateCopy Anchor Link

With no text selected, choosing a template adds the group. With one selected text, the template replaces it, puts the selected words in its main line and keeps the selected text size. With several selected text items, each becomes its own template group. A style-locked text item cannot be put into a template.

The Text panel shows four Styles previews and See all. The full gallery starts with Generate with AI, then search and purpose categories followed by style categories. Built-in purpose categories include Title, Button, Call to action, Sale, Price, Lower third, Quote, Testimonial, Social handle, Announcement, Countdown and Caption. Built-in style categories include Bold, Elegant, Script, Neon, Outline, Gradient, Shadow and Minimal. There is no Label category.

Generate a templateCopy Anchor Link

The Text panel's AI form offers Words and Text template. With a text selected, the choices are Change the words and Put it in a template. The textTemplate operation is a separate host-configured operation. Its request contains mode, category, prompt, up to three examples, canvas, available fonts, and count (1–6; default 3). In restyle mode, it also contains the selected text's words and layout. When a brand is active and used, the request includes its fonts and colors.

The host endpoint or callback must implement this operation. The reference backend does not serve it, and hosted AI is unavailable in SDK version 1.0.0. With hosted AI, the operation is off unless the host explicitly configures ai.textTemplate.

The response is { items: [{ template: AITextTemplate }], receipt? }. Each returned template is checked before it appears; invalid entries are dropped. The clicked result previews on the canvas and becomes the current choice. Generate more appends results; Try again replaces them.

Save generated templatesCopy Anchor Link

Generated templates use the host's generated-results store when it is configured. The editor calls onSave with a textTemplate record whose result contains { template }, and reads it back from records; without a store, generated templates last for the current session. See Generated results for the saved record contract. There is no separate Save template button. Saved AI templates appear first in Styles with an AI badge. The Text panel's Generated section lists generated words, not templates.

Headless video runtimeCopy Anchor Link

The video editor exposes readTextTemplates to read host and built-in gallery templates. It does not include user-specific AI-saved templates. The video headless runtime accepts the same setting:

const runtime = createHeadlessChatRuntime({
  template,
  textTemplates,
});

The image editor does not expose this headless action. See Headless runtime and Editor API.