0
# MJML Accordion
1

2
MJML Accordion is an interactive MJML component library that provides collapsible content sections for HTML email templates. It enables developers to create space-efficient, mobile-friendly email experiences by allowing content to be collapsed into clickable tabs that expand to reveal additional information.
3

4
## Package Information
5

6
- **Package Name**: mjml-accordion
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES6+ with Babel transpilation)
9
- **Installation**: `npm install mjml-accordion`
10

11
## Core Imports
12

13
```javascript
14
const { Accordion, AccordionElement, AccordionText, AccordionTitle } = require("mjml-accordion");
15
```
16

17
For ES6 modules:
18

19
```javascript
20
import { Accordion, AccordionElement, AccordionText, AccordionTitle } from "mjml-accordion";
21
```
22

23
Note: These are default exports from the main index file, not named exports.
24

25
## Basic Usage
26

27
```xml
28
<mjml>
29
  <mj-body>
30
    <mj-section>
31
      <mj-column>
32
        <mj-accordion border="2px solid black" padding="10px 25px">
33
          <mj-accordion-element>
34
            <mj-accordion-title font-size="16px" padding="16px">
35
              Why use accordions in emails?
36
            </mj-accordion-title>
37
            <mj-accordion-text font-size="14px" padding="16px">
38
              Accordions help deliver lots of information in a mobile-friendly format
39
              by allowing users to expand only the content they're interested in.
40
            </mj-accordion-text>
41
          </mj-accordion-element>
42
          <mj-accordion-element>
43
            <mj-accordion-title>How it works</mj-accordion-title>
44
            <mj-accordion-text>
45
              Content is stacked into tabs. On mobile devices with responsive support,
46
              users can click to expand. On desktop clients without responsive support,
47
              all content is expanded by default.
48
            </mj-accordion-text>
49
          </mj-accordion-element>
50
        </mj-accordion>
51
      </mj-column>
52
    </mj-section>
53
  </mj-body>
54
</mjml>
55
```
56

57
## Architecture
58

59
MJML Accordion is built around four main components that work together:
60

61
- **Container Component**: `mj-accordion` provides the overall structure and styling context
62
- **Element Component**: `mj-accordion-element` represents individual collapsible sections
63
- **Title Component**: `mj-accordion-title` creates clickable headers with expand/collapse icons
64
- **Text Component**: `mj-accordion-text` contains the collapsible content that shows/hides
65

66
Each component extends the `BodyComponent` base class from `mjml-core` and includes comprehensive attribute validation, default styling, and responsive email client compatibility through conditional CSS.
67

68
## Capabilities
69

70
### Accordion Container
71

72
Main container component that wraps accordion elements and provides global styling context including borders, fonts, and icon configuration.
73

74
```javascript
75
import { BodyComponent } from 'mjml-core'
76
```
77

78
```javascript { .api }
79
class MjAccordion extends BodyComponent {
80
  static componentName = 'mj-accordion';
81
  static allowedAttributes = {
82
    'container-background-color': 'color',
83
    'border': 'string',
84
    'font-family': 'string',
85
    'icon-align': 'enum(top,middle,bottom)',
86
    'icon-width': 'unit(px,%)',
87
    'icon-height': 'unit(px,%)',
88
    'icon-wrapped-url': 'string',
89
    'icon-wrapped-alt': 'string',
90
    'icon-unwrapped-url': 'string',
91
    'icon-unwrapped-alt': 'string',
92
    'icon-position': 'enum(left,right)',
93
    'padding-bottom': 'unit(px,%)',
94
    'padding-left': 'unit(px,%)',
95
    'padding-right': 'unit(px,%)',
96
    'padding-top': 'unit(px,%)',
97
    'padding': 'unit(px,%){1,4}',
98
  };
99
  static defaultAttributes = {
100
    'border': '2px solid black',
101
    'font-family': 'Ubuntu, Helvetica, Arial, sans-serif',
102
    'icon-align': 'middle',
103
    'icon-wrapped-url': 'https://i.imgur.com/bIXv1bk.png',
104
    'icon-wrapped-alt': '+',
105
    'icon-unwrapped-url': 'https://i.imgur.com/w4uTygT.png',
106
    'icon-unwrapped-alt': '-',
107
    'icon-position': 'right',
108
    'icon-height': '32px',
109
    'icon-width': '32px',
110
    'padding': '10px 25px',
111
  };
112
  headStyle() { /* returns CSS string for <head> */ }
113
  getStyles() { /* returns style object */ }
114
  render() { /* returns HTML string */ }
115
}
116
```
117

118
### Accordion Element
119

120
Individual accordion section containing a title/text pair. Automatically creates missing title or text components if not explicitly provided.
121

122
```javascript
123
import { BodyComponent } from 'mjml-core'
124
import { find } from 'lodash'
125
import conditionalTag from 'mjml-core/lib/helpers/conditionalTag'
126
```
127

