English
Migrating from Stripo
This guide is for teams who've built email templates in Stripo — in the hosted editor, or through a product that embeds the Stripo Plugin — and want to move to Templatical's visual editor. @templatical/import-stripo converts Stripo HTML into Templatical's TemplateContent format. Install it, run it, and use the sections below to finish off anything it can't map on its own.
Stripo stores two different HTML surfaces. The converter auto-detects which one you passed. There is no mode flag.
| Surface | Where it comes from | Discriminator |
|---|---|---|
| Plugin / editor storage | getTemplateData() → { html, css } | esd-stripe, esd-structure, esd-block-* on elements |
| Compiled export | File → HTML, or compileEmail({ callback }) | es-wrapper, es-content-body, es-header-body — no esd-* on elements |
A leftover .esd-block-html rule inside a stylesheet is not a discriminator. CSS-only leftovers convert as generic HTML.
Installation
bash
npm install @templatical/import-stripobash
pnpm add @templatical/import-stripobash
yarn add @templatical/import-stripobash
bun add @templatical/import-stripoWithout a build step (CDN)
html
<script type="module">
import { convertStripoTemplate } from 'https://cdn.jsdelivr.net/npm/@templatical/import-stripo/+esm';
// ...then convert as shown in Usage below
</script>Usage
ts
import { convertStripoTemplate } from '@templatical/import-stripo';
// Plugin host — what you stored from getTemplateData():
const { html, css } = await window.StripoApi.getTemplateData();
const { content, report } = convertStripoTemplate(html, { css });
// Marketer File → HTML export:
const exported = await fetch('/path/to/export.html').then((r) => r.text());
const compiled = convertStripoTemplate(exported);
const editor = await init({
container: '#editor',
content: compiled.content,
});convertStripoTemplate is synchronous and returns an ImportResult with:
content— the convertedTemplateContentready for the editorreport— a conversion report with the status of each source element (converted,approximated,html-fallback, orskipped)
Pass options.css with plugin storage (getTemplateData().css). Those rules apply to each cell the HTML importer converts. A compiled File → HTML export already inlines the same rules.
Unrecognized HTML (no Stripo class attributes) is converted through @templatical/import-html and the report carries a warning naming that fallback.
Options
convertStripoTemplate accepts a second argument of type ConvertStripoOptions. 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.
ConvertStripoOptions also retains css?: string for plugin storage. HTML <html lang> declares the default.
ts
export interface ConvertStripoOptions {
defaultLocale?: string;
css?: string;
}Reading the report
Each report.entries item describes one source element:
| Status | Meaning |
|---|---|
converted | Mapped to a Templatical block with no loss of fidelity. |
approximated | Mapped to a Templatical block, with a clamp or flatten — note states what changed. |
html-fallback | No block equivalent; the original markup is preserved in an HtmlBlock. |
skipped | Reserved for parity with the other @templatical/import-* packages; this converter does not currently produce it. |
The report lists the blocks that remain in content, including each section Stripo emits. A <tr> section the HTML importer invents while walking a cell is omitted. Warnings from that walk remain.
ts
console.log(report.summary);
// { total: 18, converted: 16, approximated: 1, htmlFallback: 1, skipped: 0 }
for (const entry of report.entries) {
if (entry.status === 'approximated') {
console.warn(`<${entry.sourceTag}> approximated:`, entry.note);
}
}Path 1 — Rebuild visually using your Stripo export as a reference
For a handful of templates, rebuilding by hand next to a compiled preview is often faster than installing a package:
- Export File → HTML from Stripo and open it in a browser — that's your visual target.
- Open the Templatical editor (or the playground) side-by-side.
- Drag in the equivalent Templatical blocks (see the mapping tables below).
- Copy text content directly. Re-host images via your media library.
Most Stripo templates port in 10–20 minutes once you've done one or two. For a larger batch, run @templatical/import-stripo first and use this path only to finish off what it left approximated or as an html-fallback block.
Plugin HTML mapping
Plugin storage is a table tree labelled with esd-* classes. Each esd-structure becomes a SectionBlock; its esd-container-frame children are the columns.
| Stripo marker | Templatical block | Notes |
|---|---|---|
esd-structure with 1–4 esd-container-frames | SectionBlock (columns from the frame count and widths; see Column geometry under Where the mapping is lossy) | Frames are the columns. Padding comes from es-p* on the structure (default 0); an inline padding overrides the sides it states. |
esd-structure with 5+ frames | SectionBlock columns: "1" | Flattened; approximated. |
esd-block-text | title / paragraph | Generic HTML mapping of the inner markup. |
esd-block-image | image | Generic HTML mapping of the inner <img>, including its width rule. |
esd-block-button | button | href, text, target="_blank" → openInNewTab. Inline background / color / border-radius when present. Inline font-size (the anchor's, else the wrapping es-button-border's) becomes fontSize when it is a px length or a bare number, rounded to whole pixels; any other value, or one that rounds to 0 or below, imports at the factory 15px, approximated. Inline line-height (the anchor's, else the wrapping es-button-border's, where a percentage or em is first resolved against that wrapper's font-size, and an anchor's inherit takes the wrapper's; when the anchor sets its own font-size and the wrapper's is missing or not px, 15px stands in for the wrapper's and the button is noted) becomes lineHeight, a multiple of the label size: 150% is 1.5, a number or em length is itself, and a px length is over the button's font size, so font-size:18px; line-height:27px is 1.5. A percentage or em beside an anchor font-size it can't read keeps its ratio to that 15px label. An anchor's 120%, normal and a missing value stay unset (1.2); a wrapper's 120% is resolved like any other wrapper percentage, so it stays unset only when it comes to 1.2 of the label. A value it can't read imports at 1.2, approximated. |
esd-block-menu (2+ item cells) | menu | One MenuItemData per item cell. |
esd-block-menu (1 item cell) | paragraph (or the inner mapping) | A stacked step, not a nav — Password-reset rows stay copy. |
esd-block-social | social | Platform from title / src / alt. An unmatched icon with an image becomes a custom icon (its own image, link and alt) in the same social block. Without an image it becomes a website icon and the block is reported approximated. |
esd-block-spacer | spacer or divider | A visible border-bottom or border-top on the spacer or its inner cell becomes a divider (style, colour, thickness, and the width rule below). Otherwise a spacer: height from style, the height attribute, or vertical padding. |
esd-block-html | html | Inner markup preserved. |
Compiled HTML mapping
Compiled export drops esd-* from elements and keeps es-* leftovers. Each direct row of a stripe becomes its own section, in document order. Columns are the floated es-left / es-right tables inside that row.
| Stripo marker | Templatical block | Notes |
|---|---|---|
es-header / es-content / es-footer | one or more SectionBlocks | One section per direct row of the stripe's es-*-body. A stripe with no es-*-body uses its own rows. An empty row is skipped. |
| Content beside the columns in the same cell | one-column SectionBlock | Leading content stays before the column section and trailing content after it. Content that sat between the columns is placed after the column section (approximated). Splitting one padded cell into more than one section is approximated; the top padding stays on the first section, the bottom on the last, and the sides on each. |
1–4 es-left / es-right in one row | columns from the column count and widths; see Column geometry under Where the mapping is lossy | Floated tables in that row, including tables nested in a wrapper. Columns nested inside another es-left / es-right stay inside it. |
| 5+ floated tables in one row | columns: "4" | Extra columns merge into the fourth slot; approximated. |
a.es-button | button | Inline background / color / border-radius / font-size / line-height, including from the wrapping es-button-border, read as for esd-block-button. Widgets stay in document order with the copy around them. |
table.es-menu (2+ item cells) | menu | |
table.es-menu (1 item cell) | inner mapping | A stacked step, same rule as the plugin path. |
table.es-social | social | Same platform mapping as the plugin path. An unmatched icon with an image becomes a custom icon (its own image, link and alt) in the same social block. Without an image it becomes a website icon and the block is reported approximated. |
es-spacer with a visible border | divider | Style, colour and thickness from border-bottom or border-top. Width follows the rule below. |
es-spacer with no border | spacer | Height from style, the height attribute, or vertical padding. |
settings.backgroundColor is the first painted es-wrapper or es-wrapper-color (#ffffff when neither is set). An es-*-body fill is the section's background. A stripe (esd-stripe, or es-header / es-content / es-footer) around that body whose colour differs from the page is a full-width band: the colour becomes section.wrapper.backgroundColor with wrapper.fullWidth: true, so the band runs to the window edge and the content stays at the email width, including when the stripe colour matches the body. A transparent body moves that colour off the section onto the wrapper. A stripe colour the same as the page stays off the wrapper. A stripe with no inner body keeps its colour on the section. Background images, and what they do to that band colour, follow Background images.
The structure cell's padding is the section's padding. The default is 0. On plugin HTML, es-p20 sets every side and es-p10t / es-p10r / es-p10b / es-p10l override one side; an inline padding overrides the sides it states. Those classes are read on the structure element.
A divider's width uses the column it sits in. No width, auto or 100% spans that column. Another percentage stays a percentage, rounded to two decimals and clamped to 0–100. A px width stays px until it fills the column's room (the column's share, by its layout or its columnWidths, of the section's inner box, which is the body width less the section's left and right padding, then less the divider's own side padding). double, groove, ridge, inset and outset import as solid. A partial-width line aligned left or right is centred, and that entry is approximated. A partial line with no alignment is treated as left.
Everything else in a row goes through @templatical/import-html (headings, paragraphs, images, <hr> dividers).
Background images
An element's image is read from its inline background-image, the image in its background shorthand, or its background attribute. A section takes the nearest:
- The structure's own image: the row cell,
esd-structurein plugin HTML. - The
es-*-bodyimage, the content area behind every structure in the stripe. - The containers' images (
es-left/es-right, oresd-container-frame), when there is one container or they all share the same image. Otherwise, or beside a nearer image, they're dropped, and the note names the columns. - The stripe's image becomes
wrapper.backgroundImagewithwrapper.fullWidth: true, including when the body covers it. A stripe with no inner body keeps its colour on the section and still puts that image on the wrapper.
An image behind several sections, such as a body image or a stripe image across several structures, is copied onto each, and each entry is approximated with a note. When a section has an image, a stripe colour that would have become section.wrapper.backgroundColor is dropped with a note instead, because Outlook desktop paints a wrapper colour over the section's image. The stripe image stays on the wrapper. An es-wrapper image has no Templatical equivalent, and report.warnings names it.
background-size, background-position and background-repeat come along, with CSS's initial values where unset. A size that fills a side (100%, 100% auto, or a px width at least the body's) becomes cover, and any other length or percentage becomes auto. A percentage position snaps to the nearest of left, center and right (top, center and bottom), and a length to the left or top edge. repeat-x, repeat-y, round and space become repeat. Each such value is noted.
Where the mapping is lossy
- Column geometry — Templatical supports these column layouts (
1,2,3,4,2-1,1-2,3-1,1-3,1-2-1). A row of two to four columns reads each column's px width from its plugin frame or its compiledes-left/es-righttable. A column's share is its width over the sum of the row's widths, so the gutter between columns is not a share. Widths within 1px of each other are the equal layout2,3or4. Widths within 1px of2-1,1-2,3-1,1-3or1-2-1are that layout:200px/400pxis1-2. Any other widths keep the equal layout and setcolumnWidthsto their shares scaled to 100:180px/420pxis2with[30, 70]. All of these stayconverted. When a column has no readable width, the row has no ratio and keeps the equal layout. The section isapproximatedwith a note naming every width when at least two readable widths differ by more than 1px; with fewer than two readable widths, or readable widths within 1px, it staysconverted. Plugin HTML with 5 or more frames flattens to one column. Compiled HTML with 5 or more floated tables in one row keeps four slots and folds the rest into the last. Content between those columns becomes its own one-column section after them, and a padded cell split across the resulting sections isapproximated. - Social icon
alt— an unrecognised icon with an image becomes a custom icon and keeps itsalt(ortitle); a recognised platform is drawn with Templatical's built-in icon and stores noalt. - Block IDs — every imported block gets a freshly generated ID.
- AMP / timers / modules — no Templatical equivalent; inner markup lands as
htmlor is skipped with a warning. - Plugin CSS — pass
options.csswith plugin storage. Rules that live only in that stylesheet are applied to the converted blocks. Compiled exports already inline them.
Things that don't map automatically
- A round-trip back into Stripo — the output is Templatical JSON, not Stripo editor HTML.
- Generic HTML that was never a Stripo document — use
@templatical/import-htmldirectly. Passing it here still converts, with a warning.
Further help
Open a discussion with a redacted snippet of your Stripo HTML and what you're trying to achieve. We use these reports to improve @templatical/import-stripo's coverage.