MJML Bullet List: <mj-list> and <mj-li>

Making bulletproof bulleted lists in emails easy with MJML!

Report a Bug - Request a Feature - Ask a Question

---

This MJML component is brought to you by Premail, and the following documentation can also be found at https://premail.dev/docs/components/mjml-bullet-list

---

<ul> and <li> HTML elements can be used in HTML emails, but getting them to render consistently takes a little work. This is a shortcut for these elements. Its output is predictably boring, but bulletproof (forgive the pun) for email clients:

<mj-list> replaces <ul>. Use it alongside <mj-text> within <mj-column>.

<mj-li> replaces <li>. Use it inside <mj-list></mj-list>.

MJML Bullet List is designed for MJML 4+ and is unrelated to the v3 component mjml-list.

---

• Usage
  • Coding
  • MJML Head
  • Styling
  • Options
    • Available options for <mj-list>
    • Available options for <mj-li>
  • Adding this to your emails
  • Fork or contribute to this component
• Security
• License

Usage

Coding

This MJML:

<mj-list>
  <mj-li>List item one.</mj-li>
  <mj-li>List item two.</mj-li>
  <mj-li>List item three.</mj-li>
  <mj-li>List item four.</mj-li>
</mj-list>

Will produce the following visual representation:

Not very exciting, but reliably rendered in all email clients.

But you can get more creative. This MJML:

<mj-text>
  <p>
    Examples of the custom "mj-list" and "mj-li" tags. Here is a list with an
    option set on the entire list:
  </p>
</mj-text>
<mj-list background-color="#ddd">
  <mj-li>List item one.</mj-li>
  <mj-li>List item two.</mj-li>
  <mj-li>List item three.</mj-li>
  <mj-li>List item four.</mj-li>
</mj-list>
<mj-text>
  <p>And here's a list with options set on individual list items:</p>
</mj-text>
<mj-list>
  <mj-li
    >List item one. Lorem ipsum dolor sit amet, sed do eiusmod tempor incididunt
    ut labore et dolore magna aliqua.</mj-li
  >
  <mj-li color="blue"
    >List item two, customized color for the entire list item.</mj-li
  >
  <mj-li>List item three.</mj-li>
  <mj-li bullet-color="red" padding-left="40px"
    >List item four, customized bullet color and left padding. Duis aute irure
    dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
    pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui
    officia deserunt mollit anim id est laborum.</mj-li
  >
  <mj-li gutter="20px">List item five, custom gutter size.</mj-li>
  <mj-li>List item six.</mj-li>
  <mj-li text-color="green"
    >List item seven, customized text (only) color. Ut enim ad minim veniam,
    quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
    consequat.</mj-li
  >
</mj-list>

Will produce the following visual representation:

MJML Head

In your <mj-head> component, you should also add the following:

<mj-html-attributes>
  <mj-selector path=".list table table">
    <mj-html-attribute name="role">list</mj-html-attribute>
  </mj-selector>
  <mj-selector path=".list table table > tbody">
    <mj-html-attribute name="role">presentation</mj-html-attribute>
  </mj-selector>
</mj-html-attributes>

This will ensure that these lists are properly described as such when the email is read using assistive technology.

Styling

In addition to setting attributes with the elements options (see below), you can also modify them through CSS. Use <mj-style> and target the .list and .list-item classes.

You can see this being done in the example MJML file.

Options

Available options for <mj-list>

option	unit	details	default value
background-color	color	Applies to entire list	none
border	string (border)	Applies to entire list	none
border-top	string (border)	Applies to entire list	none
border-right	string (border)	Applies to entire list	none
border-bottom	string (border)	Applies to entire list	none
border-left	string (border)	Applies to entire list	none
border-radius	pixels	Applies to entire list	none
direction	ltr, rtl	Language direction	ltr
inner-background-color	color	Applies to entire list	none
padding	pixels	Applies to entire list	none
padding-top	pixels	Applies to entire list	none
padding-right	pixels	Applies to entire list	none
padding-bottom	pixels	Applies to entire list	none
padding-left	pixels	Applies to entire list	25px (note that if you set this to 0, the bullet icons in the list may overflow their container)
vertical-align	top, middle, bottom	Applies to entire list	top
width	pixels	Applies to entire list	none (full width of container)

Available options for <mj-li>

option	unit	details	default value
color	color	Applies to both bullet marker and text	none (inherited from parent text style)
bullet-color	color	Applies to bullet marker only	none (inherited from color)
text-color	color	Applies to text only	none (inherited from color)
background-color	color	Applies to list item	none
font-family	string	Applies to list item	Ubuntu, Helvetica, Arial, sans-serif (from <mj-text>)
font-size	pixels	Applies to list item	13px (from <mj-text>)
font-style	string	Applies to list item	none
font-weight	string	Applies to list item	none
gutter	pixels	Distance between bullet marker and text	3px
letter-spacing	pixels (negative allowed)	Applies to list item	none
line-height	number, pixels or percentage	Applies to list item	none
padding-right	pixels	Applies to list item	none
padding-left	pixels	Applies to list item	none
text-align	left, center, right, justify	Applies to list item	left
text-decoration	string	Applies to list item	none
text-transform	string	Applies to list item	none
vertical-align	top, middle, bottom	Applies to list item	top

Adding this to your emails

In your MJML project directory, install this package via npm:

npm install mjml-bullet-list

In your build process script (such as gulp), require the package:

const mjmlBulletList = require('mjml-bullet-list')

or

import mjmlBulletList from mjml-bullet-list

Finally, add the package to your .mjmlconfig:

{
  "packages": ["mjml-bullet-list/lib/MjList", "mjml-bullet-list/lib/MjLi"]
}

You can now use <mj-list> and <mj-li> in your MJML emails.

Fork or contribute to this component

If you want to edit this component, first grab it via git:

git clone https://github.com/premail/mjml-bullet-list.git

Navigate to the folder and install:

cd mjml-bullet-list
npm install

Edit the component script file in ./components/, then run gulp build or gulp watch to compile. We include sheerun/modern-node, which formats and lints code automatically on commits using Prettier and ESLint. You can use npm run format and npm run lint on their own as well.

To run tests, use npm run test

If you want to use a forked version of this component in your emails without having to publish it to npm, see premail/mjml-custom-component for a guide.

Security

Legalese: This component is provided "as is" without any warranty. Use at your own risk.

For more information and to report security issues, please refer to our security documentation.

License

mjml-bullet-list is licensed under the GNU Affero General Public License v3.0 or later. To be clear: This license only covers the component's code, not any content you generate using it.

For the legal details of the AGPL, see the complete LICENSE.