@hyper-elements/react
v0.4.8
Published
React components for transactional emails, landing pages, invoices and PDFs: email-safe HTML, responsive web HTML, and print-ready PDF HTML from one component tree.
Readme
@hyper-elements/react
React components for transactional emails, email templates, landing pages, invoices, reports and documents. One template renders to email-safe HTML, a responsive web page, print-ready HTML, a PDF or an image, on your own server, with no network calls.
Installation
npm install @hyper-elements/react
# or
pnpm add @hyper-elements/reactQuick start
Import from @hyper-elements/react. A template has one root, its styles go in style={{ }}, and the space between blocks is their parent's gap.
import { Button, Column, defineTheme, Email, Heading, Image, Link, List, ListItem, MergeTag, Text, Row, Span, Table, TableCell, TableRow, token } from "@hyper-elements/react";
// The brand, once: every Email, Page, Document and Canvas that takes it is on brand.
const acme = defineTheme({
colors: { background: "#f4f4f5", foreground: "#18181b", primary: "#111827", primaryForeground: "#ffffff", muted: "#71717a", border: "#e4e4e7" },
fonts: { body: "Inter, Arial, sans-serif" },
elements: {
Heading: { by: { level: { 1: { fontSize: 24, mobile: { fontSize: 20 } } } } },
Button: { borderRadius: 6, hover: { backgroundColor: "#374151" } },
},
styles: { card: { backgroundColor: "#ffffff", padding: 32, gap: 16, borderRadius: 8 } },
});
export default function Receipt() {
return (
<Email theme={acme} previewText="Your Acme receipt" style={{ gap: 16 }}>
<Image src={{ src: "https://example.com/logo.png", width: 240, height: 80 }} alt="Acme" style={{ width: 120 }} />
<Column style={{ apply: ["card"] }}>
<Heading level={1}>
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: { width: 1, style: "solid", color: token("colors.border") } }}>
<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">View your order</Button>
</Column>
<Text style={{ fontSize: 12, color: token("colors.muted"), textAlign: "center" }}>Acme Inc., 1 Market St, San Francisco</Text>
</Email>
);
}import { outline, render, validate } from "@hyper-elements/react";
const { html, text, diagnostics } = await render(<Receipt />); // warnings in diagnostics; errors throw an ElementsError
const { valid } = validate(<Receipt />); // the same checks, without rendering
console.log(outline(<Receipt />)); // the laid-out template as text: each block, its width, its wordsTo write a template, read GUIDE.md: how a template is written, and every element on a line. REFERENCE.md has every prop and style in full. Both are written from the elements' definitions.
Upgrading from Unlayer Elements? See Moving from Unlayer Elements.
Using with an AI agent
With an AI agent: in Claude Code, add this line to your project's CLAUDE.md, and every session starts out knowing these elements:
@node_modules/@hyper-elements/react/GUIDE.mdFor 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."
Or install the same guide as an agent skill: npx skills add hyper-elements/hyper-elements.
An agent that runs commands can check what it writes with npx hyper-elements check <file> --json (@hyper-elements/cli): one JSON line per template, with its diagnostics.
Structure
<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: space between blocks is their parent's gap, and space inside a box is its padding.
Elements
Roots
| Element | Renders to |
|-----------|-------------|
| <Email> | Email-safe HTML: tables, with Outlook's markup in conditional comments |
| <Page> | A responsive web page |
| <Document> | Print-ready HTML on pages of its size, and a PDF with @hyper-elements/react/pdf |
| <Canvas> | An image of a fixed size, with @hyper-elements/react/image |
Layout
| Element | Description |
|-----------|-------------|
| <Section> | A band across the whole window, directly in an Email or Page |
| <Row> | Its children side by side; stacked on phones |
| <Column> | Its children stacked, with its own spacing and box; with a background, a card |
| <Grid> | Its children in columns of equal width, row after row |
| <Layer> | Its children over each other: an image with words on it |
Content
| Element | Description |
|-----------|-------------|
| <Heading> | A heading, level 1 to 6 |
| <Text> | A block of text |
| <Span>, <Link>, <LineBreak>, <MergeTag> | Inside text: a styled run, a link, a new line, a value the sending service fills in |
| <Button> | A link drawn as a button, with its colors on hover |
| <Image> | An image; src has the file's size, style.width the size shown |
| <Divider> | A horizontal line |
| <List>, <ListItem> | A bulleted or numbered list |
| <Table>, <TableRow>, <TableCell> | A table of data |
| <Video> | A YouTube or Vimeo video: its player on a page, its linked thumbnail in an email |
| <Social> | A line of social network icons, each a link |
| <Menu> | A line or column of links |
| <Svg> and its shapes | Shapes drawn in a box of their own |
| <Html> | Markup written as it is, for what no element says |
| <PageBreak>, <PageHeader>, <PageFooter>, <PageNumber> | In a Document: where a page ends, what's on every page, and page numbers |
Columns
A Column in a Row takes its width, or a share of what's left.
import { Column, Grid, Row } from "@hyper-elements/react";
// 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>
// Side by side on phones too.
<Row stackOnMobile={false}>
<Column>{/* content */}</Column>
<Column>{/* content */}</Column>
</Row>
// Rows of three, one under another on phones.
<Grid columns={3} style={{ gap: 16 }}>
<Column>{/* content */}</Column>
<Column>{/* content */}</Column>
<Column>{/* content */}</Column>
</Grid>Rendering
const { html, text, head, body, bodyStyle, diagnostics } = await render(<Receipt />);htmlis the whole document, from<!DOCTYPE html>, with no React hydration markers and no client-side JavaScript.textis the plain-text version.head,bodyandbodyStyleare for embedding the output in a page of your own.diagnosticsholds warnings and notes. A template with errors throws anElementsError, whosediagnosticsgive each problem'scode,messageandpath.
The options are pretty (the HTML indented, for reading it), mergeTag (how a merge tag is written, by default {{name}}) and classPrefix (what every class name starts with, for HTML embedded where other CSS is).
validate() runs the same checks without rendering, and outline() prints the laid-out template, to check the layout without reading the HTML.
From the shell, @hyper-elements/cli does the same with no script: npx hyper-elements check emails/ validates each template (a module whose default export renders the root), npx hyper-elements render emails/ writes each one's HTML and plain text (a Document's PDF, a Canvas's PNG), and npx hyper-elements preview emails/welcome.tsx shows an Email in each email client (with @hyper-elements/email-clients). With --json they print one line per template, and they exit 1 when a template has errors.
One template, every output
Share the content, and give each output its root:
import { Button, Column, Document, Email, Heading, Page, Text, render } from "@hyper-elements/react";
const Invoice = () => (
<Column style={{ gap: 12 }}>
<Heading level={1} style={{ fontSize: 24 }}>Invoice 2705</Heading>
<Text>Thank you for your order.</Text>
<Button href="https://example.com/invoices/2705" style={{ backgroundColor: "#111827" }}>View it online</Button>
</Column>
);
const email = await render(<Email><Invoice /></Email>);
const page = await render(<Page><Invoice /></Page>);
const printed = await render(<Document size="A4" margin={48}><Invoice /></Document>);printed.html is print-ready HTML. For PDF files, @hyper-elements/react/pdf writes a Document with no browser, and @hyper-elements/react/image writes a Canvas as PNG or SVG.
Phones and hover
Inside style, mobile holds an element's styles on phones and hover its styles under the pointer; hidden shows it on one size only. Each element's list is in GUIDE.md.
<Heading style={{ fontSize: 32, mobile: { fontSize: 24, textAlign: "center" } }}>Welcome</Heading>
<Text hidden={{ mobile: true }}>Desktop detail</Text>
<Text hidden={{ desktop: true }}>Phone detail</Text>
<Button href="https://example.com" style={{ backgroundColor: "#111827", hover: { backgroundColor: "#374151" } }}>Buy</Button>Phones are at or below an email's width plus 20px, and at or below 480px on a page, or its own width: <Page breakpoints={{ mobile: 600 }}>. Hover styles apply on keyboard focus too.
Themes
A theme is the brand, written once and given to any root. Its tokens (colors, spacing, fontSizes, lineHeights, fonts, radii) are referred to with token(). Some are roles the built-in elements read:
- the root's background,
colors.background; - body text, which Text, table cells and list items inherit:
colors.foreground,fonts.body,fontSizes.bodyandlineHeights.body; - a Button's colors,
colors.primaryandcolors.primaryForeground, and its size,fontSizes.body; - a Link's color,
colors.primary; a Heading's font,fonts.heading; a Divider's color,colors.border.
elements gives each element its defaults, by one prop's value with by (a type scale) and as variants; styles are named styles, applied with style={{ apply: [...] }}.
import { defineTheme, token, Button, Email, Heading, Section, Text } from "@hyper-elements/react";
const brand = defineTheme({
colors: { background: "#ffffff", foreground: "#111827", primary: "#0f766e", primaryForeground: "#ffffff", muted: "#f3f4f6" },
fonts: { body: "Inter, Arial, sans-serif", heading: "Georgia, serif" },
fontSizes: { body: 16 },
lineHeights: { body: 1.6 },
elements: {
Heading: { by: { level: { 1: { fontSize: 40, mobile: { fontSize: 30 } }, 2: { fontSize: 28 } } } },
Button: { borderRadius: 8, variants: { secondary: { backgroundColor: "{colors.muted}", color: "{colors.foreground}" } } },
},
styles: { card: { padding: 32, mobile: { padding: 16 } } },
});
<Email theme={brand}>
<Section style={{ apply: ["card"] }}>
<Heading>Welcome</Heading>
<Button href="https://example.com/start">Get started</Button>
<Button href="https://example.com/docs" variant="secondary">Read the docs</Button>
</Section>
<Section tokens={{ colors: { background: "#111827", foreground: "#ffffff" } }}>
<Text style={{ color: token("colors.primary") }}>An inverted band: one prop.</Text>
</Section>
</Email>Inside a theme a token is "{colors.primary}". tokens on a Section, Row, Column or Grid overrides tokens for what it holds. formats: { email: { … } } overrides the theme for one kind of root, and extendTheme(base, overrides) makes a brand's or a customer's theme from a shared one. Register a theme to type every token, variant and named style:
declare module "@hyper-elements/react" {
interface Register {
theme: typeof brand;
}
}Everything is written as values: an email, a PDF and an image hold no theme. A Page also writes its tokens as CSS custom properties (--colors-primary) for its own CSS and Html blocks. inspect() lists the theme. The Themes page has the rest: which style takes which tokens, the order styles merge in, formats, and your own elements.
Common design patterns
Header with a logo
<Section style={{ backgroundColor: "#ffffff", padding: [24, 40] }}>
<Image src={{ src: "https://example.com/logo.png", width: 240, height: 80 }} alt="Logo" style={{ width: 120 }} />
</Section>Accent bar
<Divider style={{ borderTop: "3px solid #4f46e5" }} />Feature grid
<Grid columns={2} style={{ backgroundColor: "#ffffff", padding: [24, 40], gap: 24 }}>
<Column style={{ gap: 4 }}>
<Heading level={3} style={{ fontSize: 16, fontWeight: 600 }}>Feature 1</Heading>
<Text style={{ fontSize: 13, color: "#71717a" }}>Description of the feature.</Text>
</Column>
<Column style={{ gap: 4 }}>
<Heading level={3} style={{ fontSize: 16, fontWeight: 600 }}>Feature 2</Heading>
<Text style={{ fontSize: 13, color: "#71717a" }}>Description of the feature.</Text>
</Column>
</Grid>Metric cards
<Row style={{ gap: 16 }}>
<Column style={{ backgroundColor: "#ffffff", padding: 16, borderRadius: 8, textAlign: "center" }}>
<Heading level={2} style={{ fontSize: 28, fontWeight: 700, color: "#0f172a" }}>1.2M</Heading>
<Text style={{ fontSize: 12, color: "#94a3b8" }}>API calls</Text>
</Column>
{/* One Column for each metric */}
</Row>Product card
<Row style={{ backgroundColor: "#ffffff", padding: [20, 40], gap: 16 }}>
<Column style={{ width: 160 }}>
<Image src={{ src: "https://example.com/product.jpg", width: 320, height: 320 }} alt="Product" style={{ width: "100%" }} />
</Column>
<Column style={{ gap: 4 }}>
<Heading level={3} style={{ fontSize: 16, fontWeight: 600 }}>Product name</Heading>
<Text style={{ fontSize: 13, color: "#a1a1aa" }}>Matte white, medium</Text>
<Text style={{ fontSize: 16, fontWeight: 700 }}>$89.00</Text>
</Column>
</Row>Footer
<Section style={{ padding: [20, 40, 40, 40] }}>
<Text style={{ fontSize: 12, color: "#a1a1aa", textAlign: "center" }}>Company name, City, State</Text>
</Section>Your own elements
A function that returns elements is a component of your own, as in One template, every output. For a named block with typed props and its own editors, use defineElement():
import { Button, Column, Heading, Image, defineElement, prop } from "@hyper-elements/react";
const ProductCard = defineElement({
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 }),
accent: prop.color({ label: "Accent", default: "#0879a1" }),
},
render: ({ name, photo, href, accent }) => (
<Column style={{ gap: 8 }}>
<Image src={photo} alt={name} />
<Heading level={3}>{name}</Heading>
<Button href={href} style={{ backgroundColor: accent }}>Buy</Button>
</Column>
),
});For markup no element says, <Html html="…" /> writes it as it is, in an email and on a page, with nothing in it checked or escaped. Put only markup you wrote there.
To the Unlayer builder and back
@hyper-elements/react/builder: toDesign() writes a template as the builder's design JSON, for loadDesign(); fromDesign() reads a design (made by toDesign(), edited in the builder or made there) back as a template, as an element to render and as JSX source.
import { fromDesign, toDesign } from "@hyper-elements/react/builder";
const { design, report } = toDesign(<Receipt />); // report: what the builder can't hold as it is, one line each
// …the design is edited in the builder, and saved…
const { element, code, report: read } = fromDesign(saved, { displayMode: "email" }); // "web" a Page, "document" a DocumentThe design holds no Hyper Elements data. A style or prop a builder tool has no field for is a hidden property of that tool, kept in the design under its own name and drawn by Hyper Elements, with no editor in the builder yet. What the builder can't arrange comes back with the same look, flatter: a Section around several Rows as a Section each, a box's padding on its blocks, a Grid as Rows of Columns. What no tool shows (a Layer, an Svg, a box nested in a column, your own defineElement()) goes as an HTML block of the new engine's markup, and comes back as an Html block, as the builder's own HTML blocks do. A Table is the builder's table, and comes back as a Table; in an Email or a Page, one the builder's table would draw otherwise (a line between rows only, a cell spanning columns, a border around it, a width) stays an HTML block, which draws it exactly, and report says why. A design's markup comes back as it is: where designs can hold untrusted content, pass your sanitizer, fromDesign(saved, { toSafeHtml }). A line height goes in the builder's field as a whole percentage, as browsers draw it, so 24px at 13px is 185%, a twentieth of a pixel taller there. The builder has no page numbers yet: a PageNumber goes as its token, which the editor's PDF prints as it is, and report says so.
What each root takes
Not everything goes in every root: an Svg isn't in an Email, a PageNumber is only in a Document, and phone styles are only in an Email or a Page. @hyper-elements/react/inspect says which, as data, for an agent or an editor: before writing a template, what a root takes; after, whether each part of it is allowed where it is.
import { describeElement, describeElements, inspect } from "@hyper-elements/react/inspect";
describeElements({ root: "Email" }); // the elements an Email takes, each prop and style with its kind, group and default
describeElement("Svg", { root: "Email" }); // undefined: an Email doesn't take one
describeElement("Svg").roots; // ["Page", "Document", "Canvas"]
const { valid, nodes } = inspect(<Welcome />);
// nodes: each element, in order: { path, type, roots, allowed, given: ["style.padding", "mobile.padding"], problems }inspect() checks what validate() checks, without rendering, and puts each problem on the element it's on. Your own elements (defineElement()) are described with the built-in ones: describeElements({ elements: [ProductCard] }).
Task guides and runnable examples
- Transactional email in React: render HTML and plain text, then send a receipt.
- Resend, AWS SES, Postmark, SendGrid, and Nodemailer: complete provider integrations.
- One React template to email, web, and PDF: shared invoice content with output-specific roots.
- React invoice PDF with Playwright: generate actual PDF bytes from document HTML.
- React to Unlayer visual editing:
toDesign(), editor loading, export, and what the builder can hold.
See when to choose Hyper Elements and the runnable example.
Moving from Unlayer Elements
Unlayer Elements (@unlayer/react-elements) is the old package. Its components (Body, ColumnLayouts, renderToHtml() and the rest) aren't in this one. The codemod moves templates written with them:
npx @hyper-elements/migrate src/emails --from unlayer-elements # templates written with Unlayer Elements
npx @hyper-elements/migrate src/emails # React Email templatesIt lists what it would change, and --write replaces the files (only those git can restore). Then install @hyper-elements/react, and remove @unlayer/react-elements once nothing imports it. What it can't move is listed, and that file is left as it was to rewrite by hand. See the migration guide and @hyper-elements/migrate.
Development
pnpm build # Build the package
pnpm test # Run tests
pnpm storybook # Launch StorybookLicense
MIT
