npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@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/react

Quick 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 words

To 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.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."

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 />);
  • html is the whole document, from <!DOCTYPE html>, with no React hydration markers and no client-side JavaScript.
  • text is the plain-text version.
  • head, body and bodyStyle are for embedding the output in a page of your own.
  • diagnostics holds warnings and notes. A template with errors throws an ElementsError, whose diagnostics give each problem's code, message and path.

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.body and lineHeights.body;
  • a Button's colors, colors.primary and colors.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 Document

The 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

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 templates

It 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 Storybook

License

MIT