https://github.com/premail/mjml-bullet-list
Easily use bulleted lists in your MJML emails.
https://github.com/premail/mjml-bullet-list
email mjml mjml-component mjml-framework mjml-template mjml-to-html mjml4
Last synced: about 1 month ago
JSON representation
Easily use bulleted lists in your MJML emails.
- Host: GitHub
- URL: https://github.com/premail/mjml-bullet-list
- Owner: premail
- License: agpl-3.0
- Created: 2021-09-28T23:46:28.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-07-29T10:18:35.000Z (almost 2 years ago)
- Last Synced: 2025-03-29T09:01:33.495Z (about 2 months ago)
- Topics: email, mjml, mjml-component, mjml-framework, mjml-template, mjml-to-html, mjml4
- Language: JavaScript
- Homepage:
- Size: 484 KB
- Stars: 14
- Watchers: 1
- Forks: 4
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Contributing: docs/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: docs/CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: docs/SECURITY.md
Awesome Lists containing this project
README
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
[](https://www.npmjs.com/package/mjml-bullet-list)
[](https://github.com/premail/mjml-bullet-list/releases)
[](https://github.com/premail/premail/releases/latest)
[](https://github.com/mjmlio/mjml/releases)
[](https://github.com/premail/mjml-bullet-list/blob/main/LICENSE)
[](https://github.com/premail/mjml-bullet-list/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22%2C%22Status%3A+Available%22+sort%3Aupdated-desc+)
---
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
---
`
- ` 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
- `. 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).
[``](https://documentation.mjml.io/#mj-text) within
[``](https://documentation.mjml.io/#mj-column).**``** replaces `
- `. Use it inside ``.