---
title: Migration from HTML
description: Convert HTML email templates to Templatical format using @templatical/import-html.
---

# Migration from HTML

The `@templatical/import-html` package converts HTML email templates into Templatical's `TemplateContent` format. It's designed for the table-based HTML that real marketing emails actually ship — output of MJML, Mailchimp/SendGrid/Campaign Monitor exports, hand-coded campaigns.

::: warning
This package is in active development. Modern (flex/grid) HTML is preserved via HTML-fallback blocks rather than re-decomposed; review your converted templates before using them in production.
:::

## Installation

::: code-group

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

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

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

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

:::

### Without a build step (CDN)

You can also load it from a CDN:

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

## Usage {#usage}

```ts
import { convertHtmlTemplate } from '@templatical/import-html';

// Load the raw HTML source of an email
const res = await fetch('/path/to/email.html');
const html = await res.text();

// Convert to Templatical format
const { content, report } = convertHtmlTemplate(html);

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

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

[Open in playground](https://play.templatical.com/scenes/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 element (`converted`, `approximated`, `html-fallback`, or `skipped`)

## Options {#options}

`convertHtmlTemplate` accepts a second argument of type `ConvertHtmlOptions`. `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.

The source declares its default with `<html lang>`.

```ts
export interface ConvertHtmlOptions {
  defaultLocale?: string;
}
```

## Element Mapping

HTML elements map to Templatical equivalents:

