# @editorjs/list

> List Tool for EditorJS

Latest version **2.0.9** (published 2025-11-13) · MIT license · 0 weekly downloads

## Install

```sh
npm install @editorjs/list
pnpm add @editorjs/list
yarn add @editorjs/list
bun add @editorjs/list
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.0.9 |
| Published | 2025-11-13 |
| First published | 2019-03-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 156 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 76 |
| Author | CodeX |
| Maintainers | codex-team |
| Keywords | codex editor, list, editor.js, editorjs |

## Links

- npm: https://www.npmjs.com/package/@editorjs/list
- Repository: https://github.com/editor-js/list
- npm.io page: https://npm.io/package/@editorjs/list

## Dependencies (1)

- [@codexteam/icons](https://npm.io/package/@codexteam/icons.md) ^0.3.2

## Alternatives

- [ext-list](https://npm.io/package/ext-list.md) — 6.3M weekly downloads
- [@lexical/selection](https://npm.io/package/@lexical/selection.md) — 3.8M weekly downloads
- [@lexical/text](https://npm.io/package/@lexical/text.md) — 3.6M weekly downloads
- [@lexical/clipboard](https://npm.io/package/@lexical/clipboard.md) — 3.0M weekly downloads
- [@tiptap/extension-mention](https://npm.io/package/@tiptap/extension-mention.md) — 3.0M weekly downloads

## Recent versions

- 2.0.9 (latest) — 2025-11-13
- 2.0.8 — 2025-05-04
- 2.0.7 — 2025-05-04
- 2.0.6 — 2025-02-28
- 2.0.5 — 2025-02-27
- 2.0.4 — 2025-01-24
- 2.0.3 — 2025-01-18
- 2.0.2 — 2024-11-20
- 2.0.1 — 2024-11-20
- 2.0.0 — 2024-11-13
- 1.10.0 — 2024-07-24
- 1.9.0 — 2023-11-10
- 1.8.0 — 2022-11-29
- 1.7.0 — 2022-03-09
- 1.6.2 — 2021-01-26
- … 10 more at https://npm.io/package/@editorjs/list/versions

## README

![](https://badgen.net/badge/Editor.js/v2.19.2/blue)

# Editorjs List Tool

![](assets/readme_image.png)

- 🤩 Part of [Editor.js](https://editorjs.io/) ecosystem.
- 📂 Nesting.
- 🔥 Ordered and Unordered lists.
- ✅ Checklists.
- 🔢 Customizable start number.
- 🏛️ Customizable counter type (e.g. `lower-roman`).
- 🪜 Max nesting level configuration.
- 📝 Compatible with [List](https://github.com/editor-js/list) and [Checklist](https://github.com/editor-js/checklist).

![](assets/demo.gif)

Use `Tab` and `Shift+Tab` keys to create or remove sublist with a padding.

## Installation

Get the package

```shell
yarn add @editorjs/list
```

Include module at your application

```javascript
import EditorjsList from '@editorjs/list';
```

Optionally, you can load this tool from CDN [JsDelivr CDN](https://cdn.jsdelivr.net/npm/@editorjs/list@2)

## Usage

Add the List Tool to the `tools` property of the Editor.js initial config.

```javascript
import EditorJS from '@editorjs/editorjs';
import EditorjsList from '@editorjs/list';

var editor = EditorJS({
  // ...
  tools: {
    ...
    List: {
      class: EditorjsList,
      inlineToolbar: true,
      config: {
        defaultStyle: 'unordered'
      },
    },
  },
});
```
> [!IMPORTANT]
> Note that in List 2.0 class name changed from `List` to `EditorjsList`.

## Config Params

| Field        | Type     | Description                                                    |
|--------------|----------|----------------------------------------------------------------|
| defaultStyle | `string` | default list style: `ordered`, `unordered` or `checklist`, default is `unordered` |
| maxLevel     | `number` | maximum level of the list nesting, could be set to `1` to disable nesting, unlimited by default |
| counterTypes | `string[]` | specifies which counter types should be shown in the ordered list style, could be set to `['numeric','upper-roman']`, default is `undefined` which shows all counter types |

## Output data

| Field             | Type      |  Description                                                                                                              |
| ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------- |
| style             | `string`  |  list will be rendered with this style: `ordered`, `unordered` or `checklist`, default is `defaultStyle` from tool config |
| meta              | `ItemMeta`|  Item meta based on the list style                                                                                         |
| items             | `Item[]`  |  the array of list's items                                                                                                |

Object `Item`:

| Field   | Type       | Description                 |
| ------- | ---------- | --------------------------- |
| content | `string`   | item's string content       |
| meta    | `ItemMeta` | meta information about item |
| items   | `Item[]`   | the array of list's items   |

Object `ItemMeta` for Checklist:

| Field   | Type      | Description               |
| ------- | --------- | ------------------------- |
| checked | `boolean` | state of the checkbox     |

Object `ItemMeta` for Ordered list

| Field   | Type      | Description               |
| ------- | --------- | ------------------------- |
| start   | `number`  | number for list to start with, default is 1 |
| counterType | `string`  | counter type for list, it could be `numeric`, `lower-roman`, `upper-roman`, `lower-alpha`, `upper-alpha`, default is `numeric` |


Object `ItemMeta` for Unordered list would be empty.

## Localisation
If you want to use your language for toolbox items, you can pass i18n dictionary to the editorjs instance below the tools `block`:
```javascript
i18n: { 
  messages: {
    "toolNames": {
      "Ordered List": "Nummerierte Liste",
      "Unordered List": "Unnummeriert Liste",
      "Checklist": "Checkliste",
    },
    "tools": {
      "List": {
        'Unordered': 'Unnummeriert',
        'Ordered': 'Nummerierte',
        'Checklist': 'Checkliste',
      }
    },
  },
},
```

### Other supported keys for `tools.List`
- `Start with`
- `Counter type`
- `Numeric`
- `Lower Roman`
- `Upper Roman`
- `Lower Alpha`
- `Upper Alpha`

## Example of the content for `Unordered List`
```json
{
  "type" : "list",
  "data" : {
    "style": "unordered",
    "items": [
      {
        "content": "Apples",
        "meta": {},
        "items": [
          {
            "content": "Red",
            "meta": {},
            "items": []
          },
        ]
      },
    ]
  }
},
```

## Example of the content for `Ordered List`
```json
{
  "type" : "list",
  "data" : {
    "style": "ordered",
    "meta": {
      "start": 2,
      "counterType": "upper-roman",
    },
    "items" : [
      {
        "content": "Apples",
        "meta": {},
        "items": [
          {
            "content": "Red",
            "meta": {},
            "items": []
          },
        ]
      },
    ]
  }
},
```

## Example of the content for `Checklist`
```json
{
  "type" : "list",
  "data" : {
    "style": "checklist",
    "items" : [
      {
        "content": "Apples",
        "meta": {
          "checked": false
        },
        "items": [
          {
            "content": "Red",
            "meta": {
              "checked": true
            },
            "items": []
          },
        ]
      },
    ]
  }
},
```

---
_Source: https://npm.io/package/@editorjs/list · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._