Tutorial: creating your own MJML component

MJML is built upon components, used under the form of tags in the markup language. Added to the standard library of components, it is possible for anyone to create their own component, leveraging MJML’s easy syntax to make it easier to reuse bits of code without having to type them over and over.

Let’s walk you through the component creation process. Since MJML is written in ES6, it is dependant on a few things like Babel. Don’t worry though, we got you covered with a boilerplate so all you have to do is clone the component boilerplate. To do so, just open your terminal (go to wherever you want your folder to be created) and run git clone https://github.com/mjmlio/mjml-component-boilerplate.git && cd mjml-component-boilerplate. Then, run npm install to install the dependencies.

Understanding the structure

While you’re installing dependencies, let’s go over what is in this folder. The most important elements of this boilerplate are:

  • An index.mjml file. This is where your MJML lives and where we will use the custom component (uncomment it to use it!).
  • A components folder, where your custom components written in ES6 are located.
  • A lib folder, where custom components compiled from ES6 to ES5 with babel are located. You should not edit the files in this folder.
  • .mjmlconfig file where you are registering your custom components so they can be used by the MJML engine which wouldn’t know them otherwise.

Creating your first component

First, it is important that you change the path to your component in .mjmlconfig. The file will probably be hidden by default when you browse the folder. To open it, just run open .mjmlconfig in your terminal and replace the path to /lib/MjColumnImageText.js to your local path to this file. To get the local path from your terminal, run pwd (echo %cd% on Windows).

Run npm start so that index.mjml and your custom components are recompiled at each edit you’ll make. If you don’t want to automatically watch and recompile the files, you can simply run npm run build to compile them manually whenever you want.

Now, let’s create a component together. We’ll create a simple component that display a 2 column layout with an image on the left part and a text on the right part. It is intentionally basic as the idea is to show you how to create your own component specific to your need.

Example of use of our custom component

Now, we obviously want to make some of the content of this component dynamic so we can customise it when using the component. Here is what we will be able to customise thanks to the components attributes:

  • The direction of the component (whether the image should be on the left or right) thanks to the attribute direction
  • The style of the image thanks to the attributes image-padding, image-src, image-width
  • The style of the text thanks to the attributes color, font-size
  • Feel free to add more attributes to Section, Column, Image or Text following the same structure (given the components support the attributes you use)

The great thing with MJML components is that you can create them using HTML but also MJML.

Show me the code!

Let’s split the code of our custom component bits by bits. All the code snippets below are taken from the file MjColumnImageText.js located in the components folder.

1. Importing dependencies

First, we need to import dependencies. This includes React but also MJML components that we’ll reuse. Here, we’ll use mjml-core, in charge of rendering MJML and the section, column, image and text components.

2. Setting up the component and its default attributes

Then, we’ll “configure” our component, stating explicitly its name, where it can be used, whether it uses MJML or HTML and what the default attributes are.

3. Defining the component and what it renders

Now, this is where all the magic happens, where we’re defining what our component renders (whether it is MJML or HTML). Here, we’ll leverage the existing components Section, Column, Image, Text so we don’t even have to bother with responsive HTML. As we’re creating a component made of Image and Text, we decided to create 3 render methods:

  • A render method for the image column (renderImage())
  • A render method for the text column (renderContent())
  • A render method to render the image + the text columns (render())

4. Making our component available

Finally, we’re just binding the configuration we did at step 2 to the component we just created and exporting our component so we can reuse it.

Using your component

Open index.mjml and uncomment the custom component (lines 15 to 17).

If you were running npm start as you were making changes, your files are up to date. All you have to do to see the magic happen is open index.html.

If you were not running npm start, run npm run build to compile your components and index.mjml Then, you can open index.html to see how your component looks.

Publishing your component

Now that you have a shiny new component, you might want to open source it so the community can benefit from it. One way to do that is to publish the code of your component in a repository on Github so people can clone it and npm install it like you did in this tutorial. Better yet, you can publish it on NPM so people can directly install it!

Need help?

You can find a list of MJML components here if you need inspiration.

If you encounter any trouble, please open an issue on Github so we can help you.


We hope you enjoyed this tutorial. Feel free to share feedback in comments, on Twitter and directly on Slack! Want to be the first to know about what’s new in MJML? Subscribe to the newsletter from the website.