Skip to content

Migration from Unlayer ​

The @templatical/import-unlayer package converts Unlayer design JSON (the output of editor.saveDesign(...) from react-email-editor or the Unlayer hosted editor) into Templatical's TemplateContent format.

WARNING

This package is in active development. Some content types and advanced features may not be fully supported yet. Test your converted templates before using them in production.

Installation ​

bash
npm install @templatical/import-unlayer
bash
pnpm add @templatical/import-unlayer
bash
yarn add @templatical/import-unlayer
bash
bun add @templatical/import-unlayer

Without a build step (CDN) ​

You can also load it from a CDN:

html
<script type="module">
  import { convertUnlayerTemplate } from 'https://cdn.jsdelivr.net/npm/@templatical/import-unlayer/+esm';
  // ...then convert as shown in Usage below
</script>

Usage ​

ts
import { convertUnlayerTemplate } from '@templatical/import-unlayer';

// Load your Unlayer design JSON (whatever editor.saveDesign returned)
const res = await fetch('/api/unlayer-templates/123');
const unlayerJson = await res.json();

// Convert to Templatical format
const { content, report } = convertUnlayerTemplate(unlayerJson);

// Use in the editor
const editor = await init({
  container: '#editor',
  content,
});

// Check the conversion report for any issues
console.log(report);

Open in playground

Each report.entries item is one source module:

StatusMeaning
convertedMapped to a Templatical block with no loss of fidelity.
approximatedMapped, with a clamp or flatten — note states what changed.
html-fallbackNo block equivalent; original markup is an HtmlBlock.
skippedNo output (forms, a divider that draws no line and takes no space, and anything the converter refuses).

The design JSON Unlayer's hosted editor and editor.saveDesign() emit is the input. A compiled HTML export is a different envelope — use @templatical/import-html.

The function returns an ImportResult with:

  • content — the converted TemplateContent ready for the editor
  • report — a conversion report with the status of each content node (converted, approximated, html-fallback, or skipped)

Languages ​

values._languages[locale] supplies overrides. Text and textJson become paragraph content; heading text, button text, image altText, and menu item text become hashed text entries. Image src.url becomes set.src; row backgroundImage.url becomes the section's set.backgroundImage. Menu items map by position only when item counts match; otherwise the menu translation is dropped with a warning. Translated menu item links are not mapped; warnings name each discarded key and language once. A localized background image inherits the default image’s unspecified settings; an explicitly empty translated URL stores set.backgroundImage = null, removing the image in that language only.

Modern text uses Lexical textJson before legacy text; the paragraph content type is supported. Successfully read Lexical block markup is kept without an extra paragraph wrapper. Unreadable Lexical state falls back to values.text. A translation uses only its own textJson or legacy text: if neither is readable, no text entry is stored, coverage remains missing, and the report warns. The JSON has no default language or per-language direction: pass the host's default as defaultLocale. Without it, a multilingual design assumes "en" and warns. Device _override.<device>._languages translations are dropped with warnings. Unknown translation keys and HTML-fallback targets also warn.

The mappings follow Unlayer's documented overrides, checked 2026-10-28. Fixtures are built from that documentation, not real multilingual exports.

Codes normalize _ to - and must pass isLocaleTag. Unsupported tags are dropped with a warning naming the language. Text entries carry { value, sourceHash }, hashed from the imported default. Enable init({ localization: { locales } }) with the imported languages to show the Languages menu. Check the result with template-tools validate imported.json --locale <tag> and inspect report.warnings.

Options ​

convertUnlayerTemplate accepts a second argument of type ConvertUnlayerOptions. defaultLocale?: string supplies settings.locale when the source declares no default language; the fallback is "en". A declared default wins. Locale codes normalize _ to -. A declared default or defaultLocale that still isn't a language tag, such as a templated {{lang}}, is ignored with a report.warnings entry naming it, and the next valid value or "en" applies.

This JSON format supplies no default language to the importer. Pass the language configured by the host as defaultLocale.

ts
export interface ConvertUnlayerOptions {
  defaultLocale?: string;
}

Block Mapping ​

Unlayer content types map to Templatical equivalents:

