# Hyper Elements

> The content engine for agents: React components your agent writes, rendered to emails, pages, PDFs and images, checked in every client, with the fix for what's wrong.

Install: `npm i @hyper-elements/react`. Import components from `@hyper-elements/react`. A template has one root (Email, Page, Document or Canvas); styles go in style={{ }}; space between blocks is the parent's gap (no margins); render() returns { html, text, diagnostics }; validate() checks without rendering; outline() prints the laid-out template as text.

---

# Introduction

Source: https://hyperelements.dev/docs

Hyper Elements is a set of React components for emails, web pages, printed documents and images. You write a template once in JSX, and `render()` gives you the HTML its root asks for, with a plain-text version beside it, on your own server and with no network calls.

```tsx
import { Button, Column, Email, Heading, Text, render } from "@hyper-elements/react";

const welcome = (
  <Email previewText="Your account is ready" style={{ backgroundColor: "#f4f4f5" }}>
    <Column style={{ backgroundColor: "#ffffff", padding: 32, gap: 16 }}>
      <Heading level={1} style={{ fontSize: 24 }}>Welcome aboard</Heading>
      <Text>Your account is ready.</Text>
      <Button href="https://example.com/start">Get started</Button>
    </Column>
  </Email>
);

const { html, text } = await render(welcome);
```

## One template, four outputs

The root decides the output. Change the root and the same content renders somewhere else.

| Root | Output | Written by |
|------|--------|------------|
| `<Email>` | Email-safe HTML: tables, px widths, Outlook's markup in conditional comments | `render()` |
| `<Page>` | A responsive web page: semantic HTML and flexbox, no client-side JavaScript | `render()` |
| `<Document>` | Print-ready HTML on pages of its size, and a PDF | `render()`, and `renderPdf()` from `@hyper-elements/react/pdf` |
| `<Canvas>` | A PNG or SVG image of a fixed size | `renderImage()` from `@hyper-elements/react/image` |

## What you stop doing

- **Nesting tables by hand.** A `Row` of `Column`s becomes the tables Outlook needs, with every width worked out in px before anything is written.
- **Writing Outlook conditional comments.** Outlook-only markup goes inside `<!--[if mso]>`, and nothing other clients need goes in one.
- **Inlining styles.** Layout, colors, fonts, sizes and spacing are written inline, so the email holds its desktop layout where a client drops `<style>`.
- **Keeping a plain-text version in sync.** Every `render()` returns `text` beside `html`.
- **Writing media queries.** A `Row` stacks its children on phones by default, and `mobile={{ }}` holds a component's phone styles.
- **Running headless Chrome for a PDF.** `@hyper-elements/react/pdf` writes a `Document` as a PDF with no browser.
- **Guessing what an email client will do.** `validate()` checks every prop and style, and says what the output can't show as asked, with the path to the value.

## The shape of a template

```text
<Email>            the root: Email, Page, Document or Canvas
  <Section>        a band whose background spans the window (optional)
    <Row>          its children side by side, stacked on phones
      <Column>     its children stacked
        <Heading />
        <Text />
        <Button />
      </Column>
    </Row>
  </Section>
</Email>
```

A root, a `Section` and a `Column` stack what they hold, so a block doesn't need a `Row` around it. There are no margins: the space between blocks is their parent's `gap`, and the space inside a box is its `padding`. Styles go in `style={{ }}`, and a number is px.

## What's in the box

| Package | What it does |
|---------|--------------|
| `@hyper-elements/react` | The components, `render()`, `validate()`, `outline()`, `formatDiagnostics()`, `component()` and `prop`, and `ElementsError` |
| `@hyper-elements/react/builder` | `toDesign()` and `fromDesign()`: a template as the Unlayer builder's design JSON, and a design back as a template |
| `@hyper-elements/react/pdf` | `renderPdf()`: a `Document` as a PDF, with react-pdf, no browser |
| `@hyper-elements/react/image` | `renderImage()`: a `Canvas` as PNG or SVG, with Satori and resvg |
| `@hyper-elements/migrate` | `npx @hyper-elements/migrate`: React Email templates converted and checked against the originals, and templates written with Elements 0.2's components rewritten, with what may draw differently listed |

