0
# MJML Wrapper
1

2
MJML Wrapper is a specialized component within the MJML email framework that enables wrapping multiple sections together for creating nested layouts with shared borders, background colors, and background images across sections. It extends the functionality of the standard MJML section component to support complex multi-section layouts while maintaining full compatibility with Outlook's VML limitations.
3

4
**Important**: While `mjml-wrapper` exists as a separate npm package, it is typically installed and used as part of the main `mjml` package, which includes all core components in a preset.
5

6
## Package Information
7

8
- **Package Name**: mjml-wrapper
9
- **Package Type**: npm
10
- **Language**: JavaScript
11
- **Installation**: `npm install mjml` (mjml-wrapper is included as part of the core MJML package)
12
- **Version**: 4.15.3
13
- **Dependencies**: mjml-core, mjml-section, lodash, @babel/runtime
14

15
## Core Imports
16

17
MJML Wrapper is used declaratively within MJML markup and does not require direct JavaScript imports for typical usage:
18

19
```xml
20
<mjml>
21
  <mj-body>
22
    <mj-wrapper>
23
      <!-- sections go here -->
24
    </mj-wrapper>
25
  </mj-body>
26
</mjml>
27
```
28

29
For programmatic usage or custom component development, mjml-wrapper is included with the main mjml package:
30

31
```javascript
32
import mjml from 'mjml';
33
// mjml-wrapper is automatically registered as part of the core preset
34
```
35

36
Direct import (for component extension):
37

38
```javascript
39
import MjWrapper from 'mjml-wrapper';
40
```
41

42
## Basic Usage
43

44
```xml
45
<mjml>
46
  <mj-body>
47
    <mj-wrapper border="1px solid #000000" background-color="#f4f4f4" padding="30px">
48
      <mj-section border="1px solid #dddddd" padding="20px">
49
        <mj-column>
50
          <mj-text>First section content</mj-text>
51
        </mj-column>
52
      </mj-section>
53
      <mj-section border="1px solid #dddddd" padding="20px">
54
        <mj-column>
55
          <mj-text>Second section content</mj-text>
56
        </mj-column>
57
      </mj-section>
58
    </mj-wrapper>
59
  </mj-body>
60
</mjml>
61
```
62

63
## Capabilities
64

65
### Component Definition
66

67
The MjWrapper component extends MjSection to provide wrapper functionality for multiple sections.
68

69
```javascript { .api }
70
class MjWrapper extends MjSection {
71
  static componentName: 'mj-wrapper';
72
  static allowedAttributes: object; // Inherits all attributes from MjSection
73
  static defaultAttributes: object; // Inherits default values from MjSection
74
  
75
  /**
76
   * Renders wrapped child sections with Outlook-compatible table structure
77
   * @returns {string} HTML markup for wrapped child components
78
   */
79
  renderWrappedChildren(): string;
80
  
81
  /**
82
   * Provides context to child components including container width
83
   * @returns {object} Child context with containerWidth
84
   */
85
  getChildContext(): object;
86
}
87
```
88

89
### Supported Attributes
90

91
All attributes inherited from MjSection are supported:
92

93
```typescript { .api }
94
interface MjWrapperAttributes {
95
  'background-color'?: string;           // Section background color
96
  'background-url'?: string;             // Background image URL  
97
  'background-repeat'?: 'repeat' | 'no-repeat';  // CSS background repeat (default: 'repeat')
98
  'background-size'?: string;            // CSS background size (default: 'auto')
99
  'background-position'?: string;        // CSS background position (default: 'top center')
100
  'background-position-x'?: string;      // CSS background position X
101
  'background-position-y'?: string;      // CSS background position Y
102
  'border'?: string;                     // CSS border format
103
  'border-bottom'?: string;              // CSS border format
104
  'border-left'?: string;                // CSS border format
105
  'border-radius'?: string;              // Border radius
106
  'border-right'?: string;               // CSS border format
107
  'border-top'?: string;                 // CSS border format
108
  'direction'?: 'ltr' | 'rtl';          // Text direction (default: 'ltr')
109
  'full-width'?: 'full-width' | '';     // Make wrapper full-width
110
  'padding'?: string;                    // Padding supports up to 4 parameters (default: '20px 0')
111
  'padding-top'?: string;                // Section top offset
112
  'padding-bottom'?: string;             // Section bottom offset
113
  'padding-left'?: string;               // Section left offset
114
  'padding-right'?: string;              // Section right offset
115
  'text-align'?: 'left' | 'center' | 'right'; // CSS text alignment (default: 'center')
116
  'text-padding'?: string;               // Text padding (default: '4px 4px 4px 0')
117
  'css-class'?: string;                  // CSS class name added to root HTML element
118
}
119
```
120

121
### Component Hierarchy
122

123
MjWrapper supports specific child and parent components within the MJML structure:
124

125
```typescript { .api }
126
interface MjWrapperHierarchy {
127
  // Valid parent components
128
  parents: ['mj-body'];
129
  
130
  // Valid child components that can be placed inside mj-wrapper
131
  children: ['mj-hero', 'mj-raw', 'mj-section'];
132
}
133
```
134

135
### Wrapper Rendering
136

137
The core rendering method that handles the wrapper layout:
138

139
```javascript { .api }
140
/**
141
 * Renders wrapped child sections with Outlook-compatible table structure
142
 * @returns {string} HTML markup for wrapped child components
143
 */
144
renderWrappedChildren(): string;
145
```
146

147
**Usage Examples:**
148

149
Basic wrapper with multiple sections:
150

151
```xml
152
<mj-wrapper background-color="#ffffff" border="2px solid #e0e0e0" padding="40px 20px">
153
  <mj-section background-color="#f9f9f9" padding="20px">
154
    <mj-column>
155
      <mj-image src="https://example.com/header.jpg" alt="Header" />
156
    </mj-column>
157
  </mj-section>
158
  <mj-section background-color="#ffffff" padding="30px">
159
    <mj-column>
160
      <mj-text font-size="16px" color="#333333">
161
        Main content section with shared wrapper styling.
162
      </mj-text>
163
    </mj-column>
164
  </mj-section>
165
</mj-wrapper>
166
```
167

168
Wrapper with mj-hero component (hero sections can also be wrapped):
169

170
```xml
171
<mj-wrapper background-color="#4a90e2" padding="30px">
172
  <mj-hero 
173
    mode="fluid-height"
174
    background-url="https://example.com/hero-bg.jpg"
175
    background-size="cover"
176
    padding="100px 0">
177
    <mj-text color="#ffffff" font-size="24px" align="center">
178
      Hero content within wrapper
179
    </mj-text>
180
  </mj-hero>
181
</mj-wrapper>
182
```
183

184
### Full-Width Support
185

186
Enable full-width wrapper for edge-to-edge backgrounds:
187

188
```xml
189
<mj-wrapper full-width="full-width" background-color="#4a90e2" padding="50px 0">
190
  <mj-section>
191
    <mj-column>
192
      <mj-text color="#ffffff" align="center">
193
        Full-width wrapper with centered content
194
      </mj-text>
195
    </mj-column>
196
  </mj-section>
197
</mj-wrapper>
198
```
199

200
### Background Image Handling
201

202
Apply background images across multiple sections:
203

204
```xml
205
<mj-wrapper 
206
  background-url="https://example.com/background.jpg" 
207
  background-size="cover" 
208
  background-position="center center"
209
  background-repeat="no-repeat"
210
  padding="60px 30px">
211
  <mj-section background-color="rgba(255,255,255,0.9)" padding="30px">
212
    <mj-column>
213
      <mj-text>Content with semi-transparent background over image</mj-text>
214
    </mj-column>
215
  </mj-section>
216
  <mj-section background-color="rgba(0,0,0,0.8)" padding="30px">
217
    <mj-column>
218
      <mj-text color="#ffffff">Contrasting section with same background image</mj-text>
219
    </mj-column>
220
  </mj-section>
221
</mj-wrapper>
222
```
223

224
## Key Features
225

226
### Outlook Compatibility
227
- Generates VML-compatible markup for Outlook desktop clients
228
- Handles nested table structures required for complex layouts
229
- Manages z-index limitations in Outlook's rendering engine
230

231
### Nested Layout Support
232
- Enables shared styling across multiple sections
233
- Maintains proper spacing and borders between wrapped sections  
234
- Supports both standard and full-width layout modes
235

236
### Background Management
237
- Allows background images to span multiple sections
238
- Handles background positioning, sizing, and repeat options
239
- Provides fallback support for clients with limited CSS support
240

241
## Important Limitations
242

243
### Outlook VML Restrictions
244
- Cannot nest full-width sections inside full-width wrappers
245
- Background images on wrapper and child sections may conflict in Outlook Desktop
246
- Z-index properties are ignored in most Outlook VML contexts
247

248
### Background Layering
249
- If using background-url on mj-wrapper, avoid background-url on child sections
250
- Background-color on wrapper will appear over background-images on child sections in Outlook Desktop
251
- No reliable way to control layer ordering due to VML limitations
252

253
## Component Architecture
254

255
The MjWrapper component follows MJML's component architecture:
256

257
### Component Registration
258

259
MjWrapper is automatically registered as part of the MJML core preset:
260

261
```javascript { .api }
262
// Component is included in mjml-preset-core and automatically available
263
// when using the main mjml package
264
import mjml from 'mjml';
265

266
// The component is registered via:
267
// mjml-preset-core -> components -> mjml-wrapper
268
```
269

270
### Architecture Details
271

272
- **Extends**: MjSection (inherits all section functionality including styling, background handling, and VML generation)
273
- **Component Name**: 'mj-wrapper' (used in MJML markup)
274
- **Rendering**: Overrides `renderWrappedChildren()` for specialized wrapper behavior with Outlook-compatible table nesting
275
- **Context**: Provides containerWidth context to child components via `getChildContext()`
276
- **Dependencies**: Requires mjml-core for BodyComponent base class and mjml-section for inheritance