React Email 5.0: Tailwind 4, Dark Mode Theming, and What Changes for Your Templates

What shipped in React Email 5.0

React Email hit 920,000+ weekly npm downloads before this release. Version 5.0 is a big architecture change. Here's what matters for your templates:

The CSS compatibility checker is the sleeper hit. It scans your template output and flags properties that specific email clients ignore. Instead of finding out that gapdoesn't work in Outlook after 200 users get a broken layout, you catch it at dev time.

The Tailwind 4 migration for email templates

Tailwind 4 is a full engine rewrite. The config file moves from tailwind.config.jsto a CSS-first approach, and a bunch of utility classes get renamed. For a Next.js app, the upgrade is quick. For email templates, it's more work because every class ultimately becomes an inline style.

The automated upgrade tool handles the class renames:

# Run the Tailwind upgrade tool
npx @tailwindcss/upgrade

# Common renames it handles automatically:
# bg-gradient-to-r  →  bg-linear-to-r
# flex-shrink-0     →  shrink-0
# flex-grow         →  grow
# overflow-clip     →  overflow-clip (unchanged but re-validated)

That covers roughly 90% of the changes. The remaining 10% is where email templates diverge from web apps:

// ❌ React Email 4.x: className on components inlined styles
<Section className="bg-white py-8 px-6">
  <Text className="text-gray-900 text-sm">Hello</Text>
</Section>

// ✅ React Email 5.0: className only inlines on elements
// Wrapper components need explicit style props or Tailwind on inner elements
<Section style={{ backgroundColor: "#ffffff", padding: "32px 24px" }}>
  <Text className="text-gray-900 text-sm">Hello</Text>
</Section>

This is the one that bites people. If you built custom layout components that rely on className for spacing and backgrounds, those styles silently disappear after the upgrade. The template renders fine, but the visual output is wrong. Every custom wrapper in your library needs a review.

Native dark mode theming

Before 5.0, dark mode in email required stacking @media (prefers-color-scheme: dark) blocks with !important overrides and hoping each client respected them. Gmail stripped most of it. Outlook ignored all of it. Apple Mail worked but only sometimes.

The 5.0 theming system handles the client-specific workarounds for you. Define your theme once and the renderer outputs the right mix of inline styles, media queries, and MSO conditionals per client:

import { Theme, Email, Section, Text } from "@react-email/components";

const theme = {
  light: {
    bg: "#ffffff",
    text: "#1a1a1a",
    muted: "#6b7280",
    accent: "#f59e0b",
  },
  dark: {
    bg: "#111827",
    text: "#f9fafb",
    muted: "#9ca3af",
    accent: "#fbbf24",
  },
};

export function WelcomeEmail({ name }: { name: string }) {
  return (
    <Theme value={theme}>
      {({ colors }) => (
        <Email>
          <Section style={{ backgroundColor: colors.bg, padding: "32px" }}>
            <Text style={{ color: colors.text, fontSize: "16px" }}>
              Welcome to the team, {name}.
            </Text>
          </Section>
        </Email>
      )}
    </Theme>
  );
}

The output works across Gmail, Apple Mail, Outlook (desktop and web), and Yahoo Mail. No more maintaining a spreadsheet of which hacks work in which client.

The real cost of migrating

The migration isn't hard. It's tedious. You run the upgrade tool, fix the class renames it misses, audit every component that uses className, re-test in Litmus or Email on Acid, fix the Outlook quirks that the CSS checker surfaces, and repeat for every template. The code changes are small, but the testing loop multiplied across templates adds up.

If your templates are battle-tested and tightly coupled to your brand, migrate them. If you're still on generic templates or building new flows, a production-ready template bundle that already runs on React Email 5.0 is the faster path.

Upgrade checklist

Whether you migrate or start fresh, here's the rundown:

# 1. Update both packages together
npm install react-email@latest @react-email/components@latest

# 2. Run the Tailwind upgrade tool
npx @tailwindcss/upgrade

# 3. Search for className on custom wrapper components
grep -rn "className" ./emails/components/

# 4. Run the CSS compatibility checker
npx react-email check ./emails/

# 5. Test dark mode in preview
npx react-email dev