Unlayer ContentTemplatical BlockStatus
TextparagraphConverted
HeadingtitleConverted
ImageimageConverted (approximated when a maxWidth under 100% becomes px; see Image width)
ButtonbuttonConverted (approximated when its size.width is clamped or unusable, see Button width, or its lineHeight can't be read, see Button line height)
Dividerdivider, or spacer when it draws no lineConverted (approximated when a partial-width divider is aligned left or right; skipped when it draws no line and takes no space)
SpacerspacerConverted
HtmlhtmlConverted
MenumenuApproximated (styles may differ)
SocialsocialConverted
VideovideoConverted
TimerhtmlHTML fallback (rebuild manually)
Form—Skipped

Unknown content types are converted to HTML blocks as a fallback.

Image width ​

Unlayer imageImageBlock.widthStatus
autoWidth (the default), src.width narrower than the image's roomthe px numberConverted
autoWidth, src.width as wide as the room or wider, or missing"full"Converted
autoWidth: false, maxWidth 100% or missing"full"Converted
autoWidth: false, maxWidth under 100%, such as 75%that share of the room in pxApproximated
autoWidth: false, unreadable maxWidth"full"Approximated

src.width and src.height are the uploaded file's size. The image's room is its column's width (see Divider width) less its left and right containerPadding. src.height is not imported, so the image keeps the file's aspect ratio at the width it is shown at.

TIP

A px width keeps its size on a phone, where a percentage shrinks with the column, so a maxWidth under 100% is approximated.

Button width ​

Unlayer sizeButtonBlock.widthStatus
missing, or autoWidth true (the default)none, so the button fits its labelConverted
autoWidth: false, width 100%"full"Converted
autoWidth: false, width above 0 and below 100%, such as 40%that percentage, rounded to two decimals, "40%"Converted
autoWidth: false, width above 100%"full"Approximated
autoWidth: false, width that rounds to 0%none, so the button fits its labelApproximated
autoWidth: false, width missing or not a percentagenone, so the button fits its labelApproximated

Unlayer applies width only when autoWidth is false. A percentage is a share of the column less the button's containerPadding, the box a percentage ButtonBlock.width is measured against, so the button shrinks with its column on a phone. fullWidthOnMobile is not imported.

Button line height ​

lineHeight becomes ButtonBlock.lineHeight, a multiple of the label's font size. A percentage is that number over 100 (150% is 1.5), a unitless number is itself, a px length is that many pixels over the button's font size, and an em length is the number. It is rounded to two decimals. 120% (Unlayer's default), normal, and a missing value leave it unset, which renders 1.2. A value it can't read imports at 1.2, and the entry is approximated with a note naming it: Button line-height "auto" could not be read; imported at 1.2.

Divider width ​

Unlayer widthDividerBlock.widthStatus
missing, or 100%"full"Converted
a percentage under 100%, such as 50%the same percentage to two decimals, "50%"Converted
below 0% or above 100%clamped to "0%" or "full"Approximated
px, narrower than the line's spanthe px numberConverted
px, as wide as that span or wider"full"Converted
any other value"full"Approximated

A px width is compared with the line's span: its column's width less the divider's left and right containerPadding. The column's width is its share, under the section's column layout or its columnWidths, of the row's inner width, which is settings.width less the row's left and right padding, and settings.width is a px contentWidth, else 600.

TIP

mj-divider draws 100% across that span, so a px width that reaches it renders the same as "full". "full" also narrows with the column on a phone.

Templatical centres every divider. A partial-width divider that Unlayer aligns left or right (textAlign) is approximated, and its note names the alignment.

Dividers that draw no line ​

A divider draws no line when its border.borderTopWidth is 0, its borderTopStyle is none or hidden, or its borderTopColor is transparent: transparent, or a colour with an alpha of 0 such as rgba(0, 0, 0, 0) or #ffffff00. Such a divider only adds space.

Unlayer dividerResultStatus
draws a linedivider, by the rules aboveConverted
draws no line, and its padding and transparent border add up to more than 0pxspacerConverted, with a note naming the height
draws no line and takes no spaceno blockSkipped

The spacer's height is the top plus bottom containerPadding plus the width of a transparent border. A containerPadding with a negative side counts as no padding, since CSS drops it. A none or hidden border takes no space, so its width doesn't count. A spacer renders no padding, so its own padding is 0. A divider with no border at all imports as a 1px solid black line.

Column Layout Conversion ​

Unlayer organizes content into rows with columns whose widths come from a cells weight array. These map to Templatical's SectionBlock with the appropriate ColumnLayout:

Unlayer cellsTemplatical Layout
[1] (single column)'1'
[1, 1] (equal halves)'2'
[1, 1, 1] (equal thirds)'3'
[1, 2]'1-2'
[2, 1]'2-1'
[1, 3]'1-3'
[3, 1]'3-1'
[1, 2, 1]'1-2-1'
[1, 1, 1, 1] (equal quarters)'4'
5+ cellsflattened to a single column with a warning

Cells are relative weights: a column's share is its cell over the sum of the row's cells. Cells whose shares equal a preset's keep that layout and set no columnWidths, so [2, 4] is '1-2' and [3, 3, 3] is '3'. Any other ratio of two, three or four cells keeps the even layout of that count ('2', '3' or '4') and sets columnWidths to the shares scaled to 100. [7, 3] is [70, 30], [2, 5, 2] is [22.22, 55.56, 22.22] and [6, 2, 2, 2] is [50, 16.67, 16.67, 16.66]. The import adds no warning for that ratio. A cell that is not a number above 0 leaves the even layout with no columnWidths. When the cells total more than 0, one warning names the ratio: Row with 2 columns at ratio 1:0 was kept as an even split. A cell that is not above 0 cannot be stored as column widths. Cells that total 0 or less add no warning.

Section background ​

Unlayer row valuessection.styles.backgroundColor
columnsBackgroundColor setcolumnsBackgroundColor
only backgroundColor setunset; the colour is the full-width wrapper

When a row sets backgroundColor, that colour becomes section.wrapper.backgroundColor with wrapper.fullWidth: true, including when it matches columnsBackgroundColor. The section keeps columnsBackgroundColor. With no content colour the section background stays unset, so the band shows through the content box.

TIP

columnsBackgroundColor fills the content width, the area a section paints. backgroundColor fills the band outside it and is stored on section.wrapper with fullWidth: true, so the band runs to the window edge.

Section background image ​

A row's backgroundImage becomes the section's backgroundImage:

backgroundImage.fullWidthResult
false (the content area)The section's image, exactly.
omitted or truewrapper.backgroundImage with wrapper.fullWidth: true. The section keeps columnsBackgroundColor, or stays unset when that colour is absent.

A band colour is left off the wrapper when the section keeps a content-area image (fullWidth: false): Outlook desktop paints a wrapper colour over that image, and report.warnings names the dropped colour.

size cover and contain carry over, and custom is the image at its own size (auto). The nine position keywords map to the matching grid point. A custom position's customPosition percentage snaps to the nearest of left, center and right (top, center and bottom), and a length to the left or top edge. repeat-x and repeat-y become repeat. Older designs' cover and center flags are read when size and position are absent: cover maps to cover (false to auto), and center to center top (false to left top). Each value with no exact keyword adds a line to report.warnings.

Template Settings ​

Global template settings are converted where possible:

  • Width — Unlayer body.values.contentWidth maps to settings.width
  • Background color — body.values.backgroundColor maps to settings.backgroundColor
  • Background image — body.values.backgroundImage has no Templatical equivalent, since the email body takes a colour only. It's dropped, and report.warnings names it.
  • Text color — body.values.textColor maps to settings.textColor. Headings, menus and paragraphs with no colour of their own inherit it.
  • Links — body.values.linkStyle.linkColor maps to settings.linkColor, and linkStyle.linkUnderline to settings.linkUnderline. When linkStyle sets no linkUnderline, links are underlined, as in Unlayer.
  • Preheader — body.values.preheaderText maps to settings.preheaderText, omitted when empty
  • Font family — body.values.fontFamily.value carries over to settings.fontFamily. The whole stack carries over, so its fallbacks survive; a stack that is exactly a built-in font's own (Arial, sans-serif) is stored as the bare name.

Known Limitations ​

  • Custom fonts — Unlayer custom font declarations are not automatically imported. Add them manually via the fonts config option.
  • Display conditions / dynamic content — Unlayer's conditional content syntax has no direct equivalent and is dropped during conversion. Use Templatical's display conditions to recreate them.
  • Custom modules / paid-tier blocks — Unlayer custom blocks are converted to placeholder HTML blocks. Recreate them as a custom block if reusable.
  • Forms — Unlayer form blocks are skipped. Most email clients block form submission for security reasons; rebuild the call-to-action as a button linking to a hosted form.
  • Timers / countdowns — Imported as a placeholder HTML block. Do not emit type: "countdown": that block needs Cloud's server-side GIF and the OSS renderer cannot produce it. Recreate as a static title or paragraph (the date, or "X days to go"), or keep the HTML placeholder.
  • Link hover styles and per-block link styles — linkStyle.linkHoverColor and linkHoverUnderline have no Templatical field and are dropped. A text block's own linkStyle is not read, so its links take the document's link settings.
  • AMP for Email — not currently supported in Templatical.

Verifying Converted Templates ​

After conversion, review the output in the editor to check for:

  1. Missing images (re-upload or update URLs if needed)
  2. Font rendering (add custom fonts to the editor config)
  3. Column proportions (adjust layouts if the automatic mapping doesn't match)
  4. Spacing and padding (fine-tune in the block settings panel)