Document Shell Components
Relevant source files
The following files were used as context for generating this wiki page:
Document Shell Components provide the foundational structure for HTML email templates. These components manage the boilerplate required for cross-client compatibility, including document type definitions, meta tags, and high-level layout wrappers.
The shell system ensures that emails render consistently across major clients like Gmail, Outlook, and Apple Mail by handling inconsistencies in table-based layouts and archaic markup. It reduces development friction for responsive emails and dark mode support.
Sources: README.md:14-17, skills/react-email/SKILL.md:12-14
Component Architecture
The document shell follows a strict nesting hierarchy to ensure valid HTML generation and proper style extraction.
This diagram shows the standard nesting order for Document Shell components.
Sources: skills/react-email/references/COMPONENTS.md:53-61, skills/react-email/references/STYLING.md:40-47
Core Component Definitions
| Component | Description | Key Attributes |
|---|---|---|
Html | The root wrapper for the entire email. | lang, dir |
Head | Contains document-level metadata, styles, and fonts. | N/A |
Body | The main visible content wrapper for the email. | className |
Preview | Hidden text displayed in the recipient's inbox preview. | N/A |
Sources: skills/react-email/references/COMPONENTS.md:11-30
Html
The Html component acts as the outermost container. It sets global attributes for the document, such as language and text direction, which are critical for accessibility and internationalization.
- lang: Defines the language code (e.g., "en", "es").
- dir: Sets the text direction ("ltr" or "rtl").
Sources: skills/react-email/references/COMPONENTS.md:73-83, skills/react-email/SKILL.md:275-278
Head
The Head component manages document metadata. It serves as the injection point for styles generated by the Tailwind component and web fonts defined via the Font component.
- Placement: You must define
<Head />inside the<Tailwind>component when using utility-based styling to ensure media queries are correctly extracted to the<style>tag. - Functionality: It automatically handles structural defaults, such as emitting a
<title>tag derived from thePreviewcomponent.
Sources: skills/react-email/references/STYLING.md:40-47, skills/react-email/references/COMPONENTS.md:85-92, skills/react-email/SKILL.md:273-273
Body and Layout
The Body and Container components define the visual canvas and horizontal constraints of the email.
Body Component
The Body component wraps the email's content. It is typically used to apply global background colors and font families to the entire message.
Sources: skills/react-email/references/COMPONENTS.md:94-100, skills/react-email/references/STYLING.md:52-54
Container Component
The Container component centers content horizontally. It includes a built-in max-width constraint of 37.5em (approximately 600px).
- Constraint: Use only once per email as the outermost centering wrapper.
- Alignment: It defaults to centering the content on a breaking point.
Sources: skills/react-email/references/COMPONENTS.md:102-108, skills/react-email/SKILL.md:112-113
Preview
The Preview component provides the "snippet" text seen in email clients before the message is opened.
- Placement: It must always be the first element inside the
<Body>component. - Character Limit: Maintain a length under 140 characters for optimal display.
- Behavior: In addition to the inbox snippet, it emits a
<title>tag within the document head for accessibility.
Sources: skills/react-email/references/COMPONENTS.md:162-177, skills/react-email/SKILL.md:144-144, skills/react-email/SKILL.md:273-273
Data Flow and Rendering
The shell components interact during the rendering process to transform React components into email-ready HTML.
This diagram illustrates the flow from a React template through the serialization process to generate the final shell-wrapped HTML.
Sources: packages/editor/src/core/serializer/compose-react-email.spec.tsx:288-293, skills/react-email/references/EDITOR.md:200-207
Implementation Summary
When constructing the document shell, follow these steps:
- Wrap the entire template in
Html. - Wrap content in
TailwindandpixelBasedPresetto handle CSS-to-inline conversion. - Place
Headinside the styling wrapper. - Place
Previewimmediately after theBodytag. - Use a single
Containerfor the main content area.
Sources: skills/react-email/SKILL.md:53-87, skills/react-email/references/STYLING.md:40-47