128
```javascript { .api }
129
class MjAccordionElement extends BodyComponent {
130
  static componentName = 'mj-accordion-element';
131
  static allowedAttributes = {
132
    'background-color': 'color',
133
    'border': 'string',
134
    'font-family': 'string',
135
    'icon-align': 'enum(top,middle,bottom)',
136
    'icon-width': 'unit(px,%)',
137
    'icon-height': 'unit(px,%)',
138
    'icon-wrapped-url': 'string',
139
    'icon-wrapped-alt': 'string',
140
    'icon-unwrapped-url': 'string',
141
    'icon-unwrapped-alt': 'string',
142
    'icon-position': 'enum(left,right)',
143
  };
144
  static defaultAttributes = {
145
    title: {
146
      img: {
147
        width: '32px',
148
        height: '32px',
149
      },
150
    },
151
  };
152
  getStyles() { /* returns style objects */ }
153
  handleMissingChildren() { /* creates missing title/text components */ }
154
  render() { /* returns HTML string */ }
155
}
156
```
157

158
### Accordion Title
159

160
Clickable title component that displays the accordion header with expand/collapse icons. Supports HTML content as it is an ending tag component.
161

162
```javascript
163
import { BodyComponent } from 'mjml-core'
164
import conditionalTag from 'mjml-core/lib/helpers/conditionalTag'
165
```
166

167
```javascript { .api }
168
class MjAccordionTitle extends BodyComponent {
169
  static componentName = 'mj-accordion-title';
170
  static endingTag = true;
171
  static allowedAttributes = {
172
    'background-color': 'color',
173
    'color': 'color',
174
    'font-size': 'unit(px)',
175
    'font-family': 'string',
176
    'padding-bottom': 'unit(px,%)',
177
    'padding-left': 'unit(px,%)',
178
    'padding-right': 'unit(px,%)',
179
    'padding-top': 'unit(px,%)',
180
    'padding': 'unit(px,%){1,4}',
181
  };
182
  static defaultAttributes = {
183
    'font-size': '13px',
184
    'padding': '16px',
185
  };
186
  getStyles() { /* returns style objects */ }
187
  renderTitle() { /* renders title cell */ }
188
  renderIcons() { /* renders expand/collapse icons */ }
189
  render() { /* returns HTML string */ }
190
}
191
```
192

193
### Accordion Text
194

195
Collapsible text content component that contains the hidden/shown content. Supports HTML content as it is an ending tag component.
196

197
```javascript
198
import { BodyComponent } from 'mjml-core'
199
```
200

201
```javascript { .api }
202
class MjAccordionText extends BodyComponent {
203
  static componentName = 'mj-accordion-text';
204
  static endingTag = true;
205
  static allowedAttributes = {
206
    'background-color': 'color',
207
    'font-size': 'unit(px)',
208
    'font-family': 'string',
209
    'font-weight': 'string',
210
    'letter-spacing': 'unitWithNegative(px,em)',
211
    'line-height': 'unit(px,%,)',
212
    'color': 'color',
213
    'padding-bottom': 'unit(px,%)',
214
    'padding-left': 'unit(px,%)',
215
    'padding-right': 'unit(px,%)',
216
    'padding-top': 'unit(px,%)',
217
    'padding': 'unit(px,%){1,4}',
218
  };
219
  static defaultAttributes = {
220
    'font-size': '13px',
221
    'line-height': '1',
222
    'padding': '16px',
223
  };
224
  getStyles() { /* returns style objects */ }
225
  renderContent() { /* renders content cell */ }
226
  render() { /* returns HTML string */ }
227
}
228
```
229

230
## Types
231

232
```javascript { .api }
233
// Base class from mjml-core - all accordion components extend this
234
class BodyComponent {
235
  constructor(initialDatas) { /* component initialization */ }
236
  getAttribute(name) { /* get attribute value */ }
237
  getChildContext() { /* get component context */ }
238
  htmlAttributes(attributes) { /* format HTML attributes */ }
239
  renderChildren(children, options) { /* render child components */ }
240
  getContent() { /* get component inner content */ }
241
}
242

243
// Utility functions from dependencies
244
const { find } = require('lodash'); // Used in AccordionElement
245
const conditionalTag = require('mjml-core/lib/helpers/conditionalTag'); // Used for conditional HTML output
246
```
247

248
## Email Client Compatibility
249

250
The accordion components include sophisticated CSS that provides different behaviors across email clients:
251

252
- **Mobile/Responsive Clients**: Interactive accordion behavior with clickable titles
253
- **Desktop Clients**: All content expanded by default for maximum compatibility
254
- **Outlook**: Uses conditional comments and fallback styles for proper rendering
255
- **Gmail**: Responsive styles work in mobile Gmail apps but fallback to expanded view in desktop
256

257
The component automatically handles cross-client compatibility without requiring additional configuration.