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:
index.mjmlfile. 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.
.mjmlconfigfile 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
echo %cd% on Windows).
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.
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
- The style of the image thanks to the attributes
- The style of the text thanks to the attributes
- 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
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
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
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!
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.