0
# MJML Head
1

2
MJML Head is a core component of the MJML email framework that provides the container functionality for managing head elements in email templates. As a HeadComponent, it serves as the parent container for various head-specific components like styles, fonts, attributes, and metadata configurations that are essential for responsive email rendering.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
import MjHead from "mjml-head";
15
// or commonly imported as:
16
import Head from "mjml-head";
17
```
18

19
For CommonJS:
20

21
```javascript
22
const MjHead = require("mjml-head");
23
// or commonly required as:
24
const Head = require("mjml-head");
25
```
26

27
## Basic Usage
28

29
```javascript
30
import MjHead from "mjml-head";
31

32
// Typical usage within MJML component registration
33
// This component is usually registered automatically when using the full MJML package
34
// and used declaratively in MJML markup as <mj-head>
35
```
36

37
In MJML markup:
38

39
```xml
40
<mjml>
41
  <mj-head>
42
    <!-- Head components like mj-style, mj-font, etc. -->
43
    <mj-style>
44
      .custom-class { color: blue; }
45
    </mj-style>
46
  </mj-head>
47
  <mj-body>
48
    <!-- Body content -->
49
  </mj-body>
50
</mjml>
51
```
52

53
## Architecture
54

55
The MjHead component is built on MJML's component architecture:
56

57
- **HeadComponent Base**: Inherits from HeadComponent which provides head-specific processing capabilities
58
- **Component Registration**: Automatically registered with MJML core using the componentName 'mj-head'
59
- **Child Processing**: Delegates child component handling to the inherited handlerChildren() method
60
- **MJML Integration**: Seamlessly integrates with MJML's parsing and rendering pipeline
61

62
## Capabilities
63

64
### MjHead Class
65

66
The main component class that extends HeadComponent to provide head container functionality.
67

68
```javascript { .api }
69
/**
70
 * Main head component class for MJML email templates
71
 * Extends HeadComponent to provide container functionality for head elements
72
 */
73
export default class MjHead extends HeadComponent {
74
  /** MJML component tag name identifier */
75
  static componentName = 'mj-head';
76
  
77
  /** 
78
   * Processes child components by delegating to inherited handlerChildren() method
79
   * @returns {Array} Array of processed child components
80
   */
81
  handler() {
82
    return this.handlerChildren();
83
  }
84
}
85
```
86

87
### Static Properties
88

89
Component identifier used by MJML's registration system.
90

91
```javascript { .api }
92
/**
93
 * MJML component tag name identifier
94
 * Used by MJML core for component registration and recognition
95
 */
96
static componentName = 'mj-head';
97
```
98

99
### Instance Methods
100

101
Core processing method that handles child component initialization and processing.
102

103
```javascript { .api }
104
/**
105
 * Main processing method that handles child components
106
 * Delegates to the inherited handlerChildren() method for actual processing
107
 * @returns {Array} Array of processed child components from handlerChildren()
108
 */
109
handler() {
110
  return this.handlerChildren();
111
}
112
```
113

114
### Inherited API (from HeadComponent)
115

116
Base functionality inherited from the HeadComponent class.
117

118
```javascript { .api }
119
/**
120
 * Processes all child components in the head section
121
 * Maps over children props and initializes each child component
122
 * @returns {Array} Array of rendered child components
123
 */
124
handlerChildren() {
125
  // Implementation inherited from HeadComponent
126
}
127

128
/**
129
 * Returns the component's tag name
130
 * Uses componentName or falls back to kebab-cased class name
131
 * @returns {string} Component tag name as string
132
 */
133
static getTagName() {
134
  return this.componentName || kebabCase(this.name);
135
}
136
```
137

138
### Component Properties
139

140
Core properties available on component instances.
141

142
```javascript { .api }
143
/**
144
 * Component properties and attributes passed from MJML parsing
145
 * @type {Object}
146
 * @property {Array} children - Array of child components
147
 */
148
props = {
149
  children: [],
150
  // Additional properties from MJML parsing
151
};
152

153
/**
154
 * MJML rendering context containing component registry and processing state
155
 * @type {Object}
156
 * @property {Object} components - Registry of available MJML components
157
 * @property {Function} addHeadStyle - Function to add head styles
158
 * @property {Function} addComponentHeadSyle - Function to add component-specific head styles
159
 */
160
context = {
161
  components: {},
162
  addHeadStyle: function(name, style) {},
163
  addComponentHeadSyle: function(style) {},
164
  // Additional context properties
165
};
166
```
167

168
## Types
169

170
Core type definitions for the MjHead component.
171

172
```javascript { .api }
173
/**
174
 * Child component structure as processed by MJML parser
175
 * @typedef {Object} ChildComponent
176
 * @property {string} tagName - The MJML tag name
177
 * @property {Object} [attributes] - Component attributes
178
 * @property {Array} [children] - Child components
179
 * @property {string} [content] - Text content
180
 */
181

182
/**
183
 * MJML component initialization data structure
184
 * @typedef {Object} ComponentInitialData  
185
 * @property {string} tagName - The component tag name
186
 * @property {Object} [attributes] - Component attributes
187
 * @property {Array<ChildComponent>} [children] - Array of child components
188
 * @property {Object} context - MJML rendering context
189
 */
190
```
191

192
## Usage Context
193

194
The MjHead component is typically used as a container in MJML email templates and can contain various head-specific child components:
195

196
- **mj-attributes**: Global attribute definitions
197
- **mj-style**: CSS styles for email
198
- **mj-font**: Font definitions
199
- **mj-breakpoint**: Responsive breakpoint settings
200
- **mj-title**: Email title metadata
201
- **mj-preview**: Email preview text
202
- **mj-html-attributes**: HTML attribute settings
203

204
## Error Handling
205

206
The component inherits error handling from the HeadComponent base class:
207

208
- Logs errors for unmatched child component tags to console
209
- Returns null for invalid child components to prevent rendering errors
210
- Continues processing remaining valid child components when errors occur