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 feature, the numbering format is retained.

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 or via our support.

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 or via our support.

Multi-level lists follow the 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:

.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 notes apply to multi-level lists too.

The config.list.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 section of the lists editing behavior guide for the full description.

After installing the editor, add the features to your plugin list and toolbar configuration:

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

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

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

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

To use this premium feature, you need to activate it with proper credentials. Refer to the License key and activation guide for details.

• Ordered and unordered lists – Create ordered and unordered lists with configurable markers.
• To-do lists – Create a list of interactive checkboxes with labels.
• Block indentation – Set indentation for text blocks such as paragraphs or headings and lists.
• Paste from Office enhanced – Paste Office documents with high compatibility.

The MultiLevelList registers:

• The 'multiLevelList' UI dropdown component.
• The 'multiLevelList' command implemented by MultiLevelListCommand.

You can execute the command using the editor.execute() method:

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