Configure Text

Control the fonts, defaults, and rich preset catalog of the Text tool with config.text. Presets can insert one styled text block or a complete, editable composition of text and shape blocks, organized in a searchable gallery.

When to use this

• You want on-brand typography instead of the generic system fonts.
• You're loading custom web fonts and want them selectable in the editor.
• You need consistent defaults (family, size, colour, weight, alignment...) for every new text block.
• You want branded styles or multi-layer layouts available in one click.

Configure the text tool

<ImageEditor
  src="/photo.jpg"
  config={{
    text: {
      fonts: ["Poppins", "Roboto Mono", "Playfair Display"],
      defaultFontFamily: "Poppins",
      defaultFontSize: 32,
      defaultColor: "#ffffff",
      defaultFontWeight: "normal",
      defaultFontStyle: "normal",
      defaultTextAlign: "left",
      defaultLineHeight: 1.2,
      defaultLetterSpacing: 0,
      minFontSize: 8,
      maxFontSize: 400,
      additionalPresetGroups: [{
        id: "brand",
        label: "Brand",
        presets: [{
          id: "brand-title",
          label: "Brand title",
          blocks: [{ text: "Brand title", fontSizeScale: 3, fontWeight: "bold" }],
        }],
      }],
    },
    // Shared swatch palette for every colour picker (text, shapes, background):
    colors: ["#ffffff", "#111827", "#4f46e5", "#e11d48", "#16a34a", "#f59e0b"],
  }}
/>

Customize the gallery

Use presetGroups to replace the complete built-in catalog. Use additionalPresetGroups to retain the built-ins and append branded categories. When an additional group uses a built-in id such as styles, its presets are appended to that existing row. The gallery searches translated category labels and preset labels.

Rich text presets

Each modern preset contains one or more blocks. A block can define gradients, stroke, shadows, highlights, background boxes, curved text, and UTF-16 runOverrides. Omit geometry for a centered, auto-sized style preset.

text: {
  presetGroups: [{
    id: "brand",
    label: "Brand",
    presets: [{
      id: "highlight",
      label: "Highlight",
      blocks: [{
        text: "Brand",
        fontSizeScale: 2,
        transform: "uppercase",
        backgroundColor: "#fde68a",
        runOverrides: [
          { start: 1, end: 3, style: { backgroundColor: "#86efac" } },
        ],
      }],
    }],
  }],
}

Layered text compositions

Add composition.elements to arrange editable text and shape layers with normalized page coordinates. Elements are ordered back to front. Referenced text blocks must omit their own geometry.

{
  id: "announcement",
  label: "Announcement",
  blocks: [{ text: "New collection", fontSizeScale: 2, fontWeight: "bold", fill: "#ffffff" }],
  composition: {
    elements: [
      {
        kind: "shape",
        layout: { x: 0.15, y: 0.42, width: 0.7, height: 0.16 },
        shape: { kind: "rect", cornerRadius: 12 },
        fill: { kind: "color", color: "#dc2626" },
      },
      {
        kind: "text",
        block: 0,
        layout: { x: 0.22, y: 0.46, width: 0.56, height: 0.08 },
        widthMode: "auto",
      },
    ],
  },
}

Thumbnails are derived from the preset's blocks and composition. The deprecated optional preview field remains accepted but is not needed for new presets.

How defaultFontSize is applied

defaultFontSize is a reference size at a 1080px canvas, not a literal pixel value. The applied size is scaled to the canvas and chosen preset:

appliedSize = round(defaultFontSize × preset.fontSizeScale × min(pageW, pageH) / 1080)

So defaultFontSize: 32 on a large image with the Title preset lands well above 32px — this keeps text proportionate across image resolutions. The exact px is editable in the Text Properties panel (bounded by min/maxFontSize).

Load the matching web fonts yourself (via a <link> or @font-face) so the names you list actually render.

Try it

Open the Text tool — the gallery shows your custom presetGroups (just Display and Caption). Add one, and the new block picks up every default below: the Playfair Display family, red fill, bold weight, italic style, and centre alignment. Open the font picker in the selection bar and it lists only your configured fonts (each previewed in its own typeface); open the colour picker and it shows just your custom colors swatches:

Next steps

• Customize the Theme — set the UI font and colours.
• Configure the Adjust Tool — trim the adjustment sliders.
• Configuration — the full config reference.

Verified by tests/guides/configure-fonts.spec.tsx in the @editx/image-editor package.