Layout Components
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/COMPONENTS.md
- skills/react-email/references/STYLING.md
- apps/web/components/structure.ts
- packages/react-email/src/components/container/container.tsx
- packages/react-email/src/components/section/section.tsx
- packages/react-email/src/components/row/row.tsx
- packages/react-email/src/components/column/column.tsx
Layout components in React Email provide high-quality, unstyled primitives for building responsive email structures. These components abstract the complexity of table-based layouts, ensuring consistency across archaic email clients like Outlook and modern clients like Gmail. By using a component-based approach, they replace manual table nesting and CSS hacks with a clean, declarative API.
These components handle specific email client inconsistencies, such as dark mode support and responsive behavior, while maintaining a standard max-width for optimal readability.
Sources: README.md:15-18, skills/react-email/SKILL.md:130-140, skills/react-email/references/COMPONENTS.md:12-32
Core Structural Architecture
The layout system follows a specific hierarchy to ensure accessibility and cross-client compatibility. The system renders layout tables with role="presentation" by default to prevent screen readers from announcing them as data tables.
Layout Hierarchy
The following diagram illustrates the standard nesting order for layout components within a React Email template.
The hierarchy ensures that styles are applied globally via Tailwind before content is centered and structured.
Sources: skills/react-email/references/COMPONENTS.md:88-92, skills/react-email/references/STYLING.md:46-52
Container
The Container is a layout component that centers content horizontally on a breaking point. It applies a built-in maximum width constraint of 37.5em (approximately 600px), which is the standard for email templates to ensure readability and mobile responsiveness.
- Usage: Use only once per email as the outermost centering wrapper.
- Default Styling: Typically configured with a white background and centered via
mx-auto.
Sources: skills/react-email/SKILL.md:135, skills/react-email/references/COMPONENTS.md:104-106, skills/react-email/references/STYLING.md:65-67
Section
The Section component divides content into distinct blocks. Unlike the Container, it has no built-in max-width, making it suitable for interior content grouping.
- Functionality: Groups related elements like text, images, and buttons.
- Nesting: Sections often contain
RowandColumncomponents for internal layout. - Accessibility: Renders as a table with
role="presentation".
Sources: skills/react-email/SKILL.md:136, skills/react-email/references/COMPONENTS.md:112-114, apps/web/components/structure.ts:51-57
Multi-Column Layouts (Row and Column)
Because email clients have limited support for CSS Flexbox and Grid, React Email provides Row and Column components to create horizontal layouts. A Column must always be used within a Row.
Components and Data Flow
| Component | Description | Requirements |
|---|---|---|
Row | Separates content areas horizontally. | Acts as a wrapper for one or more Column components. |
Column | Separates content areas vertically. | Must be a direct child of a Row. |
Sources: skills/react-email/references/COMPONENTS.md:121-125, skills/react-email/references/STYLING.md:27-28
Implementation Logic
When building multi-column layouts, you must specify widths to maintain structure across clients.
- Widths: Use percentage-based widths (e.g.,
w-1/2) or Tailwind width utilities. - Alignment: Use vertical alignment classes (e.g.,
align-top) to ensure content aligns correctly if column heights differ. - Limitations: Avoid media queries (e.g.,
sm:,md:) as they are not supported by most email clients.
This diagram shows the horizontal data flow within a single layout row.
Sources: skills/react-email/references/COMPONENTS.md:127-140, skills/react-email/references/STYLING.md:108-113
Layout Component Summary
The following table summarizes the key layout components and their primary purposes as defined in the project structure.
| Category | Component | Slug (Identifier) | Description |
|---|---|---|---|
| Container | Simple Container | simple-container | Standard centering wrapper for all email content. |
| Section | Simple Section | simple-section | Basic content divider for grouping elements. |
| Grid | One Row, Two Columns | one-row-two-columns | A standard two-column layout using Row and Column. |
| Grid | One Row, Three Columns | one-row-three-columns | A three-column layout variant. |
| Divider | Simple Divider | simple-divider | Visual separation between rows or sections. |
Sources: apps/web/components/structure.ts:44-77
Technical Constraints and Best Practices
- No Flexbox/Grid: Email clients do not support modern CSS layout engines; always use
RowandColumncomponents. - Pixel-Based Units: Email clients do not support
rem. When using Tailwind for layouts, ensure thepixelBasedPresetis active to convert units topx. - Standard Width: Keep the main container max-width around 600px to prevent clipping in clients like Gmail.
- Borders: Always specify a border style (e.g.,
border-solid) as clients do not inherit this property.
Sources: skills/react-email/SKILL.md:188-195, skills/react-email/references/STYLING.md:18-20, skills/react-email/references/STYLING.md:32-40
Layout components form the foundation of the React Email ecosystem. They translate modern React code into the rigid table structures required by legacy email clients, allowing developers to focus on content rather than markup hacks. Through the combination of Container, Section, Row, and Column, complex and responsive email designs become maintainable and accessible.
Sources: README.md:15-18, skills/react-email/SKILL.md:130-140