# Multi-level lists

Multi-level lists with the legal style numbering feature allows for easy creation and modification of numbered lists with counters (1, 1.1, 1.1.1). These are crucial for clear referencing and hierarchical organization in complex documents. The feature offers full compatibility with Microsoft Word. When lists with such formatting are pasted to the editor with the [paste from Office enhanced](../pasting/paste-from-office-enhanced.md) feature, the numbering format is retained.

> **Unlock this feature with selected CKEditor Plans**
>
> Try all premium features – no credit card needed.
>
> [Sign up for a free trial ](https://portal.ckeditor.com/checkout?plan=free)[Select a Plan](https://ckeditor.com/pricing/)

<a id="demo">

## Demo

<!-- AI-AGENT-NOTE: An interactive demo is embedded here but is not represented in this Markdown file. If you need to see it in action, open this page in a browser (e.g. via a browser-automation MCP like Chrome DevTools or Playwright), or let the user know a live demo is available on this page. -->

This demo presents a limited set of features. Visit the [feature-rich editor example](../../examples/builds-custom/full-featured-editor.md) to see more in action.

<a id="additional-feature-information">

## Additional feature information

<a id="headings-in-multi-level-lists">

### Headings in multi-level lists

Multi-level lists support headings in list items. The marker, which denotes the counter, will insert itself into the heading block to achieve more similar styles.

While creation of a legal document with a list of numbered headings is possible, the editing of long-form documents may not be the best experience. You might want full support for the **numbered headings feature** that Microsoft Word places in the multi-level lists interface. We do not have it yet, but if you are interested, please let us know in [this GitHub issue](https://github.com/ckeditor/ckeditor5/issues/16161) or via our support.

<a id="custom-multi-level-list-styles">

### Custom multi-level list styles

For now, we provide one style for multi-level lists: legal style numbering. But this first step opens a possibility for us to add more styles in the future or allow integrators to create their own styles. If you are interested, please let us know in [this GitHub issue](https://github.com/ckeditor/ckeditor5/issues/8687) or via our support.

<a id="marker-formatting-in-multi-level-lists">

### Marker formatting in multi-level lists

Multi-level lists follow the [list item marker formatting](lists-properties.md#list-item-marker-formatting) rules and use the same `ck-list-marker-*` classes and CSS variables as ordered and unordered lists. The difference is the marker itself: a multi-level list renders it as a regular element with the `multi-level-list__marker` class instead of the `::marker` pseudo-element, so target that element in your CSS. For example, this keeps one font family for all markers:

```css
.ck-content ol.multi-level-list li.ck-list-marker-font-family > .multi-level-list__marker,
.ck-content ol.multi-level-list li.ck-list-marker-font-family > * > .multi-level-list__marker {
	font-family: var(--ck-content-font-family);
}
```

The `ol` part of the selector is there on purpose. Without it, the rule has the same specificity as the built-in one and works only when your style sheet is loaded after the content styles.

A wider marker extends to the left here as well, so the [marker width and list alignment](lists-properties.md#marker-width-and-list-alignment) notes apply to multi-level lists too.

<a id="skip-level-lists">

### Skip-level lists

The [`config.list.enableSkipLevelLists`](../../api/module_list_listconfig-ListConfig.md#member-enableSkipLevelLists) option also applies to multi-level lists. When enabled, items can skip indentation levels, and any skipped levels are filled with `1` in the legal-style marker. For example, an item at indent 0 (`1`) followed directly by an item at indent 2 renders as `1.1.1`. See the [Skip-level lists](lists-editing.md#skip-level-lists) section of the lists editing behavior guide for the full description.

<a id="installation">

## Installation

> **Note**
>
> Please note that this plugin requires the [basic `List` plugin](lists.md) to work properly.

After [installing the editor](../../getting-started/installation/cloud/quick-start.md), add the features to your plugin list and toolbar configuration:

**NPM**

```js
import { List } from 'ckeditor5';
import { MultiLevelList } from 'ckeditor5-premium-features';

ClassicEditor
	.create( {
		licenseKey: '<YOUR_LICENSE_KEY>',
		plugins: [ List, MultiLevelList, /* ... */ ],
		toolbar: [ 'multiLevelList', /* ... */ ]
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

**CDN**

```js
const { List } = CKEDITOR;
const { MultiLevelList } = CKEDITOR_PREMIUM_FEATURES;

ClassicEditor
	.create( {
		licenseKey: '<YOUR_LICENSE_KEY>',
		plugins: [ List, MultiLevelList, /* ... */ ],
		toolbar: [ 'multiLevelList', /* ... */ ]
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

> **Note**
>
> Read more about [installing plugins](../../getting-started/setup/configuration.md) and [toolbar configuration](../../getting-started/setup/toolbar.md).

<a id="activating-the-feature">

### Activating the feature

To use this premium feature, you need to activate it with proper credentials. Refer to the [License key and activation](../../getting-started/licensing/license-key-and-activation.md) guide for details.

<a id="related-features">

## Related features

* [Ordered and unordered lists](lists.md) – Create ordered and unordered lists with configurable markers.
* [To-do lists](todo-lists.md) – Create a list of interactive checkboxes with labels.
* [Block indentation](../indent.md) – Set indentation for text blocks such as paragraphs or headings and lists.
* [Paste from Office enhanced](../pasting/paste-from-office-enhanced.md) – Paste Office documents with high compatibility.

<a id="common-api">

## Common API

The [`MultiLevelList`](../../api/module_list-multi-level_multilevellist-MultiLevelList.md) registers:

* The `'multiLevelList'` UI dropdown component.
* The `'multiLevelList'` command implemented by [`MultiLevelListCommand`](../../api/module_list-multi-level_multilevellistcommand-MultiLevelListCommand.md).

You can execute the command using the [`editor.execute()`](../../api/module_core_editor_editor-Editor.md#function-execute) method:

```js
// Change selected content to multi level list.
editor.execute( 'multiLevelList' );
```

> **Note**
>
> We recommend using the official [CKEditor 5 inspector](../../framework/development-tools/inspector.md) for development and debugging. It will give you tons of useful information about the state of the editor such as internal data structures, selection, commands, and many more.

---

Full index of the CKEditor 5 documentation: [llms.txt](../../../llms.txt)