| HTML Element | Templatical Block | Status |
|---|---|---|
| `<h1>` – `<h4>` | `title` | Converted (level preserved) |
| `<h5>` – `<h6>` | `title` | Converted (clamped to level 4) |
| A heading wrapped in a `<div>`, `<center>` or `<main>` | `title` | Converted (wrapper unwrapped) |
| `<p>` / text-only `<div>` / `<span>` | `paragraph` | Converted |
| Text-only `<td>` in a layout table | `paragraph` | Converted |
| Bare text at body level or directly inside a wrapper | `paragraph` | Converted |
| `<img>` | `image` | Converted (approximated when a percentage width becomes px; see [Image width](#image-width)) |
| `<a>` styled as button (background color, padding, border-radius, or `display: inline-block`) | `button` | Converted (approximated when its `line-height` can't be read; see [Button line height](#button-line-height)) |
| `<a>` (text link) | folded into the surrounding `paragraph` | Converted |
| `<a>` wrapping an `<img>` | `image` with `linkUrl` | Converted |
| `<hr>` | `divider`, or `spacer` when it [draws no line](#hr-lines) | Converted (approximated when the width is clamped or unreadable, or a partial-width divider is aligned left or right; skipped when it draws no line and takes no space) |
| Empty `<td>` with explicit height | `spacer` | Converted |
| `<td>` whose entire content is one styled text `<a>` | `button` | Converted (cell-as-button pattern; approximated when its `line-height` can't be read) |
| `<table>` (layout, multi-row/column) | `section` (one per `<tr>`) | Converted |
| `<table>` (data table — text-only cells) | `html` | HTML fallback |
| Unknown / custom elements | `html` | HTML fallback |

Anything that can't be mapped is preserved verbatim inside an HTML block, so no visible content is lost.

A cell mixing copy with a link becomes one `paragraph` holding both, with the `<a>` and its `href` inline. A cell whose entire content is one styled text `<a>` reads as a button.

A `<div>`, `<center>` or `<main>` that wraps a table produces no block of its own: the importer descends into it, at any nesting depth, and maps the tables it finds. A wrapper holding only text keeps its `paragraph` mapping, and a wrapper whose whole content is one heading is unwrapped so the heading is what gets mapped.

A text-only wrapper's `text-align` applies to each `<p>` inside it that states no `text-align` of its own. A `<p>` that states one keeps it.

### Image width {#image-width}

| `<img>` width | `ImageBlock.width` | Status |
|---|---|---|
| missing, or `100%` | `"full"` | Converted |
| px, narrower than the image's room | the px number | Converted |
| px, as wide as the room or wider | `"full"` | Converted |
| a percentage under `100%`, such as `50%` | that share of the room in px | Approximated |

The `width` attribute is read first, then the `width` style. The image's room is its column's width less the image's left and right padding. Where the room is unknown (an image inside a link that also holds text), a px width stays as written and a percentage is `"full"`, approximated.

A `height` style overrides the `height` attribute, as it does in a browser, so `height: auto` leaves the height unset and the image keeps its aspect ratio.

### Button line height

A button's `line-height` style 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. The font size is the button's `font-size`, else 16px. A button cell reads both from the cell and the `<a>`, the `<a>` winning. A percentage or `em` line height that only the cell states is the length it computes to on the cell, as CSS inherits it: `font-size:20px; line-height:150%` on the cell around a 10px `<a>` is `3`. An `<a>` with `line-height: inherit` takes the cell's. When neither the cell nor the `<a>` sets a font size, both inherit the same one, so the ratio is kept as written (`150%` is `1.5`). When the `<a>` sets its own and the cell's is missing or not a px length, 16px stands in for the cell's and the entry is approximated with a note. A bulletproof anchor with `font-size:16px; line-height:44px` is `2.75`. `normal`, a value that rounds to 1.2, 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 "calc(1em + 4px)" could not be read; imported at 1.2.`

### Divider width

The width comes from the `<hr>`'s `width` style, then its `width` attribute.

| `<hr>` width | `DividerBlock.width` | Status |
|---|---|---|
| missing, `auto` 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 room | the px number | Converted |
| px, as wide as the line's room or wider | `"full"` | Converted |
| a negative px width | `0` | Approximated |
| any other value, such as `20em` | `"full"` | Approximated |

The line's room is the column's share of `settings.width`, by the section's column layout or its `columnWidths`, less the padding of the section, of every cell and wrapper around the `<hr>`, and of the `<hr>` itself.

Templatical centres every divider. A partial-width `<hr>` that its `align` attribute or its margins place at the left or the right is approximated, and its `note` names the alignment.

### `<hr>` lines and spacing {#hr-lines}

An `<hr>` imports as the line it draws. Its line is the top border (`border-top`, else the `border` shorthand), or the bottom border when the top draws nothing, as in `border: 0; border-bottom: 1px solid #cccccc`. Each side's longhands (`border-top-color`, `border-width: 0 0 1px` and the like) apply over its shorthand. A border draws nothing when it's 0 wide, `none` or `hidden`, or transparent: `transparent`, or a colour with an alpha of 0 such as `rgba(0, 0, 0, 0)` or `#ffffff00`.

| `<hr>` | Result | Status |
|---|---|---|
| no border declared for the top or bottom: no `border`, `border-top` or `border-bottom`, and none of their width, style or colour longhands | `divider`, 1px solid black | Converted |
| a border that draws | `divider` in the border's width and colour; `dashed` and `dotted` keep their style, any other style is `solid` | Converted |
| no border that draws, and a `background` or `background-color` with a `height` | `divider` in the background colour, as thick as `height`, solid | Converted |
| no border that draws, no background, and room taken | `spacer` | Converted, with a `note` naming the height |
| no border that draws, no background, and no room taken | no block | Skipped |

The usual email `<hr>`, `border: 0; height: 1px; background: #cccccc`, is the background row. A background that is transparent, or a `height` of 0, draws no line. The spacer's `height` is the `<hr>`'s top and bottom margins and padding, its `height`, and the widths of transparent top and bottom borders; a `none` or `hidden` border takes no room. A negative padding or `height` counts as 0, since CSS drops it; a negative margin counts. It never goes below 0, so negative margins that add up to less are skipped. A spacer renders no padding, so its own padding is 0. The width rules above apply to every divider row.

## Inline Formatting

`<br>`, `<em>`, `<strong>`, `<i>`, `<b>`, `<u>`, `<small>`, `<sub>` and `<sup>` stay inside the text they belong to. A run of them, together with the bare text around it, becomes one `paragraph` whose colour, size and alignment come from the containing cell — so `Hello<br>World` in a `<td>` imports as a single paragraph holding both words and the line break.

A text `<a>` folds into that run, keeping its `href`, so a sentence containing a link arrives as one paragraph rather than as a link torn out of its copy. An `<a>` wrapping an `<img>` becomes an `image` with `linkUrl` from a non-empty href. An `<a>` wrapping both an image and text becomes that `image` plus a sibling `paragraph` that keeps the remaining `<a>`.

::: tip
Bare text counts as content here. A cell walk that visited only element children dropped the words between two inline tags, and dropped a loose sentence sitting beside a table at body or wrapper level. Both are now kept.
:::

## Column Layout Conversion

Each `<tr>` in a layout table becomes a `SectionBlock`. The row's direct `<td>` / `<th>` children are the layout:

| Cells per row | Templatical Layout |
|---|---|
| 1 | `'1'` |
| 2 | `'2'`, `'2-1'`, `'1-2'`, `'3-1'` or `'1-3'`, by declared width |
| 3 | `'3'` or `'1-2-1'`, by declared width |
| 4 | `'4'` |
| 5+ | merged into `'1'`, with a warning and an `approximated` report entry |

### Column ratios

A row picks among the layouts that hold its column count, from the widths its cells declare — a `width` attribute, a `style="width:…"`, or the share in an `mj-column-per-*` class name. Every cell must declare a width, all in px or all in percent. A `100%` width states no share, since a cell sharing its row with it fills what is left, so it counts as undeclared: `30%` beside `100%` keeps the equal layout with no `columnWidths`. A column's share is its width over the sum of the declared widths, so a gutter between cells is not a share. Two cells choose among `'2'`, `'2-1'`, `'1-2'`, `'3-1'` and `'1-3'`; three cells between `'3'` and `'1-2-1'`; four cells are `'4'`. The closest wins when it sits within 2 percentage points on the worst column, so `350` / `190` reads as `'2-1'`, `25%` / `75%` as `'1-3'` and `130` / `280` / `130` as `'1-2-1'`.

Any other ratio keeps the equal layout for that cell count and sets [`columnWidths`](/guide/sections-and-columns#custom-column-widths) to the shares scaled to 100. `70%` / `30%` is `'2'` with `[70, 30]`, `200` / `300` is `'2'` with `[40, 60]`, and `10%` / `80%` / `10%` is `'3'` with `[10, 80, 10]`. The section entry stays `converted`. A row that declares no widths, declares only some of them, or mixes px and percent keeps the equal layout with no `columnWidths`.

### Wrapper rows

Table-based emails wrap their real layout in one-cell tables. A row holding a single cell whose content is nothing but tables is descended instead of becoming a section, so the column count is read off the row that declares it. The descent applies only when that cell holds no content beside its tables and the row's `style` sets no background colour, no background image and no padding — a row failing any of those becomes a section of its own, because the section is what carries a row's background and padding.

A fill the descent passes, from the row's `bgcolor`, the cell or the table, carries to the sections below it. So does a background image on the cell or the table; when one lands on more than one section, each of those entries is `approximated` with a note.

A packaging row whose table or single cell has `width="100%"` (attribute or style), and a background colour or image, and whose every inner table has a fixed px width, is a full-width band. Each section inside it gets `section.wrapper` with that colour and image and `wrapper.fullWidth: true`, so the band runs to the window edge while the content stays at the email width. Fills on the inner tables stay on the sections. A band colour is left off that wrapper when the section keeps its own background image, and that section's report entry is `approximated` with a note: Outlook desktop paints a wrapper colour over the section image. The band image still sits on the wrapper. A band reached from inside a column is not viewport-wide. Page chrome that matches the pattern — an outer `width="100%"` table around a fixed-width content table — becomes a wrapper on each section; `settings.backgroundColor` still comes from the `<body>`.

### Gutter rows

A row that pads its content with empty cells — `&nbsp;` either side of a centred container — is read as the single column it lays out, not as one column per cell. The signal is content: a cell holding nothing takes part in no layout.

### Sibling column containers

A single `<td>` holding one `display: inline-block` container per column is read as a column set, with the column count taken from the number of containers and the ratio from their declared widths. This is how hybrid templates and compiled MJML state their columns — MJML puts a whole section's columns into one cell as sibling `<div class="mj-column-per-*">` elements — so such a row has no cell count to read.

Every container must be laid out side by side, none may be empty, and no text of the cell's own may sit beside them. A cell failing any of those is a single column.

::: tip
`display: inline-block` is what makes a set of containers a set of columns, since a block-level `<div>` stacks instead. Requiring it keeps two stacked divs from being read as a layout the source never stated.
:::

### Nesting

Templatical sections cannot nest. Tables nested inside a `<td>` are flattened — their inner blocks are merged into the parent cell. A nested row with more than one cell loses its columns that way, and `report.entries` records it as `approximated` with a note.

### Section backgrounds

A section takes the nearest fill, read from a `background-color` style, the colour in a `background` shorthand (even one that also sets an image) or a `bgcolor` attribute:

1. The `<tr>`.
2. The row's cells, when they all share one fill. Gutter cells do not count, and a cell whose entire content is one styled text `<a>` keeps its colour on the `button`.
3. The `<table>` holding the row, then the tables and wrapper cells around it.

A section has one background colour, so a row whose cells render on different fills is approximated, and its `note` names each cell's fill.

### Section background images {#background-images}

A section takes the nearest image, read from a `background-image` style, the image in a `background` shorthand, or the `background` attribute of a `<table>`, `<td>` or `<th>`. A `background-image` or `background` declaration on the element overrides the attribute; a `background-color` doesn't.

1. The `<tr>`, or the cell holding a row's column containers.
2. The row's columns, when there is one or they all share the same image. Gutter cells don't count, and neither does a cell whose entire content is one styled text `<a>`. Columns whose images differ, and column images beside a nearer image, are dropped, and the `note` names the columns.
3. The `<table>` holding the row, then the wrapper cells and tables around it. An image that lands on several sections is copied onto each, and each of those entries is `approximated` with a note.

`background-size`, `background-position` (and `-x` / `-y`) and `background-repeat` come along, longhands winning over the shorthand, with CSS's initial values (`auto`, `0% 0%`, `repeat`) where unset. A bare `background` attribute tiles from the top left at the image's own size, as a browser draws it. A value with no exact keyword maps to the nearest one, `approximated` with a note. A size that fills a side (`100%`, `100% auto`, or a px width at least the email'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`. Of several layers the first image is kept, and the note says so.

### Cell padding {#cell-padding}

A cell's padding is added to the padding of every block the cell holds: the left and right to every block, the top to the first and the bottom to the last. A table's `cellpadding` pads each of its cells, and a side the cell's own `padding` states overrides it.

The padding of nested cells, and of the `<div>`, `<center>` and `<main>` wrappers inside a cell, adds up. A cell holding one column container per column pads the row: the top and bottom go to each column's first and last block, the left to the first column and the right to the last.

A spacer renders at its height, so a spacer at a cell's edge takes that side's padding as extra height. A cell whose entire content is one styled text `<a>` keeps its padding as the `button`'s own.

## CSS Handling

`<style>` blocks are resolved onto matching elements before conversion:

- **Inline styles always win** over rules from `<style>` blocks.
- **`@media` queries are skipped** — they would always apply if flattened. Email is rendered at one viewport in the editor.
- **`@font-face`, `@keyframes`, `@supports`** are skipped.
- **Pseudo-classes (`:hover`, `::before`)** are skipped.
- **External stylesheets (`<link rel="stylesheet">`)** are not fetched.
- **`!important` markers** are dropped (no specificity conflicts to resolve).

For best fidelity, inline your styles before importing. Most production marketing emails are already inlined by their sending pipeline.

## Template Settings

Global template settings are extracted from the document:

- **Width** — outermost `<table>` `width` attribute or `style="width:…"`. Defaults to `600`.
- **Background color** — `<body>` `background-color` style, or the colour in its `background` shorthand. Defaults to `#ffffff`.
- **Background image** — a `<body>` background image (style or `background` attribute) has no Templatical equivalent. It's dropped, and `report.warnings` names it.
- **Font family** — `<body>` `font-family` style. Defaults to `Arial`. 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.
- **Link underline** — `text-decoration` in a `<style>` rule for every link, `a { … }`. Defaults to `true`, the browser default. A rule scoped to some links, a `:hover` state or an `@media` query does not set it.
- **Preheader text** — first `<div style="display:none">` near the top of the body, by convention.

## Known Limitations

- **Modern HTML (flex / grid / `<div>` layouts)** — produces low-fidelity output, mostly HTML-fallback blocks. The importer is tuned for table-based email HTML.
- **Custom fonts** — `@font-face` rules are not imported. Add fonts manually via the editor's [`fonts` config option](/guide/fonts).
- **Display conditions / merge tags** — proprietary merge tag syntax (<code v-pre>{{var}}</code>, `*|VAR|*`, `<%= var %>`) is preserved as raw text. Recreate using Templatical [merge tags](/guide/merge-tags) or [display conditions](/guide/display-conditions).
- **External resources** — `<link>`, external stylesheets, web fonts, and remote images are not fetched. Image `src` URLs are preserved as-is.
- **Outlook MSO conditional comments** — preserved as HTML inside their containing block (they're inert in non-Outlook clients anyway).
- **`<form>` / `<input>` / `<button>` form controls** — preserved as HTML-fallback. Most email clients block form submission; rebuild the call-to-action as a button linking to a hosted form.
- **Rows of more than four cells** — `ColumnLayout` holds at most four columns, so a wider row is merged into one and reported.
- **AMP for Email** — not currently supported in Templatical.

## Verifying Converted Templates

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

1. **Element classification** — review `report.entries` for entries with `status: 'approximated'` or `status: 'html-fallback'`.
2. **Image URLs** — relative paths and CID references won't resolve in the preview; replace with absolute URLs.
3. **Column proportions** — a ratio within 2 percentage points of a preset snaps to it, and a row whose cells declare no widths is an equal split; fine-tune in the section settings panel.
4. **Spacing and padding** — cell padding is carried onto the blocks it holds, as described in [Cell padding](#cell-padding). Margins are not imported and may need touch-up.
5. **HTML-fallback blocks** — anything that landed in an HTML block can be edited inline or replaced with first-class blocks.

## Reading the Report

```ts
const { content, report } = convertHtmlTemplate(html);

console.log(report.summary);
// { total: 12, converted: 10, approximated: 1, htmlFallback: 1, skipped: 0 }

for (const entry of report.entries) {
  if (entry.status === 'html-fallback') {
    console.warn(
      `Element <${entry.sourceTag}> preserved as HTML:`,
      entry.note,
    );
  }
}

for (const warning of report.warnings) {
  console.warn(warning);
}
```

### Sections in the report

`report.entries` accounts for the sections alongside the leaf blocks, so the entries reconcile against `content.blocks`:

- One entry per section, with `sourceTag: 'tr'` and `templaticalBlockType: 'section'`. Its status is `converted` when every cell kept its own column and its fill, and `approximated` with a note when cells were merged, when the ratio had no equivalent, or when its cells rendered on different fills.
- One entry with `sourceTag: 'body'` and a note when loose top-level content is grouped into a synthetic single-column section.
- One entry with `templaticalBlockType: null` and a note for a nested row whose columns were dropped.

A wrapper the importer descends through contributes no entry of its own: nothing is created and nothing lost. So a heading lifted out of a `<div>` is reported under its own tag, and a cell's column containers appear nowhere.

::: warning Entry counts changed
Sections and lost layouts are reported where they previously were not, so `report.summary.total` is higher for the same document, and `approximated` now covers cases that raised only a `warnings` string or went unreported. Code that asserts on exact totals needs updating; code that filters by `status` or `templaticalBlockType` does not.
:::

HTML fallback blocks remain pass-through content. Check their client support with the [compatibility linter](/quality/compatibility/) and [caniemail](https://www.caniemail.com/) after import.
