Unlayer Elements

Write once in React. Render emails, web pages, and PDFs from the same component tree.

Unlayer Elements is an open-source React component library for transactional emails, email templates, landing pages, invoices, reports, documents, and PDFs. Build content once and render it across three output modes:

Email → Outlook, Gmail, Yahoo, Apple Mail
Web → Responsive pages and embedded experiences
Document → Print-ready HTML for PDF generation

Elements is built and maintained by the team behind Unlayer, the content creation platform used by thousands of companies to power email, page, and document experiences inside their products.

Why Elements?

Tool	Email	Web	PDF
React Email	✅	❌	❌
MJML	✅	❌	❌
PDF libraries	❌	❌	✅
Elements	✅	✅	✅

Elements is designed for teams that need to generate email, web, and document experiences from a single React codebase.

Quick Start

npm install @unlayer/react-elements

import {
  Email, Row, Column, ColumnLayouts,
  Heading, Paragraph, Button, renderToHtml
} from '@unlayer/react-elements';

function WelcomeEmail() {
  return (
    <Email backgroundColor="#f0f0f0" contentWidth="600px">
      <Row layout={ColumnLayouts.OneColumn} backgroundColor="#ffffff" padding="20px">
        <Column>
          <Heading
            fontSize="24px"
            fontFamily={{ label: "Arial", value: "arial,helvetica,sans-serif" }}
          >
            Welcome!
          </Heading>
          <Paragraph html="Thanks for signing up." fontSize="14px" />
          <Button
            href="https://example.com"
            backgroundColor="#0879A1"
            color="#ffffff"
          >
            Get Started
          </Button>
        </Column>
      </Row>
    </Email>
  );
}

// Render to a complete HTML document (<!DOCTYPE ...> to </html>) —
// email-client-safe shell included, no React hydration markers
const html = renderToHtml(<WelcomeEmail />);

Try it in your browser: the Elements Playground renders Elements code as an email, page, or document with nothing to install. Write plain JSX, export the HTML or design JSON, and open the result in the Unlayer builder.

Email Client Compatibility Notes

Targeted Clients

Email mode is designed for the major clients listed throughout this repo:

Outlook
Gmail
Yahoo
Apple Mail

Why Email Mode Uses Table-Based HTML

