0
# MJML Head Preview
1

2
MJML Head Preview provides the `<mj-preview>` component for setting email preview text that appears in email client inboxes before emails are opened. This component is part of the MJML email framework ecosystem and enables developers to control the preview text displayed in email clients.
3

4
## Package Information
5

6
- **Package Name**: mjml-head-preview
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install mjml-head-preview`
10

11
## Core Imports
12

13
```javascript
14
import MjPreview from "mjml-head-preview";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const MjPreview = require("mjml-head-preview");
21
```
22

23
For component development (extending the component):
24

25
```javascript
26
import { HeadComponent } from "mjml-core";
27
```
28

29
## Basic Usage
30

31
The `<mj-preview>` component is used within the `<mj-head>` section of MJML templates to set the preview text:
32

33
```xml
34
<mjml>
35
  <mj-head>
36
    <mj-preview>Your preview text appears here</mj-preview>
37
  </mj-head>
38
  <mj-body>
39
    <mj-section>
40
      <mj-column>
41
        <mj-text>Email content goes here</mj-text>
42
      </mj-column>
43
    </mj-section>
44
  </mj-body>
45
</mjml>
46
```
47

48
## Architecture
49

50
The mjml-head-preview package provides a single MJML component class that extends the HeadComponent base class from mjml-core. The component processes the preview text during MJML compilation and adds it to the global context for inclusion in the final HTML output.
51

52
## Capabilities
53

54
### MjPreview Component
55

56
The main and only export from the package, providing the `<mj-preview>` MJML component functionality.
57

58
```javascript { .api }
59
/**
60
 * MJML head component for setting email preview text
61
 * Extends HeadComponent from mjml-core
62
 */
63
export default class MjPreview extends HeadComponent {
64
  /** Component name used as MJML tag */
65
  static componentName = 'mj-preview';
66
  
67
  /** Indicates component accepts content between tags */
68
  static endingTag = true;
69
  
70
  /** 
71
   * Processes the component and adds preview text to global context
72
   * Called during MJML compilation
73
   */
74
  handler() {
75
    const { add } = this.context;
76
    add('preview', this.getContent());
77
  }
78
}
79
```
80

81
**Usage in MJML Templates:**
82

83
```xml
84
<!-- Basic preview text -->
85
<mj-head>
86
  <mj-preview>Check out our latest newsletter!</mj-preview>
87
</mj-head>
88

89
<!-- Preview text with promotional content -->
90
<mj-head>
91
  <mj-preview>🎉 Flash Sale: 50% off everything - Limited time offer</mj-preview>
92
</mj-head>
93
```
94

95
**Component Registration:**
96

97
When registering with MJML core:
98

99
```javascript
100
import mjml2html from "mjml-core";
101
import MjPreview from "mjml-head-preview";
102

103
// Component is typically auto-registered in MJML ecosystem
104
// Manual registration if needed:
105
mjml2html.registerComponent(MjPreview);
106
```
107

108
## Integration with MJML Core
109

110
The MjPreview component integrates with the MJML compilation process through the following mechanisms:
111

112
- **HeadComponent Base Class**: Inherits core functionality from mjml-core's HeadComponent
113
- **Context Integration**: Uses `this.context.add('preview', this.getContent())` to set global preview data
114
- **Content Processing**: Inherits `getContent()` method from Component base class to extract and trim text content from component tags
115
- **Component Registration**: Follows MJML component registration patterns for ecosystem integration
116

117
The actual implementation:
118
```javascript
119
handler() {
120
  const { add } = this.context;
121
  add('preview', this.getContent());
122
}
123
```
124

125
## HTML Output
126

127
The preview text is rendered as a hidden `<div>` element in the email HTML using the preview helper from mjml-core:
128

129
```html
130
<div style="display:none;font-size:1px;color:#ffffff;line-height:1px;max-height:0px;max-width:0px;opacity:0;overflow:hidden;">Your preview text appears here</div>
131
```
132

133
This hidden div is positioned early in the HTML structure so email clients can extract it as preview text while keeping it invisible to email recipients. The exact styling and structure is handled by the `preview` helper function in mjml-core.
134

135
## Types
136

137
```javascript { .api }
138
/**
139
 * Base HeadComponent class from mjml-core
140
 * Extended by MjPreview
141
 */
142
class HeadComponent {
143
  /**
144
   * Component context with global data and helper methods
145
   * @property {Function} add - Add data to global context
146
   */
147
  context = {
148
    add(key, value) { /* adds data to global context */ }
149
  };
150
  
151
  /**
152
   * Get text content from component tags
153
   * @returns {string} The content between opening and closing tags
154
   */
155
  getContent() {
156
    return this.props.content.trim();
157
  }
158
  
159
  /**
160
   * Process component during compilation
161
   * Must be implemented by extending classes
162
   */
163
  handler() { /* implementation specific */ }
164
}
165
```