or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-mjml-wrapper

MJML wrapper component that enables wrapping multiple sections together for nested layouts with shared borders or background images.

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/mjml-wrapper@4.15.x

To install, run

npx @tessl/cli install tessl/npm-mjml-wrapper@4.15.0

MJML Wrapper

MJML Wrapper is a specialized component within the MJML email framework that enables wrapping multiple sections together for creating nested layouts with shared borders, background colors, and background images across sections. It extends the functionality of the standard MJML section component to support complex multi-section layouts while maintaining full compatibility with Outlook's VML limitations.

Important: While mjml-wrapper exists as a separate npm package, it is typically installed and used as part of the main mjml package, which includes all core components in a preset.

Package Information

Package Name: mjml-wrapper
Package Type: npm
Language: JavaScript
Installation: npm install mjml (mjml-wrapper is included as part of the core MJML package)
Version: 4.15.3
Dependencies: mjml-core, mjml-section, lodash, @babel/runtime

Core Imports

MJML Wrapper is used declaratively within MJML markup and does not require direct JavaScript imports for typical usage:

<mjml>
  <mj-body>
    <mj-wrapper>
      <!-- sections go here -->
    </mj-wrapper>
  </mj-body>
</mjml>

For programmatic usage or custom component development, mjml-wrapper is included with the main mjml package:

import mjml from 'mjml';
// mjml-wrapper is automatically registered as part of the core preset

Direct import (for component extension):

import MjWrapper from 'mjml-wrapper';

Basic Usage

<mjml>
  <mj-body>
    <mj-wrapper border="1px solid #000000" background-color="#f4f4f4" padding="30px">
      <mj-section border="1px solid #dddddd" padding="20px">
        <mj-column>
          <mj-text>First section content</mj-text>
        </mj-column>
      </mj-section>
      <mj-section border="1px solid #dddddd" padding="20px">
        <mj-column>
          <mj-text>Second section content</mj-text>
        </mj-column>
      </mj-section>
    </mj-wrapper>
  </mj-body>
</mjml>

Capabilities

Component Definition

The MjWrapper component extends MjSection to provide wrapper functionality for multiple sections.

class MjWrapper extends MjSection {
  static componentName: 'mj-wrapper';
  static allowedAttributes: object; // Inherits all attributes from MjSection
  static defaultAttributes: object; // Inherits default values from MjSection
  
  /**
   * Renders wrapped child sections with Outlook-compatible table structure
   * @returns {string} HTML markup for wrapped child components
   */
  renderWrappedChildren(): string;
  
  /**
   * Provides context to child components including container width
   * @returns {object} Child context with containerWidth
   */
  getChildContext(): object;
}

Supported Attributes

All attributes inherited from MjSection are supported:

interface MjWrapperAttributes {
  'background-color'?: string;           // Section background color
  'background-url'?: string;             // Background image URL  
  'background-repeat'?: 'repeat' | 'no-repeat';  // CSS background repeat (default: 'repeat')
  'background-size'?: string;            // CSS background size (default: 'auto')
  'background-position'?: string;        // CSS background position (default: 'top center')
  'background-position-x'?: string;      // CSS background position X
  'background-position-y'?: string;      // CSS background position Y
  'border'?: string;                     // CSS border format
  'border-bottom'?: string;              // CSS border format
  'border-left'?: string;                // CSS border format
  'border-radius'?: string;              // Border radius
  'border-right'?: string;               // CSS border format
  'border-top'?: string;                 // CSS border format
  'direction'?: 'ltr' | 'rtl';          // Text direction (default: 'ltr')
  'full-width'?: 'full-width' | '';     // Make wrapper full-width
  'padding'?: string;                    // Padding supports up to 4 parameters (default: '20px 0')
  'padding-top'?: string;                // Section top offset
  'padding-bottom'?: string;             // Section bottom offset
  'padding-left'?: string;               // Section left offset
  'padding-right'?: string;              // Section right offset
  'text-align'?: 'left' | 'center' | 'right'; // CSS text alignment (default: 'center')
  'text-padding'?: string;               // Text padding (default: '4px 4px 4px 0')
  'css-class'?: string;                  // CSS class name added to root HTML element
}

Component Hierarchy

MjWrapper supports specific child and parent components within the MJML structure:

interface MjWrapperHierarchy {
  // Valid parent components
  parents: ['mj-body'];
  
  // Valid child components that can be placed inside mj-wrapper
  children: ['mj-hero', 'mj-raw', 'mj-section'];
}

Wrapper Rendering

The core rendering method that handles the wrapper layout:

/**
 * Renders wrapped child sections with Outlook-compatible table structure
 * @returns {string} HTML markup for wrapped child components
 */
renderWrappedChildren(): string;

Usage Examples:

Basic wrapper with multiple sections:

<mj-wrapper background-color="#ffffff" border="2px solid #e0e0e0" padding="40px 20px">
  <mj-section background-color="#f9f9f9" padding="20px">
    <mj-column>
      <mj-image src="https://example.com/header.jpg" alt="Header" />
    </mj-column>
  </mj-section>
  <mj-section background-color="#ffffff" padding="30px">
    <mj-column>
      <mj-text font-size="16px" color="#333333">
        Main content section with shared wrapper styling.
      </mj-text>
    </mj-column>
  </mj-section>
</mj-wrapper>

Wrapper with mj-hero component (hero sections can also be wrapped):

<mj-wrapper background-color="#4a90e2" padding="30px">
  <mj-hero 
    mode="fluid-height"
    background-url="https://example.com/hero-bg.jpg"
    background-size="cover"
    padding="100px 0">
    <mj-text color="#ffffff" font-size="24px" align="center">
      Hero content within wrapper
    </mj-text>
  </mj-hero>
</mj-wrapper>

Full-Width Support

Enable full-width wrapper for edge-to-edge backgrounds:

<mj-wrapper full-width="full-width" background-color="#4a90e2" padding="50px 0">
  <mj-section>
    <mj-column>
      <mj-text color="#ffffff" align="center">
        Full-width wrapper with centered content
      </mj-text>
    </mj-column>
  </mj-section>
</mj-wrapper>

Background Image Handling

Apply background images across multiple sections:

<mj-wrapper 
  background-url="https://example.com/background.jpg" 
  background-size="cover" 
  background-position="center center"
  background-repeat="no-repeat"
  padding="60px 30px">
  <mj-section background-color="rgba(255,255,255,0.9)" padding="30px">
    <mj-column>
      <mj-text>Content with semi-transparent background over image</mj-text>
    </mj-column>
  </mj-section>
  <mj-section background-color="rgba(0,0,0,0.8)" padding="30px">
    <mj-column>
      <mj-text color="#ffffff">Contrasting section with same background image</mj-text>
    </mj-column>
  </mj-section>
</mj-wrapper>

Key Features

Outlook Compatibility

Generates VML-compatible markup for Outlook desktop clients
Handles nested table structures required for complex layouts
Manages z-index limitations in Outlook's rendering engine

Nested Layout Support

Enables shared styling across multiple sections
Maintains proper spacing and borders between wrapped sections
Supports both standard and full-width layout modes

Background Management

Allows background images to span multiple sections
Handles background positioning, sizing, and repeat options
Provides fallback support for clients with limited CSS support

Important Limitations

Outlook VML Restrictions

Cannot nest full-width sections inside full-width wrappers
Background images on wrapper and child sections may conflict in Outlook Desktop
Z-index properties are ignored in most Outlook VML contexts

Background Layering

If using background-url on mj-wrapper, avoid background-url on child sections
Background-color on wrapper will appear over background-images on child sections in Outlook Desktop
No reliable way to control layer ordering due to VML limitations

Component Architecture

The MjWrapper component follows MJML's component architecture:

Component Registration

MjWrapper is automatically registered as part of the MJML core preset:

// Component is included in mjml-preset-core and automatically available
// when using the main mjml package
import mjml from 'mjml';

// The component is registered via:
// mjml-preset-core -> components -> mjml-wrapper

Architecture Details

Extends: MjSection (inherits all section functionality including styling, background handling, and VML generation)
Component Name: 'mj-wrapper' (used in MJML markup)
Rendering: Overrides renderWrappedChildren() for specialized wrapper behavior with Outlook-compatible table nesting
Context: Provides containerWidth context to child components via getChildContext()
Dependencies: Requires mjml-core for BodyComponent base class and mjml-section for inheritance