Email clients do not share a modern browser CSS baseline. To keep layout behavior stable across major inboxes (especially Outlook's Word-based renderer), <Email> renders with table-oriented HTML and MSO-specific patterns instead of web-style div/flex layouts.

Repository evidence:

<Email> is documented and tested as table-based output for email clients: packages/react/README.md
The email document shell includes MSO conditionals and Office namespaces: packages/react/src/utils/document-layouts.ts
Golden output asserts table markup and Outlook-specific conditionals ([if mso]): packages/react/src/golden-template.test.tsx

Known Compatibility Caveats (Current Repo Scope)

Validation in this repo is renderer-focused and browser-based (snapshots + Chromium E2E). It is not a client-emulator matrix checked into this repository.
Email responsive stacking depends on head CSS/media queries; this is explicitly exercised by the E2E gate in Chromium, not by an inbox simulator.

Validation references:

Snapshot coverage (components in email + web modes): packages/react/src/components/snapshots.test.tsx
Golden end-to-end template coverage: packages/react/src/golden-template.test.tsx
Browser E2E gate and exact assertions: packages/react/scripts/browser-e2e.mjs

CSP Safety Validation

Elements includes a strict CSP gate that runs the built package under:

node --disallow-code-generation-from-strings

The gate's purpose is to fail if import/render paths evaluate strings (eval / new Function), including behavior coming from pinned dependencies.

CSP probe implementation: packages/react/scripts/csp-probe.mjs
Package script (test:csp): packages/react/package.json
Pinned exporter dependency source: pnpm-workspace.yaml

Interpretation guidance:

A passing test:csp run is evidence that the exercised import/render paths are compatible with CSP configurations that disallow 'unsafe-eval'.
This probe is not a universal guarantee for every browser/runtime configuration.
If test:csp is failing in CI or your local environment, treat strict CSP compatibility as unresolved for that run and investigate the reported failure.

Features

One Component Tree

Build content once and render it as email, web, or document. Share components, styling, and content across all three output modes from the same React codebase.

React Developer Workflow

Works with React, Next.js, Remix, and Server Components. Use familiar JSX patterns and existing frontend workflows without learning a new templating language.

Production Output

Generates email-safe HTML, responsive web HTML, and print-ready HTML for PDF generation — optimized output for each destination without maintaining separate implementations.

Visual Builder Compatible

Export Unlayer-compatible design JSON with renderToJson() to hand code-authored templates to the visual editor. Persist edited designs as JSON and export their HTML from the editor; edited JSON does not regenerate React source. See the code-to-visual-editing workflow.

TypeScript First

Built with TypeScript from the ground up — full type definitions, autocomplete for components and props, and safer development with better IDE support.

Clean HTML Output

renderToHtml() generates a complete, production-ready HTML document with no React hydration markers, no framework artifacts, and no client-side JavaScript required. Need to compose the document yourself? renderToHtmlParts() returns { head, body } chunks.

Lightweight & Tree-Shakeable

~12KB gzipped (under 60KB ESM), tree-shakeable, with zero client-side JavaScript required. Designed for performance-sensitive applications and server-side rendering environments.

Real-World Use Cases

Transactional Emails

Build and maintain order confirmations, password resets, and receipts from the same React codebase that powers your application.

PDF Generation

Generate invoices, contracts, and reports server-side without maintaining a separate PDF system.

CMS-Driven Content

Render content from a CMS, API, or database into emails, web pages, and documents using a shared component model.

Email + Web Parity

Publish the same content as an email campaign, a web archive, and a public landing page from a single source of truth.

Components

Component	Description
`<Email>`	Root wrapper — email-safe HTML (tables for Outlook/Gmail)
`<Page>`	Root wrapper — responsive web (div + flexbox)
`<Document>`	Root wrapper — print/PDF optimized
`<Row>`	Layout container with column layout support
`<Column>`	Column inside a Row
`<Button>`	CTA button with hover states and links
`<Heading>`	Heading (h1–h4)
`<Paragraph>`	Rich text with plain text or HTML content
`<Image>`	Responsive image with alt text
`<Divider>`	Horizontal separator
`<Social>`	Social media icon links
`<Menu>`	Navigation menu
`<Table>`	Data table with repeating document headers and footers
`<PageBreak>`	Force subsequent document content onto a new PDF page
`<Video>`	YouTube/Vimeo embed
`<Html>`	Custom HTML passthrough

Structure

Components follow a strict hierarchy:

<Email>              ← sets render mode
  <Row layout={…}>   ← layout container
    <Column>         ← must match layout column count
      <Button />     ← content components
      <Paragraph />
    </Column>
  </Row>
</Email>

Column Layouts

import { Row, Column, ColumnLayouts } from '@unlayer/react-elements';

// Each Row must contain the matching number of <Column> children.
<Row layout={ColumnLayouts.OneColumn}>                {/* [1]         → 100% */}
  <Column>{/* content */}</Column>
</Row>
<Row layout={ColumnLayouts.TwoEqual}>                 {/* [1,1]       → 50% + 50% */}
  <Column>{/* content */}</Column>
  <Column>{/* content */}</Column>
</Row>
<Row layout={ColumnLayouts.TwoWideNarrow}>            {/* [2,1]       → 67% + 33% */}
  <Column>{/* content */}</Column>
  <Column>{/* content */}</Column>
</Row>
<Row layout={ColumnLayouts.ThreeEqual}>               {/* [1,1,1]     → 33% each */}
  <Column>{/* content */}</Column>
  <Column>{/* content */}</Column>
  <Column>{/* content */}</Column>
</Row>
<Row layout={ColumnLayouts.FourEqual}>                {/* [1,1,1,1]   → 25% each */}
  <Column>{/* content */}</Column>
  <Column>{/* content */}</Column>
  <Column>{/* content */}</Column>
  <Column>{/* content */}</Column>
</Row>
<Row cells={[3, 1]}>                                  {/* custom ratio */}
  <Column>{/* content */}</Column>
  <Column>{/* content */}</Column>
</Row>

Documentation

For the full API reference, component props, design patterns, and common mistakes, see the React package documentation.

Packages

Package	Description	Published
`@unlayer/react-elements`	React components and renderers
`@unlayer/migrate`	Migrate React Email templates to Elements, checked against the originals	Not yet
`@unlayer/from-react-email`	The React Email → Elements converter, as a library	Private (bundled into `@unlayer/migrate`, API at `@unlayer/migrate/react-email`)
`@unlayer/convert-core`	Shared model for converters (Elements tree, report, TSX printer, layout check)	Internal
`@unlayer-internal/shared-elements`	Framework-agnostic shared logic	Internal
`@unlayer/elements-demo`	Demo application	—

Examples

Runnable projects you can clone and experiment with:

Example	Description
`examples/content-workflows`	One React invoice → email + web + real PDF, five email providers, and editable design JSON
`examples/nextjs-app-router`	Next.js 15 App Router — renders an email with `renderToHtml()` in a Server Component, previews it at `/email-preview`, and serves the raw HTML from a Route Handler

Development

# Prerequisites: Node.js (see .nvmrc), pnpm 9+

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

# Run tests with coverage
pnpm test:coverage

# Launch Storybook
pnpm storybook:hub

FAQ

What makes Elements production ready?

Elements generates its HTML with the same battle-tested engine that powers exports in the Unlayer editor, an engine used in production by thousands of companies for years. The engine version is pinned per release, and every component's output is locked down by snapshot tests, a golden-template test, and browser-level gates (see below), so upgrades cannot silently change the HTML you ship. Releases follow semantic versioning and each one is published with release notes, so any change to the API or output is visible before you upgrade.

How is the email output actually tested?

Every release must pass, in CI:

Golden template test: a full, realistic email rendered through all render pipelines and compared against committed output.
Snapshot tests: every component rendered in both email and web modes.
Browser E2E gate: complete documents rendered from the built package and verified in headless Chromium: responsive columns stack at the mobile breakpoint, paragraphs compute to true zero margins, RTL text direction propagates, button hover states apply, the preheader stays invisible, no horizontal overflow on mobile, and accessibility basics hold (image alt text, link names, role="presentation" on layout tables). The suite includes a negative control that must fail, proving the gate can catch regressions rather than just pass vacuously.
Visual-drift gate: the computed styles of every Storybook story are fingerprinted at desktop and mobile widths and diffed against a committed baseline, so unintended style changes fail the build with property-level diffs.
Next.js integration test: a real Next.js 15 app with Server Components builds against the published package artifact.

The email mode emits the same table-based, Outlook-safe HTML patterns as Unlayer's editor exports, which land in real inboxes every day. Our templates are tested on Litmus and Email on Acid across major email clients, including Outlook, Gmail, Yahoo, and Apple Mail. For repository-scoped compatibility evidence and caveats, see Email Client Compatibility Notes.

Is the PDF output a real PDF engine?

Elements itself produces print-ready HTML, not PDF bytes. The Playwright guide shows a complete local PDF pipeline. You can generate PDF files in two ways: use Unlayer's PDF export service to get a finished PDF with a single API call, or pass the print-optimized HTML from <Document> to any HTML-to-PDF library. Pagination (page breaks, margins, and headers and footers) is controlled with standard CSS print rules plus your renderer's options.

Can I use Elements without the Unlayer platform?

Yes. The package is MIT-licensed, makes no network calls, requires no API key or account, and has no runtime dependency on Unlayer's platform. renderToHtml() runs entirely in your own process, and the output is plain, static HTML that you own outright. The platform integrations (design-JSON round-tripping via renderToJson() and Custom Tools shared with the visual editor) are strictly opt-in: valuable if you also use the Unlayer builder, ignorable if you don't.

Is there a visual editor for Elements?

Yes. Elements is fully compatible with the Unlayer editor, the drag-and-drop builder for emails, pages, and documents that you can embed in your own product. renderToJson() exports your component tree as Unlayer design JSON that loads directly into the editor, so developers can build templates in code and hand them off to non-technical teammates for visual editing. Custom Tools bridge the two as well: the same tool definition renders in the editor and in code. To see it in action, write Elements code in the Elements Playground and switch to Builder.

Can I create custom components?

Yes. registerElementsTool() turns a custom tool definition into a first-class React component with typed props and full control over its output in each render mode (email, web, and document). See the Custom Tools documentation for a complete example.

Task Guides

Start with when to use Elements, or go directly to a runnable workflow:

Build transactional emails in React — HTML and plain-text receipts, order confirmations, and password reset patterns.
Send with Resend, AWS SES, Postmark, SendGrid, or Nodemailer — provider setup and complete server-side integrations.
One React invoice to email, web, and PDF — share content across all three output modes.
Generate a real PDF with Playwright — print document HTML with Chromium.
Make code and AI-generated templates visually editable — renderToJson() → Unlayer loadDesign() → edited JSON and HTML.

The content workflows example contains the executable source behind these guides.

Contributing

See CONTRIBUTING.md for setup instructions and guidelines.

License

MIT — Unlayer, Inc.