Create beautiful, responsive HTML emails using React components with React Email. Build transactional emails with modern components, support internationalization, and integrate with email service providers like Resend. Use when creating welcome emails, password resets, notifications, order confirmations, or any HTML email templates.
Build and send HTML emails using React components - a modern, component-based approach to email development that works across all major email clients.
Scaffold a new React Email project:
npx create-email@latest
cd react-email-starter
npm install
npm run dev
This creates a react-email-starter folder with sample templates. Also works with yarn, pnpm, or bun.
Add React Email to an existing codebase:
npm install @react-email/components
npm install react-email @react-email/preview-server -D
mkdir emails
{
"scripts": {
"email:dev": "email dev"
}
}
npm run email:dev
The --dir flag specifies where email templates are stored. Adjust the path to match your project structure (e.g., src/emails, app/emails).
Before creating any email template, gather brand information from the user. This ensures visual consistency across all emails.
Ask the user for:
Brand colors
#1a1a1a for light mode)#f4f4f5 for light mode)Logo
Typography (optional)
Style preferences (optional)
Once gathered, define a reusable Tailwind configuration. Using satisfies TailwindConfig provides intellisense support for all configuration options:
// emails/tailwind.config.ts
import { pixelBasedPreset, type TailwindConfig } from '@react-email/components';
export default {
presets: [pixelBasedPreset],
theme: {
extend: {
colors: {
brand: {
primary: '#007bff', // User's primary brand color
secondary: '#6c757d', // User's secondary color
},
},
},
},
} satisfies TailwindConfig;
// For non-Tailwind brand assets (optional)
export const brandAssets = {
logo: {
src: 'https://example.com/logo.png', // User's logo URL
alt: 'Company Name',
width: 120,
},
};
import * as React from "react";
import tailwindConfig, { brandAssets } from './tailwind.config';
import { Tailwind, Img } from '@react-email/components';
<Tailwind config={tailwindConfig}>
<Body className="bg-gray-100 font-sans">
<Container className="max-w-xl mx-auto bg-white p-6">
<Img
src={brandAssets.logo.src}
alt={brandAssets.logo.alt}
width={brandAssets.logo.width}
className="mx-auto mb-6"
/>
<Button className="bg-brand-primary text-white rounded px-5 py-3">
Call to Action
</Button>
</Container>
</Body>
</Tailwind>
Direct users to place brand assets in appropriate locations:
emails/static/.Font component with a web font URL (Google Fonts, Adobe Fonts, or self-hosted).Example prompt for gathering brand info:
"Before I create your email template, I need some brand information to ensure consistency. Could you provide:
- Your primary brand color (hex code, e.g., #007bff)
- Your logo URL (must be a publicly accessible PNG or JPEG)
- Any secondary colors you'd like to use
- Style preference (modern/minimal or classic/traditional)"
Replace the sample email templates. Here is how to create a new email template:
Create an email component with proper structure using the Tailwind component for styling:
import * as React from "react";
import {
Html,
Head,
Preview,
Body,
Container,
Heading,
Text,
Button,
Tailwind,
pixelBasedPreset
} from '@react-email/components';
interface WelcomeEmailProps {
name: string;
verificationUrl: string;
}
export default function WelcomeEmail({ name, verificationUrl }: WelcomeEmailProps) {
return (
<Html lang="en">
<Tailwind
config={{
presets: [pixelBasedPreset],
theme: {
extend: {
colors: {
brand: '#007bff',
},
},
},
}}
>
<Head />
<Preview>Welcome - Verify your email</Preview>
<Body className="bg-gray-100 font-sans">
<Container className="max-w-xl mx-auto p-5">
<Heading className="text-2xl text-gray-800">
Welcome!
</Heading>
<Text className="text-base text-gray-800">
Hi {name}, thanks for signing up!
</Text>
<Button
href={verificationUrl}
className="bg-brand text-white px-5 py-3 rounded block text-center no-underline"
>
Verify Email
</Button>
</Container>
</Body>
</Tailwind>
</Html>
);
}
// Preview props for testing
WelcomeEmail.PreviewProps = {
name: 'John Doe',
verificationUrl: 'https://example.com/verify/abc123'
} satisfies WelcomeEmailProps;
export { WelcomeEmail };
See references/COMPONENTS.md for complete component documentation.
Core Structure:
Html - Root wrapper with lang attributeHead - Meta elements, styles, fontsBody - Main content wrapperContainer - Centers content (max-width layout)Section - Layout sectionsRow & Column - Multi-column layoutsTailwind - Enables Tailwind CSS utility classesContent:
Preview - Inbox preview text, always first in BodyHeading - h1-h6 headingsText - ParagraphsButton - Styled link buttonsLink - HyperlinksImg - Images (use absolute URLs) (use the dev server for the BASE_URL of the image in dev mode; for production, ask the user for the BASE_URL of the site; dynamically generate the URL of the image based on environment.)Hr - Horizontal dividersSpecialized:
CodeBlock - Syntax-highlighted codeCodeInline - Inline codeMarkdown - Render markdownFont - Custom web fontstailwind.config.ts file exists in the emails directory, use it for all new templates.tailwind.config.ts and offer to update existing templates.const EmailTemplate = (props) => {
return (
{/* ... rest of the code ... */}
<h1>Hello, {props.variableName}!</h1>
{/* ... rest of the code ... */}
);
}
EmailTemplate.PreviewProps = {
// ... rest of the props ...
variableName: "{{variableName}}",
// ... rest of the props ...
};
export default EmailTemplate;
Use the Tailwind component with pixelBasedPreset for styling (email clients don't support rem units). If not using Tailwind, use inline styles.
Critical limitations (email clients don't support these):
Row/Column components or tablessm:, md:, etc.) or theme selectors (dark:, light:)border-solid, etc.)Structure rules:
<Head /> inside <Tailwind> when using TailwindPreviewProps that the component usesSee references/STYLING.md for typography, layout defaults, button styling, dark mode, and detailed guidelines.
import { render } from '@react-email/components';
import { WelcomeEmail } from './emails/welcome';
const html = await render(
<WelcomeEmail name="John" verificationUrl="https://example.com/verify" />
);
import { render } from '@react-email/components';
import { WelcomeEmail } from './emails/welcome';
const text = await render(<WelcomeEmail name="John" verificationUrl="https://example.com/verify" />, { plainText: true });
React Email supports sending with any email service provider. If the user wants to know how to send, view the Sending guidelines.
Quick example using the Resend SDK for Node.js:
import * as React from "react";
import { Resend } from 'resend';
import { WelcomeEmail } from './emails/welcome';
const resend = new Resend(process.env.RESEND_API_KEY);
const { data, error } = await resend.emails.send({
from: 'Acme <onboarding@resend.dev>',
to: ['user@example.com'],
subject: 'Welcome to Acme',
react: <WelcomeEmail name="John" verificationUrl="https://example.com/verify" />
});
if (error) {
console.error('Failed to send:', error);
}
The Node SDK automatically handles the plain-text rendering and HTML rendering for you.
See references/I18N.md for complete i18n documentation.
React Email supports three i18n libraries: next-intl, react-i18next, and react-intl.
import * as React from "react";
import { createTranslator } from 'next-intl';
import {
Html,
Body,
Container,
Text,
Button,
Tailwind,
pixelBasedPreset
} from '@react-email/components';
interface EmailProps {
name: string;
locale: string;
}
export default async function WelcomeEmail({ name, locale }: EmailProps) {
const t = createTranslator({
messages: await import(\`../messages/\${locale}.json\`),
namespace: 'welcome-email',
locale
});
return (
<Html lang={locale}>
<Tailwind config={{ presets: [pixelBasedPreset] }}>
<Body className="bg-gray-100 font-sans">
<Container className="max-w-xl mx-auto p-5">
<Text className="text-base text-gray-800">{t('greeting')} {name},</Text>
<Text className="text-base text-gray-800">{t('body')}</Text>
<Button href="https://example.com" className="bg-blue-600 text-white px-5 py-3 rounded">
{t('cta')}
</Button>
</Container>
</Body>
</Tailwind>
</Html>
);
}
Message files (`messages/en.json`, `messages/es.json`, etc.):
{
"welcome-email": {
"greeting": "Hi",
"body": "Thanks for signing up!",
"cta": "Get Started"
}
}
Test across email clients - Test in Gmail, Outlook, Apple Mail, Yahoo Mail. Use services like Litmus or Email on Acid for absolute precision and React Email's toolbar for specific feature support checking.
Keep it responsive - Max-width around 600px, test on mobile devices.
Use absolute image URLs - Host on reliable CDN, always include alt text.
Provide plain text version - Required for accessibility and some email clients. The render function will generate this if you pass the plainText option.
Keep file size under 102KB - Gmail clips larger emails.
Add proper TypeScript types - Define interfaces for all email props.
Include preview props - Add .PreviewProps to components for development testing.
Handle errors - Always check for errors when sending emails.
See references/PATTERNS.md for complete examples including:
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer