0
# MJML Group
1
2
MJML Group is a component for the MJML email framework that prevents columns from stacking on mobile devices. It maintains side-by-side column layouts in responsive emails, essential for complex multi-column email designs that need to preserve their structure across desktop and mobile email clients.
3
4
## Package Information
5
6
- **Package Name**: mjml-group
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install mjml-group`
10
11
## Core Imports
12
13
```javascript
14
// ES Modules
15
import MjGroup from "mjml-group";
16
17
// CommonJS
18
const MjGroup = require("mjml-group");
19
```
20
21
## Basic Usage
22
23
MJML Group is used within MJML templates to wrap columns that should remain side-by-side on mobile:
24
25
```xml
26
<mjml>
27
<mj-body>
28
<mj-section>
29
<mj-group width="100%" background-color="#f0f0f0">
30
<mj-column width="50%">
31
<mj-text>Left column content</mj-text>
32
</mj-column>
33
<mj-column width="50%">
34
<mj-text>Right column content</mj-text>
35
</mj-column>
36
</mj-group>
37
</mj-section>
38
</mj-body>
39
</mjml>
40
```
41
42
## Architecture
43
44
MJML Group extends the MJML BodyComponent base class and integrates with the MJML ecosystem:
45
46
- **Component Registration**: Registered with MJML as `mj-group` tag
47
- **Width Calculation**: Sophisticated responsive width calculations supporting both percentage and pixel units
48
- **CSS Generation**: Generates email-client-compatible CSS with media queries for responsive behavior
49
- **Outlook Compatibility**: Uses conditional HTML comments for Microsoft Outlook email client support
50
- **Context Management**: Maintains rendering context for child components with proper width distribution
51
52
## Capabilities
53
54
### MjGroup Component Class
55
56
The main component class that handles group rendering and responsive behavior.
57
58
```javascript { .api }
59
/**
60
* MJML Group component class extending BodyComponent
61
* Prevents columns from stacking on mobile devices
62
*/
63
class MjGroup extends BodyComponent {
64
static componentName: string;
65
static allowedAttributes: {
66
'background-color': string;
67
direction: string;
68
'vertical-align': string;
69
width: string;
70
};
71
static defaultAttributes: {
72
direction: string;
73
};
74
}
75
```
76
77
### Component Configuration
78
79
Static properties defining the component's behavior and allowed attributes.
80
81
```javascript { .api }
82
/**
83
* MJML component tag name
84
*/
85
static componentName: "mj-group"
86
87
/**
88
* Allowed MJML attributes with validation types
89
*/
90
static allowedAttributes: {
91
'background-color': 'color',
92
'css-class': 'string',
93
direction: 'enum(ltr,rtl)',
94
'vertical-align': 'enum(top,bottom,middle)',
95
width: 'unit(px,%)'
96
}
97
98
/**
99
* Default attribute values
100
*/
101
static defaultAttributes: {
102
direction: 'ltr'
103
}
104
```
105
106
### Context Management
107
108
Methods for managing child component context and width calculations.
109
110
```javascript { .api }
111
/**
112
* Calculates and returns context for child components
113
* @returns {Object} Child context with container width and sibling information
114
*/
115
getChildContext(): {
116
...parentContext,
117
containerWidth: string;
118
nonRawSiblings: number;
119
}
120
```
121
122
### Style Generation
123
124
Methods for generating CSS styles and responsive classes.
125
126
```javascript { .api }
127
/**
128
* Generates CSS styles for the group component
129
* @returns {Object} CSS styles object with div and tdOutlook properties
130
*/
131
getStyles(): {
132
div: {
133
'font-size': string;
134
'line-height': string;
135
'text-align': string;
136
display: string;
137
width: string;
138
direction: string;
139
'vertical-align': string;
140
'background-color': string;
141
};
142
tdOutlook: {
143
'vertical-align': string;
144
width: string;
145
};
146
}
147
148
/**
149
* Generates CSS class name for responsive media queries
150
* @returns {string} CSS class name (e.g., "mj-column-per-50" or "mj-column-px-300")
151
*/
152
getColumnClass(): string
153
```
154
155
### Width Calculations
156
157
Methods for handling responsive width calculations in different units.
158
159
```javascript { .api }
160
/**
161
* Parses width attribute and returns width information
162
* @param {boolean} toString - Whether to return formatted string or object
163
* @returns {string|Object} Width value as string or parsed width object
164
*/
165
getParsedWidth(toString?: boolean): string | {
166
unit: string;
167
parsedWidth: number;
168
}
169
170
/**
171
* Converts current width to pixel value regardless of original unit
172
* @returns {string} Width in pixels (e.g., "300px")
173
*/
174
getWidthAsPixel(): string
175
```
176
177
### HTML Rendering
178
179
Main rendering method that generates the final HTML output.
180
181
```javascript { .api }
182
/**
183
* Renders the group component to HTML with Outlook conditional comments
184
* @returns {string} HTML string output with responsive behavior
185
*/
186
render(): string
187
```
188
189
### Inherited API Methods
190
191
MJML Group inherits additional methods from BodyComponent:
192
193
```javascript { .api }
194
/**
195
* Retrieves attribute value by name
196
* @param {string} name - Attribute name
197
* @returns {any} Attribute value
198
*/
199
getAttribute(name: string): any
200
201
/**
202
* Retrieves shorthand attribute values (e.g., padding, margin)
203
* @param {string} attribute - Base attribute name
204
* @param {string} direction - Direction (top, right, bottom, left)
205
* @returns {number} Parsed attribute value
206
*/
207
getShorthandAttrValue(attribute: string, direction: string): number
208
209
/**
210
* Calculates width values for layout calculations
211
* @returns {Object} Width information including totalWidth, borders, paddings, box
212
*/
213
getBoxWidths(): {
214
totalWidth: number;
215
borders: number;
216
paddings: number;
217
box: number;
218
}
219
220
/**
221
* Generates CSS styles string from style object or style name
222
* @param {string|Object} styles - Style object or style property name
223
* @returns {string} CSS styles as string
224
*/
225
styles(styles: string | Object): string
226
227
/**
228
* Formats attributes for HTML output
229
* @param {Object} attributes - Attributes object
230
* @returns {string} Formatted HTML attributes string
231
*/
232
htmlAttributes(attributes: Object): string
233
234
/**
235
* Renders child components within the group
236
* @param {Array} children - Child components array
237
* @param {Object} options - Rendering options
238
* @returns {string} Rendered children HTML
239
*/
240
renderChildren(children: Array, options: Object): string
241
```
242
243
## MJML Template Attributes
244
245
When used in MJML templates, `mj-group` supports these attributes:
246
247
```xml { .api }
248
<!-- Group width in pixels or percentage -->
249
<mj-group width="50%" />
250
<mj-group width="300px" />
251
252
<!-- Vertical alignment of group content -->
253
<mj-group vertical-align="top" /> <!-- default -->
254
<mj-group vertical-align="middle" />
255
<mj-group vertical-align="bottom" />
256
257
<!-- Background color -->
258
<mj-group background-color="#f0f0f0" />
259
<mj-group background-color="red" />
260
261
<!-- Text direction -->
262
<mj-group direction="ltr" /> <!-- default -->
263
<mj-group direction="rtl" />
264
265
<!-- Custom CSS class -->
266
<mj-group css-class="custom-group" />
267
```
268
269
## Usage Examples
270
271
**Basic Side-by-Side Layout:**
272
273
```xml
274
<mj-section>
275
<mj-group>
276
<mj-column width="50%">
277
<mj-text>Left content</mj-text>
278
</mj-column>
279
<mj-column width="50%">
280
<mj-text>Right content</mj-text>
281
</mj-column>
282
</mj-group>
283
</mj-section>
284
```
285
286
**Styled Group with Background:**
287
288
```xml
289
<mj-section>
290
<mj-group width="80%" background-color="#e8f4f8" vertical-align="middle">
291
<mj-column width="60%">
292
<mj-text>Main content area</mj-text>
293
</mj-column>
294
<mj-column width="40%">
295
<mj-image src="image.jpg" />
296
</mj-column>
297
</mj-group>
298
</mj-section>
299
```
300
301
**Mixed Groups and Columns:**
302
303
```xml
304
<mj-section>
305
<!-- Regular column that will stack on mobile -->
306
<mj-column>
307
<mj-text>Header content</mj-text>
308
</mj-column>
309
310
<!-- Group that maintains side-by-side layout on mobile -->
311
<mj-group>
312
<mj-column width="50%">
313
<mj-text>Left sidebar</mj-text>
314
</mj-column>
315
<mj-column width="50%">
316
<mj-text>Right sidebar</mj-text>
317
</mj-column>
318
</mj-group>
319
</mj-section>
320
```
321
322
## Important Notes
323
324
- **Column Width Requirements**: Columns inside a group must have width specified in percentage, not pixels
325
- **iOS 9 Compatibility**: Avoid HTML beautification that adds spaces between columns in a group, as this causes stacking issues on iOS 9
326
- **Email Client Support**: Includes specific handling for Microsoft Outlook through conditional HTML comments
327
- **Mobile Behavior**: Primary purpose is preventing default column stacking behavior on mobile devices
328
- **Media Query Integration**: Automatically generates and registers CSS classes for responsive behavior with MJML's media query system