---
title: Migrating from Stripo
description: Convert Stripo email templates to Templatical format using @templatical/import-stripo.
---

# Migrating from Stripo

This guide is for teams who've built email templates in [Stripo](https://stripo.email) — 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

::: code-group

```bash [npm]
npm install @templatical/import-stripo
```

```bash [pnpm]
pnpm add @templatical/import-stripo
```

```bash [yarn]
yarn add @templatical/import-stripo
```

```bash [bun]
bun add @templatical/import-stripo
```

:::

### Without 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 {#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,
});
```

[Open in playground](https://play.templatical.com/scenes/import-stripo)

`convertStripoTemplate` is synchronous and returns an `ImportResult` with:

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

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 {#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 <code v-pre>{{lang}}</code>, 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:

1. Export File → HTML from Stripo and open it in a browser — that's your visual target.
2. Open the Templatical editor (or [the playground](https://play.templatical.com)) side-by-side.
3. Drag in the equivalent Templatical blocks (see the mapping tables below).
4. 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-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-frame`s | `SectionBlock` (`columns` from the frame count and widths; see Column geometry under [Where the mapping is lossy](#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](/guide/migration-from-html#image-width). |
| `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-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 `SectionBlock`s | 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](#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](#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 {#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:

1. The structure's own image: the row cell, `esd-structure` in plugin HTML.
2. The `es-*-body` image, the content area behind every structure in the stripe.
3. The containers' images (`es-left` / `es-right`, or `esd-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.
4. The stripe's image becomes `wrapper.backgroundImage` with `wrapper.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 {#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 compiled `es-left` / `es-right` table. 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 layout `2`, `3` or `4`. Widths within 1px of `2-1`, `1-2`, `3-1`, `1-3` or `1-2-1` are that layout: `200px` / `400px` is `1-2`. Any other widths keep the equal layout and set [`columnWidths`](/guide/sections-and-columns#custom-column-widths) to their shares scaled to 100: `180px` / `420px` is `2` with `[30, 70]`. All of these stay `converted`. When a column has no readable width, the row has no ratio and keeps the equal layout. The section is `approximated` with 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 stays `converted`. 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 is `approximated`.
- **Social icon `alt`** — an unrecognised icon with an image becomes a custom icon and keeps its `alt` (or `title`); a recognised platform is drawn with Templatical's built-in icon and stores no `alt`.
- **Block IDs** — every imported block gets a freshly generated ID.
- **AMP / timers / modules** — no Templatical equivalent; inner markup lands as `html` or is skipped with a warning.
- **Plugin CSS** — pass `options.css` with 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-html`](/guide/migration-from-html) directly. Passing it here still converts, with a warning.

## Further help

[Open a discussion](https://github.com/templatical/sdk/discussions) 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.
