Skip to content

Easily use bulleted lists in your MJML emails.

License

Notifications You must be signed in to change notification settings

premail/mjml-bullet-list

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

npm GitHub release (latest SemVer) Release Date MJML 4.0+ valid License: AGPL-3.0+ Pull Requests welcome


PremailThis 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:

Example of simple generated markup from the MJML Bullet List component

<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

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:

Example of simple generated markup from the MJML Bullet List component

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:

Example of advanced generated markup from the MJML Bullet List component

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.