MJML 6.0.0-apha.1 - summary

Highlights

• Refreshed the underlying HTML to modernise where possible and reduce code bloat
• Added support for:
  • Dark mode via specific --dark modifier attributes
  • Responsive layout changes via specific --responsive modifier attributes
  • Accessibility ARIA attributes
• Upgraded Node versions and relevant dependencies

⚠️ Breaking changes

• Node.js 22 or later is required
• Updated all default font-size to 16px and line-height to 150% (and auto added mso-line-height of 120%)
• Removed Helvetica and Arial as fallback fonts
• Removed all <tbody> tags
• Changed default <p> marginin CSS from 13px to 1em

HTML

Overview

We took a comprehensive look at the HTML that was being compiled and reduced as much as possible to make savings. Benchmark testing cam in at about a 10-15% reduction in the components and templates we tested.

Full details: https://github.com/mjmlio/mjml/pull/305

What Changed (specific hightlights)

• Added support-outlook-classic option to mjml tag to remove support for Outlook classic (removes ghost tables and other Outlook specific code. Set to true by default.
• Added option to mj-preview to add blank space after preview text using the attributes [Fixes: #1829]
• Updated skeleton:
  • changed default margin from 13px to 1em[⚠️ BREAKING CHANGE]
• From all <table>s:
  • removed all <tbody> tags [⚠️ BREAKING CHANGE]
• From font-family declarations
  • removed Helvetica and Arial as fallbacks [⚠️ BREAKING CHANGE - as fonts will change to system default sans-serif font]
• For body tag
  • added xml:lang=“” (populated from globalData language, declared on mjml tag)
• mj-button
  • set display to block and removed mso-padding-alt declaration to solve issue where the full button is not clickable when the width is set
    • added multiline option to allow users to negate issues with the above in Outlook classic when button text wraps
    • added function to remove 1px padding to compensate for the added border
  • removed default cursor: auto set on <td> and margin: 0 set on <a>
• mj-carousel
  • removed [owa] class as no longer used
• mj-carousel-image
  • now respects target attribute
• mj-divider
  • now uses either table or p (based on support-outlook-classic) and only outputs one
• mj-hero
  • fixed issue where left padding disappeared in Outlook when background-url (VML) added
• mj-navbar
  • hamburger now takes set font-family / font-size / line-height when declaring in mj-attributes > mj-all. Previously it was using its own
  • removed hamburger CSS when hamburger is not set [Fixes #2848]
• mj-section
  • changed text-align option to column-align as it was poorly named. Aliased the deprecated option for backwards compatibility
  • fixed issue where left padding disappeared in Outlook when background-url (VML) added
• mj-social
  • updated sharer URLs
  • removed icon width declarations [Fixes #3043]

For specific details, see: https://github.com/mjmlio/mjml/blob/0ed566958c39ad45ba436c9316132ffb18d50061/CHANGELOG.md

Dark mode

Overview

Overhauls MJML dark-mode support across body components giving the user the option to support and attribute tools to make simple changes to colours and images in clients that support it. [Fixes: #2010]

Full details: #3068

What Changed

• Added option to support dark-mode via <mjml support-dark-mode="true"> which adds both <meta> tags and CSS. Full details:
• Implemented/extended dark attributes using --dark attributes for existing color and image related attributes:
• Added validator rule that warns when dark-mode attributes are used without root support-dark-mode="true".

For specific attributes, see: https://github.com/mjmlio/mjml/blob/0ed566958c39ad45ba436c9316132ffb18d50061/CHANGELOG.md

Responsive

Overview

Overhauls MJML responsive-mode support across body components giving the user the option to support and attribute tools to make simple changes to desktop vs mobile display in clients that support it.

Full details: #3123

What Changed

• Implemented/extended responsive attributes using --responsive attributes for existing size, padding, direction, background and alignment related attributes.
• Added layout--responsive to deal with display of mj-navbar, mj-social and mj-table in narrow views

For specific attributes, see: https://github.com/mjmlio/mjml/blob/0ed566958c39ad45ba436c9316132ffb18d50061/CHANGELOG.md

Accessibility

Overview

Overhauls MJML accessibility support across body components giving the user the option to support and attribute tools to make simple changes to accessibility display in clients that support it.

Full details: #3117

What's changed

• Implemented acciesibility attributes aria-label aria-roledescription role and aria-hidden across various components
• Added normalize-elements attribute to mj-text to normalize rendering of lists (ul, ol). Can be overwritten inline (except Outlook classic)
• Added keyboard accessibility to mj-accordion mj-carousel, and mj-navbar [Fixes #2336]
• Updated mj-divider to use a semantic <hr>
• Updated all default font-size to 16px and line-height to 150% (and auto added mso-line-height of 120%) [⚠️ BREAKING CHANGE]

For specific attributes, see: https://github.com/mjmlio/mjml/blob/0ed566958c39ad45ba436c9316132ffb18d50061/CHANGELOG.md

Other

Full details: #3129

• Added container-border-radius attribute to 10 components
• Updated mj-social padding attributes to be more logical:
• mj-table cellpadding / cellspacing now use the integer(px) type [Fixes #3137]

For specific details, see: https://github.com/mjmlio/mjml/blob/0ed566958c39ad45ba436c9316132ffb18d50061/CHANGELOG.md

Node.js 22 or later is required (⚠️ Breaking change)

What changed

• All published packages (except mjml-browser) now declare "engines": { "node": ">=22" }.
• CI tests Node 22, 24 and 26. Node 20 is no longer tested.

What to do

• Upgrade to the latest Node 22 release (22.18 or later), or to Node 24 or 26.

ES module config, custom components

What changed

• Since Node 22.12, require() can load ES modules, but it returns { default: ... } instead of the exported value. MJML now unwraps the default export when loading .mjmlconfig.js
• Exports that are not objects (for example export const VERSION = '1.0') are skipped when registering custom components, instead of throwing a RangeError.

Impact

• An ESM .mjmlconfig.js file on Node >22.12 was silently ignored: custom components were not registered and the build still exited with code 0.
• CommonJS and JSON config files are unchanged.

// .mjmlconfig.js — now works export default { packages: ['./my-component.js'] }

For contributors

• Local development uses Node 26 (.nvmrc). Run nvm use in the repository root.
• The test runner moved from mocha 10 to 12.
• CI installs with yarn install --frozen-lockfile. PRs that change dependencies must commit the updated yarn.lock.
• Obsolete resolutions were removed.