Tailwind CSS Integration

Relevant source files

The following files were used as context for generating this wiki page:

• packages/react-email/src/components/tailwind/tailwind.tsx
• packages/react-email/src/components/tailwind/utils/css/make-inline-styles-for.ts
• packages/react-email/src/components/tailwind/utils/tailwindcss/setup-tailwind.ts
• skills/react-email/references/STYLING.md
• packages/react-email/src/components/tailwind/tailwind.spec.tsx
• packages/react-email/CHANGELOG.md

Tailwind CSS Integration provides a wrapper component that enables utility-first styling for React Email templates. The Tailwind component processes React children to convert standard Tailwind classes into inline styles and embedded CSS for email client compatibility.

This module automates the conversion of modern CSS features into the restricted formats required by inbox providers like Gmail, Outlook, and Apple Mail. It specifically addresses email-specific limitations such as lack of rem unit support and limited media query execution.

Core Component: Tailwind

The Tailwind component serves as the primary entry point for styling templates. It wraps the entire email structure or specific sections to process utility classes within its scope.

Processing Workflow

1. The component parses the React tree for className attributes.
2. The internal engine generates a stylesheet based on the provided configuration.
3. The engine resolves CSS variables and normalizes color formats (e.g., converting rgba to rgb).
4. Inlinable styles apply directly to the style prop of child elements.
5. Non-inlinable styles, such as media queries and dark mode selectors, inject into a <style> block within the <Head> component.

The diagram shows the transformation of utility classes into email-compatible styles.
Sources: packages/react-email/src/components/tailwind/tailwind.tsx, packages/react-email/src/components/tailwind/utils/css/make-inline-styles-for.ts

Component Properties

The Tailwind component accepts several configuration properties to customize the styling engine.

Property	Type	Description
config	TailwindConfig	Standard Tailwind configuration object including themes, plugins, and presets.
theme	string	A CSS string for Tailwind v4 CSS-first configuration (e.g., @theme blocks).
utility	string	A CSS string for custom utility definitions.
children	React.ReactNode	The email template components to be styled.

Sources: packages/react-email/src/components/tailwind/tailwind.tsx:49-65, packages/react-email/CHANGELOG.md

Technical Implementation Details

Pixel-Based Scaling

Email clients generally lack support for rem units. To ensure consistent rendering, you must use the pixelBasedPreset. This preset converts all rem-based utility values into absolute pixel values.

import { Tailwind, pixelBasedPreset } from 'react-email';

<Tailwind config={{ presets: [pixelBasedPreset] }}>
  <Body className="p-4"> {/* Converted to 16px padding */}
    ...
  </Body>
</Tailwind>

Sources: skills/react-email/references/STYLING.md, skills/react-email/SKILL.md

Style Inlining and Normalization

The integration performs automatic normalization to fix common email rendering issues:

• RGB Normalization: It converts rgba(r g b / a) syntax to the more widely supported rgb(r,g,b,a) format.
• Variable Stripping: It resolves and removes unresolved --tw-* CSS variables in non-inlinable rules to prevent Gmail from breaking.
• Logical Shorthands: It splits two-value logical shorthands (like margin-inline) into specific per-side declarations for better client support.

Sources: packages/react-email/CHANGELOG.md, packages/react-email/src/components/tailwind/utils/css/make-inline-styles-for.ts

Media Query and Dark Mode Handling

Responsive classes (e.g., sm:, md:) and theme selectors (e.g., dark:) require the presence of a <Head> component inside the Tailwind wrapper.

The sequence illustrates the requirement for a Head component when using non-inlinable CSS.
Sources: packages/react-email/src/components/tailwind/tailwind.tsx:90-110, packages/react-email/src/components/tailwind/tailwind.spec.tsx

Usage Guidelines and Constraints

To maintain template integrity across various email clients, follow these constraints derived from the codebase:

• Border Handling: Email clients often fail to inherit border styles. You must specify the border type (e.g., border-solid) explicitly when using border width utilities.
• Box-Sizing: Always apply box-border to Button components to prevent padding from overflowing the element width.
• Head Placement: Define the <Head /> component inside the <Tailwind> wrapper. The system will throw an error if media-query variants are detected without a target <head> element in the tree.
• Layout Restriction: Do not use Flexbox or Grid. Use Row and Column components instead, as Tailwind's flex/grid utilities have poor email client support.

Sources: skills/react-email/references/STYLING.md, packages/react-email/src/components/tailwind/tailwind.spec.tsx

Summary

Tailwind CSS Integration allows developers to use modern utility classes while ensuring high compatibility with archaic email clients. By combining automatic style inlining with a pixel-based conversion engine, the system bridges the gap between web development standards and email development requirements. Always prioritize the pixelBasedPreset and include a <Head> component for responsive templates.