MJML Head Font

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.

Package Information

• Package Name: mjml-head-font
• Package Type: npm
• Language: JavaScript (ES6)
• Installation: npm install mjml-head-font

Core Imports

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

import MjFont from "mjml-head-font";

For CommonJS:

const MjFont = require("mjml-head-font");

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

<mj-font name="FontName" href="https://example.com/font.css" />

Basic Usage

<mjml>
  <mj-head>
    <mj-font name="Raleway" href="https://fonts.googleapis.com/css?family=Raleway" />
    <mj-font name="Open Sans" href="https://fonts.googleapis.com/css?family=Open+Sans:300,400,700" />
  </mj-head>
  <mj-body>
    <mj-section>
      <mj-column>
        <mj-text font-family="Raleway, Arial">
          Custom font text
        </mj-text>
      </mj-column>
    </mj-section>
  </mj-body>
</mjml>

Capabilities

MjFont Component

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

/**
 * MJML head component for importing custom fonts
 * Extends HeadComponent from mjml-core
 */
export default class MjFont extends HeadComponent {
  static componentName;
  static allowedAttributes;
  handler();
}

Component Properties

/**
 * The MJML tag name for this component
 */
static componentName = "mj-font";

/**
 * Defines allowed attributes and their types
 */
static allowedAttributes = {
  name: "string",    // Font family name
  href: "string"     // URL to hosted CSS file with @font-face declarations
};

Handler Method

/**
 * Processes the component by registering the font with MJML context
 * Called during MJML head processing phase
 */
handler();

The handler method implementation:

handler() {
  const { add } = this.context;
  add('fonts', this.getAttribute('name'), this.getAttribute('href'));
}

The handler method:

1. Destructures the add function from this.context
2. Retrieves the font name from the name attribute using this.getAttribute('name')
3. Retrieves the CSS URL from the href attribute using this.getAttribute('href')
4. Registers the font with the MJML global context using add('fonts', name, href)

Default Export

/**
 * Default export of the MjFont component class
 */
export default class MjFont extends HeadComponent;

Inherited Methods

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

/**
 * Get the value of a component attribute
 * @param {string} name - The attribute name
 * @returns {string} The attribute value
 */
getAttribute(name);

/**
 * Get the child context for nested components
 * @returns {object} The component context
 */
getChildContext();

/**
 * Get the text content from the component
 * @returns {string} The trimmed content
 */
getContent();

Attributes

The mj-font component accepts the following attributes:

name

• Type: string
• Required: Yes
• Description: The font family name that will be used in CSS font-family declarations

href

• Type: string
• Required: Yes
• Description: URL pointing to a hosted CSS file containing @font-face declarations for the font

Example CSS file content:

@font-face {
  font-family: 'Raleway';
  font-style: normal;
  font-weight: 400;
  src: url(https://fonts.gstatic.com/s/raleway/v28/1Ptxg8zYS_SKggPN4iEgvnHyvveLxVvaoorCP.woff2) format('woff2');
}

Component Registration

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:

import { registerComponent } from 'mjml-core';
import MjFont from 'mjml-head-font';

registerComponent(MjFont);

Integration

This component integrates with the MJML framework through:

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

Processing Lifecycle

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

Error Handling

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.

Browser and Email Client Support

Font support depends on the email client's CSS capabilities:

• Modern clients: Full support for web fonts
• Outlook: Limited support; fallback fonts recommended
• Gmail: Good support for web fonts
• Apple Mail: Excellent support

Always provide fallback fonts in your font-family declarations.