MJML

repository·master·Indexed 12 days ago

https://github.com/mjmlio/mjml

A markup language designed to simplify the creation of responsive emails, providing a semantic syntax and a library of standard components that are translated into responsive HTML. Includes a browser-based parsing package, mjml-browser, and components such as mj-accordion, mj-body, mj-button, and mj-carousel.

Tokens
56.1K
Snippets
155
Records
201
Agent score
94%

What's inside MJML

  1. Use mj-bar-chart to create embedded bar charts

    master

    The mj-bar-chart component allows you to create fully embedded, static bar charts directly within your MJML templates. These charts are built using 100% HTML tables, ensuring high compatibility in email clients without requiring external dependencies or JavaScript.

    Key features include:

    • Basic bar chart rendering.
    • Stacked bar chart support.
    • Customizable legends (e.g., vertical alignment).
    • Ability to add links to data sources.
    • Lightweight and written in TypeScript.
  2. What is MJML and how does it work

    master

    MJML (Mailjet Markup Language) is a markup language designed to simplify the creation of responsive emails. It provides a semantic syntax and a library of standard components that abstract away the complexities of HTML email design, such as nested tables and client-specific CSS.

    Instead of writing raw HTML, you use MJML tags like <mj-section>, <mj-column>, and <mj-text>. The MJML engine then compiles this syntax into high-quality, responsive HTML that follows current industry best practices and is compatible with various email clients.

    <mjml>
      <mj-body>
        <mj-section>
          <mj-column>
            <mj-image
              width="100px"
              src="https://mjml.io/assets/img/logo-small.png"
            ></mj-image>
            <mj-divider border-color="#F45E43"></mj-divider>
            <mj-text font-size="20px" color="#F45E43" font-family="helvetica"
              >Hello World</mj-text
            >
          </mj-column>
        </mj-section>
      </mj-body>
    </mjml>
  3. Use Head components to manage styles and fonts

    master

    MJML <mj-head> components allow you to manage global settings for your email template. You can use them to:

    • Import web fonts.
    • Define default styles for MJML components.
    • Create CSS classes that can be applied to MJML components via the mj-class attribute.
  4. Structure an MJML document with mjml, mj-head, and mj-body

    master

    An MJML document must be wrapped in an <mjml> tag. The structure follows a standard HTML-like hierarchy where the <mjml> tag can only contain two primary child tags:

    1. <mj-head>: Contains document head components such as <mj-style> or <mj-font>.
    2. <mj-body>: Contains the visible content of the email.

    mjml Attributes

    attributeacceptsdescriptiondefault value
    owastringIf set to desktop, forces the desktop version for older (self-hosted) versions of Outlook.com that lack media query support.none
    langstringAdds a lang attribute to the <html> and <body> > <div> tags.und
    dirstringAdds a dir attribute to the <html> and <body> > <div> tags.auto
    <mjml>
      <mj-head>
        <!-- Head components go here -->
      </mj-head>
      <mj-body>
        <!-- Body components go here -->
      </mj-body>
    </mjml>
  5. Manage MJML includes and directory roots

    master

    By default, <mj-include> is disabled for security (ignoreIncludes: true). To use includes during development, you must explicitly opt-in and potentially define allowed directories.

    Key Configuration Keys:

    • allowIncludes: Set to true to enable <mj-include>.
    • filePath: Sets a base path for resolving relative includes. This allows you to keep partials in a central folder regardless of where the input file is located.
    • includePath: An array of additional allowed root directories for includes. These are resolved relative to the current working directory (process.cwd()).

    Security Constraints:

    • Includes are restricted to the filePath directory and its subdirectories, plus any includePath entries.
    • Absolute paths, UNC paths, and Windows drive letters are rejected.
    • Only .mjml, .css, and .html files are supported via <mj-include type="...">.
    # Enable includes and set a base path for partials
    mjml input.mjml --config.allowIncludes true --config.filePath ./my-partials/
    
    # Enable includes and allowlist additional sibling directories
    mjml template.mjml \
      --config.filePath /project/templates/newsletter \
      --config.allowIncludes true \
      --config.includePath '["../_common","../vendor"]'
  6. Create reusable style groups with mj-class

    master

    The <mj-class> tag allows you to create named groups of attributes that can be reused across multiple components. To apply a class, use the mj-class attribute on a component and provide the name of the class you defined.

    Example: Defining a 'blue' class and a 'big' class, then applying both to an <mj-text> component.

    <mjml>
     <mj-head>
       <mj-attributes>
         <mj-class name="blue" color="blue" />
         <mj-class name="big" font-size="20px" />
       </mj-attributes>
     </mj-head>
     <mj-body>
       <mj-section>
         <mj-column>
           <mj-text mj-class="blue big">
             Hello World!
           </mj-text>
         </mj-column>
       </mj-section>
     </mj-body>
    </mjml>
  7. Use the mj-body component

    master

    The mj-body component serves as the starting point for your email content. It is a required structural element within an <mjml> tag.

    To improve accessibility, MJML automatically wraps the content inside mj-body with a div tag containing specific ARIA attributes:

    • role="article"
    • aria-roledescription="email"
    • aria-label="EMAIL NAME" (where 'EMAIL NAME' is derived from the <mj-title> tag content).

    Additionally, the lang and dir attributes are inherited from the <mjml> tag and applied to this container.

    <mjml>
      <mj-body>
        <!-- Your email goes here -->
      </mj-body>
    </mjml>
  8. Configure column sizing in MJML

    master

    MJML provides two ways to manage the width of columns within an <mj-section>:

    Auto sizing

    By default, the MJML engine divides the available section space equally among all declared <mj-column> elements. For example, two columns will each take 50% of the width, and three columns will take approximately 33%.

    Manual sizing

    You can explicitly define the width of a column using the width attribute on the <mj-column> tag. You can use pixel values (e.g., 200px) or percentages (e.g., 50%).

    <!-- Auto sizing example -->
    <mj-section>
      <mj-column></mj-column>
      <mj-column></mj-column>
    </mj-section>
    
    <!-- Manual sizing example -->
    <mj-section>
      <mj-column width="200px"></mj-column>
      <mj-column width="400px"></mj-column>
    </mj-section>
  9. Use mj-section to structure email layouts

    master

    The mj-section component acts as a row within your email and is used to structure the layout. It serves as a container for columns (mj-column).

    Key constraints:

    • mj-section tags cannot be nested inside other mj-section tags.
    • To change the width from the default 600px to 100%, use the full-width="full-width" attribute.
    • To invert the display order of columns in desktop view, arrange your columns in the desired mobile stacking order and add direction="rtl" to the mj-section tag.
    <mjml>
      <mj-body>
        <mj-section full-width="full-width" background-color="red">
          <!-- Your columns go here -->
        </mj-section>
      </mj-body>
    </mjml>
  10. Use MJML as a JSON object

    master

    Instead of using MJML markup strings, you can define your email structure using a JSON object. This is particularly useful for programmatic manipulation or when interacting with the MJML API.

    In the JSON format, an MJML component is represented as an object with the following structure:

    • tagName (string): The name of the MJML component (e.g., 'mj-section').
    • attributes (object): A collection of key-value pairs representing the component's attributes.
    • content (string) OR children (array):
      • Use content to provide a plain text string for components that hold text.
      • Use children to provide an array of nested component objects.
    import mjml2html from 'mjml'
    
    async function example() {
      const result = await mjml2html({
        tagName: 'mjml',
        attributes: {},
        children: [
          {
            tagName: 'mj-body',
            attributes: {},
            children: [
              {
                tagName: 'mj-section',
                attributes: {},
                children: [
                  {
                    tagName: 'mj-column',
                    attributes: {},
                    children: [
                      {
                        tagName: 'mj-image',
                        attributes: {
                          width: '100px',
                          src: '/assets/img/logo-small.png',
                        },
                      },
                      {
                        tagName: 'mj-divider',
                        attributes: {
                          'border-color': '#F46E43',
                        },
                      },
                      {
                        tagName: 'mj-text',
                        attributes: {
                          'font-size': '20px',
                          color: '#F45E43',
                          'font-family': 'Helvetica',
                        },
                        content: 'Hello World',
                      },
                    ],
                  },
                ],
              },
            ],
          },
        ]
      })
      console.log(result)
    }
    
    example()
  11. Use the mj-hero component

    master

    The mj-hero component displays a hero image and functions similarly to an mj-section containing a single mj-column.

    Key Requirements

    • Mandatory Attributes: You must provide background-width and background-height.
    • Image Sizing: For best results, use an image with a width matching your mj-body (default 600px) and a height equal to or larger than the hero's height.
    • Fallback Color: Always use background-color to provide a fallback color for email clients that do not support background-url.

    Height Modes

    • fluid-height (Default): The hero height adjusts based on the content inside.
    • fixed-height: The hero maintains a specific height. When using this mode, the height attribute is required.
    <!-- Example of Fixed Height Mode -->
    <mjml>
      <mj-body>
        <mj-hero
          mode="fixed-height"
          height="469px"
          background-width="600px"
          background-height="469px"
          background-url="https://static.mailjet.com/mjml-website/documentation/hero.jpg"
          background-color="#2a3448"
          padding="100px 0px">
          <mj-text>GO TO SPACE</mj-text>
        </mj-hero>
      </mj-body>
    </mjml>
  12. Define global styles with mj-all

    master

    The <mj-all> tag is used inside <mj-attributes> to apply specific attributes to all MJML components globally. This is useful for setting a universal font family or base color across the entire email.

    <mjml>
     <mj-head>
       <mj-attributes>
         <mj-all font-family="Arial" />
       </mj-attributes>
     </mj-head>
     <mj-body>
       <!-- All components will now use Arial by default -->
     </mj-body>
    </mjml>