0
# MJML Head Font
1

2
MJML Head Font provides the `mj-font` component for importing custom fonts into MJML email templates. This head component allows developers to register fonts that can be used throughout their email layouts, ensuring consistent typography across email clients.
3

4
## Package Information
5

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

11
## Core Imports
12

13
This component is typically used within the MJML framework. When developing custom MJML components or extending MJML:
14

15
```javascript
16
import MjFont from "mjml-head-font";
17
```
18

19
For CommonJS:
20

21
```javascript
22
const MjFont = require("mjml-head-font");
23
```
24

25
The component is automatically registered when MJML preset-core is loaded. In MJML templates, you use the component directly without imports:
26

27
```xml
28
<mj-font name="FontName" href="https://example.com/font.css" />
29
```
30

31
## Basic Usage
32

33
```xml
34
<mjml>
35
  <mj-head>
36
    <mj-font name="Raleway" href="https://fonts.googleapis.com/css?family=Raleway" />
37
    <mj-font name="Open Sans" href="https://fonts.googleapis.com/css?family=Open+Sans:300,400,700" />
38
  </mj-head>
39
  <mj-body>
40
    <mj-section>
41
      <mj-column>
42
        <mj-text font-family="Raleway, Arial">
43
          Custom font text
44
        </mj-text>
45
      </mj-column>
46
    </mj-section>
47
  </mj-body>
48
</mjml>
49
```
50

51
## Capabilities
52

53
### MjFont Component
54

55
The main component class that extends MJML's HeadComponent to provide font registration functionality.
56

57
```javascript { .api }
58
/**
59
 * MJML head component for importing custom fonts
60
 * Extends HeadComponent from mjml-core
61
 */
62
export default class MjFont extends HeadComponent {
63
  static componentName;
64
  static allowedAttributes;
65
  handler();
66
}
67
```
68

69
### Component Properties
70

71
```javascript { .api }
72
/**
73
 * The MJML tag name for this component
74
 */
75
static componentName = "mj-font";
76

77
/**
78
 * Defines allowed attributes and their types
79
 */
80
static allowedAttributes = {
81
  name: "string",    // Font family name
82
  href: "string"     // URL to hosted CSS file with @font-face declarations
83
};
84
```
85

86
### Handler Method
87

88
```javascript { .api }
89
/**
90
 * Processes the component by registering the font with MJML context
91
 * Called during MJML head processing phase
92
 */
93
handler();
94
```
95

96
The handler method implementation:
97
```javascript { .api }
98
handler() {
99
  const { add } = this.context;
100
  add('fonts', this.getAttribute('name'), this.getAttribute('href'));
101
}
102
```
103

104
The handler method:
105
1. Destructures the `add` function from `this.context`
106
2. Retrieves the font name from the `name` attribute using `this.getAttribute('name')`
107
3. Retrieves the CSS URL from the `href` attribute using `this.getAttribute('href')`
108
4. Registers the font with the MJML global context using `add('fonts', name, href)`
109

110
### Default Export
111

112
```javascript { .api }
113
/**
114
 * Default export of the MjFont component class
115
 */
116
export default class MjFont extends HeadComponent;
117
```
118

119
### Inherited Methods
120

121
The MjFont component inherits the following methods from HeadComponent/Component:
122

123
```javascript { .api }
124
/**
125
 * Get the value of a component attribute
126
 * @param {string} name - The attribute name
127
 * @returns {string} The attribute value
128
 */
129
getAttribute(name);
130

131
/**
132
 * Get the child context for nested components
133
 * @returns {object} The component context
134
 */
135
getChildContext();
136

137
/**
138
 * Get the text content from the component
139
 * @returns {string} The trimmed content
140
 */
141
getContent();
142
```
143

144
## Attributes
145

146
The `mj-font` component accepts the following attributes:
147

148
### name
149

150
- **Type**: string
151
- **Required**: Yes
152
- **Description**: The font family name that will be used in CSS font-family declarations
153

154
### href
155

156
- **Type**: string  
157
- **Required**: Yes
158
- **Description**: URL pointing to a hosted CSS file containing `@font-face` declarations for the font
159

160
**Example CSS file content:**
161
```css
162
@font-face {
163
  font-family: 'Raleway';
164
  font-style: normal;
165
  font-weight: 400;
166
  src: url(https://fonts.gstatic.com/s/raleway/v28/1Ptxg8zYS_SKggPN4iEgvnHyvveLxVvaoorCP.woff2) format('woff2');
167
}
168
```
169

170
## Component Registration
171

172
This component is part of the MJML preset-core package and is automatically registered when MJML is initialized. For custom MJML setups, you can register it manually:
173

174
```javascript
175
import { registerComponent } from 'mjml-core';
176
import MjFont from 'mjml-head-font';
177

178
registerComponent(MjFont);
179
```
180

181
## Integration
182

183
This component integrates with the MJML framework through:
184

185
1. **Component Registration**: Automatically registered with MJML preset-core
186
2. **Head Processing**: Executed during the `mj-head` processing phase via `handlerChildren()`
187
3. **Global Context**: Adds font definitions to the global MJML context using `context.add()`
188
4. **CSS Generation**: Font information is used to generate appropriate `<link>` tags in the email HTML head
189
5. **Template Usage**: Registered fonts become available for use in `font-family` attributes throughout the MJML template
190

191
### Processing Lifecycle
192

193
1. MJML parser encounters `<mj-font>` in `<mj-head>`
194
2. MjFont component is instantiated with attributes
195
3. `handler()` method is called during head processing
196
4. Font definition is added to global context
197
5. Final HTML includes the font CSS link in the `<head>` section
198

199
## Error Handling
200

201
The component relies on MJML's built-in validation system. Invalid attributes or missing required attributes will be caught by the MJML validator based on the `allowedAttributes` definition.
202

203
## Browser and Email Client Support
204

205
Font support depends on the email client's CSS capabilities:
206
- **Modern clients**: Full support for web fonts
207
- **Outlook**: Limited support; fallback fonts recommended
208
- **Gmail**: Good support for web fonts
209
- **Apple Mail**: Excellent support
210

211
Always provide fallback fonts in your `font-family` declarations.