Styling Limitations & Best Practices

Relevant source files

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

• README.md
• skills/react-email/SKILL.md
• skills/react-email/references/STYLING.md
• skills/react-email/references/COMPONENTS.md
• skills/react-email/TESTS.md
• packages/react-email/src/components/tailwind/utils/tailwindcss/tailwind-stylesheets/index.ts

React Email uses high-quality, unstyled components to create responsive emails. It handles inconsistencies between major email clients like Gmail and Outlook by converting React components into table-based HTML layouts.

This guide outlines the specific technical constraints of email rendering and the recommended patterns for applying styles using Tailwind CSS or inline properties.

Styling Architecture and Data Flow

The Tailwind component serves as a wrapper that processes utility classes into email-compatible formats. It automatically performs three primary actions:

1. Converts utility classes into inline styles.
2. Resolves CSS variables.
3. Normalizes RGB color syntax for broader client compatibility.

Sources: skills/react-email/references/COMPONENTS.md:46-52

Style Processing Flow

The following diagram illustrates how the Tailwind component transforms source code into final email markup.

The Tailwind component extracts media queries to a <style> tag in the <head>, though many email clients ignore these.
Sources: skills/react-email/references/COMPONENTS.md:50-51

Core Limitations

Email clients use archaic rendering engines that do not support modern CSS features like Flexbox or Grid. You must use specific alternatives to ensure layout consistency.

Unsupported CSS Features

Feature	Limitation	Alternative
Flexbox / Grid	Outlook and other clients ignore display: flex and display: grid.	Use Row and Column components or standard tables.
Media Queries	Gmail and Outlook often strip or ignore sm:, md:, lg: prefixes.	Use a mobile-first, single-column stacked layout.
rem units	Email clients do not consistently interpret rem.	Use the pixelBasedPreset to convert units to px.
Theme Selectors	The dark: prefix is not supported.	Apply dark colors directly to styles if a dark theme is required.
SVG / WEBP	These formats fail to render in most major clients.	Use PNG or JPEG images only.

Sources: skills/react-email/SKILL.md:120-128, skills/react-email/references/STYLING.md:24-34, skills/react-email/TESTS.md:42-50

Unit Conversion Requirement

Always include the pixelBasedPreset in your Tailwind configuration. This preset converts Tailwind's default rem values into px values, which are required for reliable email rendering.

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

<Tailwind config={{ presets: [pixelBasedPreset] }}>
  {/* Content */}
</Tailwind>

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

Best Practices for Layout and Components

Multi-Column Layouts

Multi-column layouts must rely on the Row and Column components. These components render as HTML tables to maintain alignment. You should define percentage-based widths for columns to ensure they total 100%.

Essential Component Rules

Certain components require specific utility classes to prevent rendering bugs in Outlook and Gmail.

Component	Required Class	Technical Reason
Button	box-border	Prevents padding from overflowing the button's defined width.
Hr / Borders	border-solid	Email clients do not inherit default border styles (e.g., solid).
Single Borders	border-none	Reset default borders on all sides before applying a specific side (e.g., border-t).

Sources: skills/react-email/SKILL.md:136-141, skills/react-email/references/STYLING.md:109-116

Asset Management

Image URL Handling

Images must use absolute URLs and be hosted on a public CDN. For development, use a baseURL pattern that switches between the local dev server and the production CDN based on NODE_ENV.

Image Attributes

• Dimensions: Set explicit width and height on the Img component to prevent layout shifts.
• Accessibility: Provide descriptive alt text for meaningful images. Use alt="" for decorative images (e.g., dividers) so screen readers skip them.
• Linked Images: Never leave alt empty if the image is inside a Link or Button. The alt text must describe the link's destination.

Sources: skills/react-email/references/COMPONENTS.md:195-212, skills/react-email/references/STYLING.md:88-93

Typography and Hierarchy

Establish a clear visual hierarchy using the Heading and Text components.

• Headings: Use as="h1" through as="h6". Do not skip heading levels.
• Spacing: Apply larger margins to headings and smaller margins to body text for consistent vertical rhythm.
• Standard Defaults: The system uses a sans-serif stack including system-ui and Apple Color Emoji by default.

Sources: packages/react-email/src/components/tailwind/utils/tailwindcss/tailwind-stylesheets/index.ts:5-8, skills/react-email/references/STYLING.md:75-83

Summary

Styling for React Email requires a strict adherence to table-based layouts and pixel-based units. By utilizing the Tailwind component with the pixelBasedPreset, developers can use familiar utility classes while the system handles the complexities of cross-client compatibility. Avoid modern CSS layout engines and non-standard image formats to ensure emails reach recipients as intended.