The source is on GitHub at [hyper-elements/hyper-elements](https://github.com/hyper-elements/hyper-elements), MIT licensed.

## What it doesn't do yet

- **Real email clients.** The email output is checked in Chromium and against a model of classic Outlook's layout built from captures of real Outlook. It hasn't been checked in real email clients yet, so test in the ones you send to.
- **Measuring text.** The layout gives every box a width without measuring its words, so a box can get less room than its content needs. See [Layout](https://hyperelements.dev/docs/layout).
- **Fetching files for PDF and images.** `renderPdf()` and `renderImage()` take fonts and images as bytes. Nothing is fetched.

## Where to go next

- [Quickstart](https://hyperelements.dev/docs/quickstart): install, write an email, render it and send it.
- [Templates and roots](https://hyperelements.dev/docs/templates): the four roots, their props, and your own components.
- [Layout](https://hyperelements.dev/docs/layout): Section, Row, Column, Grid and Layer.
- [Styles, phones and hover](https://hyperelements.dev/docs/styles): `style`, `mobile`, `hidden`, `hover` and fonts.
- [Rendering](https://hyperelements.dev/docs/rendering): `render()`, `validate()`, `outline()` and merge tags.
- [Diagnostics](https://hyperelements.dev/docs/diagnostics): what the checks report, and how to use them in CI.
- [Custom components](https://hyperelements.dev/docs/custom-components): `component()` and `<Html>`.
- Outputs: [Email](https://hyperelements.dev/docs/outputs/email), [Page](https://hyperelements.dev/docs/outputs/page), [PDF](https://hyperelements.dev/docs/outputs/pdf), [Image](https://hyperelements.dev/docs/outputs/image).

---

# Quickstart

Source: https://hyperelements.dev/docs/quickstart

This page takes you from an empty project to a sent email: install, write a template, render it, send it, and check it.

## Install

```bash
npm install @hyper-elements/react react react-dom
```

```bash
pnpm add @hyper-elements/react react react-dom
```

```bash
yarn add @hyper-elements/react react react-dom
```

```bash
bun add @hyper-elements/react react react-dom
```

`react` and `react-dom` are peer dependencies, version 18 or later. With TypeScript, set `"jsx": "react-jsx"` in your `tsconfig.json`.

## Write your first email

A template is a React component that returns one root. Everything comes from `@hyper-elements/react`.

```tsx
// emails/welcome.tsx
import { Button, Column, Email, Heading, Image, Text } from "@hyper-elements/react";

export function Welcome({ name }: { name: string }) {
  return (
    <Email previewText="Your Acme account is ready" style={{ backgroundColor: "#f4f4f5", fontFamily: "Helvetica, Arial, sans-serif", gap: 16 }}>
      <Image src={{ src: "https://example.com/logo.png", width: 240, height: 80 }} alt="Acme" style={{ width: 120 }} />
      <Column style={{ backgroundColor: "#ffffff", padding: 32, gap: 16, borderRadius: 8 }}>
        <Heading level={1} style={{ fontSize: 24 }} mobile={{ fontSize: 20 }}>
          Welcome, {name}
        </Heading>
        <Text>Your account is ready. Create your first project to get going.</Text>
        <Button href="https://example.com/projects/new" style={{ backgroundColor: "#111827", borderRadius: 6 }} hover={{ backgroundColor: "#374151" }}>
          Create a project
        </Button>
      </Column>
      <Text style={{ fontSize: 12, color: "#71717a", textAlign: "center" }}>Acme Inc., 1 Market St, San Francisco</Text>
    </Email>
  );
}
```

A few things to notice:

- Styles go in `style={{ }}`, never as props, and a number is px.
- There are no margins. The `gap` on the `Email` and the `Column` is the space between their children.
- The `Column` with a background and padding is a card. You didn't write a table.
- `Image` takes the file's size in `src` and the size shown in `style.width`. Without a width in either, Outlook shows the image at the size of its file. The file's size also gives Outlook its height.
- `mobile` holds the heading's size on phones, and `hover` the button's color under the pointer.

## Render it

```tsx
import { render } from "@hyper-elements/react";
import { Welcome } from "./emails/welcome";

const { html, text, diagnostics } = await render(<Welcome name="Ada" />);
```

`html` is the whole email document. `text` is the plain-text version, written from the same template:

```text
[Acme]

WELCOME, ADA

Your account is ready. Create your first project to get going.

Create a project (https://example.com/projects/new)

Acme Inc., 1 Market St, San Francisco
```

`diagnostics` holds warnings and notes. This template gets two notes, because classic Outlook draws square corners:

```text
info email/outlook-degraded at root.children[1].style.borderRadius: borderRadius on this Column in classic Outlook: square corners
info email/outlook-degraded at root.children[1].children[2].style.borderRadius: borderRadius on this Button in classic Outlook: square corners
```

A template with errors doesn't render: `render()` rejects with an `ElementsError` that lists each one. See [Diagnostics](https://hyperelements.dev/docs/diagnostics).

## Send it

Hyper Elements writes the email. Your provider delivers it. Pass both `html` and `text`. With [Resend](https://resend.com):

```bash
npm install resend
```

```tsx
import { Resend } from "resend";
import { render } from "@hyper-elements/react";
import { Welcome } from "./emails/welcome";

const resend = new Resend(process.env.RESEND_API_KEY);
const { html, text } = await render(<Welcome name="Ada" />);

const { data, error } = await resend.emails.send({
  from: "Acme <hello@your-verified-domain.com>",
  to: "ada@example.com",
  subject: "Welcome to Acme",
  html,
  text,
});
if (error) throw new Error(`Resend: ${error.message}`);
console.info("Resend accepted:", data?.id);
```

Send the `html` string as it is, head styles included. The provider doesn't render your React tree again.

> **Note:** Keep rendering and your API key on the server. The subject is the provider's field. The `Email`'s `title` prop sets the HTML `<title>`, which is a different thing.

The same `html` and `text` work with AWS SES, Postmark, SendGrid or Nodemailer: each takes an HTML body and a text body.

## Preview it

Write the HTML to a file and open it in a browser:

```tsx
import { writeFile } from "node:fs/promises";

await writeFile("welcome.html", html);
```

> **Warning:** A browser preview shows you the layout, not what every inbox does. Send a test to the email clients your users have.

## Check it without rendering

`validate()` runs `render()`'s checks without writing anything, and never throws. It runs all of them but the email's size against Gmail's limits, which needs the HTML:

```tsx
import { validate } from "@hyper-elements/react";

const { valid, diagnostics } = validate(<Welcome name="Ada" />);
```

`outline()` prints the laid-out template, each block with its width, so you can check the layout without reading HTML:

```tsx
import { outline } from "@hyper-elements/react";

console.log(outline(<Welcome name="Ada" />));
```

```text
Email 600px: background #f4f4f5
  Image 120px [Acme] https://example.com/logo.png
  Column 600px: background #ffffff
    Heading h1 536px "Welcome, Ada"
    Text 536px "Your account is ready. Create your first project to get going."
    Button: background #111827 "Create a project" → https://example.com/projects/new
  Text 600px "Acme Inc., 1 Market St, San Francisco"
```

The heading is 536px: the 600px column less 32px of padding on each side.

## With an AI agent

The package ships a guide to writing templates, `GUIDE.md`. In Claude Code, add this line to your project's `CLAUDE.md` and every session starts out knowing the components:

```text
@node_modules/@hyper-elements/react/GUIDE.md
```

For Codex, Cursor and other agents, add to `AGENTS.md` (or a rule): "Before writing a Hyper Elements template, read node_modules/@hyper-elements/react/GUIDE.md." Then have the agent run `validate()` on what it writes. See [Diagnostics](https://hyperelements.dev/docs/diagnostics).

## Next

- [Templates and roots](https://hyperelements.dev/docs/templates)
- [Layout](https://hyperelements.dev/docs/layout)
- [Rendering](https://hyperelements.dev/docs/rendering)

---

# Templates and roots

Source: https://hyperelements.dev/docs/templates

A template is JSX with one root, and the root decides what `render()` writes. This page covers the four roots, their props, and how to build templates out of your own components.

```tsx
import { Email, Heading, Text } from "@hyper-elements/react";

const welcome = (
  <Email width={600} previewText="Thanks for signing up" lang="en">
    <Heading>Welcome</Heading>
    <Text>Thanks for signing up.</Text>
  </Email>
);
```

That is a whole email. A root stacks its children down its content width, centered in the window, so you don't need a `Row`, a `Column` or a container to start.

## The four roots

| Root | Output | Width |
|------|--------|-------|
| [`Email`](https://hyperelements.dev/docs/components/email) | Email-safe HTML | `width`, 600 by default |
| [`Page`](https://hyperelements.dev/docs/components/page) | A responsive web page | `width`, 1200 by default: the widest the content gets |
| [`Document`](https://hyperelements.dev/docs/components/document) | Print-ready HTML on pages of its size, and a PDF with `@hyper-elements/react/pdf` | From its `size`, `orientation` and `margin` |
| [`Canvas`](https://hyperelements.dev/docs/components/canvas) | An image with `@hyper-elements/react/image` (and HTML from `render()`, to look at) | `width` 1200 and `height` 630 by default |

A template has exactly one root. A `<div>` or any other HTML element around it is an error.

## Root props

| Prop | Roots | What it does |
|------|-------|--------------|
| `width` | Email, Page, Canvas | The content width in px |
| `height` | Canvas | The image's height in px. What's past it is cut |
| `previewText` | Email | Shown after the subject in inbox lists, not in the email |
| `description` | Page | The page's meta description |
| `title` | all | The document's `<title>`, shown in a browser tab and by some email clients |
| `lang` | all | The language, as a BCP 47 tag (`"en"`, `"ar"`) |
| `dir` | all | `"ltr"`, `"rtl"` or `"auto"`. Text starts on that side unless you align it |
| `fonts` | all | The font files the template loads. See [Styles](https://hyperelements.dev/docs/styles#fonts) |
| `size` | Document | `"A3"`, `"A4"`, `"A5"`, `"Letter"`, `"Legal"` or `"Tabloid"`, `"A4"` by default |
| `orientation` | Document | `"portrait"` or `"landscape"`, `"portrait"` by default |
| `margin` | Document | Around each page's content, 48px on each side by default (96px to the inch) |

A root's width is a prop, not a style, and a root has no padding. Put padding on a `Column` (a card) or a `Section` (a band) inside it:

```tsx
<Email width={640} style={{ backgroundColor: "#f4f4f5" }}>
  <Column style={{ backgroundColor: "#ffffff", padding: 32 }}>
    <Text>The card has the padding, not the root.</Text>
  </Column>
</Email>
```

The root's `style` takes the text styles every block inherits (`color`, `fontFamily`, `fontSize`, `lineHeight` and the rest), `backgroundColor`, `gap` and `alignItems`. A `Canvas` also takes `padding` and `justifyContent`. See [Styles](https://hyperelements.dev/docs/styles).

## What goes inside

| Kind | Components |
|------|------------|
| Layout | [`Section`](https://hyperelements.dev/docs/components/section), [`Row`](https://hyperelements.dev/docs/components/row), [`Column`](https://hyperelements.dev/docs/components/column), [`Grid`](https://hyperelements.dev/docs/components/grid), [`Layer`](https://hyperelements.dev/docs/components/layer) |
| Text | [`Heading`](https://hyperelements.dev/docs/components/heading) (`level` 1 to 6), [`Text`](https://hyperelements.dev/docs/components/text) |
| Inside text | [`Span`](https://hyperelements.dev/docs/components/span), [`Link`](https://hyperelements.dev/docs/components/link), [`LineBreak`](https://hyperelements.dev/docs/components/linebreak), [`MergeTag`](https://hyperelements.dev/docs/components/mergetag) |
| Blocks | [`Button`](https://hyperelements.dev/docs/components/button), [`Image`](https://hyperelements.dev/docs/components/image), [`Divider`](https://hyperelements.dev/docs/components/divider), [`List`](https://hyperelements.dev/docs/components/list), [`Table`](https://hyperelements.dev/docs/components/table), [`Video`](https://hyperelements.dev/docs/components/video), [`Social`](https://hyperelements.dev/docs/components/social), [`Menu`](https://hyperelements.dev/docs/components/menu), [`Svg`](https://hyperelements.dev/docs/components/svg) (not in an Email), [`Html`](https://hyperelements.dev/docs/components/html) |
| Parts | [`ListItem`](https://hyperelements.dev/docs/components/listitem) in a `List`; [`TableRow`](https://hyperelements.dev/docs/components/tablerow) and [`TableCell`](https://hyperelements.dev/docs/components/tablecell) in a `Table` |
| Shapes, in an `Svg` | [`Rect`](https://hyperelements.dev/docs/components/rect), [`Circle`](https://hyperelements.dev/docs/components/circle), [`Ellipse`](https://hyperelements.dev/docs/components/ellipse), [`Line`](https://hyperelements.dev/docs/components/line), [`Polygon`](https://hyperelements.dev/docs/components/polygon), [`Path`](https://hyperelements.dev/docs/components/path) |
| Document parts | [`Document.Page`](https://hyperelements.dev/docs/components/document-page), [`PageBreak`](https://hyperelements.dev/docs/components/pagebreak), [`PageHeader`](https://hyperelements.dev/docs/components/pageheader), [`PageFooter`](https://hyperelements.dev/docs/components/pagefooter), [`PageNumber`](https://hyperelements.dev/docs/components/pagenumber) |

Text is components, not HTML. Inside a `Text`, a `Span` styles a run, a `Link` links one, a `LineBreak` breaks the line and a `MergeTag` writes a merge tag:

```tsx
<Text>
  Order <Span style={{ fontWeight: 700 }}>#10482</Span> ships tomorrow.<LineBreak />
  <Link href="https://example.com/orders/10482">Track it</Link>
</Text>
```

`<b>`, `<br>`, `<div>` and other HTML elements in a template are errors (`jsx/markup`). For markup no component says, there's [`<Html>`](https://hyperelements.dev/docs/custom-components#html-markup-as-it-is).

## Your own components

A function that returns components is a component of your own. Write templates the way you write the rest of your React app:

```tsx
import { Column, Email, Heading, Text } from "@hyper-elements/react";

function Footer({ company }: { company: string }) {
  return <Text style={{ fontSize: 12, color: "#71717a", textAlign: "center" }}>{company}</Text>;
}

export function OrderShipped({ name, items }: { name: string; items: string[] }) {
  return (
    <Email previewText="Your order is on its way" style={{ gap: 16 }}>
      <Column style={{ gap: 8 }}>
        <Heading level={1}>On its way, {name}</Heading>
        {items.map((item) => (
          <Text key={item}>{item}</Text>
        ))}
      </Column>
      <Footer company="Acme Inc." />
    </Email>
  );
}
```

`render()` runs your components with React, so props, hooks, Context, Fragments, arrays and conditions work as React shows them.

A component that's async or suspends is an error (`jsx/async`): `render()` doesn't wait for it. Fetch your data first and pass it in as props.

Data you pass as children or props is escaped when the HTML is written, so a customer's name can't add markup.

## Share content between roots

Write the content once, and give each output its root:

```tsx
import { Button, Column, Document, Email, Heading, Page, Text, Span, render } from "@hyper-elements/react";

interface Invoice {
  number: string;
  customer: string;
  total: string;
  url: string;
}

function InvoiceContent({ invoice }: { invoice: Invoice }) {
  return (
    <Column style={{ backgroundColor: "#ffffff", padding: 24, gap: 16 }}>
      <Heading level={1} style={{ fontSize: 28 }}>Payment receipt</Heading>
      <Text>Invoice <Span style={{ fontWeight: 700 }}>{invoice.number}</Span></Text>
      <Text>Thank you, {invoice.customer}. You paid {invoice.total}.</Text>
      <Button href={invoice.url}>View invoice</Button>
    </Column>
  );
}

const invoice = { number: "INV-1001", customer: "Ada Lovelace", total: "$49.00", url: "https://example.com/invoices/INV-1001" };
const title = `Invoice ${invoice.number}`;

const email = await render(<Email title={title} previewText="Your payment receipt is ready."><InvoiceContent invoice={invoice} /></Email>);
const page = await render(<Page title={title} width={600}><InvoiceContent invoice={invoice} /></Page>);
const printed = await render(<Document title={title} size="A4" margin={48}><InvoiceContent invoice={invoice} /></Document>);
```

`render()` needs no mode: the root says what to write. `email.html` is email HTML, `page.html` a web page and `printed.html` print HTML. For the PDF itself, pass the same `Document` to `renderPdf()`. See [PDF](https://hyperelements.dev/docs/outputs/pdf).

Shared content doesn't mean identical pixels. Email is written as tables, a page with flexbox, and a document on pages of a fixed size. Each output's page says what it does differently.

## Next

- [Layout](https://hyperelements.dev/docs/layout): arrange blocks with Section, Row, Column, Grid and Layer.
- [Custom components](https://hyperelements.dev/docs/custom-components): named blocks with typed props.

---

# Layout

Source: https://hyperelements.dev/docs/layout

Five components arrange blocks: `Section`, `Row`, `Column`, `Grid` and `Layer`. None is required, since a root stacks its children. Reach for them when you want bands, columns, cards or words over an image.

```tsx
import { Column, Email, Text, Row } from "@hyper-elements/react";

const template = (
  <Email width={600}>
    <Row style={{ gap: 16 }}>
      <Column style={{ width: 180 }}><Text>Fixed</Text></Column>
      <Column style={{ flex: 2 }}><Text>Two shares</Text></Column>
      <Column><Text>One share</Text></Column>
    </Row>
  </Email>
);
```

`outline(template)` shows the widths the layout worked out:

```text
Email 600px
  Row 600px: 3 side by side, stacked on phones
    Column 180px
      Text 180px "Fixed"
    Column 259px
      Text 259px "Two shares"
    Column 129px
      Text 129px "One share"
```

The fixed column takes 180px, the two gaps take 32px, and the other two share the 388px left, two to one.

## Gap and padding, no margins

There are no margins. Space between blocks is their parent's `gap`. Space inside a box is its `padding`.

```tsx
<Column style={{ backgroundColor: "#ffffff", padding: 32, gap: 16 }}>
  <Heading level={2}>Your order</Heading>
  <Text>Ships tomorrow.</Text>
</Column>
```

`marginBottom` and the other margins are errors that tell you to use the parent's `gap` or `padding`. In an email, every block sits in a cell the writer owns, so spacing is cell padding and holds up in Outlook.

`padding` takes `16` (every side), `[12, 24]` (vertical, horizontal), `[8, 16, 8, 16]` (top, right, bottom, left), `"12px 24px"` or `{ top, right, bottom, left }`.

## Section

A [`Section`](https://hyperelements.dev/docs/components/section) is a band across the whole window. It goes directly in a root, never inside a Column, Row or another Section. Its background spans the window, and its children are stacked at the content width.

```tsx
<Email width={600}>
  <Section style={{ backgroundColor: "#111827", padding: [24, 40], color: "#ffffff" }}>
    <Heading level={2}>Acme weekly</Heading>
  </Section>
  <Section style={{ padding: [32, 40], gap: 16 }}>
    <Text>This week's news.</Text>
  </Section>
</Email>
```

The heading is 520px wide: the 600px content less 40px of padding on each side.

## Row

A [`Row`](https://hyperelements.dev/docs/components/row) puts its children side by side. Each child takes its `width`, or a share of what's left: its `flex`, 1 by default.

```tsx
// Equal shares.
<Row style={{ gap: 16 }}>
  <Column>{/* content */}</Column>
  <Column>{/* content */}</Column>
</Row>

// A set width, and what's left.
<Row style={{ gap: 16 }}>
  <Column style={{ width: 180 }}>{/* content */}</Column>
  <Column>{/* content */}</Column>
</Row>

// Shares of two to one.
<Row style={{ gap: 16 }}>
  <Column style={{ flex: 2 }}>{/* content */}</Column>
  <Column>{/* content */}</Column>
</Row>
```

`width` takes px or a percentage of the parent's content box. `flex: "none"` makes a child take its own size. `minWidth` and `maxWidth` hold a child's width where the shares would go past them.

### Stacking on phones

In an Email or a Page, a Row stacks its children full-width on phones. To keep them side by side, set `stackOnMobile={false}`:

```tsx
<Row stackOnMobile={false} style={{ gap: 12 }}>
  <Column><Text>Subtotal</Text></Column>
  <Column><Text style={{ textAlign: "right" }}>$48.00</Text></Column>
</Row>
```

Phones are at or below the content width plus 20px in an email (620px for a 600px email), and at or below 480px on a page. In an email, a stacking Row is written so its children sit side by side where there's room and stack where there isn't, with no media query needed. See [Email](https://hyperelements.dev/docs/outputs/email#rows-that-stack-without-media-queries).

`flexWrap: "wrap"` lets children that don't fit wrap onto another line. In an email it applies to a Row kept side by side on phones.

## Column

A [`Column`](https://hyperelements.dev/docs/components/column) stacks its children, with its own `gap`, `padding` and box. With a background, it's a card.

```tsx
<Column style={{ backgroundColor: "#ffffff", padding: 24, gap: 12, border: "1px solid #e4e4e7", borderRadius: 8 }}>
  <Heading level={3}>Pro plan</Heading>
  <Text>$12 a month</Text>
</Column>
```

A child of a stack (a root, a Section, a Column) fills its width, unless it takes its own size (a Button, an Image) or has a width.

## Grid

A [`Grid`](https://hyperelements.dev/docs/components/grid) puts its children in columns of equal width, row after row. On phones, they go one under another unless `stackOnMobile={false}`.

```tsx
<Grid columns={3} style={{ gap: 16, rowGap: 24 }}>
  <Column><Text>One</Text></Column>
  <Column><Text>Two</Text></Column>
  <Column><Text>Three</Text></Column>
  <Column><Text>Four</Text></Column>
</Grid>
```

`columns` is 1 to 12, 2 by default. `gap` is the space across and down, and `rowGap` the space between rows where it differs. A Grid is laid out as the Rows of Columns it is, so every output draws it.

## Layer

A [`Layer`](https://hyperelements.dev/docs/components/layer) puts its children over each other, in one box as tall as the tallest. Use it for words on an image.

```tsx
<Layer style={{ height: 280, alignItems: "end" }}>
  <Image src={{ src: "https://example.com/hero.jpg", width: 1200, height: 560 }} alt="" />
  <Column style={{ padding: 32 }}>
    <Heading level={2} style={{ color: "#ffffff" }}>Spring collection</Heading>
  </Column>
</Layer>
```

`height` makes the image under its children cover the Layer, cut at its sides or its top and bottom. `alignItems` places the children down the box (`"start"` by default), and `justifyItems` across it (`"stretch"` by default).

> **Note:** An email draws one shape of Layer: an Image as wide as the Layer (100%) with one child over it. Any other shape is an error for email (`email/layer`).

## Alignment

`alignItems` places children across the layout's direction: vertically in a Row, horizontally in a Column. `justifyContent` places them along it. The values are CSS's: `"start"`, `"center"`, `"end"`, plus `"stretch"` for `alignItems` and `"space-between"` for `justifyContent`.

```tsx
<Row style={{ gap: 16, alignItems: "center" }}>
  <Column style={{ width: 64 }}>
    <Image src={{ src: "https://example.com/avatar.png", width: 128, height: 128 }} alt="" style={{ width: 64, borderRadius: 32 }} />
  </Column>
  <Column>
    <Text style={{ fontWeight: 700 }}>Ada Lovelace</Text>
    <Text>Commented on your design</Text>
  </Column>
</Row>

<Column style={{ alignItems: "center", gap: 12 }}>
  <Heading level={2}>Centered</Heading>
  <Button href="https://example.com">Also centered</Button>
</Column>
```

A Button can place itself with `alignSelf` (`"start"`, `"center"` or `"end"`), whatever its stack's `alignItems`, and somewhere else on phones with `mobile={{ alignSelf }}`.

> **Note:** `justifyContent: "space-between"` isn't possible in a Row in an email. Its children start at the left, and `validate()` warns (`email/unsupported`).

## Every box gets a px width

Before anything is written, the layout resolver works out every box's width in px, from the root's width down, and every text's styles. Each output's writer reads the same layout, so the email (which needs px widths for Outlook's tables) and the page agree.

Rows are resolved the way CSS flexbox resolves them: each child starts from its width or its own size, what's left is shared by `flex`, and a child that reaches its `minWidth` or `maxWidth` keeps it. When widths don't fit, they're narrowed as a browser narrows them, with a warning (`layout/shrunk`). Minimums that can't fit are reported too (`layout/overflow`).

`outline()` prints these widths. See [Rendering](https://hyperelements.dev/docs/rendering#outline).

> **Warning:** The resolver doesn't measure text. It can give a box less room than its content needs: text in a few px, a label wider than its button. A page then overflows the box, while email tables, like Outlook's, widen the cell to its longest word and its neighbours give way. No diagnostic says so yet, so give boxes room for their words.

---

# Styles, phones and hover

Source: https://hyperelements.dev/docs/styles

Every component takes its styles in `style={{ }}`, with CSS's property names and values. Phone styles go in `mobile`, hover styles in `hover`, and `hidden` shows a block on one size only.

```tsx
<Heading level={1} style={{ fontSize: 32, color: "#111827" }} mobile={{ fontSize: 24, textAlign: "center" }}>
  Welcome
</Heading>
```

## style

Styles go in `style`, never as props. `<Email backgroundColor="#fff">` is an error whose message tells you to write `style={{ backgroundColor: "#fff" }}`.

- **A number is px.** `padding: 16` is 16px, `fontSize: 15` is 15px.
- **Names are CSS's** where the meaning is the same: `alignItems`, `justifyContent: "space-between"`, `textTransform`, `borderRadius`. Where a behavior isn't CSS, it's a prop (`<Row stackOnMobile={false}>`).
- **Each component takes its own list.** A style a component doesn't take is an error (`style/unknown`), which names what to use instead where there's an equivalent. Each component's page lists its styles, with their defaults.

### Values

| Kind | What it takes |
|------|---------------|
| Color | `"#0879a1"`, `"rgb(…)"`, `"rgba(…)"` or a CSS name |
| Font family | A stack, as CSS writes it: `"Inter, Arial, sans-serif"` |
| Font weight | 100 to 900 in hundreds, `"normal"` or `"bold"` |
| Line height | A multiple of the font size (`1.5`), a percentage (`"150%"`), px (`"24px"`) or `"normal"` |
| Insets (`padding`, a Document's `margin`) | `16` for every side, `[v, h]`, `[top, h, bottom]`, `[top, right, bottom, left]`, `"8px 16px"` (1 to 4 values) or `{ top, right, bottom, left }` |
| Border | `"1px solid #ccc"`, `{ width, style, color }` for every side, or `{ top, right, bottom, left }` with one of those each |
| Radius | px for every corner, `[topLeft, topRight, bottomRight, bottomLeft]` or `{ topLeft, topRight, bottomRight, bottomLeft }` |
| Flex | A share of the free width (0 or more), or `"none"` |

```tsx
<Column
  style={{
    padding: [24, 32],
    backgroundColor: "#ffffff",
    border: { width: 1, style: "solid", color: "#e4e4e7" },
    borderRadius: [8, 8, 0, 0],
  }}
>
  <Heading level={2} style={{ fontWeight: "bold", lineHeight: "120%", textTransform: "uppercase" }}>
    Title
  </Heading>
  <Text style={{ lineHeight: "24px", border: { bottom: "1px solid #e4e4e7" } }}>
    E = mc<Span style={{ verticalAlign: "super" }}>2</Span>
  </Text>
</Column>
```

### Text styles are inherited

`color`, `fontFamily`, `fontSize`, `fontWeight`, `fontStyle`, `lineHeight`, `letterSpacing`, `textAlign` and `textTransform` pass down from the root to everything inside. Set your type once on the root:

```tsx
<Email style={{ color: "#111827", fontFamily: "Inter, Arial, sans-serif", fontSize: 15, lineHeight: 1.6 }}>
  {/* every block inherits these */}
</Email>
```

The root's defaults are `color: "#000000"`, `fontFamily: "Arial, Helvetica, sans-serif"`, `fontSize: 16`, `fontWeight: 400`, `lineHeight: 1.5` and `textAlign: "left"`. Some components have their own: a Heading is bold at a line height of 1.25, a Button is white 14px text on `#0879a1`, a Link is `#0000ee` and underlined.

In an email, every text style is written on the text itself, since Outlook doesn't pass styles down through tables. You don't have to think about it.

Box styles (`width`, `padding`, `backgroundColor`, `border`, `borderRadius` and the rest) aren't inherited.

### No margins

There are no margins. Space between blocks is their parent's `gap`, and space inside a box is its `padding`. See [Layout](https://hyperelements.dev/docs/layout#gap-and-padding-no-margins).

## mobile

`mobile` holds a component's styles on phones, in an Email or a Page:

```tsx
<Column style={{ padding: 32 }} mobile={{ padding: 16 }}>
  <Heading style={{ fontSize: 32 }} mobile={{ fontSize: 24, textAlign: "center" }}>Welcome</Heading>
</Column>
```

Each component takes a short list of phone styles, mostly sizes, spacing and alignment: `fontSize`, `lineHeight`, `letterSpacing`, `textAlign`, `width`, `maxWidth`, `padding`, `border`, `gap`, `rowGap`, `alignSelf`. A style that isn't on the list is an error (`mobile/not-allowed`), and so are phone styles in a Document or a Canvas, which have no phone width (`mobile/not-supported`).

Phones are at or below the content width plus 20px in an email, and at or below 480px on a page. Rows also stack on phones; see [Layout](https://hyperelements.dev/docs/layout#stacking-on-phones).

## hidden

`hidden` shows a block on one size only:

```tsx
<Text hidden={{ mobile: true }}>Desktop detail</Text>
<Text hidden={{ desktop: true }}>Phone detail</Text>
```

Hidden on both, a block never shows, and `validate()` warns (`hidden/everywhere`).

## hover

`hover` holds a link's or a button's styles under the pointer:

```tsx
<Button href="https://example.com/buy" style={{ backgroundColor: "#111827" }} hover={{ backgroundColor: "#374151" }}>
  Buy
</Button>

<Text>
  <Link href="https://example.com/help" style={{ color: "#2563eb", textDecoration: "none" }} hover={{ textDecoration: "underline" }}>
    Help
  </Link>
</Text>
```

A Button takes `color` and `backgroundColor` on hover. A Link takes `color`, `textDecoration` and `backgroundColor`. A PDF and an image can't show hover, and say so.

## Fonts

The root's `fonts` lists the font files the template loads, one face each:

```tsx
<Email
  fonts={[
    { family: "Inter", src: "https://example.com/inter-400.woff2", weight: 400 },
    { family: "Inter", src: "https://example.com/inter-700.woff2", weight: "bold" },
    { family: "Inter", src: "https://example.com/inter-italic.woff2", style: "italic" },
  ]}
  style={{ fontFamily: "Inter, Arial, sans-serif" }}
>
```

A face is `{ family, src, format, weight, style }`. The format comes from the file's extension where you don't give it, and a variable font's weight is a range (`"100 900"`). Name the family in a `fontFamily` stack, before the fonts to show where it can't load. The browser picks the face for each weight and style.

- **On a page**, each face is an `@font-face` rule with `font-display: swap`.
- **In an email**, Apple Mail and iOS Mail load web fonts. Gmail and classic Outlook don't, and show the next font in the stack. `validate()` notes this (`email/degraded`), and warns when a stack ends on a web font (`email/font-fallback`), since a client that can't load it then picks its own.
- **In a PDF or an image**, you pass the font files as bytes. See [PDF](https://hyperelements.dev/docs/outputs/pdf#fonts-and-images) and [Image](https://hyperelements.dev/docs/outputs/image#fonts-and-images).

## Text direction

A root's `dir` and a text block's own `dir` (Text, Heading, ListItem, TableCell, and a Row) set the direction. Text starts on that side unless you align it: a right-to-left email is right-aligned by default, and an Arabic paragraph in an English email sits on the right.

```tsx
<Email lang="ar" dir="rtl">
  <Text>مرحبا بك</Text>
</Email>
```

## What each output can't show

A familiar CSS name doesn't promise every output can show it. Each style declares, for each output, whether it's shown as asked, shown everywhere but classic Outlook, shown partly, or not at all, and `validate()` reports what your template's output can't do. Rounded corners are the common case: classic Outlook draws them square, and you get a note.

```text
info email/outlook-degraded at root.children[0].style.borderRadius: borderRadius on this Column in classic Outlook: square corners
```

See [Diagnostics](https://hyperelements.dev/docs/diagnostics).

---

# Rendering

Source: https://hyperelements.dev/docs/rendering

`render()` turns a template into the output its root asks for. `validate()` runs the same checks without writing anything, and `outline()` prints the layout as text.

```tsx
import { render } from "@hyper-elements/react";

const { html, text, head, body, bodyStyle, diagnostics } = await render(<Receipt />);
```

The examples on this page use this receipt:

```tsx
import { Button, Column, Email, Heading, Image, Link, List, ListItem, MergeTag, Text, Row, Span, Table, TableCell, TableRow } from "@hyper-elements/react";

export default function Receipt() {
  return (
    <Email previewText="Your Acme receipt" style={{ backgroundColor: "#f4f4f5", fontFamily: "Inter, Arial, sans-serif", gap: 16 }}>
      <Image src={{ src: "https://example.com/logo.png", width: 240, height: 80 }} alt="Acme" style={{ width: 120 }} />
      <Column style={{ backgroundColor: "#ffffff", padding: 32, gap: 16, borderRadius: 8 }}>
        <Heading level={1} style={{ fontSize: 24 }} mobile={{ fontSize: 20 }}>
          Thanks for your order, <MergeTag name="first_name" />
        </Heading>
        <Text>
          Order <Span style={{ fontWeight: 700 }}>#10482</Span> ships tomorrow. <Link href="https://example.com/orders/10482">Track it</Link>.
        </Text>
        <Table style={{ cellPadding: [8, 0], rowBorder: "1px solid #e4e4e7" }}>
          <TableRow header>
            <TableCell>Item</TableCell>
            <TableCell style={{ textAlign: "right" }}>Price</TableCell>
          </TableRow>
          <TableRow>
            <TableCell>Linen shirt</TableCell>
            <TableCell style={{ textAlign: "right" }}>$48.00</TableCell>
          </TableRow>
        </Table>
        <Row style={{ gap: 16 }}>
          <Column>
            <Text style={{ fontWeight: 700 }}>Shipping to</Text>
            <Text>Ada Lovelace, London</Text>
          </Column>
          <Column>
            <Text style={{ fontWeight: 700 }}>Next steps</Text>
            <List type="number">
              <ListItem>We pack it</ListItem>
              <ListItem>You track it</ListItem>
            </List>
          </Column>
        </Row>
        <Button href="https://example.com/orders/10482" style={{ backgroundColor: "#111827", borderRadius: 6 }} hover={{ backgroundColor: "#374151" }}>
          View your order
        </Button>
      </Column>
      <Text style={{ fontSize: 12, color: "#71717a", textAlign: "center" }}>Acme Inc., 1 Market St, San Francisco</Text>
    </Email>
  );
}
```

## render()

`render(element, options?)` is async. It resolves to:

| Field | What it is |
|-------|------------|
| `html` | The whole document, with no React hydration markers and no client-side JavaScript |
| `text` | The plain-text version, from the same template |
| `head` | What goes in `<head>`: meta tags, the title, the stylesheet |
| `body` | What goes in `<body>` |
| `bodyStyle` | The body's own inline style |
| `diagnostics` | Warnings and notes. Errors aren't here: they make `render()` reject |

`head`, `body` and `bodyStyle` are for embedding the output in a page of your own. See [Page](https://hyperelements.dev/docs/outputs/page#embed-it-in-your-own-page).

A template with errors doesn't render. `render()` rejects with an `ElementsError`, whose `diagnostics` give each problem's `code`, `message` and `path`:

```tsx
import { ElementsError, render } from "@hyper-elements/react";

try {
  await render(<Receipt />);
} catch (error) {
  if (error instanceof ElementsError) {
    for (const { code, message, path } of error.diagnostics) console.error(code, path, message);
  }
  throw error;
}
```

### The plain-text version

`text` is written from the same template, so it never drifts from the HTML. Headings are in capitals, links and buttons show their URL in brackets, list items get their numbers (or a `-`), a table's cells are joined with `|`, and an image shows its alt text. The receipt's:

```text
[Acme]

THANKS FOR YOUR ORDER, {{first_name}}

Order #10482 ships tomorrow. Track it (https://example.com/orders/10482).

Item | Price
Linen shirt | $48.00

Shipping to

Ada Lovelace, London

Next steps

1. We pack it
2. You track it

View your order (https://example.com/orders/10482)

Acme Inc., 1 Market St, San Francisco
```

The preview text isn't in it.

### Options

| Option | Default | What it does |
|--------|---------|--------------|
| `pretty` | `false` | Indents the HTML, for reading it. For sending, keep the compact HTML: white space may change how some email clients show it |
| `mergeTag` | `` (name) => `{{name}}` `` | A function from a merge tag's name to how it's written |
| `classPrefix` | `"e"` | What every class name in the stylesheet starts with, for HTML embedded where other CSS is. A Document's page boxes keep the class `elements-page` |
| `hideBelow` | Where the phone styles start | In an Email, the window width in px at and below which what's hidden on phones is hidden |

```tsx
const { html } = await render(<Receipt />, { pretty: true, classPrefix: "acme-" });
```

## Merge tags

A [`MergeTag`](https://hyperelements.dev/docs/components/mergetag) is a value your sending service fills in, written in that service's syntax:

```tsx
<Text>
  Hi <MergeTag name="first_name" />, your order has shipped.
</Text>
```

By default it's written as `{{first_name}}`, in the HTML and in the plain text. For another syntax, pass `mergeTag`:

```tsx
// Mailchimp-style: *|FIRST_NAME|*
await render(<Receipt />, { mergeTag: (name) => `*|${name.toUpperCase()}|*` });

// Liquid with spaces: {{ first_name }}
await render(<Receipt />, { mergeTag: (name) => `{{ ${name} }}` });
```

What `mergeTag` returns goes into the HTML as it is, with the name in it escaped, so a syntax with `<` in it (`<%= name %>`) works there too.

A link can be a merge tag as well: `href` takes a URL or a tag, so `<Link href="{{unsubscribe_url}}">` writes `href="{{unsubscribe_url}}"`.

### Tags in your text

Text you write is escaped, and tags without `<`, `>` or `&` in them pass through unchanged: `{{code}}`, `*|FNAME|*` and `{% if vip %}` reach the HTML and the plain text as you wrote them. A tag with `<` in it, written as text, is escaped in the HTML (`&lt;%= name %&gt;`). Write those with `MergeTag` and a `mergeTag` function.

## validate()

`validate(element)` runs the checks `render()` runs, except Gmail's size limits, without writing anything. What's wrong with the template comes back in `diagnostics`, not as an error:

```tsx
import { validate } from "@hyper-elements/react";

const { valid, diagnostics } = validate(<Receipt />);
```

`valid` is `false` when there's an error. Warnings and notes leave it `true`. It checks props, styles, children and ids, expands your custom components, runs the output's checks and the layout, and reports what the output can't show as asked. Only what needs the written HTML is left to `render()`: an email's size against Gmail's limits. It's synchronous. See [Diagnostics](https://hyperelements.dev/docs/diagnostics).

## outline()

`outline(element)` prints the laid-out template: each block on a line under what holds it, with its width on desktop and what it shows (a heading's words, a link's URL, an image's alt text), and whether a Row stacks on phones. Use it to check a layout without reading HTML, in a test or from an agent.

```tsx
import { outline } from "@hyper-elements/react";

console.log(outline(<Receipt />));
```

```text
Email 600px: background #f4f4f5
  Image 120px [Acme] https://example.com/logo.png
  Column 600px: background #ffffff
    Heading h1 536px "Thanks for your order, {{first_name}}"
    Text 536px "Order #10482 ships tomorrow. Track it (https://example.com/orders/10482)."
    Table 536px
      TableRow 536px
        TableCell 268px "Item"
        TableCell 268px "Price"
      TableRow 536px
        TableCell 268px "Linen shirt"
        TableCell 268px "$48.00"
    Row 536px: 2 side by side, stacked on phones
      Column 260px
        Text 260px "Shipping to"
        Text 260px "Ada Lovelace, London"
      Column 260px
        Text 260px "Next steps"
        List 260px
          ListItem 236px "We pack it"
          ListItem 236px "You track it"
    Button: background #111827 "View your order" → https://example.com/orders/10482
  Text 600px "Acme Inc., 1 Market St, San Francisco"
```

Like `render()`, it throws an `ElementsError` when the template has errors.

## The same input, the same output

A template renders the same every time. Rules the inline styles can't express (phone styles, hiding, hover) go in a stylesheet under short classes named after the rule's content, like `.e3k9fa`. The same rule always gets the same class, and the HTML gets no generated ids, only the `id`s you write. Snapshot tests stay stable, and diffs show real changes.

`renderPdf()` and `renderImage()` hold to the same rule: the same template writes the same bytes.

## Where it runs

`render()` runs on your server, with no network calls. It works in plain Node.js and in Next.js route handlers, Server Components and Client Components' server render. Rendering is one React render that collects the template into a tree, lays it out, and writes it, and that render needs no React context, which React's server build doesn't have.

`@hyper-elements/react/pdf` and `@hyper-elements/react/image` run in Node.js only.

> **Tip:** Fetch your data before you render, and pass it in as props. A component that's async or suspends is an error, since `render()` doesn't wait for it.

---

# Diagnostics

Source: https://hyperelements.dev/docs/diagnostics

Every check Hyper Elements runs ends up as a diagnostic: a stable code, a severity, a message that says what to do instead, and the path to the value. Errors stop a render. Warnings and notes tell you what an output can't show as you asked.

```tsx
import { Email, Text, validate } from "@hyper-elements/react";

const { valid, diagnostics } = validate(
  <Email>
    <Text style={{ marginBottom: 16 }}>Hi</Text>
  </Email>
);
// valid: false
// diagnostics[0].code: "style/unknown"
// diagnostics[0].path: "root.children[0].style.marginBottom"
// diagnostics[0].message: "\"marginBottom\" isn't a style a Text takes: use the parent's gap, or padding. …"
```

Props and styles are typed from each component's definition, so in TypeScript a margin like this one is a type error before it's a diagnostic. `validate()` catches it at runtime too, with the path and the fix, for JavaScript, generated templates and agents.

## A diagnostic

```ts
interface Diagnostic {
  code: string;                              // stable, for tools to match on: "style/unknown"
  severity: "error" | "warning" | "info";
  message: string;                           // what's wrong, and what to do instead
  path: string;                              // where: "root.children[1].style.padding"
  nodeId?: string;                           // the node's id, where it has one
}
```

The path walks the template from the root: `root.children[2].style.justifyContent` is the third child's `justifyContent` style.

## Severities

| Severity | Means | `render()` | `validate()` |
|----------|-------|------------|--------------|
| `error` | The template can't be rendered as written | Rejects with an `ElementsError` | `valid: false` |
| `warning` | It renders, but not as you asked: an output can't show something, a width doesn't fit | In `diagnostics` | `valid: true` |
| `info` | A note: shown as asked, except somewhere (classic Outlook's square corners) | In `diagnostics` | `valid: true` |

## ElementsError

A template with errors makes `render()` reject, and `outline()` throw, with an `ElementsError`. Its `diagnostics` hold everything found, and its message lists the errors, one per line:

```text
[Elements] The template has 1 error:
error style/unknown at root.children[0].style.marginBottom: "marginBottom" isn't a style a Text takes: use the parent's gap, or padding. …
```

`formatDiagnostics(diagnostics)` writes any list in that one-line form, for logs.

```tsx
import { ElementsError, formatDiagnostics, render } from "@hyper-elements/react";

try {
  const { html, diagnostics } = await render(<Receipt />);
  if (diagnostics.length) console.warn(formatDiagnostics(diagnostics));
} catch (error) {
  if (error instanceof ElementsError) console.error(formatDiagnostics(error.diagnostics));
  throw error;
}
```

## Codes you'll meet

### Errors: how the template is written

| Code | What triggers it |
|------|------------------|
| `jsx/markup` | An HTML element in a template (`<b>`, `<br>`, `<div>`), or around the root |
| `jsx/root` | Something beside the root, such as two roots |
| `jsx/async` | A component that's async or suspends. Load its data first and pass it in as props |
| `jsx/error` | A component that threw inside a `<Suspense>` |
| `prop/unknown` | A prop the component doesn't take, often a style written as a prop: `<Email backgroundColor="#fff">` |
| `prop/required` | A required prop is missing: a Button's `href`, an Image's `src` |
| `prop/invalid` | A prop's value isn't one it takes, such as a `javascript:` link |
| `style/unknown` | A style the component doesn't take: a margin, a root's `padding`, an old name like `align` (the message names the new one) |
| `style/invalid` | A style's value isn't one it takes: `justifyContent: "around"`, `fontWeight: 650` |
| `mobile/not-allowed` | A phone style the component doesn't take on phones |
| `mobile/not-supported` | Phone styles in a Document or a Canvas, which have no phone width |
| `hidden/not-supported` | `hidden` in a Document or a Canvas |
| `hover/not-allowed` | A hover style the component doesn't take |
| `children/not-allowed` | A child the component can't hold: a Heading in a Text, a root inside a root |
| `children/text-not-allowed` | Loose text where it can't go, such as straight in a Row. Put it in a Text or Heading |
| `children/one-only` | A second `PageHeader` or `PageFooter` in a Document |
| `id/duplicate` | Two components with one `id` |
| `id/invalid` | An `id` that doesn't start with a letter |
| `mobile/invalid`, `hover/invalid`, `hidden/invalid` | A `mobile`, `hover` or `hidden` value that isn't one they take |
| `target/unsupported` | A component the output can't draw: an `Svg` or a `PageNumber` in an email (Gmail and classic Outlook drop inline SVG) |
| `document/page-number` | A `PageNumber` in a Page or a Canvas, which have no pages |
| `email/layer` | A Layer email can't draw: in an email it's an Image as wide as the Layer with one child over it |
| `custom/render` | A custom component's `render` throws, or returns something other than one component |
| `custom/depth` | Custom components expanding into each other too deep, as when one contains itself |
| `custom/duplicate` | Two different `component()` definitions with one `type` |

### Warnings and notes: what an output can't show

| Code | Severity | What triggers it |
|------|----------|------------------|
| `email/unsupported` | warning | A style or prop email can't show. The message says what it shows instead: `justifyContent: "space-between"` starts children at the left |
| `email/outlook-degraded` | info | Shown as asked, except in classic Outlook: square corners, normal letter spacing |
| `email/degraded` | info | Not quite as asked anywhere the email is read, such as web fonts in Gmail |
| `email/image-width` | warning | An Image with no width: Outlook shows it at its file's size. Give `src` the file's `width` and `height` |
| `email/width` | warning | A child of a Row takes its own size and its size isn't known, so Outlook can't lay the Row out |
| `email/font-fallback` | warning | A font stack ends on a web font, so a client that can't load it picks its own |
| `email/video-thumbnail` | warning | A Vimeo Video with no `thumbnail`, which can't be found without the network |
| `email/size` | warning | The HTML is large enough for Gmail to clip it (`render()` only) |
| `email/style-size` | warning | The stylesheet is more than Gmail reads (`render()` only) |
| `web/unsupported` | warning | The same, for a page |
| `layout/shrunk` | warning | A Row's children's widths add up to more than it has. They're narrowed to fit, as a browser does |
| `layout/overflow` | warning | Content wider than the space it has: a Row's children at their minimum widths, a box wider than its parent, a Table's columns wider than the Table |
| `style/ignored` | warning | A style that does nothing where it is, such as `flex` on a child that isn't in a Row |
| `email/layer-phone` | info | On phones, an email keeps a Layer's height and cuts its image at the sides |
| `hidden/everywhere` | warning | Hidden on phones and on desktop, so it never shows |
| `id/dropped` | info | An `id` inside a custom component used without one of its own is left out |
| `mobile/not-shown` | warning | A custom component's `mobile` style that nothing it renders has a phone version of |
| `jsx/compat` | warning | A `compat` prop on a root, which is left out |
| `document/overflow` | warning | A page's content looks taller than the page (an estimate) |
| `canvas/overflow` | warning | A Canvas's content looks taller than the Canvas (an estimate) |

`renderPdf()` and `renderImage()` add codes of their own (`pdf/…`, `image/…`). See [PDF](https://hyperelements.dev/docs/outputs/pdf#diagnostics) and [Image](https://hyperelements.dev/docs/outputs/image#diagnostics).

## Where support data comes from

Each style and prop of each component declares how each output shows it: `full`, `outlook` (as asked, but classic Outlook shows something else), `partial`, or `none` (with what it shows instead). One pass reads those declarations for the styles and props you set, and turns each into a diagnostic. A test keeps the declarations true: every style and prop, at every value, either changes the output or gives a diagnostic. Nothing is dropped silently.

Each declaration names its evidence: captures of real classic Outlook for Windows, caniemail.com's tables, the writer's own output checked in Chromium and against a model of Outlook's layout, or plain CSS. Some are marked as not checked yet.

## Use it in CI and with agents

`validate()` is synchronous, writes nothing, and returns what's wrong rather than throwing it, so it fits in a unit test:

```tsx
import { expect, test } from "vitest";
import { validate } from "@hyper-elements/react";
import { Welcome } from "./emails/welcome";

test("the welcome email is valid and has no warnings", () => {
  const { valid, diagnostics } = validate(<Welcome name="Ada" />);
  expect(valid).toBe(true);
  expect(diagnostics.filter((d) => d.severity === "warning")).toEqual([]);
});
```

Match on `code`, which is stable for tools to match on, and show people the `message`.

For an agent, `validate()` is the feedback loop. Each message says what to use instead and where, so an agent that writes a template, validates it and reads the messages can fix its own mistakes: a margin becomes the parent's `gap`, a style written as a prop goes into `style`. Pair it with [`outline()`](https://hyperelements.dev/docs/rendering#outline) to check the layout as text, without reading HTML.

> **Tip:** Point your agent at the package's guide, `node_modules/@hyper-elements/react/GUIDE.md`, before it writes a template. It lists every component on a line, and the mistakes that most often fail a first try.

---

# Custom components

Source: https://hyperelements.dev/docs/custom-components

There are two ways to make components of your own. A plain function that returns components is enough for most templates. `component()` makes a named block with typed, validated props, and `<Html>` writes markup no component says.

```tsx
import { Text } from "@hyper-elements/react";

function Footer({ company }: { company: string }) {
  return <Text style={{ fontSize: 12, color: "#71717a", textAlign: "center" }}>{company}</Text>;
}
```

## Plain function components

A function that returns Hyper Elements components is a component. Use it anywhere its root component can go:

```tsx
<Email>
  {/* … */}
  <Footer company="Acme Inc., 1 Market St, San Francisco" />
</Email>
```

`render()` runs it with React, so props, hooks, Context, Fragments, arrays and conditions work. It must return components, not HTML elements, and it can't be async or suspend: fetch data first and pass it in as props.

Use plain functions for layouts, headers, footers and anything that's only code. They aren't named blocks: validation sees the components they return, not the function.

## component()

`component()` makes a named, reusable block with its own typed props. Validation checks its props like a built-in component's, and every output renders it, because it's expanded into the built-in components before layout.

```tsx
import { Button, Column, Heading, Image, Text, component, prop } from "@hyper-elements/react";

export const ProductCard = component({
  type: "acme.ProductCard",
  label: "Product card",
  props: {
    name: prop.text({ label: "Name", required: true }),
    photo: prop.image({ label: "Photo", required: true }),
    href: prop.link({ label: "Link", required: true }),
    price: prop.text({ label: "Price" }),
    accent: prop.color({ label: "Accent", default: "#0879a1" }),
    size: prop.choice(["compact", "large"], { label: "Size", default: "compact" }),
    soldOut: prop.boolean({ label: "Sold out", default: false }),
  },
  render: ({ name, photo, href, price, accent, size, soldOut }) => (
    <Column style={{ gap: 8 }}>
      <Image src={photo} alt={name} />
      <Heading level={3} style={{ fontSize: size === "large" ? 22 : 16 }}>{name}</Heading>
      {price ? <Text>{price}</Text> : null}
      <Button href={href} style={{ backgroundColor: soldOut ? "#a1a1aa" : accent }}>
        {soldOut ? "Sold out" : "Buy"}
      </Button>
    </Column>
  ),
});
```

Use it like any component:

```tsx
const photo = { src: "https://example.com/shirt.jpg", width: 560, height: 560 };

<Row style={{ gap: 16 }}>
  <ProductCard name="Linen shirt" photo={photo} href="https://example.com/p/1" price="$48.00" />
  <ProductCard name="Wool scarf" photo={photo} href="https://example.com/p/2" accent="#b91c1c" soldOut style={{ flex: 2 }} />
</Row>
```

A wrong value is a diagnostic with a path, like a built-in component's:

```text
error prop/invalid at root.children[0].props.size: size: expected one of "compact", "large", not "huge"
```

### The spec

| Field | What it is |
|-------|------------|
| `type` | A namespace, a dot and a capitalized name: `"acme.ProductCard"`. The namespace keeps it from clashing with built-in components |
| `label` | Its name for people |
| `description` | Optional: what it's for |
| `props` | Its props, made with `prop.*` |
| `placement` | `"block"` (the default) goes where a block goes. `"section"` goes where a Section goes, and renders a Section |
| `render` | The block as built-in components, from its props with defaults applied |

`render` is a pure function of its props: no hooks and no data, so it renders anywhere. It returns one component, which takes the custom component's place.

### Props

| Helper | Takes |
|--------|-------|
| `prop.text()` | Text |
| `prop.color()` | A color |
| `prop.image()` | An image: a URL, or `{ src, width, height }` |
| `prop.link()` | A link: a URL or a merge tag, or `{ href, target }` |
| `prop.boolean()` | `true` or `false` |
| `prop.number()` | A number, with optional `min`, `max` and `integer` |
| `prop.length()` | A length, px by default |
| `prop.choice(values, …)` | One of `values` |
| `prop.fontFamily()` | A font stack |
| `prop.fontWeight()` | A font weight |

Each takes `label`, and optionally a `description`, `required: true` or a `default`. Their types carry through to `render`'s props and to the JSX.

### On each instance

Beside its own props, an instance takes `id`, `hidden`, and `style={{ flex }}` for its share of a Row. Its `flex` and `hidden` go onto the component it renders.

Ids inside a custom component are prefixed with the instance's `id`. Without one, they're left out (with an `id/dropped` note), so two instances never share an id.

### A section-level component

```tsx
import { Text, Section, component, prop } from "@hyper-elements/react";

export const Banner = component({
  type: "acme.Banner",
  label: "Banner",
  placement: "section",
  props: {
    text: prop.text({ label: "Text", required: true }),
    background: prop.color({ label: "Background", default: "#111827" }),
  },
  render: ({ text, background }) => (
    <Section style={{ backgroundColor: background, padding: [16, 40], color: "#ffffff", textAlign: "center" }}>
      <Text>{text}</Text>
    </Section>
  ),
});
```

## Html: markup as it is

For markup no component says, `<Html>` writes it as it is, in an email and on a page:

```tsx
import { Email, Html } from "@hyper-elements/react";

<Email>
  <Html html={'<p style="margin:0">Written <b>as it is</b>.</p>'} text="Written as it is." />
</Email>
```

Or give the markup as JSX inside the block, which React writes:

```tsx
<Html text="Written as JSX.">
  <p style={{ margin: 0 }}>Written <b>as JSX</b>.</p>
</Html>
```

`text` is what the block reads as in the plain-text version. Without it, the markup's words are used. A Document's PDF and a Canvas's image can't draw markup, so they draw that plain text, and say so.

> **Warning:** Nothing in an `Html` block is checked or escaped. Put only markup you wrote there, never a customer's data. Everywhere else, values you pass as children or props are escaped for you.

Html is the escape hatch, not the way in. Inside it, you're back to writing email HTML yourself: tables for Outlook, inline styles, and testing in each client.

---

# Email

Source: https://hyperelements.dev/docs/outputs/email

An `<Email>` root renders to email-safe HTML: tables with px widths, inline styles, and Outlook's markup in conditional comments. You write the layout once in components, and the writer handles the client quirks.

```tsx
import { Column, Email, Text, Row, render } from "@hyper-elements/react";

const { html, text } = await render(
  <Email previewText="Two columns" title="Hi">
    <Row style={{ gap: 16 }}>
      <Column><Text>Left</Text></Column>
      <Column style={{ width: 180 }}><Text mobile={{ fontSize: 14 }}>Right</Text></Column>
    </Row>
  </Email>
);
```

## The rules it writes by

1. **Right without `<style>`.** Layout at desktop width, colors, fonts, sizes and spacing are inline. The stylesheet only adds phone styles, hiding, hover and client resets. Gmail drops `<style>` for some accounts, and the email still holds its desktop layout.
2. **Widths are decided before writing.** Every table, cell and image gets a px width attribute from the layout resolver. Outlook's Word engine sizes by attributes and ignores the sizes of `div`s.
3. **Tables for layout**, with `role="presentation"`, no spacing and no borders. Spacing is cell padding.
4. **Outlook-only markup only inside `<!--[if mso]>`**, and nothing other clients need inside one.

## What you get

The document is the Unlayer editor's email shell: an XHTML doctype, Office settings for Outlook, `x-apple-disable-message-reformatting`, `X-UA-Compatible`, `-webkit-text-size-adjust`, `color-scheme`, a `border-collapse` reset, and the preview text. The content sits in a full-width table with the window's background, inside a centered table of the content's width. The language, direction and background are also on a `role="article"` wrapper, since Gmail drops `<html>` and `<body>`.

How each component is written:

| Component | In the email |
|-----------|--------------|
| `Section` | A full-width row with its background, its content at the content width inside it |
| `Row` | Each child an inline-block `div`, with an Outlook-only table of the same widths in conditional comments. With `stackOnMobile={false}`, a table row |
| `Column` and other boxes | A one-cell table around the content (Word has no box on a `div` or `p`), its children as table rows |
| Text blocks | The semantic tag with `margin:0`, every text style on it (Outlook doesn't pass styles down through tables), and line heights in px with `mso-line-height-rule: exactly` |
| `Button` | A one-cell table: background, border and corners on the cell, the padding on the link so all of it is clickable, and as the cell's `mso-padding-alt` for Outlook |
| `Image` | An `<img>` with a px `width` attribute, fluid elsewhere (`width:100%` up to its width), its height in proportion when the file's size is known |
| `Divider` | A table with a top border and an empty cell Word can't make taller |
| `List` | A table: an item a row, its marker right-aligned in a cell of the indent's width, with `role="list"` and `"listitem"` |
| `Table` | A data table with fixed layout: column widths in a `colgroup` and on each cell, header rows in `thead` with `th` |
| `Span` | A `<span>`, or `<sup>` and `<sub>` with no line height of their own, so a line keeps its height |
| `Video` | Its thumbnail, linked to the video. An email can't play one |

The Button is a table, not VML: captures of classic Outlook show Word drawing a VML button's label in its own font, wrapped inside the shape's fixed size.

## Rows that stack without media queries

A Row is written "fluid hybrid": each child is an inline-block as wide as its desktop width at most, and 100% otherwise. The children sit side by side where there's room and stack where there isn't, without a media query, so they stack in clients that ignore `<style>` too. Outlook gets a table of the same widths inside conditional comments.

The stylesheet adds the rest for phones: a stacked child goes full width, and your `mobile` styles apply. In an email, phones are below the content width plus 20px, so a 600px email's phone rules apply at 620px and narrower.

## Preview text

`previewText` is shown after the subject in inbox lists, not in the email. It's written as a hidden block at the top of the body, and left out of the plain text.

## Merge tags

A `MergeTag` is written in your sending service's syntax, `{{name}}` by default, in the HTML and the plain text. A link's `href` can be a merge tag too. See [Rendering](https://hyperelements.dev/docs/rendering#merge-tags).

## Fonts

Web fonts in `fonts` are written as `@font-face` rules where classic Outlook doesn't read them, so Outlook draws the next font in the stack. Apple Mail and iOS Mail load web fonts. Gmail and classic Outlook don't. End every stack on a font the client has: `"Inter, Arial, sans-serif"`. See [Styles](https://hyperelements.dev/docs/styles#fonts).

## Size budgets

`render()` warns before Gmail clips a message (`email/size`, at about 100 KB of HTML) and when the stylesheet is more than Gmail reads, 16 KB (`email/style-size`).

## What email can't do

`validate()` tells you each of these for your template, with the path:

- **Svg.** Gmail and classic Outlook drop inline SVG, so an `Svg` in an email is an error. Use an `Image` of it, a PNG.
- **Layer.** An email draws one shape of it: an Image as wide as the Layer, with one child over it. The image is the cell's background, with VML for Outlook.
- **`justifyContent: "space-between"`.** The children start at the left.
- **Rounded corners and letter spacing in classic Outlook.** Corners are square, and letter spacing is normal. You get a note (`email/outlook-degraded`).
- **A Vimeo video's thumbnail.** It can't be found without the network, so give the `Video` a `thumbnail`.
- **An Image without its file's size.** Outlook shows it at the file's size, however wide that is. Give `src` its `width` and `height`.

There are no dark-mode styles yet. The head declares `color-scheme` as light.

## How it's checked

- Unit tests of each component's markup.
- A hostile-input test: user text, links and font URLs with markup in them add no element or attribute, including inside Outlook's comments.
- Chromium tests that every box is as wide as the layout says on desktop, with and without the stylesheet, that Rows stack on phones either way, that hover, fonts and superscripts work, and that Row widths match the page in every min, max and gap case.
- Checks against a model of classic Outlook's layout, built from captures of real Outlook, at 96 and 192 DPI.

> **Warning:** Chromium and a model of Outlook aren't email clients. The output hasn't been checked in real email clients yet, and button padding through `mso-padding-alt` hasn't been measured in real Outlook. Send tests to the clients your users have before you rely on a layout.

The layout doesn't measure text, either. A box with less room than its words needs looks different in email, where the table cell widens to its longest word, than on a page. See [Layout](https://hyperelements.dev/docs/layout#every-box-gets-a-px-width).

---

# Page

Source: https://hyperelements.dev/docs/outputs/page

A `<Page>` root renders to a responsive web page: one element per component, semantic tags, inline styles and flexbox. Use it for the web version of an email, a receipt behind a login, or a landing page you generate on the server.

```tsx
import { Button, Column, Heading, Page, Text, Row, render } from "@hyper-elements/react";

const { html } = await render(
  <Page title="Pricing" description="Plans for teams of every size" width={960}>
    <Heading>Pricing</Heading>
    <Row style={{ gap: 16 }}>
      <Column>
        <Text hidden={{ mobile: true }}>Compare every plan side by side.</Text>
      </Column>
      <Column>
        <Button href="/buy" hover={{ backgroundColor: "#374151" }}>Buy</Button>
      </Column>
    </Row>
  </Page>,
  { pretty: true }
);
```

## What you get

The HTML above, shortened where it says `…`:

```html
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Pricing</title>
    <meta name="description" content="Plans for teams of every size">
    <style>.emw6dn:hover{background-color:#374151!important}@media (max-width: 480px){…}</style>
  </head>
  <body style="margin:0">
    <main style="max-width:960px;margin:0 auto;display:flex;flex-direction:column;…">
      <h1 style="margin:0;font-size:32px;font-weight:700;line-height:1.25">Pricing</h1>
      <div class="emfqa6" style="display:flex;gap:16px">…</div>
    </main>
  </body>
</html>
```

- **Semantic tags**: `main`, `section`, `h1` to `h6`, `p`, `ul` and `ol`, `table`, `a`, `img`.
- **Styles inline**, with flexbox for Rows and stacks.
- **A small stylesheet** for what inline styles can't say: phone styles, hiding, hover, and a Row stacking on phones. Its classes are short and named after their rule, so the same template always gets the same classes.
- **No client-side JavaScript** and no React hydration markers. The page is plain HTML.

The content is centered and as wide as the Page's `width` at most, 1200px by default. A `Section`'s background spans the window, with its content at that width. On phones, at 480px and narrower, Rows stack and `mobile` styles apply.

A `Video` is its player on a page: YouTube's or Vimeo's embed, in a 16:9 box. Web fonts in `fonts` are `@font-face` rules with `font-display: swap`.

## Embed it in your own page

`render()` also returns the document in parts, so you can put the output inside a page of your own, a Next.js route or a CMS layout. With the `InvoiceContent` from [Templates and roots](https://hyperelements.dev/docs/templates#share-content-between-roots):

```tsx
import { Page, render } from "@hyper-elements/react";

const { head, body, bodyStyle } = await render(<Page title="Receipt"><InvoiceContent invoice={invoice} /></Page>, { classPrefix: "receipt-" });
```

| Part | What it is |
|------|------------|
| `head` | What goes in `<head>`: meta tags, the title, the stylesheet |
| `body` | What goes in `<body>`: the `<main>` and everything in it |
| `bodyStyle` | The body's own style, such as `margin:0;background-color:#fafafa` for a Page with a background |

`classPrefix` sets what every class in the stylesheet starts with (`e` by default), so the output's rules don't collide with the CSS already on your page. With `classPrefix: "receipt-"`, a class looks like `receipt-mw6dn`.

> **Tip:** Embedding and the plain `html` come from the same render, so a page you embed and the one you serve on its own are the same markup.

## Page, Document and Canvas

A `Document` renders to print HTML with the same page writer, plus a CSS `@page` size, page breaks and one box per page. A `Canvas` renders to HTML to look at, at its fixed size. See [PDF](https://hyperelements.dev/docs/outputs/pdf) and [Image](https://hyperelements.dev/docs/outputs/image).

## Limits

- The layout gives every box a width in px without measuring text. A box with less room than its words needs overflows on a page. See [Layout](https://hyperelements.dev/docs/layout#every-box-gets-a-px-width).
- `validate()` reports what a page can't show as asked (`web/unsupported`).

---

# PDF

Source: https://hyperelements.dev/docs/outputs/pdf

A `<Document>` root lays its content out on pages of a fixed size, with a header and a footer on each. `render()` writes it as print-ready HTML, and `renderPdf()` from `@hyper-elements/react/pdf` writes it as a PDF, on your server, with no headless Chrome.

```tsx
import { readFile, writeFile } from "node:fs/promises";
import { Document, Heading, Image, PageBreak, PageFooter, PageHeader, PageNumber, Text, Table, TableCell, TableRow } from "@hyper-elements/react";
import { renderPdf } from "@hyper-elements/react/pdf";

const Invoice = () => (
  <Document size="A4" margin={48} title="Invoice 2705" style={{ fontFamily: "Inter, sans-serif", gap: 16 }}>
    <PageHeader style={{ padding: [0, 0, 16, 0] }}>
      <Image src={{ src: "https://cdn.acme.com/logo.png", width: 240, height: 80 }} alt="Acme" style={{ width: 120 }} />
    </PageHeader>
    <Heading level={1}>Invoice 2705</Heading>
    <Text>Thank you for your order.</Text>
    <Table style={{ cellPadding: [8, 0], rowBorder: "1px solid #e4e4e7" }}>
      <TableRow header>
        <TableCell>Item</TableCell>
        <TableCell style={{ textAlign: "right" }}>Price</TableCell>
      </TableRow>
      <TableRow>
        <TableCell>Linen shirt</TableCell>
        <TableCell style={{ textAlign: "right" }}>$48.00</TableCell>
      </TableRow>
    </Table>
    <PageBreak />
    <Heading level={2}>Terms</Heading>
    <Text>Payment is due in 30 days.</Text>
    <PageFooter>
      <Text style={{ fontSize: 10, textAlign: "right" }}>
        Page <PageNumber /> of <PageNumber total />
      </Text>
    </PageFooter>
  </Document>
);

const { pdf, diagnostics } = await renderPdf(<Invoice />, {
  fonts: [
    { family: "Inter", src: await readFile("fonts/Inter-Regular.ttf") },
    { family: "Inter", src: await readFile("fonts/Inter-Bold.ttf"), weight: 700 },
  ],
  images: { "https://cdn.acme.com/logo.png": await readFile("images/logo.png") },
});
for (const { code, message } of diagnostics) console.warn(code, message);
await writeFile("invoice.pdf", pdf);
```

## Install

```bash
npm install @hyper-elements/react @react-pdf/renderer react react-dom
```

| Peer dependency | Version | Why |
|-----------------|---------|-----|
| `@react-pdf/renderer` | `^4.9.0` (optional: only for `/pdf`) | Draws the pages |
| `react`, `react-dom` | `>=18` | |

`/pdf` is an entry of `@hyper-elements/react`. Its engine is an optional peer dependency, so a project that doesn't import `/pdf` installs nothing for it, and the main entry never loads it.

It runs in Node.js only. If it loads a second copy of `@hyper-elements/react` that lays templates out in another version, `renderPdf()` throws an `ElementsError` (`pdf/version`) rather than drawing the template wrong.

## The Document

| Prop | Takes | Default |
|------|-------|---------|
| `size` | `"A3"`, `"A4"`, `"A5"`, `"Letter"`, `"Legal"`, `"Tabloid"` | `"A4"` |
| `orientation` | `"portrait"`, `"landscape"` | `"portrait"` |
| `margin` | Insets around each page's content, its header and footer too, in px at 96 to the inch | 48 on every side |
| `title`, `lang`, `dir`, `fonts` | As on every root | |

A Document's width comes from its size and margin: an A4 page with 48px margins has 698px of content. It has no phone layout, so `mobile` styles are an error in one.

### Pages

The content goes on pages in one of two ways:

- **Runs split by [`PageBreak`](https://hyperelements.dev/docs/components/pagebreak).** What follows a `PageBreak` starts the next page.
- **[`Document.Page`](https://hyperelements.dev/docs/components/document-page)s.** Each one is a page, its children stacked inside the Document's margins.

```tsx
<Document size="Letter" orientation="landscape">
  <Document.Page style={{ gap: 16 }}>
    <Heading>Q3 report</Heading>
    <Text>Revenue grew 12%.</Text>
  </Document.Page>
  <Document.Page style={{ gap: 16 }}>
    <Heading level={2}>Details</Heading>
  </Document.Page>
</Document>
```

### Header, footer and page numbers

One [`PageHeader`](https://hyperelements.dev/docs/components/pageheader) and one [`PageFooter`](https://hyperelements.dev/docs/components/pagefooter) are drawn on every page, inside its margins. A second of either is an error. A [`PageNumber`](https://hyperelements.dev/docs/components/pagenumber) in their text, or anywhere in the Document's text, is the number of the page it's on, and `<PageNumber total />` is how many pages there are.

A table row with `footer` ends the table.

## Print HTML

`render()` writes a Document as print HTML: a box of the paper's size for each page, with the header and footer in each, and a CSS `@page` rule for the paper's size and orientation, with no page margin.

```tsx
import { render } from "@hyper-elements/react";

const { html } = await render(<Invoice />);
```

Open it in a browser to look at the pages, or print it. If you print it to PDF with Playwright, pass `preferCSSPageSize: true` and `printBackground: true` to `page.pdf()`, and set the margin on the Document: a `margin` passed to `page.pdf()` changes nothing, since each page draws its own.

## renderPdf()

`renderPdf(element, options)` returns `{ pdf, diagnostics }`: the file's bytes, and the warnings and notes. Errors reject with an `ElementsError` listing them. Its pages, header, footer and page numbers are the print HTML's, laid out at the same widths.

The same template writes the same bytes. The `date` option is when the PDF says it was made: a fixed date by default, which is what keeps the bytes the same. Pass `new Date()` if you want the real one.

| Option | What it takes |
|--------|---------------|
| `fonts` | Font files, by family (below) |
| `images` | Image files, by URL (below) |
| `date` | When the PDF says it was made, a fixed date by default |

### Fonts and images

Nothing is fetched. Give each file the template needs, as bytes:

- **Fonts** in `fonts`: `{ family, src, weight?, style? }`, one entry per file. `src` is a TTF, OTF or WOFF file's bytes. `family` is the name your `fontFamily` stacks use. The files in a Document's `fonts` prop are for its HTML: `renderPdf()` doesn't load them, `data:` URIs included.
- **Images** in `images`, by the URL the template gives them (`{ "https://…/logo.png": bytes }`), or as `data:` URIs in the template. A PDF draws PNG and JPEG.

Text whose `fontFamily` has no file given is drawn in a standard PDF font: Helvetica, Times or Courier, whichever is closest. Those draw Western European characters only. For any other script, give a font file that has it.

A `Video` shows its thumbnail where its file is given (its own, or a YouTube video's by the URL `img.youtube.com/vi/<id>/0.jpg`), and otherwise its title, linked to the video.

### Diagnostics

| Code | Severity | When |
|------|----------|------|
| `pdf/root` | error | The template isn't a Document |
| `pdf/version` | error | A second copy of `@hyper-elements/react` lays the template out in another version |
| `pdf/image` | error | An image isn't given, or its file isn't a PNG or JPEG |
| `pdf/image` | warning | An image is SVG: its alt text is shown in its box |
| `pdf/font` | warning | A font in the Document's `fonts` isn't given, a file given is WOFF2, or text in a standard PDF font has characters it can't draw |
| `pdf/font-weight` | warning | Text in a weight or style of a family that isn't given. It's drawn in the nearest file given |
| `pdf/unsupported` | warning | What a PDF can't show that the HTML can: a hover, a Video's player, an `Html` block's markup (its plain text is drawn), a line too wide to wrap (it goes past the edge) |
| `document/overflow` | warning | A page's content looks taller than the page. An estimate: text isn't measured yet |

`validate()` from `@hyper-elements/react` reports `pdf/unsupported` and `document/overflow` without rendering. The font and image checks need the files, so only `renderPdf()` makes them.

## Limits

- **Nothing flows from one page to the next.** Content taller than its page is cut off, and you get `document/overflow`. Split it with a `PageBreak` or into `Document.Page`s, and test with your longest real data.
- **WOFF2 isn't drawn.** react-pdf would embed its letters blank. Give TTF, OTF or WOFF.
- **SVG images aren't drawn.** Give a PNG or JPEG. An `Svg` component is drawn as vectors.
- **The standard PDF fonts draw Western European characters only.** Whether a font file you give has every character isn't checked.
- **No hover and no video player.** A Button shows its own colors, a Video its thumbnail or title.

---

# Image

Source: https://hyperelements.dev/docs/outputs/image

A `<Canvas>` root is an image of a fixed size. `renderImage()` from `@hyper-elements/react/image` writes it as a PNG or an SVG, on your server, with Satori and resvg. No browser, no screenshot service, no network.

```tsx
import { readFile, writeFile } from "node:fs/promises";
import { Canvas, Circle, Heading, Image, Text, Row, Svg } from "@hyper-elements/react";
import { renderImage } from "@hyper-elements/react/image";

function PostCard({ title, author }: { title: string; author: string }) {
  return (
    <Canvas width={1200} height={630} style={{ backgroundColor: "#0f172a", padding: 64, gap: 24, color: "#ffffff", fontFamily: "Inter, sans-serif", justifyContent: "space-between" }}>
      <Image src={{ src: "https://example.com/logo.png", width: 240, height: 80 }} alt="Acme" style={{ width: 120 }} />
      <Heading level={1} style={{ fontSize: 64 }}>{title}</Heading>
      <Row style={{ gap: 16, alignItems: "center" }}>
        <Svg width={40} height={40} style={{ flex: "none" }}>
          <Circle cx={20} cy={20} r={20} style={{ fill: "#38bdf8" }} />
        </Svg>
        <Text style={{ fontSize: 28, color: "#cbd5e1" }}>{author}</Text>
      </Row>
    </Canvas>
  );
}

const { image, width, height, diagnostics } = await renderImage(<PostCard title="Launch week" author="Ada Lovelace" />, {
  fonts: [
    { family: "Inter", src: await readFile("fonts/Inter-Regular.ttf") },
    { family: "Inter", src: await readFile("fonts/Inter-Bold.ttf"), weight: 700 },
  ],
  images: { "https://example.com/logo.png": await readFile("images/logo.png") },
});
await writeFile("card.png", image);
```

Use it for social cards, Open Graph images, banners, or any image you'd otherwise build in a design tool and export by hand. Pass a different `title` and you have a card per blog post.

## Install

```bash
npm install @hyper-elements/react satori @resvg/resvg-js react react-dom
```

| Peer dependency | Version | Why |
|-----------------|---------|-----|
| `satori` | `^0.33.5` (optional: only for `/image`) | Lays out the Canvas and draws its text as paths, as SVG |
| `@resvg/resvg-js` | `^2.6.2` (optional: only for `/image`) | Draws that SVG as a PNG |
| `react`, `react-dom` | `>=18` | |

`/image` is an entry of `@hyper-elements/react`. Its engines are optional peer dependencies, so a project that doesn't import `/image` installs nothing for them, and the main entry never loads them.

It runs in Node.js only. If it loads a second copy of `@hyper-elements/react` that lays templates out in another version, `renderImage()` throws an `ElementsError` (`image/version`) rather than drawing the template wrong.

> **Note:** Satori runs WebAssembly, which a Content-Security-Policy without `'wasm-unsafe-eval'` blocks. That's one reason image output is its own entry, `@hyper-elements/react/image`, which the main entry never loads.

## The Canvas

| Prop | What it does | Default |
|------|--------------|---------|
| `width` | The image's width in px | 1200 |
| `height` | The image's height in px. What's past it is cut | 630 |
| `title`, `lang`, `dir`, `fonts` | As on every root | |

Its content is laid out as on a page, with no phone layout. Beside the text styles, `backgroundColor`, `gap` and `alignItems`, a Canvas's `style` takes `padding` and `justifyContent`, so you can push content to the bottom or spread it out (`"space-between"`).

`render()` writes a Canvas as HTML too, to look at in a browser while you design it.

## renderImage()

`renderImage(element, options)` returns `{ image, width, height, diagnostics }`: the file's bytes, its size in pixels, and the warnings and notes. Errors reject with an `ElementsError` listing them. The same template writes the same bytes.

| Option | What it takes |
|--------|---------------|
| `fonts` | Font files, by family (below) |
| `images` | Image files, by URL (below) |
| `format` | `"png"` (the default) or `"svg"`. An SVG's text is drawn as paths, so it shows without the fonts |
| `scale` | Pixels per px of a PNG: 2 for a phone's screen. At 2, a 1200 by 630 Canvas is 2400 by 1260 |

```tsx
const { image } = await renderImage(<PostCard title="Launch week" author="Ada Lovelace" />, { fonts, images, format: "svg" });
await writeFile("card.svg", image);
```

### Fonts and images

Nothing is fetched. Give each file the template needs, as bytes:

- **Fonts** in `fonts`: `{ family, src, weight?, style? }`, one entry per file. `src` is a TTF, OTF or WOFF file's bytes, and `family` is the name your `fontFamily` stacks use. A Canvas's own `fonts` given as `data:` URIs are drawn too. Ones given by URL aren't loaded.
- **Images** in `images`, by the URL the template gives them (`{ "https://…/photo.png": bytes }`), or as `data:` URIs in the template: PNG, JPEG, GIF or SVG.

An image with text needs at least one font. Text whose `fontFamily` has no file given is drawn in the first font given.

### Diagnostics

| Code | Severity | When |
|------|----------|------|
| `image/root` | error | The template isn't a Canvas |
| `image/version` | error | A second copy of `@hyper-elements/react` lays the template out in another version |
| `image/font` | error | The Canvas has text and no font is given |
| `image/font` | warning | A font in the Canvas's `fonts` isn't given, or a file given is WOFF2 |
| `image/font-weight` | warning | Text in a weight or style of a family that isn't given. It's drawn in the nearest file given |
| `image/image` | error | An image isn't given, or its file isn't a PNG, JPEG, GIF or SVG |
| `image/unsupported` | warning | What an image can't show that the HTML can: a hover, a Video's player, an `Html` block's markup (its plain text is drawn), a line too wide to wrap (it goes past the edge) |
| `canvas/overflow` | warning | The content looks taller than the Canvas. An estimate: text isn't measured yet |

`validate()` from `@hyper-elements/react` reports `image/unsupported` and `canvas/overflow` without rendering. The font and image checks need the files, so only `renderImage()` makes them.

## Limits

- **WOFF2 isn't drawn.** Satori reads TTF, OTF and WOFF. Give one of those.
- **Text is drawn only in the fonts you give.** A character none of them has comes out as an empty box. Give a font that has it.
- **What doesn't fit is cut off** at the Canvas's edges. Text isn't measured before layout, so check long titles: `canvas/overflow` is an estimate.
- **No hover and no video.** A Button shows its own colors, a Video its title.

---

# Sending email

Source: https://hyperelements.dev/docs/guides/sending

Hyper Elements renders. Your email provider delivers. You render once on your server, get two strings, and pass them to any provider's SDK. The provider never sees React, and you never write a second plain-text template by hand.

## Render once

```tsx
import { Button, Column, Email, Heading, MergeTag, Text, render } from "@hyper-elements/react";

const Welcome = ({ plan }: { plan: string }) => (
  <Email width={600} previewText="Your workspace is ready" style={{ backgroundColor: "#f4f4f5", gap: 16 }}>
    <Column style={{ backgroundColor: "#ffffff", padding: 32, gap: 16 }}>
      <Heading level={1} style={{ fontSize: 24 }}>
        Welcome, <MergeTag name="first_name" />
      </Heading>
      <Text>Your {plan} workspace is ready.</Text>
      <Button href="https://example.com/dashboard" style={{ backgroundColor: "#111827" }}>
        Open your dashboard
      </Button>
    </Column>
  </Email>
);

const { html, text, diagnostics } = await render(<Welcome plan="Pro" />);
```

- `html` is the complete document, from its doctype to `</html>`, with the email shell and its head styles. Send that string as the HTML body. Keep the head styles.
- `text` is the plain-text alternative. Send it as the text body.
- `diagnostics` holds warnings. A template with errors rejects with an `ElementsError` that lists them, so a broken template never reaches a send call.

`render()` is async, so everything that calls it awaits it. The `Email`'s `title` prop sets the HTML `<title>`. That's separate from the subject line, which you give the provider.

## A provider-ready message

Put rendering in one function and reuse it for every provider. This is the shape the examples below import as `../message`:

```ts
import { render } from "@hyper-elements/react";
import { invoiceTemplate, sampleInvoice, type InvoiceData } from "./invoice";

export async function renderInvoiceEmail(data: InvoiceData = sampleInvoice) {
  const { html, text } = await render(invoiceTemplate(data, "email"));
  return {
    subject: `Receipt for invoice ${data.number}`,
    html,
    text,
  };
}

export function requireEnv(name: string): string {
  const value = process.env[name];
  if (!value?.trim()) throw new Error(`Set ${name} before sending email`);
  return value;
}

export async function deliveryMessage() {
  return {
    ...(await renderInvoiceEmail()),
    from: requireEnv("EMAIL_FROM"),
    to: requireEnv("EMAIL_TO"),
  };
}
```

`invoiceTemplate` is a plain synchronous function that returns the root element. Fetch your data before you call it: a component that is async or suspends is an error.

Every snippet below sends one real email. Set a verified sender and a recipient you control, and keep credentials on the server, never in browser code:

```bash
export EMAIL_FROM='receipts@your-verified-domain.com'
export EMAIL_TO='your-test-inbox@example.com'
```

## Resend

```bash
npm install resend
```

Set `RESEND_API_KEY`. Resend needs an API key and a verified sending domain.

```ts
import { Resend } from "resend";
import { deliveryMessage, requireEnv } from "../message";

const client = new Resend(requireEnv("RESEND_API_KEY"));
const { data, error } = await client.emails.send(await deliveryMessage());
if (error) throw new Error(`Resend: ${error.message}`);
console.info("Resend accepted:", data?.id);
```

## AWS SES

```bash
npm install @aws-sdk/client-sesv2
```

Set `AWS_REGION` to the region that holds your verified identity. Credentials come from the AWS SDK's default chain (an IAM role or `AWS_PROFILE`) with permission to send through SES. In the SES sandbox, recipients need verifying too.

```ts
import { SESv2Client, SendEmailCommand } from "@aws-sdk/client-sesv2";
import { deliveryMessage, requireEnv } from "../message";

const client = new SESv2Client({ region: requireEnv("AWS_REGION") });
const { from, to, subject, html, text } = await deliveryMessage();
try {
  const result = await client.send(new SendEmailCommand({
    FromEmailAddress: from,
    Destination: { ToAddresses: [to] },
    Content: {
      Simple: {
        Subject: { Data: subject, Charset: "UTF-8" },
        Body: {
          Html: { Data: html, Charset: "UTF-8" },
          Text: { Data: text, Charset: "UTF-8" },
        },
      },
    },
  }));
  console.info("SES accepted:", result.MessageId);
} finally {
  client.destroy();
}
```

## Postmark

```bash
npm install postmark
```

Set `POSTMARK_SERVER_TOKEN`. Use a server token and a confirmed sender signature or domain. The `outbound` message stream is for transactional mail.

```ts
import { ServerClient } from "postmark";
import { deliveryMessage, requireEnv } from "../message";

const client = new ServerClient(requireEnv("POSTMARK_SERVER_TOKEN"));
const { from, to, subject, html, text } = await deliveryMessage();
const result = await client.sendEmail({
  From: from,
  To: to,
  Subject: subject,
  HtmlBody: html,
  TextBody: text,
  MessageStream: "outbound",
});
console.info("Postmark accepted:", result.MessageID);
```

## SendGrid

```bash
npm install @sendgrid/mail
```

Set `SENDGRID_API_KEY`. Use an API key with Mail Send permission and an authenticated sender.

```ts
import sendgrid from "@sendgrid/mail";
import { deliveryMessage, requireEnv } from "../message";

sendgrid.setApiKey(requireEnv("SENDGRID_API_KEY"));
const [response] = await sendgrid.send(await deliveryMessage());
console.info("SendGrid accepted:", response.statusCode, response.headers["x-message-id"]);
```

## Nodemailer (SMTP)

```bash
npm install nodemailer
npm install --save-dev @types/nodemailer
```

Set `SMTP_HOST`, `SMTP_PORT`, `SMTP_USER` and `SMTP_PASSWORD`, with credentials from your SMTP service. Port 465 uses implicit TLS. Submission ports such as 587 require STARTTLS here. Keep certificate verification on.

```ts
import nodemailer from "nodemailer";
import { deliveryMessage, requireEnv } from "../message";

const port = Number(requireEnv("SMTP_PORT"));
if (!Number.isInteger(port) || port < 1 || port > 65535) {
  throw new Error("SMTP_PORT must be an integer between 1 and 65535");
}
const transport = nodemailer.createTransport({
  host: requireEnv("SMTP_HOST"),
  port,
  secure: port === 465,
  requireTLS: port !== 465,
  auth: { user: requireEnv("SMTP_USER"), pass: requireEnv("SMTP_PASSWORD") },
});
try {
  const result = await transport.sendMail(await deliveryMessage());
  if (result.rejected.length) throw new Error("SMTP rejected the recipient");
  console.info("SMTP accepted:", result.messageId);
} finally {
  transport.close();
}
```

## Merge tags

Some values are filled in by the sending service, not by you: a first name in a bulk send, an unsubscribe link. Write those with `MergeTag`:

```tsx
<Heading level={1}>
  Welcome, <MergeTag name="first_name" />
</Heading>
```

By default a merge tag is written as `{{name}}`, in the HTML and in the plain text:

```text
WELCOME, {{first_name}}
```

If your provider uses another syntax, pass `mergeTag` to `render()`. It takes the tag's name and returns what to write. For a service that writes `*|FIRST_NAME|*`:

```tsx
const { html, text } = await render(<Welcome plan="Pro" />, {
  mergeTag: (name) => `*|${name.toUpperCase()}|*`,
});
```

What the function returns goes into the HTML as it is, with the name in it escaped.

A link's target can be a merge tag too. Write it in your provider's syntax: `mergeTag` changes `MergeTag` components, not the `href` strings you write.

```tsx
<Link href="*|UNSUB|*">Unsubscribe</Link>
```

> **Tip:** Values you know at render time don't need merge tags. Pass them as props and children, as `plan` is above. Elements escapes text passed as children.

## Before you send

- Keep rendering and provider credentials on the server.
- Use absolute HTTPS URLs for links and for images, and give each `Image` its file's size: `src={{ src, width, height }}`.
- Keep customer data out of an `Html` block's `html` prop. It is written as it is, unescaped.
- Use a verified sender. Add deduplication to your jobs, so a retry doesn't send a second receipt.
- A provider's "accepted" response is not inbox delivery. Record the message ID and use the provider's delivery and bounce events for the final status.
- Check the result in the email clients you care about.

> **Note:** Design JSON from `toDesign()` is for the [visual editor](https://hyperelements.dev/docs/guides/visual-editor), not an email body. Send `html` and `text`.

---

# Next.js

Source: https://hyperelements.dev/docs/guides/nextjs

Hyper Elements runs on the server, so it fits the App Router as it is. No entry in `next.config.ts`, no client bundle, no extra build step: Next.js bundles it into your server code like any other package. Only the HTML and text strings ever reach the browser.

## A template

A template is a plain component. Nothing in it is specific to Next.js, so the same tree renders from a route handler, a Server Component, a background job or a test.

```tsx
// src/emails/welcome-email.tsx
import { Button, Column, Email, Heading, Text, Span } from "@hyper-elements/react";

export interface WelcomeEmailProps {
  name: string;
  plan: string;
  dashboardUrl: string;
}

export default function WelcomeEmail({ name, plan, dashboardUrl }: WelcomeEmailProps) {
  return (
    <Email width={560} title={`Welcome, ${name}`} previewText={`Your ${plan} workspace is ready, ${name}.`} style={{ backgroundColor: "#f4f4f5", gap: 20 }}>
      <Column style={{ backgroundColor: "#ffffff", padding: [32, 40], gap: 24 }}>
        <Heading level={1} style={{ fontSize: 26 }}>Welcome, {name}</Heading>
        <Text>
          Your <Span style={{ fontWeight: 700 }}>{plan}</Span> workspace is ready.
        </Text>
        <Button href={dashboardUrl} style={{ backgroundColor: "#18181b", borderRadius: 8 }}>
          Open your dashboard
        </Button>
      </Column>
    </Email>
  );
}
```

Props like `name` come from outside: a database row, a webhook, a form. Text passed as children is escaped when Elements writes the HTML. Elements refuses links that run scripts (`javascript:`), but a URL from outside deserves a stricter check of your own, such as allowing absolute `http:` and `https:` URLs only.

## A route handler

Return the rendered HTML from a GET handler. `render()` is async, so the handler is too.

```tsx
// src/app/email-preview/raw/route.ts
import React from "react";
import { render } from "@hyper-elements/react";
import WelcomeEmail from "@/emails/welcome-email";

export async function GET() {
  const { html } = await render(
    React.createElement(WelcomeEmail, {
      name: "Ada",
      plan: "Pro",
      dashboardUrl: "https://example.com/dashboard",
    })
  );

  return new Response(html, {
    headers: { "Content-Type": "text/html; charset=utf-8" },
  });
}
```

This is the shape production code usually takes. Swap the `Response` for a call to your provider and you have a send endpoint: see [Sending email](https://hyperelements.dev/docs/guides/sending).

## A Server Component

An async Server Component awaits `render()` and passes the strings on. The template never ships to the browser.

```tsx
// src/app/email-preview/page.tsx
import { render } from "@hyper-elements/react";
import WelcomeEmail from "@/emails/welcome-email";
import PreviewDashboard from "./PreviewDashboard";

export default async function EmailPreviewPage() {
  const { html, text } = await render(
    <WelcomeEmail name="Ada" plan="Pro" dashboardUrl="https://example.com/dashboard" />
  );

  return <PreviewDashboard initialHtml={html} initialText={text} />;
}
```

`PreviewDashboard` here is your own Client Component. It receives strings, not React elements.

## Design JSON from a route

`toDesign()` from `@hyper-elements/react/builder` works in the same places. It's synchronous:

```ts
// src/app/design/route.ts
import React from "react";
import { toDesign } from "@hyper-elements/react/builder";
import WelcomeEmail from "@/emails/welcome-email";

export function GET() {
  const { design } = toDesign(
    React.createElement(WelcomeEmail, { name: "Ada", plan: "Pro", dashboardUrl: "https://example.com/dashboard" })
  );
  return Response.json(design);
}
```

See [Visual editing](https://hyperelements.dev/docs/guides/visual-editor) for what to do with it.

## An edge route

On the edge runtime, a render either works or rejects with an error that tells you to render emails in the Node.js runtime. The cause is React's: react-dom can't render with the React that React Server Components use there. Catch the error and you'll see it:

```ts
// src/app/edge/route.ts
import React from "react";
import { render } from "@hyper-elements/react";
import WelcomeEmail from "@/emails/welcome-email";

export const runtime = "edge";

export async function GET() {
  try {
    const { html } = await render(
      React.createElement(WelcomeEmail, { name: "Ada", plan: "Pro", dashboardUrl: "https://example.com/dashboard" })
    );
    return new Response(html, { headers: { "Content-Type": "text/html; charset=utf-8" } });
  } catch (error) {
    return Response.json({ error: (error as Error).message });
  }
}
```

> **Note:** Next.js 14 can't bundle Elements for the edge runtime. For emails, the Node.js runtime is the safe default on every version.

## Prerendering and Cache Components

Since Next.js 16, `create-next-app` turns on Cache Components. Pages and GET route handlers that read no request data are then prerendered when the app builds, and the build fails if one reads a random number or the current date.

Hyper Elements reads neither. A render never leaks into the next one, and the same input always gives the same output. So a route handler or Server Component like the ones above prerenders at build time with no `dynamic` flag and no workaround.

A handler or page that reads request data (a search param, a header) isn't prerendered, and renders per request as usual.

## Tested versions

CI builds a real Next.js app on each version and checks that the route handler and the Server Component each come out as a real email (email tables, not a web layout, with the words in the HTML and the plain text) and as a design with its rows:

| Next.js | React | What's checked |
|---|---|---|
| 14 | 18 | Route handler, Server Component |
| 15 (Turbopack) | 19 | Route handler, Server Component, edge route |
| 16, Cache Components on | 19 | Route handler and Server Component, prerendered at build |

---

# AI agents

Source: https://hyperelements.dev/docs/guides/ai-agents

If an agent writes your templates, Hyper Elements is built so its first try works more often, and so a wrong try tells it exactly what to fix. You don't read HTML to find out. In [our benchmark](https://hyperelements.dev/docs/benchmark), an agent reached a passing email 2× faster with Hyper Elements than with hand-written HTML or React Email.

## Why the API suits agents

- **One way to write each thing.** Styles go in `style={{ }}`, never as props. Space between blocks is the parent's `gap`; there are no margins. Text is components, not HTML. An agent doesn't have to guess which of three equivalent forms you meant.
- **Errors say where and what to do.** Every problem comes back with a `code`, a `path` into the template and a `message` that names the fix.
- **Layout without HTML.** `outline()` prints the laid-out template as text: each block, its width, its words. An agent checks that two columns sit side by side by reading a few lines, not nested email tables.
- **The guide ships with the package.** `GUIDE.md` is written from the components' own definitions, so it matches the version you installed.

## Give your agent the guide

### Claude Code

Add this line to your project's `CLAUDE.md`, and every session starts out knowing the components:

```text
@node_modules/@hyper-elements/react/GUIDE.md
```

### Codex, Cursor and other agents

Add this to `AGENTS.md`, or to a rule:

```text
Before writing a Hyper Elements template, read node_modules/@hyper-elements/react/GUIDE.md.
```

### As a skill

Install the same guide as an agent skill:

```bash
npx skills add hyper-elements/hyper-elements
```

### For any model, from the web

The site serves the docs in plain text for language models:

- [`https://hyperelements.dev/llms.txt`](https://hyperelements.dev/llms.txt): an index of the docs.
- [`https://hyperelements.dev/llms-full.txt`](https://hyperelements.dev/llms-full.txt): the docs in one file.

Every docs page also has a **Copy page** button that copies it as Markdown, ready to paste into a chat.

> **Tip:** `GUIDE.md` is the short guide: how a template is written, the common mistakes, every component on a line. `REFERENCE.md`, next to it in the package, has every prop and style in full, with defaults.

## The loop

Point your agent at this loop. Each step is cheap, and only the last one writes HTML.

### 1. Write

The agent writes a template with the components from `@hyper-elements/react`.

### 2. Validate

`validate()` runs every check `render()` runs, without rendering and without throwing:

```tsx
import { validate } from "@hyper-elements/react";

const { valid, diagnostics } = validate(<Welcome />);
for (const d of diagnostics) console.log(d.code, d.path, d.message);
```

Here's what comes back for `<Email backgroundColor="#fff">` with a `Text` styled `marginBottom: 16`:

```text
prop/unknown root.props.backgroundColor An Email has no prop "backgroundColor": it's a style, style={{ backgroundColor: … }}
style/unknown root.children[0].style.marginBottom "marginBottom" isn't a style a Text takes: use the parent's gap, or padding. See Text in @hyper-elements/react/GUIDE.md
```

Each line is a fix the agent can apply without asking you. Warnings and notes leave a template valid; only errors make `valid` false.

### 3. Outline

`outline()` prints the template as laid out on desktop, and says whether each `Row` stacks on phones:

```tsx
import { Column, Email, Heading, Text, Row, outline } from "@hyper-elements/react";

console.log(outline(
  <Email width={600}>
    <Heading level={1}>Your order</Heading>
    <Row style={{ gap: 16 }}>
      <Column style={{ width: 180 }}><Text>Shipping to</Text></Column>
      <Column><Text>Ada Lovelace</Text></Column>
    </Row>
  </Email>
));
```

```text
Email 600px
  Heading h1 600px "Your order"
  Row 600px: 2 side by side, stacked on phones
    Column 180px
      Text 180px "Shipping to"
    Column 404px
      Text 404px "Ada Lovelace"
```

The agent compares this against what you asked for. Wrong width, wrong nesting, missing words: all visible here. `outline()` throws an `ElementsError` if the template has errors, so validate first.

### 4. Render

```tsx
import { render } from "@hyper-elements/react";

const { html, text, diagnostics } = await render(<Welcome />);
```

A template with errors rejects with an `ElementsError` whose `diagnostics` hold the same `code`, `message` and `path` as `validate()`. `diagnostics` on success holds warnings. A few checks need the written output, such as an email's size against Gmail's limits, so they only run here.

## Common mistakes

Each of these made an agent's first try fail:

- `<Email backgroundColor="#fff">` → `<Email style={{ backgroundColor: "#fff" }}>`. Styles never go as props.
- `<Email style={{ width: 600, padding: 24 }}>` → `<Email width={600}>`, with the padding on a `Column` (a card) or a `Section` (a band) inside it. A root's width is a prop, and a root has no padding.
- `items={[{ text: "Home", link: "/" }]}` → `items={[{ text: "Home", href: "/" }]}`. A `Menu`'s items are `{ text, href }`, a `Social`'s icons `{ name, href }`.
- `style={{ marginBottom: 16 }}` → `gap: 16` on the parent. There are no margins.
- `ColumnLayouts`, `layout`, `headingType`, `altText`, `html` are props of the older Elements components, not these: use a `Row` of `Column`s, `level`, `alt`, and text as children.
- `<Image src="https://example.com/logo.png">` → `src={{ src: "https://example.com/logo.png", width: 240, height: 80 }}`, the file's size. Without it Outlook shows the image at its file's size, and Elements warns.

## Rules worth giving your agent

- Read `GUIDE.md` before writing a template.
- A template has one root: `Email`, `Page`, `Document` or `Canvas`. The root decides the output.
- Raw tags such as `<b>`, `<br>` or `<div>` are errors. Use `Span`, `LineBreak` and the layout components.
- Build reusable trees with a plain synchronous function that returns the root. Fetch data first: a component that is async or suspends is an error.
- Pass dynamic values as children or props, which Elements escapes. Only put markup you trust in an `Html` block.
- To move React Email templates, run `npx @hyper-elements/migrate` instead of rewriting them by hand. It keeps their logic and checks the result. Exit code `2` means a template failed to convert or lost content: report it, with the file and the reason. Don't pass `--force` to hide it. See [From React Email](https://hyperelements.dev/docs/migrate/react-email).

---

# Agent benchmark

Source: https://hyperelements.dev/docs/benchmark

We gave a coding agent the same five emails to build three ways: with Hyper Elements, with React Email, and as hand-written HTML. Each email was done when it passed the same checks. We timed how long that took and counted the tokens.

## Results

Claude Code 2.1.238 with Claude Sonnet 5 (`claude-sonnet-5`), 16 runs per approach, November 6, 2026. Every run reached a passing email.

| | Hyper Elements | Hand-written HTML | React Email |
|---|---|---|---|
| Median time to a passing email | **35s** | 65s | 76s |
| Median output tokens | **2,346** | 5,676 | 5,745 |
| Passed the checks on the first run | **11 of 16** | 4 of 16 | 5 of 16 |
| Median turns | 8 | 9 | 17.5 |
| Median tokens in all, context included | 402k | 375k | 723k |
| Median cost | $0.35 | $0.34 | $0.50 |

- **2× faster.** Hyper Elements was the fastest on every brief: 1.9× faster than hand-written HTML and 2.2× faster than React Email at the median. Within a brief it was faster in 48 of 52 pairings with HTML and 47 of 52 with React Email (one-sided Mann–Whitney, p < 0.001 for each).
- **2.4× fewer tokens written.** The agent writes a short template; the engine writes the tables.
- **Right the first time more often.** 11 of 16 Hyper Elements emails passed the first time the agent ran the checks, against 4 and 5.
- **Not cheaper in all.** The guide is in the agent's context on every turn (cached), so the tokens in all, and the cost, are about the same as hand-written HTML's, and lower than React Email's.

## The emails

Five briefs, each with the exact copy, links and images, and its layout:

| Brief | What makes it hard |
|---|---|
| Password reset | A sized logo, a button, a preview text |
| Product launch | A hero image, three feature columns that stack on phones |
| Order receipt | Line items with the price on the right, two address columns |
| Newsletter | Two stories, each an image beside text, stacked on phones |
| Event invite | Three detail columns, a button with a hover color |

## The checks

Every approach was held to the same checks, run in headless Chromium at 800px and at 375px wide:

- the copy, the links and the preview text (present, and hidden);
- each button's link, color, size and hover color;
- each image loaded, with alt text, at its size;
- a table layout with no flex or grid, content 600px wide, and no sideways scroll on a phone;
- columns side by side on desktop and stacked on a phone, and line items on one line.

## How it ran

Each run started in a fresh directory with the brief, a `CLAUDE.md` of conventions and the checker, and the same prompt: "Build the email described in BRIEF.md, following CLAUDE.md. It's done when `node tools/check.mjs` passes." The agent could edit files and run `node`, `tsc`, `ls` and `cat`, with no web access. The Hyper Elements project's `CLAUDE.md` also imported the package's guide, [as we tell you to set it up](https://hyperelements.dev/docs/guides/ai-agents), so its tokens count against Hyper Elements.

## What it doesn't show

- One agent and one model. Other agents and models may differ.
- Short, fully specified emails. A vague brief or a long email may change the picture.
- Hyper Elements 0.3 before its release, and React Email components 1.0.12.

The harness, the briefs, the checks and every run's numbers are in the repository, in [`apps/website/benchmark`](https://github.com/hyper-elements/hyper-elements/tree/main/apps/website/benchmark). Run it yourself with your own agent.

---

# Visual editing

Source: https://hyperelements.dev/docs/guides/visual-editor

You or an agent writes the template in code. Someone else changes the copy in a visual editor. You don't maintain two versions, and you don't hand-build design JSON.

`@hyper-elements/react/builder` connects your templates to Unlayer's builder, the drag-and-drop email and page editor:

- `toDesign(element)` writes a template as the builder's design JSON, for its `loadDesign()`.
- `fromDesign(design, options)` reads a design back as a template: an element to render, and its JSX source.

Rendering needs no Unlayer account or API key. The builder is Unlayer's product, with its own project setup.

## Template to design

```tsx
import { mkdir, writeFile } from "node:fs/promises";
import { toDesign } from "@hyper-elements/react/builder";
import { Email, Text } from "@hyper-elements/react";

const { design, report } = toDesign(
  <Email width={600}>
    <Text>Welcome to your new workspace.</Text>
  </Email>
);
for (const line of report) console.warn(line);
await mkdir("output", { recursive: true });
await writeFile("output/design.json", JSON.stringify(design, null, 2));
```

`design` is a serializable object with `body`, `counters` and `schemaVersion`. It holds design structure, not HTML, and no Elements data. Keep the schema version and counters it writes.

`toDesign()` is synchronous. It takes an `Email`, a `Page` or a `Document`. A `Canvas` has no design. It renders the template once with React, as `render()` does, so hooks, Context, Fragments and your own components work, at the root too.

## The report

`report` lists what the builder can't hold as it is, one line each, with the path to the block. It's empty when everything maps to a builder tool. A `Table`, for example:

```text
root.children[1]: a Table isn't a tool of the builder's: it's an HTML block of its own markup in the builder (it can be moved, not edited)
```

Read the report before you promise an editor user that a block is editable.

## What the builder holds

The builder holds what its tools can. Two things happen to the rest:

- **Hidden properties.** A style or prop a tool has no field for is a hidden property of that tool. It's kept in the design under its own name and drawn by Elements, but the builder shows no control for it yet.
- **HTML blocks.** What no tool shows (a `Layer`, an `Svg`, a `Table`, a box nested in a column, your own `component()`) goes in as an HTML block of its rendered markup. An editor user can move it, not edit it. The report names each one.

Two smaller details: a line height goes into the builder's field as a whole percentage, as browsers draw it, so `24px` at 13px becomes `185%`, a twentieth of a pixel taller there. The builder has no page numbers yet, so a `PageNumber` goes in as its token, which the editor's PDF prints as it is. The report says so.

## Load it in the builder

Create the editor, load the design when it's ready, and export when the user is done:

```html
<div id="editor" style="height: 80vh"></div>
<script src="https://editor.unlayer.com/embed.js"></script>
<script>
  const editor = unlayer.createEditor({
    id: "editor",
    displayMode: "email",
    // Add your projectId and allowed domain for your deployed integration.
  });
  editor.addEventListener("editor:ready", async () => {
    const response = await fetch("./output/design.json");
    editor.loadDesign(await response.json());
  });
  function save() {
    editor.exportHtml(({ design, html }) => {
      // Store `design` in your application. Load it next time to keep the edits.
    });
  }
</script>
```

Match the editor's `displayMode` to the template's root: `email` for an `Email`, `web` for a `Page`, `document` for a `Document`. Which tools and features the editor offers depends on its version and your project's configuration. Unlayer's docs cover [installing the editor](https://docs.unlayer.com/builder/installation) and [loading and saving designs](https://docs.unlayer.com/builder/load-and-save-designs).

> **Warning:** Once an editor user has changed a design, store their latest JSON and load that. Regenerating the design from your React source and reloading it overwrites their changes. Keep the template source and the saved designs as separate records.

## Design back to template

```tsx
import { readFile } from "node:fs/promises";
import { fromDesign } from "@hyper-elements/react/builder";
import { render } from "@hyper-elements/react";

const saved = JSON.parse(await readFile("edited.design.json", "utf8"));
const { element, code, report } = fromDesign(saved, { displayMode: "email" });
const { html, text } = await render(element);
```

- `element` renders the design. `render(element)` gives HTML and a plain-text body that match the edits, ready to [send](https://hyperelements.dev/docs/guides/sending).
- `code` is the same template as JSX in the new components.
- `report` lists what the template can't hold.

Pass the `displayMode` the design was made in: `email` gives an `Email`, `web` a `Page`, `document` a `Document`. Without one, a design with a header, a footer or a page break becomes a `Document`, any other an `Email`. `name` sets the component's name in `code`. `fromDesign()` reads designs made by `toDesign()`, edited in the builder, or made there from scratch. The builder's own HTML blocks come back as `Html` blocks.

### What comes back

The design as it stands, with its sample values. A design holds content and settings, not code, so the original's props, loops, conditions, hooks and event handlers don't come back.

What the builder can't arrange comes back with the same look, but flatter:

- a `Section` around several `Row`s comes back as a `Section` each;
- a box's padding comes back on its blocks;
- a `Grid` comes back as `Row`s of `Column`s.

The space between blocks comes back as padding too. A `Column` with `gap: 16` comes back like this, drawn the same:

```tsx
<Column style={{ padding: 32, backgroundColor: "#ffffff" }}>
  <Heading style={{ fontSize: 24 }}>{"Welcome, "}<MergeTag name="first_name" /></Heading>
  <Text style={{ padding: [16, 0, 0, 0] }}>Your Pro workspace is ready.</Text>
</Column>
```

### Untrusted designs: `toSafeHtml`

A design's markup comes back as it is. If your designs can hold content you don't trust, pass your sanitizer as `toSafeHtml`, a function from an HTML string to a safe one. Every builder HTML block's markup, and every text's before it's read, goes through it:

```tsx
const { element } = fromDesign(saved, { displayMode: "email", toSafeHtml });
```

## Limits

- A component that is async or suspends makes `toDesign()` throw, as it makes `render()` reject. Fetch data before you build the tree.
- Plain markup among the components (a `<div>`, a `<b>`) makes `toDesign()` throw too. Use the components, or an `Html` block for raw HTML, which the editor edits as HTML.
- Don't construct or guess design JSON by hand. Generate it with `toDesign()`.

---

# From React Email

Source: https://hyperelements.dev/docs/migrate/react-email

You don't rewrite your React Email templates by hand. One command converts them, keeps their props, loops and conditions, and then checks each migrated template against its original, so you know what changed before you ship it.

```bash
npx @hyper-elements/migrate emails           # converts and checks your templates, and writes nothing
npx @hyper-elements/migrate emails --write   # then replaces them (committed in git first, so git can undo it)
```

Run it from your project folder, with Node.js 20.6 or later. It uses your project's React, React Email and `tsconfig` paths.

## What it converts

Each template becomes the components from `@hyper-elements/react`, with its styles in `style={{ }}`:

| React Email | Hyper Elements |
|---|---|
| `Text` | `Text` |
| `Section`, `Row`, `Column` | `Section`, `Row`, `Column` |
| `Button` | `Button` |
| `Container` width | `Email` `width` |
| `Img` | `Image`, with its file's size in `src={{ src, width, height }}` |
| `Hr` | `Divider` |
| `Preview` | `Email` `previewText` |
| Margins | Padding on the blocks |
| Tailwind classes and inline styles | `style={{ }}` |

- **Tailwind** classes are resolved with React Email's own Tailwind and your template's config, then become styles.
- **Your own components** that a template uses, from the same file or your other files (a shared `Layout`, a `Footer`, also through an `index.ts` that re-exports them), are inlined, so their markup converts too.
- **Anything with no equivalent** is kept as an `Html` block that renders exactly as before. The block is marked `TODO(convert)` in the migrated template.
- **Default exports** wrapped in `memo` or `forwardRef` work, nested wrappers included. A template that calls hooks (`useMemo`, `useId`) migrates like any other.
- **Language and direction:** the document's `lang` and `dir` become `Email`'s `lang` and `dir` props.

JavaScript templates keep JavaScript. A `.js` file with JSX can't be loaded: rename it to `.jsx`.

## How it checks the result

The goal is an editable template with the same content, not pixel parity. The original and the migrated template are rendered with the template's `PreviewProps`, then again with each boolean prop flipped, and compared in two parts.

### Content must match

- every word the original renders, including numbers with their separators, signs, currency symbols and percentages, in the same order;
- every link, image and image `alt` text;
- no new words, links or images;
- the same on a phone (375px), and on wider screens where a rule targets them (Tailwind's `md:`, `lg:`);
- the same in dark mode, where either side has a `prefers-color-scheme: dark` rule (a logo or text swapped for dark mode);
- whether content shows, including content the original shows or hides by its props (`isGift && "hidden"`), and words CSS adds or hides (`::before` content, an ellipsis, a line clamp, a clipping `overflow`);
- every block reaching the visual editor.

Anything the converter can't map is kept as HTML, so content that differs is a converter bug. The template is still written, flagged `✗`, and the run exits with `2`. Please report it.

### How it looks is listed

At a desktop width (700px), each word's size, bold, italics, letter case, underline, color, the background behind it and a link's target; where each line of text sits across the page (a column stacked into one, a block moved to the other side); and CSS the check doesn't model that can change how words show (`white-space`, letter spacing, a transform, a text shadow, right-to-left text), unless both sides have the same. A difference here is listed under "looks different", for you to fix in the editor. The run still exits `0`.

The check fails closed: when it can't read something on one side (a selector, a condition, a value), it says so, naming the rule, instead of passing it.

### What isn't verified

Vertical spacing, exact positions (under about 120px), where images sit and an image's `srcset`, fonts as drawn, borders, corners and outer shadows, styles in dark mode (what shows there is compared), hover, and how each email client renders.

Code paths your `PreviewProps` don't reach (a loop over an empty preview array, a condition on a non-boolean prop) are converted but not verified. Extend `PreviewProps` to cover them.

## The report

```text
✓ emails/welcome.tsx: 100% editable, 1 kind of difference (image border radius dropped)
✓ emails/comment.tsx: 100% editable
    looks different: couldn't verify: the look of "Alex", "can", "you" (`white-space: pre-wrap`, a style the check doesn't verify)
- emails/components/layout.tsx: skipped (no default-exported component)

2 templates: 2 migrated and checked (1 looks different: see above). 1 other file skipped (see above). 2 written.
```

For each template:

- **Editable**: the share of content that became blocks you can edit in the visual editor. The rest is kept as HTML blocks that render exactly as before.
- **Differences**: what Hyper Elements can't express, and how it was approximated.
- **What the migration did**: changes that don't affect the look (a component inlined, a conditional `className` split into one element per class list).

Files that aren't templates (shared components, helpers, a framework's routes) are listed after the templates as skipped, with why. Write the report to a file with `--report`.

## Options

| Option | What it does |
|---|---|
| `--write` | Replace each template with its migrated version. Only templates git can restore: committed, with no changes since. |
| `--out <dir>` | Write migrated templates to `<dir>` instead, keeping the folder layout. Relative imports still resolve. |
| `--design` | Also write `<name>.design.json` next to each template, for the visual editor's `loadDesign()`. Text props shown as given become merge tags (`{{name}}`). |
| `--no-merge-tags` | Keep the `PreviewProps` values in the design JSON instead of merge tags. |
| `--report <file>` | Write the migration report: JSON for a `.json` file, Markdown for any other. |
| `--strict` | Fail a template with any difference, in its content, its look, or a style the migration couldn't keep, and don't write it. |
| `--force` | With `--strict`, write templates the check fails anyway. |
| `--overwrite` | Replace files already at a destination that this run didn't produce: what an earlier run wrote in an `--out` folder (not once it's edited), or files git can restore. |
| `--allow-dirty` | Replace files git can't restore (changed since the last commit, not committed, or not in a repository), with `--write` or `--overwrite`. |
| `--from <source>` | `react-email` (the default), or `elements` to [move older Elements templates](https://hyperelements.dev/docs/migrate/elements). |
| `-h`, `--help` | Show the help. |
| `-v`, `--version` | Show the version. |

Without `--write` or `--out`, nothing is written. Run it once to read the report, then again with `--write`.

### Safe writes

`--write` replaces templates in place, so before running anything it checks that git can give each one back. A template with uncommitted changes, one that isn't committed, or one outside a git repository stops the run with exit `1`, naming them. Commit first, and git can undo the migration. `--out <dir>` writes copies and doesn't need git. `--allow-dirty` replaces templates anyway.

All templates are converted and checked before any output is written. A template edited while the run converts it isn't replaced: it fails, and your edit stays. A run stopped with Ctrl-C cleans up after itself. One killed outright (`kill -9`) can leave a temporary copy next to a template, a dot-file named after it, safe to delete.

## Exit codes

| Code | When |
|---|---|
| `0` | Every template converted with the same content. What looks different is listed. |
| `1` | A usage error, no templates found, a template left unchecked because a file that renders it isn't migrated (a preview around it: migrate it with `--out`), a Node.js older than 20.6, an installed `@hyper-elements/react` this version doesn't support, or a `--write` blocked by files git can't restore. |
| `2` | A template failed to convert, its content differs (with `--strict`, anything differs), a file couldn't be read, or the run couldn't go on. |

A run never ends with `0` without checking what it was given. That makes it safe in CI: templates already migrated are skipped, so running it again after `--write` passes.

## Check a template you migrated yourself

```bash
npx @hyper-elements/migrate compare emails/welcome.tsx emails/welcome.elements.tsx
```

`compare` renders both with the original's `PreviewProps`, then with each true/false prop flipped, and checks the HTML and the design JSON: every word, link, image and `alt` text is still there, no new words appear, and the visual editor gets every block. What looks different is listed. Exit `0` when the content is the same, `2` with missing or extra content (with `--strict`, with any difference).

Use it after you convert a `TODO(convert)` block by hand: replace it with the new components, then run `compare` against the original (from git, if `--write` replaced it).

## How well it works

Measured on 106 real templates: 71 of React Email's own demo and example emails, 25 community templates from MIT repositories, and 10 written by agents. The codemod migrates your source; the runtime mode converts what a template renders, as `convertReactEmail()` does.

| | Codemod | Runtime |
|---|---|---|
| Converted | 106 of 106 | 106 of 106 |
| Type-check | 106 of 106 | 106 of 106 |
| Lose content | 0 | 0 |
| Problems with a boolean prop flipped | 0 | 0 |
| Blocks the editor skips | 0 | 0 |
| Editable, on average | 98.4% | 98.4% |
| Fully editable | 96 | 97 |
| Words moved on desktop (median) | 0% | 0% |

On desktop, in 105 of 106 templates at most a quarter of the words sit somewhere else, and the median is none. The one outlier sets no font, so the browser shows serif where Hyper Elements uses its sans-serif default. No conversion has a style difference on desktop. Three have one on phones: text the converter makes smaller so its words fit.

## What changes

The report lists every difference for each template. The common ones:

- **Phones.** React Email's rows are tables and never stack, so columns stay side by side, unless the template stacks them (`mobile:!block`). Side by side, they keep their share of the row, so fixed widths and images scale down with it.
- **Phone styles** become phone settings for padding, margins, font size, line height, alignment and hiding. Others (a color, font weight, letter spacing) and hover styles have no equivalent. Phone settings use a 480px breakpoint, so a source query such as `max-width: 600px` differs between 481px and 600px.
- **Column vertical alignment.** A React Email `Column` is a `<td>`, centered vertically by default. Email columns here sit at the top. It shows only next to a taller column.
- **Shadows, gradients, transforms.** A box's outer shadow is dropped and a gradient background becomes its first color. A transform, a text shadow or an inset shadow changes how text shows, so a template with one is listed as looking different.
- **Image border radius** is dropped.
- **Attributes** a block has no place for (`id`, `title`, `role`, `aria-*`).
- **A box that shrinks to fit its content** (`w-fit` around text) is as wide as its parent.
- **Text without a font family** uses the default font rather than the browser's.

## A template that can't be converted

A template that can't be written in the components at all fails: nothing is written for it, the report says why, and the run exits `2`. Rewrite that part by hand, then check it against the React Email original with `npx @hyper-elements/migrate compare <original> <migrated>`.

## After migrating

Install the package, since the migrated templates import it:

```bash
npm install @hyper-elements/react@^0.3.0
```

When a run writes templates where it isn't installed, it ends with the install command for your package manager (npm, pnpm, yarn or bun, by your lockfile).

```tsx
import { render } from "@hyper-elements/react";
import { toDesign } from "@hyper-elements/react/builder";
import Welcome from "./emails/welcome";

const element = <Welcome name="Alex" />;
const { html, text } = await render(element); // send html with any provider, with text as the text part
const { design } = toDesign(element);         // open in the visual editor with loadDesign()
```

You can remove React Email once no file imports it. After `--write`, the run lists the files that still import it, and the project files that still use a migrated template with React Email's `render()`: render those with `render()` from `@hyper-elements/react` instead. Templates with blocks kept as HTML still import React Email components for those blocks; the report lists them.

## Open React Email templates in Unlayer's builder

`--design` makes any React Email template editable in Unlayer's visual builder, without changing your source:

```bash
npx @hyper-elements/migrate emails --out unlayer --design --report unlayer/report.json
```

```js
editor.loadDesign(await fetch("/unlayer/welcome.design.json").then((r) => r.json()));
```

Web fonts aren't part of the design JSON: the editor loads and exports a web font only when it's registered when the editor is created. The JSON report lists each template's fonts in that shape:

```js
const report = await fetch("/unlayer/report.json").then((r) => r.json());
const customFonts = report.flatMap((result) => result.fonts ?? []);
const editor = unlayer.createEditor({ id: "editor", displayMode: "email", fonts: { showDefaultFonts: true, customFonts } });
```

## From code

Use the converter from an agent, a build step or a server:

```bash
npm install @hyper-elements/migrate
```

```ts
import { convertReactEmail, NewComponentsError } from "@hyper-elements/migrate/react-email";
import Welcome from "./emails/welcome";

const conversion = await convertReactEmail(Welcome); // rendered with its PreviewProps, and checked against it
const tsx = conversion.code;                  // the template in the components
const html = await conversion.html();
const design = conversion.design();           // open in the visual editor with loadDesign()
const customFonts = conversion.editorFonts(); // register when creating the editor: fonts: { customFonts }
conversion.report.missingText;                // [] when nothing was lost
```

`convertReactEmail()` converts what a template renders: loops and conditions become the content they produced (the CLI keeps them). Where that can't be written in the components, it throws a `NewComponentsError`, whose `reason` says why.

> **Warning:** The command runs your templates to check them: a template's module code runs, and its component renders, as React Email's preview does. Run it only on code you trust. It makes no network requests.

---

# From older Elements

Source: https://hyperelements.dev/docs/migrate/elements

Hyper Elements 0.3 doesn't include the older Elements components (`ColumnLayouts`, `html` props, `renderToHtml()`): templates written with them move before you upgrade, so stay on 0.2 until they have. A codemod rewrites them with the new components. It rewrites the imports and the JSX, and nothing else: your props, loops, conditions, helpers and constants stay as they are.

A template uses one set of components or the other, never both. Move a template whole.

## Run the codemod

```bash
npx @hyper-elements/migrate src/emails --from elements                  # lists what it would change
npx @hyper-elements/migrate src/emails/welcome.tsx --from elements > welcome.next.tsx   # prints one template
npx @hyper-elements/migrate src/emails --from elements --write          # replaces them (only files git can restore)
```

Run it before you upgrade the package: a template with nothing in it that only 0.2 has is migrated only while 0.2 is installed. Each migrated template starts with the line `// Migrated from Elements 0.2's components by @hyper-elements/migrate.`, so a second run changes nothing.

`--write` only replaces templates git can restore, so commit first. `--allow-dirty` skips that check. `--report notes.md` (or `.json`) writes what the codemod noted for each template.

JSX inside expressions (`items.map(...)`, `cond && ...`) is rewritten in place. A `.js`, `.jsx`, `.mjs` or `.cjs` template gets JavaScript, a `.ts` or `.tsx` one TypeScript.

### Which files it touches

Templates are the files that import the older components, directly or through your own modules that pass them on (an index with `export { Email } from ...` or `export *` from it, followed as your `tsconfig` resolves it). Other files, such as one that only calls `renderToHtml()` or that index itself, are left as they are and aren't listed.

A namespace re-export (`export * as E from ...`) isn't followed: a template that uses one fails, naming the file. A template whose root is chosen at run time (`const Root = web ? Page : Email`) stays as it was, with a note: write it with one root.

### From code

```ts
import { migrateElements } from "@hyper-elements/migrate/elements";

const { code, report } = await migrateElements(source, { installed: "0.2.1" });
```

`installed` is the version of `@hyper-elements/react` the project has, where it's known. A module that comes back as it was says why: `current` (it already uses the new components), `undecided` (nothing in it is only either's) or `refused` (it has both, with the reason).

## Before and after

```tsx
// Before
<Email>
  <Row layout={ColumnLayouts.TwoEqual} backgroundColor="#ffffff">
    <Column>
      <Heading headingType="h1">Welcome, {name}</Heading>
      <Paragraph html="Your workspace is <b>ready</b>." />
    </Column>
    <Column>
      <Button href="https://example.com" text="Open it" />
    </Column>
  </Row>
</Email>
```

```tsx
// After
<Email width={500} style={{ color: "#000000", fontFamily: "arial,helvetica,sans-serif" }}>
  <Section style={{ backgroundColor: "#ffffff" }}>
    <Row>
      <Column style={{ width: "50%" }}>
        <Heading style={{ padding: 10, fontSize: 22, fontWeight: 400, lineHeight: "140%" }}>
          Welcome, {name}
        </Heading>
        <Text style={{ padding: 10, fontSize: 14, lineHeight: "140%" }}>
          {"Your workspace is "}
          <Span style={{ fontWeight: 700 }}>ready</Span>.
        </Text>
      </Column>
      <Column style={{ width: "50%" }}>
        <Column style={{ padding: 10, alignItems: "center" }}>
          <Button href={{ href: "https://example.com", target: "_blank" }}>Open it</Button>
        </Column>
      </Column>
    </Row>
  </Section>
</Email>
```

The new template draws what the old one drew. The older components filled in defaults (a 500px email, Arial, 10px of padding on every block), and the new ones don't, so the codemod writes those values out. Delete the ones you don't want.

## What it writes

| Older components | New components |
|---|---|
| `Email`'s 500px, black text, Arial | `width={500}`, and the color and font in `style` |
| A block's 10px of padding (`containerPadding`) | `padding: 10` on the block, or on a `Column` around an `Image`, `Button`, `Social`, `Menu` or `Video` |
| `Heading`: 22px at 140%, not bold; `Paragraph`: 14px at 140% | Those values in `style` |
| `Paragraph` | `Text` |
| `headingType="h3"` | `level={3}` |
| `html="Hi <b>there</b>"` | Children: `Hi <Span style={{ fontWeight: 700 }}>there</Span>`. `<a>` becomes `Link` (its target and title kept), `<br>` `LineBreak`, `<s>`, `<sup>` and `<sub>` a `Span`. Entities are decoded. Each `<p>` is a blank line from the next, and another block starts a line of its own. |
| A text block's children, `text` and `html` | What the old one drew: a `Paragraph` its children, else its `text` (plain text), else its `html`; a `Heading` or a `Button` its `text` (as markup) over its children, never its `html` |
| `letterSpacing="0.05em"` | px, from the font size |
| A `Row` | A `Section` (its background across the window), with a `Row` of `Column`s for several columns, each its share of the layout as a `width` |
| A `Row`'s side padding | Dropped: the old one drew it outside the content, where it doesn't show |
| A line along the bottom (or top) of every `Column` of a `Row` | The `Row`'s border, and each `Column`'s on phones, where they stack |
| An `Image` 120px wide | The share of its column the old one drew it at (`width: "25%", maxWidth: 125` in a 500px email). Give it `width: 120` to draw it at 120px. |
| `html` with what a run of text can't hold (an image, a list, a table, a box in a line) | An `Html` block with that markup, in a `Column` with the text's styles |
| Markup a value decides or a list writes (`` `${note ? `<em>${note}</em>` : ""}` ``) | The same choice or list, of `Span`s and `Link`s |
| Lengths in rem, em, or following the window | px (rem and em at 16px; a width that follows the window at a phone's) |
| `Html` | `Html` in a `Column` with its padding |
| `Table`'s `headers` and `data`, or the `values` it can read | A `Table` of `TableRow`s and `TableCell`s |
| `Document`'s `documentSize`, `documentOrientation`, `documentMargin`; a `PageBreak` | `size`, `orientation`, `margin`; a `PageBreak` between `Section`s |
| `Button`'s `buttonColors` | Its `color` and `backgroundColor` in `style`. The hover colors are left out and noted: add them as `hover={{ … }}` |
| `mobile={{ ... }}`, `hideOnMobile`, `hideOnDesktop` | `mobile={{ ... }}` with the new names, `hidden={{ mobile: true }}` |
| `Social`'s `{ name, url }`; `Menu`'s `linkColor` and `textColor` | `{ name, href }`; `color` and `separatorColor` |

## What it notes

The codemod never drops anything quietly. It lists, with the line:

- a value it can't read from the source (an expression) where the old components drew something other than it says: an image's width, a `Row`'s padding, phone settings;
- `html` from an expression: it's written as text, so markup in it would show;
- markup the new components don't write, each named (an image with its `src` and `alt`, a list's bullets, a style declaration and the tag it was on, a tag they have no run for), with the text in it kept;
- a text block's source the old one didn't draw (a `Paragraph`'s `html` beside its children);
- a `Button`'s hover colors, which it leaves out;
- `Column`s whose borders or backgrounds the old components stretched to their `Row`'s height;
- a horizontal `Menu` of links written out, which becomes a wrapping `Row` of its links and separators so it draws the same (a `Menu` worked out at run time, or a vertical one, stays a `Menu`);
- custom tools, which it doesn't rewrite yet: a comment marks each one for you to rewrite;
- a `Table`'s or a text's values from code, written as text where the old ones drew them as HTML, so markup in them would show;
- old functions it leaves imported, such as `renderToHtml()`.

## What to check by hand

- **Rendering.** The new components render with `await render(element)`, which is async, in place of `renderToHtml()`. Update every caller.
- **Notes.** Read every line of the report. Each one names a place where the output may differ or where you have work to do.
- **Custom tools.** Rewrite each one marked with a comment, with the new components or `component()`.
- **Values from expressions.** Image widths, `Row` padding and phone settings from code weren't read. Check them.
- **Markup in values.** `html` and table values from code are now text. If they held markup, rewrite them as `Span`s and `Link`s.
- **Runtime roots.** A template with `const Root = web ? Page : Email` wasn't changed. Write it with one root.
- **Look at it.** The codemod's tests check what each old component becomes, and round-trip each migrated example through the builder and back. No test draws a migrated template next to the old one in a browser, so render yours and look at it before you send it.

> **Tip:** Run `npx @hyper-elements/migrate src/emails --from elements --report notes.md` first, without `--write`, and read `notes.md`. Then write.

---

# Components reference

Source: https://hyperelements.dev/docs/components

Every component, what it holds, and every prop and style it takes, with its default and what it does. [Templates and roots](https://hyperelements.dev/docs/templates) shows how a template is written; `validate()` checks one against what's here.

Every component also takes:

- `style={{ … }}`: the styles listed under it. A number is px (`padding: 16` is `16px`).
- `mobile={{ … }}`: style overrides on phones, in an `Email` or a `Page`, for the styles listed under "`mobile`".
- `hover={{ … }}`: styles on hover, for the ones listed under "`hover`".
- `hidden={{ mobile: true }}` or `hidden={{ desktop: true }}`: shown on one only.
- `id`: an id of your own, written into the HTML.


A template is one of these, and the root decides the output: `render()` writes an Email's HTML, a Page's HTML, and a Document's print HTML. `renderPdf()` (`@hyper-elements/react/pdf`) writes a Document's PDF, and `renderImage()` (`@hyper-elements/react/image`) a Canvas's PNG or SVG (`render()` writes a Canvas's HTML, to look at).


Bands and boxes that arrange blocks. None is required: a root stacks its children.


Content, stacked down whatever holds it.


Inside text: a styled run, a link, a line break, a merge tag.


Only inside the component named: a list's items, a table's rows and cells, a document's pages, header and footer.


Only inside an Svg, in its viewBox's units.

## Values

Source: https://hyperelements.dev/docs/components/values

What a property takes, where it says *kind*:

- *fontFaces*: a list of { family, src, format, weight, style }
- *color*: a color ("#0879a1", "rgb(…)", "rgba(…)" or a CSS name)
- *fontFamily*: a font stack, as CSS writes it ("Inter, Arial, sans-serif")
- *fontWeight*: 100 to 900 in hundreds, "normal" or "bold"
- *lineHeight*: a multiple of the font size (1.5), a percentage ("150%"), px ("24px") or "normal" (the font's own)
- *insets*: px for all sides, "8px 16px" (1 to 4 values), [v, h] or [t, r, b, l], or { top, right, bottom, left }
- *border*: "1px solid #ccc", { width, style, color } for all sides, or { top, right, bottom, left } with one of those each
- *radius*: px for every corner, [topLeft, topRight, bottomRight, bottomLeft], or { topLeft, topRight, bottomRight, bottomLeft }
- *flex*: a share of the free width (0 or more), or "none"
- *link*: a URL (http, https, mailto, tel, a path, or a merge tag) or { href, target }
- *attributes*: attributes by name, each a text value (no on… handlers, href or style)
- *asset*: an image URL (http, https or a data:image URI), or { src, width, height }
- *line*: "1px solid #ccc" or { width, style, color }
- *video*: a YouTube or Vimeo video's https link

## Email

Source: https://hyperelements.dev/docs/components/email

An email. Its children are stacked down the content width, centered in the window.

Holds: Section, Row, Column, Grid, Layer, Svg, Text, Heading, Link, Button, Image, Divider, List, Table, Video, Social, Menu, Html. Drawn in: email.

Props:
- `width`: a length (a number of px) (default `600`)
- `previewText`: text. Shown after the subject in inbox lists, not in the email.
- `title`: text. The document's title (shown in a browser tab, and by some email clients).
- `lang`: text. Its language, as a BCP 47 tag ("en", "ar").
- `dir`: one of "ltr", "rtl", "auto"
- `fonts`: *fontFaces*. The font files the template loads: a family's file for each weight and style it uses. Text names a family in its fontFamily stack, before the fonts to show where it can't load.

`style`:
- `color`: *color* (default `"#000000"`, inherited)
- `fontFamily`: *fontFamily* (default `"Arial, Helvetica, sans-serif"`, inherited)
- `fontSize`: a length (a number of px) (default `16`, inherited)
- `fontWeight`: *fontWeight* (default `400`, inherited)
- `fontStyle`: one of "normal", "italic" (inherited)
- `lineHeight`: *lineHeight* (default `1.5`, inherited)
- `letterSpacing`: a length (a number of px) (inherited)
- `textAlign`: one of "left", "center", "right", "justify" (default `"left"`, inherited)
- `textTransform`: one of "none", "uppercase", "lowercase", "capitalize" (inherited)
- `backgroundColor`: *color*. The window's background, behind the content.
- `gap`: a length (a number of px). Space between children.
- `alignItems`: one of "start", "center", "end", "stretch". Where children sit across the layout's direction (vertically in a Row, horizontally in a Column), as CSS align-items. Across a Column it places what has its own size (a Button, an Image, an Svg, a box with a width); a block of text fills the width, so its words move with its textAlign.

`mobile` (on phones): `fontSize`, `lineHeight`, `letterSpacing`, `textAlign`, `gap`.

## Page

Source: https://hyperelements.dev/docs/components/page

A web page. Its children are stacked down the content width, centered in the window.

Holds: Section, Row, Column, Grid, Layer, Svg, Text, Heading, Link, Button, Image, Divider, List, Table, Video, Social, Menu, Html. Drawn in: page.

Props:
- `width`: a length (a number of px) (default `1200`). The widest the content gets.
- `description`: text. The page's meta description.
- `title`: text. The document's title (shown in a browser tab, and by some email clients).
- `lang`: text. Its language, as a BCP 47 tag ("en", "ar").
- `dir`: one of "ltr", "rtl", "auto"
- `fonts`: *fontFaces*. The font files the template loads: a family's file for each weight and style it uses. Text names a family in its fontFamily stack, before the fonts to show where it can't load.

`style`:
- `color`: *color* (default `"#000000"`, inherited)
- `fontFamily`: *fontFamily* (default `"Arial, Helvetica, sans-serif"`, inherited)
- `fontSize`: a length (a number of px) (default `16`, inherited)
- `fontWeight`: *fontWeight* (default `400`, inherited)
- `fontStyle`: one of "normal", "italic" (inherited)
- `lineHeight`: *lineHeight* (default `1.5`, inherited)
- `letterSpacing`: a length (a number of px) (inherited)
- `textAlign`: one of "left", "center", "right", "justify" (default `"left"`, inherited)
- `textTransform`: one of "none", "uppercase", "lowercase", "capitalize" (inherited)
- `backgroundColor`: *color*. The window's background, behind the content.
- `gap`: a length (a number of px). Space between children.
- `alignItems`: one of "start", "center", "end", "stretch". Where children sit across the layout's direction (vertically in a Row, horizontally in a Column), as CSS align-items. Across a Column it places what has its own size (a Button, an Image, an Svg, a box with a width); a block of text fills the width, so its words move with its textAlign.

`mobile` (on phones): `fontSize`, `lineHeight`, `letterSpacing`, `textAlign`, `gap`.

## Document

Source: https://hyperelements.dev/docs/components/document

A printed document: its children on pages of its size (Document.Page, or split by PageBreaks), a PageHeader and a PageFooter on each. Renders to print HTML, and to PDF with @hyper-elements/react/pdf.

Holds: Section, Row, Column, Grid, Layer, Svg, Text, Heading, Link, Button, Image, Divider, List, Table, Video, Social, Menu, Html, Document.Page, PageBreak, PageHeader, PageFooter. Drawn in: page.

Props:
- `size`: one of "A3", "A4", "A5", "Letter", "Legal", "Tabloid" (default `"A4"`)
- `orientation`: one of "portrait", "landscape" (default `"portrait"`)
- `margin`: *insets* (default `{"top":48,"right":48,"bottom":48,"left":48}`). Around each page's content (its header and footer too), in px: 96 to the inch.
- `title`: text. The document's title (shown in a browser tab, and by some email clients).
- `lang`: text. Its language, as a BCP 47 tag ("en", "ar").
- `dir`: one of "ltr", "rtl", "auto"
- `fonts`: *fontFaces*. The font files the template loads: a family's file for each weight and style it uses. Text names a family in its fontFamily stack, before the fonts to show where it can't load.

`style`:
- `color`: *color* (default `"#000000"`, inherited)
- `fontFamily`: *fontFamily* (default `"Arial, Helvetica, sans-serif"`, inherited)
- `fontSize`: a length (a number of px) (default `16`, inherited)
- `fontWeight`: *fontWeight* (default `400`, inherited)
- `fontStyle`: one of "normal", "italic" (inherited)
- `lineHeight`: *lineHeight* (default `1.5`, inherited)
- `letterSpacing`: a length (a number of px) (inherited)
- `textAlign`: one of "left", "center", "right", "justify" (default `"left"`, inherited)
- `textTransform`: one of "none", "uppercase", "lowercase", "capitalize" (inherited)
- `backgroundColor`: *color*. Each page's background, out to its edges.
- `gap`: a length (a number of px). Space between children.
- `alignItems`: one of "start", "center", "end", "stretch". Where children sit across the layout's direction (vertically in a Row, horizontally in a Column), as CSS align-items. Across a Column it places what has its own size (a Button, an Image, an Svg, a box with a width); a block of text fills the width, so its words move with its textAlign.

`mobile` (on phones): `fontSize`, `lineHeight`, `letterSpacing`, `textAlign`, `gap`.

## Canvas

Source: https://hyperelements.dev/docs/components/canvas

An image of a fixed size (a social card, a banner): its children laid out in it as on a page. Written as PNG or SVG with @hyper-elements/react/image.

Holds: Section, Row, Column, Grid, Layer, Svg, Text, Heading, Link, Button, Image, Divider, List, Table, Video, Social, Menu, Html. Drawn in: page.

Props:
- `width`: a length (a number of px) (default `1200`). The image's width, in px.
- `height`: a length (a number of px) (default `630`). The image's height, in px: what's past it is cut.
- `title`: text. The document's title (shown in a browser tab, and by some email clients).
- `lang`: text. Its language, as a BCP 47 tag ("en", "ar").
- `dir`: one of "ltr", "rtl", "auto"
- `fonts`: *fontFaces*. The font files the template loads: a family's file for each weight and style it uses. Text names a family in its fontFamily stack, before the fonts to show where it can't load.

`style`:
- `color`: *color* (default `"#000000"`, inherited)
- `fontFamily`: *fontFamily* (default `"Arial, Helvetica, sans-serif"`, inherited)
- `fontSize`: a length (a number of px) (default `16`, inherited)
- `fontWeight`: *fontWeight* (default `400`, inherited)
- `fontStyle`: one of "normal", "italic" (inherited)
- `lineHeight`: *lineHeight* (default `1.5`, inherited)
- `letterSpacing`: a length (a number of px) (inherited)
- `textAlign`: one of "left", "center", "right", "justify" (default `"left"`, inherited)
- `textTransform`: one of "none", "uppercase", "lowercase", "capitalize" (inherited)
- `backgroundColor`: *color*. The window's background, behind the content.
- `gap`: a length (a number of px). Space between children.
- `alignItems`: one of "start", "center", "end", "stretch". Where children sit across the layout's direction (vertically in a Row, horizontally in a Column), as CSS align-items. Across a Column it places what has its own size (a Button, an Image, an Svg, a box with a width); a block of text fills the width, so its words move with its textAlign.
- `padding`: *insets*
- `justifyContent`: one of "start", "center", "end", "space-between". Where children sit along the layout's direction, as CSS justify-content.

`mobile` (on phones): `fontSize`, `lineHeight`, `letterSpacing`, `textAlign`, `gap`, `padding`.

## Section

Source: https://hyperelements.dev/docs/components/section

A band across the whole window, directly in an Email or Page: its background spans the window, its children are stacked at the content width.

Holds: Row, Column, Grid, Layer, Svg, Text, Heading, Link, Button, Image, Divider, List, Table, Video, Social, Menu, Html. Drawn in: email, page.

`style`:
- `color`: *color* (inherited)
- `fontFamily`: *fontFamily* (inherited)
- `fontSize`: a length (a number of px) (inherited)
- `fontWeight`: *fontWeight* (inherited)
- `fontStyle`: one of "normal", "italic" (inherited)
- `lineHeight`: *lineHeight* (inherited)
- `letterSpacing`: a length (a number of px) (inherited)
- `textAlign`: one of "left", "center", "right", "justify" (inherited)
- `textTransform`: one of "none", "uppercase", "lowercase", "capitalize" (inherited)
- `backgroundColor`: *color*
- `padding`: *insets*
- `border`: *border*
- `gap`: a length (a number of px). Space between children.
- `alignItems`: one of "start", "center", "end", "stretch". Where children sit across the layout's direction (vertically in a Row, horizontally in a Column), as CSS align-items. Across a Column it places what has its own size (a Button, an Image, an Svg, a box with a width); a block of text fills the width, so its words move with its textAlign.

`mobile` (on phones): `fontSize`, `lineHeight`, `letterSpacing`, `textAlign`, `padding`, `border`, `gap`.

## Row

Source: https://hyperelements.dev/docs/components/row

Lays its children out side by side. A child takes its width, or a share of what's left (its flex, 1 by default).

Holds: Row, Column, Grid, Layer, Svg, Text, Heading, Link, Button, Image, Divider, List, Table, Video, Social, Menu, Html. Drawn in: email, page.

Props:
- `stackOnMobile`: true or false (default `true`). Its children stack full-width on phones (in an Email or a Page).
- `dir`: one of "ltr", "rtl", "auto". Its text's direction, where it differs from the template's; it starts on that side unless aligned otherwise.

`style`:
- `color`: *color* (inherited)
- `fontFamily`: *fontFamily* (inherited)
- `fontSize`: a length (a number of px) (inherited)
- `fontWeight`: *fontWeight* (inherited)
- `fontStyle`: one of "normal", "italic" (inherited)
- `lineHeight`: *lineHeight* (inherited)
- `letterSpacing`: a length (a number of px) (inherited)
- `textAlign`: one of "left", "center", "right", "justify" (inherited)
- `textTransform`: one of "none", "uppercase", "lowercase", "capitalize" (inherited)
- `width`: a length (a number of px, %)
- `minWidth`: a length (a number of px, %)
- `maxWidth`: a length (a number of px, %)
- `height`: a length (a number of px)
- `padding`: *insets*
- `backgroundColor`: *color*
- `border`: *border*
- `borderRadius`: *radius*
- `overflow`: one of "visible", "hidden". Whether content past a set height is cut off.
- `gap`: a length (a number of px). Space between children.
- `alignItems`: one of "start", "center", "end", "stretch". Where children sit across the layout's direction (vertically in a Row, horizontally in a Column), as CSS align-items. Across a Column it places what has its own size (a Button, an Image, an Svg, a box with a width); a block of text fills the width, so its words move with its textAlign.
- `justifyContent`: one of "start", "center", "end", "space-between". Where children sit along the layout's direction, as CSS justify-content.
- `flexWrap`: one of "nowrap", "wrap", "words". "wrap": children that don't fit wrap onto another line, as CSS flex-wrap (in an email, in a Row kept side by side on phones, with no gap between the lines). "words": in an email, also a space of the text's font apart, on lines at least as tall as its, as words are.
- `flex`: *flex*. In a Row: its share of the width left after children with a width (default 1); "none" takes its own size.

`mobile` (on phones): `fontSize`, `lineHeight`, `letterSpacing`, `textAlign`, `width`, `maxWidth`, `padding`, `border`, `gap`.

## Column

Source: https://hyperelements.dev/docs/components/column

Stacks its children vertically, with its own spacing and box.

Holds: Row, Column, Grid, Layer, Svg, Text, Heading, Link, Button, Image, Divider, List, Table, Video, Social, Menu, Html. Drawn in: email, page.

`style`:
- `color`: *color* (inherited)
- `fontFamily`: *fontFamily* (inherited)
- `fontSize`: a length (a number of px) (inherited)
- `fontWeight`: *fontWeight* (inherited)
- `fontStyle`: one of "normal", "italic" (inherited)
- `lineHeight`: *lineHeight* (inherited)
- `letterSpacing`: a length (a number of px) (inherited)
- `textAlign`: one of "left", "center", "right", "justify" (inherited)
- `textTransform`: one of "none", "uppercase", "lowercase", "capitalize" (inherited)
- `width`: a length (a number of px, %)
- `minWidth`: a length (a number of px, %)
- `maxWidth`: a length (a number of px, %)
- `height`: a length (a number of px)
- `padding`: *insets*
- `backgroundColor`: *color*
- `border`: *border*
- `borderRadius`: *radius*
- `overflow`: one of "visible", "hidden". Whether content past a set height is cut off.
- `gap`: a length (a number of px). Space between children.
- `alignItems`: one of "start", "center", "end", "stretch". Where children sit across the layout's direction (vertically in a Row, horizontally in a Column), as CSS align-items. Across a Column it places what has its own size (a Button, an Image, an Svg, a box with a width); a block of text fills the width, so its words move with its textAlign.
- `justifyContent`: one of "start", "center", "end", "space-between". Where children sit along the layout's direction, as CSS justify-content.
- `flex`: *flex*. In a Row: its share of the width left after children with a width (default 1); "none" takes its own size.

`mobile` (on phones): `fontSize`, `lineHeight`, `letterSpacing`, `textAlign`, `width`, `maxWidth`, `padding`, `border`, `gap`.

## Grid

Source: https://hyperelements.dev/docs/components/grid

Its children in columns of equal width, row after row; on phones, one under another.

Holds: Row, Column, Grid, Layer, Svg, Text, Heading, Link, Button, Image, Divider, List, Table, Video, Social, Menu, Html. Drawn in: email, page.

Props:
- `columns`: an integer from 1 to 12 (default `2`). How many children to a row.
- `stackOnMobile`: true or false (default `true`). Its children one under another on phones (in an Email or a Page).

`style`:
- `color`: *color* (inherited)
- `fontFamily`: *fontFamily* (inherited)
- `fontSize`: a length (a number of px) (inherited)
- `fontWeight`: *fontWeight* (inherited)
- `fontStyle`: one of "normal", "italic" (inherited)
- `lineHeight`: *lineHeight* (inherited)
- `letterSpacing`: a length (a number of px) (inherited)
- `textAlign`: one of "left", "center", "right", "justify" (inherited)
- `textTransform`: one of "none", "uppercase", "lowercase", "capitalize" (inherited)
- `width`: a length (a number of px, %)
- `minWidth`: a length (a number of px, %)
- `maxWidth`: a length (a number of px, %)
- `height`: a length (a number of px)
- `padding`: *insets*
- `backgroundColor`: *color*
- `border`: *border*
- `borderRadius`: *radius*
- `overflow`: one of "visible", "hidden". Whether content past a set height is cut off.
- `gap`: a length (a number of px). Space between its children, across and down (unless rowGap is set).
- `rowGap`: a length (a number of px). Space between its rows (gap by default); on phones, where the children stack, gap is between them.
- `alignItems`: one of "start", "center", "end", "stretch". Where each child sits in its row's height, as CSS align-items.
- `flex`: *flex*. In a Row: its share of the width left after children with a width (default 1); "none" takes its own size.

`mobile` (on phones): `fontSize`, `lineHeight`, `letterSpacing`, `textAlign`, `width`, `maxWidth`, `padding`, `border`, `gap`, `rowGap`.

## Layer

Source: https://hyperelements.dev/docs/components/layer

Its children over each other, in one box as tall as the tallest: an image with words on it. In an email, an Image with one child over it.

Holds: Row, Column, Grid, Layer, Svg, Text, Heading, Link, Button, Image, Divider, List, Table, Video, Social, Menu, Html. Drawn in: email, page.

`style`:
- `color`: *color* (inherited)
- `fontFamily`: *fontFamily* (inherited)
- `fontSize`: a length (a number of px) (inherited)
- `fontWeight`: *fontWeight* (inherited)
- `fontStyle`: one of "normal", "italic" (inherited)
- `lineHeight`: *lineHeight* (inherited)
- `letterSpacing`: a length (a number of px) (inherited)
- `textAlign`: one of "left", "center", "right", "justify" (inherited)
- `textTransform`: one of "none", "uppercase", "lowercase", "capitalize" (inherited)
- `width`: a length (a number of px, %)
- `minWidth`: a length (a number of px, %)
- `maxWidth`: a length (a number of px, %)
- `backgroundColor`: *color*
- `border`: *border*
- `borderRadius`: *radius*
- `height`: a length (a number of px). Its height: the image under its children covers it, cut at its sides or its top and bottom.
- `alignItems`: one of "start", "center", "end", "stretch" (default `"start"`). Where its children sit in its height, as CSS align-items.
- `justifyItems`: one of "start", "center", "end", "stretch" (default `"stretch"`). Where its children sit across its width, as CSS justify-items: stretched to it by default.
- `flex`: *flex*. In a Row: its share of the width left after children with a width (default 1); "none" takes its own size.

`mobile` (on phones): `fontSize`, `lineHeight`, `letterSpacing`, `textAlign`, `width`, `maxWidth`, `border`.

## Svg

Source: https://hyperelements.dev/docs/components/svg

Shapes (Rect, Circle, Ellipse, Line, Polygon, Path) drawn in a box of its own: its width and height, and the coordinates its viewBox gives them.

Holds: Rect, Circle, Ellipse, Line, Polygon, Path. Drawn in: page.

Props:
- `width`: a number from 0 (required)
- `height`: a number from 0 (required)
- `viewBox`: text. The shapes' coordinates in it, as "x y width height" (its width and height by default).
- `title`: text. What it shows, read out by screen readers.

`style`:
- `padding`: *insets*
- `backgroundColor`: *color*
- `border`: *border*
- `borderRadius`: *radius*
- `flex`: *flex*. In a Row: its share of the width left after children with a width (default 1); "none" takes its own size.

`mobile` (on phones): `padding`, `border`.

## Text

Source: https://hyperelements.dev/docs/components/text

A paragraph of text.

Holds: text; PageNumber, Span, Link, LineBreak, MergeTag, Image. Drawn in: email, page.

Props:
- `dir`: one of "ltr", "rtl", "auto". Its text's direction, where it differs from the template's; it starts on that side unless aligned otherwise.

`style`:
- `color`: *color* (inherited)
- `fontFamily`: *fontFamily* (inherited)
- `fontSize`: a length (a number of px) (inherited)
- `fontWeight`: *fontWeight* (inherited)
- `fontStyle`: one of "normal", "italic" (inherited)
- `lineHeight`: *lineHeight* (inherited)
- `letterSpacing`: a length (a number of px) (inherited)
- `textAlign`: one of "left", "center", "right", "justify" (inherited)
- `textTransform`: one of "none", "uppercase", "lowercase", "capitalize" (inherited)
- `textDecoration`: one of "none", "underline", "line-through"
- `width`: a length (a number of px, %)
- `maxWidth`: a length (a number of px, %)
- `padding`: *insets*
- `backgroundColor`: *color*
- `border`: *border*
- `borderRadius`: *radius*
- `flex`: *flex*. In a Row: its share of the width left after children with a width (default 1); "none" takes its own size.

`mobile` (on phones): `fontSize`, `lineHeight`, `letterSpacing`, `textAlign`, `width`, `maxWidth`, `padding`, `border`.

## Heading

Source: https://hyperelements.dev/docs/components/heading

A heading, from level 1 (the page's title) to 6.

Holds: text; PageNumber, Span, Link, LineBreak, MergeTag. Drawn in: email, page.

Props:
- `level`: one of 1, 2, 3, 4, 5, 6 (default `1`)
- `dir`: one of "ltr", "rtl", "auto". Its text's direction, where it differs from the template's; it starts on that side unless aligned otherwise.

`style`:
- `color`: *color* (inherited)
- `fontFamily`: *fontFamily* (inherited)
- `fontSize`: a length (a number of px) (inherited)
- `fontWeight`: *fontWeight* (default `700`, inherited)
- `fontStyle`: one of "normal", "italic" (inherited)
- `lineHeight`: *lineHeight* (default `1.25`, inherited)
- `letterSpacing`: a length (a number of px) (inherited)
- `textAlign`: one of "left", "center", "right", "justify" (inherited)
- `textTransform`: one of "none", "uppercase", "lowercase", "capitalize" (inherited)
- `textDecoration`: one of "none", "underline", "line-through"
- `width`: a length (a number of px, %)
- `maxWidth`: a length (a number of px, %)
- `padding`: *insets*
- `backgroundColor`: *color*
- `border`: *border*
- `borderRadius`: *radius*
- `flex`: *flex*. In a Row: its share of the width left after children with a width (default 1); "none" takes its own size.

`mobile` (on phones): `fontSize`, `lineHeight`, `letterSpacing`, `textAlign`, `width`, `maxWidth`, `padding`, `border`.

## Button

Source: https://hyperelements.dev/docs/components/button

A link drawn as a button.

Holds: text; Span, MergeTag, LineBreak. Drawn in: email, page.

Props:
- `href`: *link* (required)
- `title`: text. Shown as a tooltip by mail clients and browsers that show one.
- `aria-label`: text. What a screen reader says for it, where its text alone doesn't say enough ("Read more about pricing").
- `attrs`: *attributes*. More attributes for its link: a class, a `data-` attribute.

`style`:
- `color`: *color* (default `"#ffffff"`, inherited)
- `fontFamily`: *fontFamily* (inherited)
- `fontSize`: a length (a number of px) (default `14`, inherited)
- `fontWeight`: *fontWeight* (inherited)
- `fontStyle`: one of "normal", "italic" (inherited)
- `lineHeight`: *lineHeight* (default `1.2`, inherited)
- `letterSpacing`: a length (a number of px) (inherited)
- `textAlign`: one of "left", "center", "right", "justify" (default `"center"`, inherited)
- `textTransform`: one of "none", "uppercase", "lowercase", "capitalize" (inherited)
- `textDecoration`: one of "none", "underline", "line-through"
- `width`: a length (a number of px, %)
- `maxWidth`: a length (a number of px, %)
- `padding`: *insets* (default `{"top":10,"right":20,"bottom":10,"left":20}`)
- `backgroundColor`: *color* (default `"#0879a1"`)
- `border`: *border*
- `borderRadius`: *radius* (default `4`)
- `boxSizing`: one of "border-box", "content-box". Whether its width holds its padding and border (border-box), or they go on top of it (content-box).
- `alignSelf`: one of "start", "center", "end". Where it sits in its stack, whatever the stack's alignItems: on phones too, another place than on desktop.
- `flex`: *flex*. In a Row: its share of the width left after children with a width (default 1); "none" takes its own size.

`hover`: `color`, `backgroundColor`.

`mobile` (on phones): `fontSize`, `lineHeight`, `letterSpacing`, `textAlign`, `width`, `maxWidth`, `padding`, `border`, `alignSelf`.

## Image

Source: https://hyperelements.dev/docs/components/image

An image in the content. Without a width it takes its own size, no wider than its parent.

Holds: nothing. Drawn in: email, page.

Props:
- `src`: *asset* (required)
- `alt`: text (default `""`). Read out by screen readers, and shown where images don't load.
- `title`: text. Shown as a tooltip by mail clients and browsers that show one.

`style`:
- `width`: a length (a number of px, %)
- `maxWidth`: a length (a number of px, %)
- `height`: a length (a number of px)
- `border`: *border*
- `borderRadius`: *radius*
- `flex`: *flex*. In a Row: its share of the width left after children with a width (default 1); "none" takes its own size.
- `alignSelf`: one of "start", "center", "end". Where it sits in its stack on phones, where that's another place than on desktop.
- `verticalAlign`: one of "top", "middle". Where it sits in a line of text it's in.

`mobile` (on phones): `width`, `maxWidth`, `border`, `alignSelf`.

## Divider

Source: https://hyperelements.dev/docs/components/divider

A horizontal line.

Holds: nothing. Drawn in: email, page.

`style`:
- `borderTop`: *line* (default `{"width":1,"style":"solid","color":"#bbbbbb"}`). The line, as CSS border-top: "1px solid #bbbbbb".
- `width`: a length (a number of px, %) (default `"100%"`)
- `padding`: *insets*

`mobile` (on phones): `width`, `padding`.

## List

Source: https://hyperelements.dev/docs/components/list

A bulleted or numbered list of ListItems. Its markers sit in a column of their own (indent) before the items.

Holds: ListItem. Drawn in: email, page.

Props:
- `type`: one of "bullet", "number" (default `"bullet"`)
- `start`: an integer from 0 (default `1`). The first item's number, in a numbered list.

`style`:
- `color`: *color* (inherited)
- `fontFamily`: *fontFamily* (inherited)
- `fontSize`: a length (a number of px) (inherited)
- `fontWeight`: *fontWeight* (inherited)
- `fontStyle`: one of "normal", "italic" (inherited)
- `lineHeight`: *lineHeight* (inherited)
- `letterSpacing`: a length (a number of px) (inherited)
- `textAlign`: one of "left", "center", "right", "justify" (inherited)
- `textTransform`: one of "none", "uppercase", "lowercase", "capitalize" (inherited)
- `width`: a length (a number of px, %)
- `maxWidth`: a length (a number of px, %)
- `padding`: *insets*
- `backgroundColor`: *color*
- `border`: *border*
- `gap`: a length (a number of px). Space between items.
- `indent`: a length (a number of px) (default `24`). The width of the markers' column, before the items.
- `flex`: *flex*. In a Row: its share of the width left after children with a width (default 1); "none" takes its own size.

`mobile` (on phones): `fontSize`, `lineHeight`, `letterSpacing`, `textAlign`, `width`, `maxWidth`, `padding`, `border`, `gap`.

## Table

Source: https://hyperelements.dev/docs/components/table

A table of data: TableRows of TableCells. Columns take their cells' widths; the rest share what's left.

Holds: TableRow. Drawn in: email, page.

`style`:
- `color`: *color* (inherited)
- `fontFamily`: *fontFamily* (inherited)
- `fontSize`: a length (a number of px) (inherited)
- `fontWeight`: *fontWeight* (inherited)
- `fontStyle`: one of "normal", "italic" (inherited)
- `lineHeight`: *lineHeight* (inherited)
- `letterSpacing`: a length (a number of px) (inherited)
- `textAlign`: one of "left", "center", "right", "justify" (inherited)
- `textTransform`: one of "none", "uppercase", "lowercase", "capitalize" (inherited)
- `width`: a length (a number of px, %)
- `maxWidth`: a length (a number of px, %)
- `backgroundColor`: *color*
- `border`: *border*
- `cellPadding`: *insets*. Every cell's padding, where the cell doesn't set its own.
- `rowBorder`: *line*
- `borderCollapse`: one of "separate", "collapse". Whether cells side by side draw a border each (separate) or share one (collapse).
- `flex`: *flex*. In a Row: its share of the width left after children with a width (default 1); "none" takes its own size.

`mobile` (on phones): `fontSize`, `lineHeight`, `letterSpacing`, `textAlign`, `width`, `maxWidth`, `border`.

## Video

Source: https://hyperelements.dev/docs/components/video

A YouTube or Vimeo video: its player on a page; in an email (which can't play one), its thumbnail, linked to it.

Holds: nothing. Drawn in: email, page.

Props:
- `src`: *video* (required). The video's YouTube or Vimeo link.
- `thumbnail`: *asset*. The image an email shows, linked to the video. A YouTube video's own where there's none; a Vimeo video's can't be found without the network.
- `title`: text (default `"Video"`). The player's title on a page, the thumbnail's alternate text in an email.

`style`:
- `width`: a length (a number of px, %)
- `maxWidth`: a length (a number of px, %)
- `flex`: *flex*. In a Row: its share of the width left after children with a width (default 1); "none" takes its own size.

`mobile` (on phones): `width`, `maxWidth`.

## Social

Source: https://hyperelements.dev/docs/components/social

Links to social profiles: a line of the networks' icons, each linked to its profile.

Holds: nothing. Drawn in: email, page.

Props:
- `icons`: a list of icons, each { name, href } (required). Each network by name ("Instagram", "LinkedIn") and the link to its profile.
- `iconType`: one of "circle", "rounded", "squared" (default `"circle"`)
- `size`: an integer from 1 (default `32`). Each icon's width and height, in px.

`style`:
- `gap`: a length (a number of px) (default `5`). Space between children.
- `justifyContent`: one of "start", "center", "end" (default `"center"`). Where the icons sit across the line.
- `flex`: *flex*. In a Row: its share of the width left after children with a width (default 1); "none" takes its own size.

`mobile` (on phones): `gap`.

## Menu

Source: https://hyperelements.dev/docs/components/menu

A line of links (a site's sections, a footer's), onto more lines where they don't fit, with a separator between them on desktop; or links down a column.

Holds: nothing. Drawn in: email, page.

Props:
- `items`: a list of items, each { text, href } (required). Each link's text and where it goes.
- `separator`: text (default `""`). Between the links of a horizontal menu ("|", "·"), on desktop: phones show none.
- `layout`: one of "horizontal", "vertical" (default `"horizontal"`)

`style`:
- `color`: *color* (default `"#0068A5"`, inherited)
- `fontFamily`: *fontFamily* (inherited)
- `fontSize`: a length (a number of px) (default `14`, inherited)
- `fontWeight`: *fontWeight* (inherited)
- `lineHeight`: *lineHeight* (default `1.2`, inherited)
- `letterSpacing`: a length (a number of px) (inherited)
- `textTransform`: one of "none", "uppercase", "lowercase", "capitalize" (inherited)
- `separatorColor`: *color* (default `"#444444"`)
- `padding`: *insets* (default `{"top":5,"right":15,"bottom":5,"left":15}`). Around each link: its sides are the space between them.
- `justifyContent`: one of "start", "center", "end" (default `"center"`). Where the links sit.
- `flex`: *flex*. In a Row: its share of the width left after children with a width (default 1); "none" takes its own size.

`mobile` (on phones): `fontSize`, `lineHeight`, `letterSpacing`.

## Html

Source: https://hyperelements.dev/docs/components/html

Markup written as it is, for what no component says (the builder's HTML block): in an email and on a page as given, nothing in it checked or escaped. A Document's PDF and a Canvas's image draw its plain text.

Holds: nothing. Drawn in: email, page.

Props:
- `html`: text (required). The markup, written as it is: only markup you trust. Or give it as JSX inside the block, which React writes.
- `text`: text. What it reads as in the plain-text version, and in a PDF or an image (its markup's words where there's none).

## PageNumber

Source: https://hyperelements.dev/docs/components/pagenumber

In a Document's text: the number of the page it's on, or (total) how many pages there are.

Holds: nothing. Drawn in: page.

Props:
- `total`: true or false (default `false`). How many pages the Document has, instead of this page's number.

## Span

Source: https://hyperelements.dev/docs/components/span

Styled text inside text; raised or lowered (superscript, subscript) with verticalAlign.

Holds: text; PageNumber, Span, Link, LineBreak, MergeTag. Drawn in: email, page.

`style`:
- `color`: *color* (inherited)
- `fontFamily`: *fontFamily* (inherited)
- `fontSize`: a length (a number of px) (inherited)
- `fontWeight`: *fontWeight* (inherited)
- `fontStyle`: one of "normal", "italic" (inherited)
- `letterSpacing`: a length (a number of px) (inherited)
- `textTransform`: one of "none", "uppercase", "lowercase", "capitalize" (inherited)
- `textDecoration`: one of "none", "underline", "line-through"
- `backgroundColor`: *color*
- `verticalAlign`: one of "baseline", "super", "sub". "super": superscript (®, a footnote mark); "sub": subscript; as CSS vertical-align.

`mobile` (on phones): `fontSize`, `letterSpacing`.

## Link

Source: https://hyperelements.dev/docs/components/link

A link: text inside text, or around an Image.

Holds: text; PageNumber, Span, Link, LineBreak, MergeTag, Image. Drawn in: email, page.

Props:
- `href`: *link* (required)
- `title`: text. Shown as a tooltip by mail clients and browsers that show one.
- `aria-label`: text. What a screen reader says for it, where its text alone doesn't say enough ("Read more about pricing").
- `attrs`: *attributes*. More attributes for it: a class, a `data-` attribute.

`style`:
- `color`: *color* (default `"#0000ee"`, inherited)
- `fontFamily`: *fontFamily* (inherited)
- `fontSize`: a length (a number of px) (inherited)
- `fontWeight`: *fontWeight* (inherited)
- `fontStyle`: one of "normal", "italic" (inherited)
- `letterSpacing`: a length (a number of px) (inherited)
- `textTransform`: one of "none", "uppercase", "lowercase", "capitalize" (inherited)
- `textDecoration`: one of "none", "underline", "line-through" (default `"underline"`)
- `backgroundColor`: *color*
- `flex`: *flex*. In a Row: its share of the width left after children with a width (default 1); "none" takes its own size.

`hover`: `color`, `textDecoration`, `backgroundColor`.

`mobile` (on phones): `fontSize`, `letterSpacing`.

## LineBreak

Source: https://hyperelements.dev/docs/components/linebreak

Starts a new line inside text.

Holds: nothing. Drawn in: email, page.

## MergeTag

Source: https://hyperelements.dev/docs/components/mergetag

A value the sending service fills in (a name, a link), written in the service's own syntax.

Holds: nothing. Drawn in: email, page.

Props:
- `name`: text (required)

## Document.Page

Source: https://hyperelements.dev/docs/components/document-page

One page of a Document (Document.Page in JSX): its children stacked down it, inside the Document's margins.

Holds: Section, Row, Column, Grid, Layer, Svg, Text, Heading, Link, Button, Image, Divider, List, Table, Video, Social, Menu, Html. Drawn in: page.

`style`:
- `color`: *color* (inherited)
- `fontFamily`: *fontFamily* (inherited)
- `fontSize`: a length (a number of px) (inherited)
- `fontWeight`: *fontWeight* (inherited)
- `fontStyle`: one of "normal", "italic" (inherited)
- `lineHeight`: *lineHeight* (inherited)
- `letterSpacing`: a length (a number of px) (inherited)
- `textAlign`: one of "left", "center", "right", "justify" (inherited)
- `textTransform`: one of "none", "uppercase", "lowercase", "capitalize" (inherited)
- `backgroundColor`: *color*. The page's background, out to its edges.
- `gap`: a length (a number of px). Space between children.
- `alignItems`: one of "start", "center", "end", "stretch". Where children sit across the layout's direction (vertically in a Row, horizontally in a Column), as CSS align-items. Across a Column it places what has its own size (a Button, an Image, an Svg, a box with a width); a block of text fills the width, so its words move with its textAlign.

`mobile` (on phones): `fontSize`, `lineHeight`, `letterSpacing`, `textAlign`, `gap`.

## PageBreak

Source: https://hyperelements.dev/docs/components/pagebreak

In a Document, where a page ends: what follows starts the next page.

Holds: nothing. Drawn in: page.

## PageHeader

Source: https://hyperelements.dev/docs/components/pageheader

In a Document: drawn at the top of every page, inside its margins.

Holds: Row, Column, Grid, Layer, Svg, Text, Heading, Link, Button, Image, Divider, List, Table, Video, Social, Menu, Html. Drawn in: page.

`style`:
- `color`: *color* (inherited)
- `fontFamily`: *fontFamily* (inherited)
- `fontSize`: a length (a number of px) (inherited)
- `fontWeight`: *fontWeight* (inherited)
- `fontStyle`: one of "normal", "italic" (inherited)
- `lineHeight`: *lineHeight* (inherited)
- `letterSpacing`: a length (a number of px) (inherited)
- `textAlign`: one of "left", "center", "right", "justify" (inherited)
- `textTransform`: one of "none", "uppercase", "lowercase", "capitalize" (inherited)
- `padding`: *insets*
- `backgroundColor`: *color*
- `border`: *border*
- `gap`: a length (a number of px). Space between children.
- `alignItems`: one of "start", "center", "end", "stretch". Where children sit across the layout's direction (vertically in a Row, horizontally in a Column), as CSS align-items. Across a Column it places what has its own size (a Button, an Image, an Svg, a box with a width); a block of text fills the width, so its words move with its textAlign.

`mobile` (on phones): `fontSize`, `lineHeight`, `letterSpacing`, `textAlign`, `padding`, `border`, `gap`.

## PageFooter

Source: https://hyperelements.dev/docs/components/pagefooter

In a Document: drawn at the bottom of every page, inside its margins.

Holds: Row, Column, Grid, Layer, Svg, Text, Heading, Link, Button, Image, Divider, List, Table, Video, Social, Menu, Html. Drawn in: page.

`style`:
- `color`: *color* (inherited)
- `fontFamily`: *fontFamily* (inherited)
- `fontSize`: a length (a number of px) (inherited)
- `fontWeight`: *fontWeight* (inherited)
- `fontStyle`: one of "normal", "italic" (inherited)
- `lineHeight`: *lineHeight* (inherited)
- `letterSpacing`: a length (a number of px) (inherited)
- `textAlign`: one of "left", "center", "right", "justify" (inherited)
- `textTransform`: one of "none", "uppercase", "lowercase", "capitalize" (inherited)
- `padding`: *insets*
- `backgroundColor`: *color*
- `border`: *border*
- `gap`: a length (a number of px). Space between children.
- `alignItems`: one of "start", "center", "end", "stretch". Where children sit across the layout's direction (vertically in a Row, horizontally in a Column), as CSS align-items. Across a Column it places what has its own size (a Button, an Image, an Svg, a box with a width); a block of text fills the width, so its words move with its textAlign.

`mobile` (on phones): `fontSize`, `lineHeight`, `letterSpacing`, `textAlign`, `padding`, `border`, `gap`.

## ListItem

Source: https://hyperelements.dev/docs/components/listitem

An item of a List: text, and a List of its own to nest one.

Holds: text; PageNumber, Span, Link, LineBreak, MergeTag, List. Drawn in: email, page.

Props:
- `dir`: one of "ltr", "rtl", "auto". Its text's direction, where it differs from the template's; it starts on that side unless aligned otherwise.

`style`:
- `color`: *color* (inherited)
- `fontFamily`: *fontFamily* (inherited)
- `fontSize`: a length (a number of px) (inherited)
- `fontWeight`: *fontWeight* (inherited)
- `fontStyle`: one of "normal", "italic" (inherited)
- `lineHeight`: *lineHeight* (inherited)
- `letterSpacing`: a length (a number of px) (inherited)
- `textAlign`: one of "left", "center", "right", "justify" (inherited)
- `textTransform`: one of "none", "uppercase", "lowercase", "capitalize" (inherited)
- `textDecoration`: one of "none", "underline", "line-through"

`mobile` (on phones): `fontSize`, `lineHeight`, `letterSpacing`, `textAlign`.

## TableRow

Source: https://hyperelements.dev/docs/components/tablerow

A row of a Table. A header row's cells are header cells, in bold.

Holds: TableCell. Drawn in: email, page.

Props:
- `header`: true or false (default `false`). Its cells head the columns below them.
- `footer`: true or false (default `false`). It ends the table (printed, on each page the table runs to).

`style`:
- `color`: *color* (inherited)
- `fontFamily`: *fontFamily* (inherited)
- `fontSize`: a length (a number of px) (inherited)
- `fontWeight`: *fontWeight* (inherited)
- `fontStyle`: one of "normal", "italic" (inherited)
- `lineHeight`: *lineHeight* (inherited)
- `letterSpacing`: a length (a number of px) (inherited)
- `textAlign`: one of "left", "center", "right", "justify" (inherited)
- `textTransform`: one of "none", "uppercase", "lowercase", "capitalize" (inherited)
- `backgroundColor`: *color*
- `height`: a length (a number of px)

`mobile` (on phones): `fontSize`, `lineHeight`, `letterSpacing`, `textAlign`.

## TableCell

Source: https://hyperelements.dev/docs/components/tablecell

A cell of a TableRow: text, and images. Its width sets its column's.

Holds: text; PageNumber, Span, Link, LineBreak, MergeTag, Image. Drawn in: email, page.

Props:
- `colSpan`: an integer from 1 (default `1`). How many columns it spans.
- `dir`: one of "ltr", "rtl", "auto". Its text's direction, where it differs from the template's; it starts on that side unless aligned otherwise.

`style`:
- `color`: *color* (inherited)
- `fontFamily`: *fontFamily* (inherited)
- `fontSize`: a length (a number of px) (inherited)
- `fontWeight`: *fontWeight* (inherited)
- `fontStyle`: one of "normal", "italic" (inherited)
- `lineHeight`: *lineHeight* (inherited)
- `letterSpacing`: a length (a number of px) (inherited)
- `textAlign`: one of "left", "center", "right", "justify" (inherited)
- `textTransform`: one of "none", "uppercase", "lowercase", "capitalize" (inherited)
- `textDecoration`: one of "none", "underline", "line-through"
- `padding`: *insets*
- `backgroundColor`: *color*
- `border`: *border*
- `width`: a length (a number of px, %). Its column's width (of a cell spanning one column).
- `verticalAlign`: one of "top", "middle", "bottom"

`mobile` (on phones): `fontSize`, `lineHeight`, `letterSpacing`, `textAlign`, `padding`, `border`.

## Rect

Source: https://hyperelements.dev/docs/components/rect

A rectangle at x, y in its Svg, rounded by rx.

Holds: nothing. Drawn in: page.

Props:
- `x`: a number (default `0`)
- `y`: a number (default `0`)
- `width`: a number from 0 (required)
- `height`: a number from 0 (required)
- `rx`: a number from 0

`style`:
- `fill`: *color* (default `"#000000"`). Its inside ("transparent" for none).
- `stroke`: *color*. Its outline's color.
- `strokeWidth`: a number from 0
- `opacity`: a number from 0 to 1

## Circle

Source: https://hyperelements.dev/docs/components/circle

A circle centered at cx, cy in its Svg.

Holds: nothing. Drawn in: page.

Props:
- `cx`: a number (default `0`)
- `cy`: a number (default `0`)
- `r`: a number from 0 (required)

`style`:
- `fill`: *color* (default `"#000000"`). Its inside ("transparent" for none).
- `stroke`: *color*. Its outline's color.
- `strokeWidth`: a number from 0
- `opacity`: a number from 0 to 1

## Ellipse

Source: https://hyperelements.dev/docs/components/ellipse

An ellipse centered at cx, cy in its Svg.

Holds: nothing. Drawn in: page.

Props:
- `cx`: a number (default `0`)
- `cy`: a number (default `0`)
- `rx`: a number from 0 (required)
- `ry`: a number from 0 (required)

`style`:
- `fill`: *color* (default `"#000000"`). Its inside ("transparent" for none).
- `stroke`: *color*. Its outline's color.
- `strokeWidth`: a number from 0
- `opacity`: a number from 0 to 1

## Line

Source: https://hyperelements.dev/docs/components/line

A straight line from x1, y1 to x2, y2 in its Svg (drawn by its stroke).

Holds: nothing. Drawn in: page.

Props:
- `x1`: a number (default `0`)
- `y1`: a number (default `0`)
- `x2`: a number (default `0`)
- `y2`: a number (default `0`)

`style`:
- `fill`: *color* (default `"#000000"`). Its inside ("transparent" for none).
- `stroke`: *color*. Its outline's color.
- `strokeWidth`: a number from 0
- `opacity`: a number from 0 to 1

## Polygon

Source: https://hyperelements.dev/docs/components/polygon

A closed shape through its points ("0,0 40,0 20,30"), in its Svg.

Holds: nothing. Drawn in: page.

Props:
- `points`: text (required)

`style`:
- `fill`: *color* (default `"#000000"`). Its inside ("transparent" for none).
- `stroke`: *color*. Its outline's color.
- `strokeWidth`: a number from 0
- `opacity`: a number from 0 to 1

## Path

Source: https://hyperelements.dev/docs/components/path

A shape drawn by an SVG path (d), in its Svg.

Holds: nothing. Drawn in: page.

Props:
- `d`: text (required). SVG path data ("M0 0 L40 0 L20 30 Z").

`style`:
- `fill`: *color* (default `"#000000"`). Its inside ("transparent" for none).
- `stroke`: *color*. Its outline's color.
- `strokeWidth`: a number from 0
- `opacity`: a number from 0 to 1