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