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

` and `
• ` HTML elements can be used in HTML emails, but getting them to render consistently [takes a little work](https://www.litmus.com/blog/the-ultimate-guide-to-bulleted-lists-in-html-email/). This is a shortcut for these elements. Its output is predictably boring, but bulletproof (forgive the pun) for email clients:  **``** replaces `
  `. Use it alongside [``](https://documentation.mjml.io/#mj-text) within [``](https://documentation.mjml.io/#mj-column). **``** replaces `
  • `. Use it inside ``. _MJML Bullet List is designed for MJML 4+ and is unrelated to the v3 component [`mjml-list`](https://www.npmjs.com/package/mjml-list)._ --- - [Usage](#usage) - [Coding](#coding) - [MJML Head](#mjml-head) - [Styling](#styling) - [Options](#options) - [Available options for <mj-list>](#available-options-for-mj-list) - [Available options for <mj-li>](#available-options-for-mj-li) - [Adding this to your emails](#adding-this-to-your-emails) - [Fork or contribute to this component](#fork-or-contribute-to-this-component) - [Security](#security) - [License](#license) # Usage ## Coding This MJML: ```html List item one. List item two. List item three. List item four. ``` Will produce the following visual representation:  Not very exciting, but reliably rendered in all email clients. But you can get more creative. This MJML: ```html

    Examples of the custom "mj-list" and "mj-li" tags. Here is a list with an option set on the entire list:

    List item one. List item two. List item three. List item four.

    And here's a list with options set on individual list items:

    List item one. Lorem ipsum dolor sit amet, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. List item two, customized color for the entire list item. List item three. 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. List item five, custom gutter size. List item six. List item seven, customized text (only) color. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. ``` Will produce the following visual representation:  ## MJML Head In your `` component, you should also add the following: ```html list presentation ``` 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 [``](https://documentation.mjml.io/#mj-style) and target the `.list` and `.list-item` classes. You can see this being done in the [example MJML file](docs/example.mjml). ## Options ### Available options for `` | option | unit | details | default value | | ------------------------ | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | `background-color` | color | Applies to entire list | none | | `border` | string ([border](https://developer.mozilla.org/en-US/docs/Web/CSS/border)) | Applies to entire list | none | | `border-top` | string ([border](https://developer.mozilla.org/en-US/docs/Web/CSS/border)) | Applies to entire list | none | | `border-right` | string ([border](https://developer.mozilla.org/en-US/docs/Web/CSS/border)) | Applies to entire list | none | | `border-bottom` | string ([border](https://developer.mozilla.org/en-US/docs/Web/CSS/border)) | Applies to entire list | none | | `border-left` | string ([border](https://developer.mozilla.org/en-US/docs/Web/CSS/border)) | Applies to entire list | none | | `border-radius` | pixels | Applies to entire list | none | | `direction` | `ltr`, `rtl` | [Language direction](https://www.w3.org/International/questions/qa-html-dir) | `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 `` | 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 [``](https://documentation.mjml.io/#mj-text)) | | `font-size` | pixels | Applies to list item | `13px` (from [``](https://documentation.mjml.io/#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: ```sh npm install mjml-bullet-list ``` In your build process script (such as gulp), require the package: ```js const mjmlBulletList = require('mjml-bullet-list') ``` or ```js import mjmlBulletList from mjml-bullet-list ``` Finally, add the package to your `.mjmlconfig`: ```json { "packages": ["mjml-bullet-list/lib/MjList", "mjml-bullet-list/lib/MjLi"] } ``` You can now use `` and `` in your MJML emails. ## Fork or contribute to this component If you want to edit this component, first grab it via git: ```sh git clone https://github.com/premail/mjml-bullet-list.git ``` Navigate to the folder and install: ```sh 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](https://github.com/sheerun/modern-node), which formats and lints code automatically on commits using [Prettier](https://prettier.io/) and [ESLint](https://eslint.org/). 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](https://github.com/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](https://github.com/premail/mjml-bullet-list/blob/main/docs/SECURITY.md)._ # 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](https://github.com/premail/mjml-bullet-list/blob/main/LICENSE).