
hyper-elements
Write emails, web pages, printed documents, PDFs and images in code with Hyper Elements, React components that render email-safe HTML, page HTML, PDFs and PNG or SVG images.
- GitHub stars
- 477
Install
/plugin install hyper-elements@hyper-elementsRun it inside Claude Code after adding the marketplace with /plugin marketplace add hyper-elements/hyper-elements.
Contents
Discovered from sourceSkills 1
Hyper Elements
Write emails, web pages, printed documents, PDFs and images in code with Hyper Elements (npm install @hyper-elements/react). This is the package's own guide to its elements at @hyper-elements/react (GUIDE.md in the package), written from their definitions: everything needed to write a design, in short. Every prop's and style's details, with its default: node_modules/@hyper-elements/react/REFERENCE.md.
To test an email in Outlook, Gmail and other clients, a design or any HTML: the email-testing skill has the steps, or run npx @hyper-elements/cli preview emails/welcome.tsx.
Before you write a design
- If the project's package.json doesn't list
@hyper-elements/react, install it:npm install @hyper-elements/react react react-dom, or the same with the project's package manager (pnpm add,yarn add,bun add). - Once it's installed, its own guide is
node_modules/@hyper-elements/react/GUIDE.md, written for the version installed.grep "hyper-elements guide" node_modules/@hyper-elements/react/GUIDE.mdgives its id; this skill's ishyper-elements guide f82a37d3. The same id: this skill is that guide, so read on. Another id, or none: read GUIDE.md and follow it where it differs from this skill.
Templates from Unlayer Elements
A project may have templates written with Unlayer Elements: they import Body, ColumnLayouts or renderToHtml() from @unlayer/react-elements, and use values, layout, html and style props such as backgroundColor="#fff". Those components aren't in Hyper Elements, a new package: these are its components.
- Move them with the codemod:
npx @hyper-elements/migrate src/emails --from unlayer-elementslists what it would change,--writereplaces the files (only those git can restore) and--report notes.mdwrites what it noted. It rewrites the imports and the JSX, and keeps props, loops and conditions. The new elements render withawait render(element), which is async, in place ofrenderToHtml(). More:npx @hyper-elements/migrate --help. - What the codemod can't move is listed, and the file is left as it was: rewrite that part by hand with these elements.
- Then
npm install @hyper-elements/react, and remove@unlayer/react-elementsonce nothing imports it. - Templates in React Email:
npx @hyper-elements/migrate src/emailswrites them in these elements and checks each against its original.
How a design is written
- Import from
@hyper-elements/react. A design has one root:Email,Page,DocumentorCanvas. - Styles go in
style={{ … }}, never as props:<Heading style={{ fontSize: 24, color: "#111827" }}>. A number is px;paddingtakes16,[12, 24]or"12px 24px". A box's text styles are inherited by what it holds. - There are no margins: space between blocks is their parent's
gap(<Column style={{ gap: 16 }}>), space inside a box itspadding. - A root, a
Sectionand aColumnstack their children. ARowputs its children side by side (eachColumnat itsstyle.width, or an equal share) and stacks them on phones.Grid columns={3}makes rows of three. ASectionis a band whose background spans the window; aColumnwith a background is a card. - Text is elements, not HTML:
Heading level={1}andTexthold text; inside themSpanstyles a run,Link hreflinks one,LineBreakbreaks the line andMergeTag namewrites a merge tag. No raw HTML (<b>,<br>,<div>) and nohtmlprop. Image src={{ src, width, height }}(the file's size in px) withalt;style.widthsets the size shown.- An image's
srcis a publichttpsURL the reader's email client can fetch: the project's own (its CDN, its other templates, its site) or one the person gives you. Never make one up:example.com, a guessed path or a file on this computer shows as a broken image. Where the design needs an image that doesn't exist yet, use a placeholder that loads, at the image's size:https://placehold.co/1200x600/png?text=Product+screenshot(width x height in px). Then tell the person which images to replace. Adata:URI works in a Page, Document or Canvas, but Gmail doesn't show one in an Email. - Lists:
<List type="number">ofListItems. Tables: aTableofTableRows (headeron the first) ofTableCells, withcellPaddingandrowBorderin the Table'sstyle. - Phones:
style={{ fontSize: 24, mobile: { fontSize: 20 } }}(the styles listed under "Phones", wheretextis fontSize, lineHeight, letterSpacing and textAlign),hidden={{ mobile: true }}; in an Email or a Page. Hover:style={{ hover: { backgroundColor: "#374151" } }}(those under "Hover"). await render(element)gives{ html, text, diagnostics }; errors throw anElementsErrorwith the samediagnostics.validate(element)runs the checks without rendering;outline(element)prints the laid-out design (each block, its width, its text).- Templates (fixed parts, typed fields and checks):
@hyper-elements/react/template. - Email clients:
@hyper-elements/email-clients.validate(email, { plugins: [await emailClients()] })adds what classic Outlook, Gmail, Apple Mail and others remove or change, naming itsclients, with afix(without it, one note:email/more-checks). To test an email in them,await renderInEmailClients(email)gives a preview per client: HTML that shows the email as that client does, in Chromium. It takes any other HTML email too.
import { writeFile } from "node:fs/promises";
import { ElementsError, formatDiagnostics, render } from "@hyper-elements/react";
import Welcome from "./welcome";
try {
const { html, diagnostics } = await render(<Welcome />);
await writeFile("welcome.html", html);
console.log(formatDiagnostics(diagnostics)); // warnings and notes, each with what to change
} catch (e) {
if (!(e instanceof ElementsError)) throw e;
console.error(formatDiagnostics(e.diagnostics));
process.exitCode = 1;
}
From the shell (@hyper-elements/cli): npx hyper-elements check emails/welcome.tsx runs these checks on the module's default export and exits 1 on errors (--json for JSON); render writes the HTML and text to out/.
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 aColumn(a card) or aSection(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: "/" }]}. AMenu's items are{ text, href }, aSocial's icons{ name, href }.style={{ marginBottom: 16 }}→gap: 16on the parent. There are no margins.ColumnLayouts,layout,headingType,altText,htmlare Unlayer Elements' props, not these: aRowofColumns,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 file at its own size.mobile={{ fontSize: 20 }},hover={{ … }},_hoverormd: { … }→style={{ fontSize: 24, mobile: { fontSize: 20 }, hover: { … } }}. Phone and hover styles are blocks ofstyle, and there's one breakpoint: phones.className="secondary"orsx={…}→variant="secondary"(the theme's) orstyle={{ apply: ["card"] }}.
Themes
A theme is the brand, written once: defineTheme({ colors, spacing, fontSizes, lineHeights, fonts, radii, elements, styles, formats }), given to a root as theme.
- In a design
token("colors.primary")is a token's value, or part of one (border: { width: 1, style: "solid", color: token("colors.border") }); inside a theme, and only there, a token is"{colors.primary}": everywhere in a design (a root'sstyle, a scope'stokens) it istoken(). Names are letters and digits: nestgray.900. - Roles:
colors.backgroundis the root's background;colors.foreground,fonts.body,fontSizes.bodyandlineHeights.bodyare its body text (color, font, size and line height), which Text, table cells and list items inherit: set body text here, not onText(a style onTextmisses table cells).fonts.headingis a Heading's font,colors.primaryandcolors.primaryForegrounda Button's (colors.primarya Link's) andfontSizes.bodyits size too,colors.bordera Divider's. elements.Button: { … }is every Button's default style;by: { level: { 1: { fontSize: 40 } } }sets one by a prop's value (a type scale);variants: { secondary: { … } }are picked withvariant="secondary"(a list merges in order).styles: { card: { … } }are named styles:style={{ apply: ["card"], padding: 8 }}. A key an element sets itself also replaces the theme's phone and hover values for it.tokenson a Section, Row, Column or Grid overrides tokens inside it: an inverted band is<Section tokens={{ colors: { background: "#111827", foreground: "#ffffff" } }}>.formats: { email: { … } }overrides it for one kind of root;extendTheme(base, overrides)makes a brand's or a customer's theme from a shared one;declare module "@hyper-elements/react" { interface Register { theme: typeof brand } }types every name.
A whole design
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>
);
}
A Canvas as an image
renderImage(element, options) (@hyper-elements/react/image) writes a Canvas as a PNG (format: "svg" an SVG, scale: 2 twice the pixels). Nothing is fetched: fonts gives each font file by the family the design names (TTF, OTF or WOFF, not WOFF2; one per weight and style used), images each image file by the src the design gives. It gives { image, width, height, diagnostics } (what it drew otherwise: a weight not given, a hover); errors throw an ElementsError.
import { readFile } from "node:fs/promises";
import { Canvas, Heading, Image } from "@hyper-elements/react";
import { renderImage } from "@hyper-elements/react/image";
const { image, diagnostics } = await renderImage(
<Canvas width={1200} height={630} style={{ padding: 64, gap: 24, fontFamily: "Inter", textAlign: "center", justifyContent: "center" }}>
<Image src={{ src: "https://example.com/logo.png", width: 240, height: 80 }} alt="Acme" style={{ width: 120 }} />
<Heading level={1} style={{ fontSize: 64 }}>Launch week</Heading>
</Canvas>,
{
fonts: [{ family: "Inter", src: await readFile("Inter-Bold.ttf"), weight: 700 }],
images: { "https://example.com/logo.png": await readFile("logo.png") },
}
);
Elements
* required. text styles: color, fontFamily, fontSize, fontWeight, fontStyle, lineHeight, letterSpacing, textAlign, textTransform. box styles: width, maxWidth, padding, backgroundColor, border, borderRadius.
Roots
- Email: An email. Its children are stacked down the content width, centered in the window. Holds sections, layout, blocks. Props: width (a length (a number of px)), previewText (text), title (text), lang (text), dir (ltr|rtl|auto), fonts (fontFaces). Style: text, backgroundColor, gap, alignItems (start|center|end|stretch). Phones: text, gap.
- Page: A web page. Its children are stacked down the content width, centered in the window. Holds sections, layout, blocks. Props: width (a length (a number of px)), description (text), breakpoints (breakpoints), title (text), lang (text), dir (ltr|rtl|auto), fonts (fontFaces). Style: text, backgroundColor, gap, alignItems (start|center|end|stretch). Phones: gap.
- 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 sections, layout, blocks, Document.Page, PageBreak, PageHeader, PageFooter. Props: size (A3|A4|A5|Letter|Legal|Tabloid), orientation (portrait|landscape), margin (insets), title (text), lang (text), dir (ltr|rtl|auto), fonts (fontFaces). Style: text, backgroundColor, gap, alignItems (start|center|end|stretch).
- 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 sections, layout, blocks. Props: width (a length (a number of px)), height (a length (a number of px)), title (text), lang (text), dir (ltr|rtl|auto), fonts (fontFaces). Style: text, backgroundColor, gap, alignItems (start|center|end|stretch), padding, justifyContent (start|center|end|space-between).
Sections and layout
- 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 layout, blocks. Style: text, backgroundColor, padding, border, gap, alignItems (start|center|end|stretch). Phones: text, padding, border, gap.
- 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 layout, blocks. Props: stackOnMobile (true or false), dir (ltr|rtl|auto). Style: text, box, minWidth, height, overflow (visible|hidden), gap, alignItems (start|center|end|stretch), justifyContent (start|center|end|space-between), flexWrap (nowrap|wrap|words), flex. Phones: text, width, maxWidth, padding, border, gap.
- Column: Stacks its children vertically, with its own spacing and box. Holds layout, blocks. Style: text, box, minWidth, height, overflow (visible|hidden), gap, alignItems (start|center|end|stretch), justifyContent (start|center|end|space-between), flex. Phones: text, width, maxWidth, padding, border, gap.
- Grid: Its children in columns of equal width, row after row; on phones, one under another. Holds layout, blocks. Props: columns (an integer from 1 to 12), stackOnMobile (true or false). Style: text, box, minWidth, height, overflow (visible|hidden), gap, rowGap, alignItems (start|center|end|stretch), flex. Phones: text, width, maxWidth, padding, border, gap, rowGap.
- Layer: Its children over each other, in one box as tall as the tallest: words on an image (a background image, its first child). In an email, an Image with one child over it. Holds layout, blocks. Style: text, width, minWidth, maxWidth, backgroundColor, border, borderRadius, height, alignItems (start|center|end|stretch), justifyItems (start|center|end|stretch), flex. Phones: text, width, maxWidth, border.
Blocks
- 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. Not in an Email. Holds shapes. Props: width* (a number from 0), height* (a number from 0), viewBox (text), title (text). Style: padding, backgroundColor, border, borderRadius, flex. Phones: padding, border.
- Text: A paragraph of text. Holds text, inline, Image. Props: dir (ltr|rtl|auto), fit ({ sizes, maxLines }). Style: text, box, textDecoration (none|underline|line-through), flex. Phones: text, width, maxWidth, padding, border.
- Heading: A heading, from level 1 (the page's title) to 6. Holds text, inline. Props: level (1|2|3|4|5|6), dir (ltr|rtl|auto), fit ({ sizes, maxLines }). Style: text, box, textDecoration (none|underline|line-through), flex. Phones: text, width, maxWidth, padding, border.
- Button: A link drawn as a button. Holds text, Span, MergeTag, LineBreak. Props: href* (link), title (text), aria-label (text), attrs (attributes). Style: text, box, textDecoration (none|underline|line-through), boxSizing (border-box|content-box), alignSelf (start|center|end), flex. Hover: color, backgroundColor. Phones: text, width, maxWidth, padding, border, alignSelf.
- Image: An image in the content. Without a width it takes its own size, no wider than its parent. Props: src* (asset), alt (text), title (text). Style: width, maxWidth, height, border, borderRadius, flex, alignSelf (start|center|end), verticalAlign (top|middle). Phones: width, maxWidth, border, alignSelf.
- Divider: A horizontal line. Style: borderTop, width, padding. Phones: width, padding.
- List: A bulleted or numbered list of ListItems. Its markers sit in a column of their own (indent) before the items. Holds ListItem. Props: type (bullet|number), start (an integer from 0). Style: text, width, maxWidth, padding, backgroundColor, border, gap, indent, flex. Phones: text, width, maxWidth, padding, border, gap.
- Table: A table of data: TableRows of TableCells. Columns take their cells' widths; the rest share what's left. Holds TableRow. Style: text, width, maxWidth, backgroundColor, border, cellPadding, rowBorder, borderCollapse (separate|collapse), flex. Phones: text, width, maxWidth, border.
- Video: A YouTube or Vimeo video: its player on a page; in an email (which can't play one), its thumbnail, linked to it. Props: src* (video), thumbnail (asset), title (text). Style: width, maxWidth, flex. Phones: width, maxWidth.
- Social: Links to social profiles: a line of the networks' icons, each linked to its profile. Props: icons* (a list of icons, each { name, href }), iconType (circle|rounded|squared), size (an integer from 1). Style: gap, justifyContent (start|center|end), flex. Phones: gap.
- 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. Props: items* (a list of items, each { text, href }), separator (text), layout (horizontal|vertical). Style: color, fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, textTransform (none|uppercase|lowercase|capitalize), separatorColor, padding, justifyContent (start|center|end), flex. Phones: fontSize, lineHeight, letterSpacing.
- Html: Markup written as it is, for what no element 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. Props: html* (text), text (text).
Inline
- PageNumber: In a Document's text: the number of the page it's on, or (total) how many pages there are. Only in a Document. Props: total (true or false).
- Span: Styled text inside text; raised or lowered (superscript, subscript) with verticalAlign. Holds text, inline. Style: color, fontFamily, fontSize, fontWeight, fontStyle (normal|italic), letterSpacing, textTransform (none|uppercase|lowercase|capitalize), textDecoration (none|underline|line-through), backgroundColor, verticalAlign (baseline|super|sub). Phones: fontSize, letterSpacing.
- Link: A link: text inside text, or around an Image. Holds text, inline, Image. Props: href* (link), title (text), aria-label (text), attrs (attributes). Style: color, fontFamily, fontSize, fontWeight, fontStyle (normal|italic), letterSpacing, textTransform (none|uppercase|lowercase|capitalize), textDecoration (none|underline|line-through), backgroundColor, flex. Hover: color, textDecoration, backgroundColor. Phones: fontSize, letterSpacing.
- LineBreak: Starts a new line inside text.
- MergeTag: A value the sending service fills in (a name, a link), written in the service's own syntax. Props: name* (text).
Parts
- Document.Page: One page of a Document (Document.Page in JSX): its children stacked down it, inside the Document's margins. Holds sections, layout, blocks. Style: text, backgroundColor, gap, alignItems (start|center|end|stretch).
- PageBreak: In a Document, where a page ends: what follows starts the next page.
- PageHeader: In a Document: drawn at the top of every page, inside its margins. Holds layout, blocks. Style: text, padding, backgroundColor, border, gap, alignItems (start|center|end|stretch).
- PageFooter: In a Document: drawn at the bottom of every page, inside its margins. Holds layout, blocks. Style: text, padding, backgroundColor, border, gap, alignItems (start|center|end|stretch).
- ListItem: An item of a List: text, and a List of its own to nest one. Holds text, inline, List. Props: dir (ltr|rtl|auto). Style: text, textDecoration (none|underline|line-through). Phones: text.
- TableRow: A row of a Table. A header row's cells are header cells, in bold. Holds TableCell. Props: header (true or false), footer (true or false). Style: text, backgroundColor, height. Phones: text.
- TableCell: A cell of a TableRow: text, and images. Its width sets its column's. Holds text, inline, Image. Props: colSpan (an integer from 1), dir (ltr|rtl|auto). Style: text, textDecoration (none|underline|line-through), padding, backgroundColor, border, width, verticalAlign (top|middle|bottom). Phones: text, padding, border.
Shapes
- Rect: A rectangle at x, y in its Svg, rounded by rx. Props: x (a number), y (a number), width* (a number from 0), height* (a number from 0), rx (a number from 0). Style: fill, stroke, strokeWidth, opacity.
- Circle: A circle centered at cx, cy in its Svg. Props: cx (a number), cy (a number), r* (a number from 0). Style: fill, stroke, strokeWidth, opacity.
- Ellipse: An ellipse centered at cx, cy in its Svg. Props: cx (a number), cy (a number), rx* (a number from 0), ry* (a number from 0). Style: fill, stroke, strokeWidth, opacity.
- Line: A straight line from x1, y1 to x2, y2 in its Svg (drawn by its stroke). Props: x1 (a number), y1 (a number), x2 (a number), y2 (a number). Style: fill, stroke, strokeWidth, opacity.
- Polygon: A closed shape through its points ("0,0 40,0 20,30"), in its Svg. Props: points* (text). Style: fill, stroke, strokeWidth, opacity.
- Path: A shape drawn by an SVG path (d), in its Svg. Props: d* (text). Style: fill, stroke, strokeWidth, opacity.
Values
- 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)
- breakpoints: { mobile }: the phone width in px (from 240)
- 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
Sponsors
Details
- Marketplace
- hyper-elements/hyper-elements
- Source
- skills/hyper-elements
- Category
- Development
- License
- MIT
- Keywords
- email, react, pdf, html-email, templates