Document list

The document list feature is based on a completely different approach than the regular list. Unlike regular list, which is a content block in itself, the document list plugin will let any part of the content be part of a list. Content blocks and elements – such as blockquotes, tables, paragraphs, and others – can now be put inside a list item, ensuring the continuity of numbering and retaining indentation.

Just like regular lists, the document list feature supports both ordered and unordered lists.

# Demo

Use the demo below to add block elements like tables, images or nested lists and see the document retain ordering and list styles. Use the toolbar buttons to insert new ordered and unordered lists list items.

# List styles

Document lists offers additional formatting tools that allow controlling the lists, just like regular lists. The list style feature introduces some more styles for the list item markers. When enabled, it adds 3 styles for unordered lists and 6 styles for ordered lists to choose from. The user will be able to set or change the list style via the dropdown that opens when you click the arrow next to the appropriate list button in the toolbar.

# List indentation

Refer to the Indenting lists section of the Block indentation feature guide.

# Related features

These features also provide similar functionality:

• 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.
• Autoformatting – Format the text on the go with Markdown code.

# Installation

# Document list feature

To add this feature to your editor, install the @ckeditor/ckeditor5-list package:

npm install --save @ckeditor/ckeditor5-list

Then add the DocumentList plugin to your plugin list and the toolbar configuration:

import DocumentList from '@ckeditor/ckeditor5-list/src/documentlist';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ DocumentList, ... ],
        toolbar: [ 'bulletedList', 'numberedList', ... ]
    } )
    .then( ... )
    .catch( ... );

# Document list properties

To enable the list properties feature for document lists, install the @ckeditor/ckeditor5-list package:

npm install --save @ckeditor/ckeditor5-list

Then add the DocumentListProperties plugin to your plugin list and configure the toolbar. To enable selected sub-features of the list properties, you need to add their configuration to your editor (set true for each feature you want to enable):

import DocumentListProperties from '@ckeditor/ckeditor5-list/src/documentlistproperties';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ DocumentListProperties, ... ],
        toolbar: [ 'bulletedList', 'numberedList', ... ],
        list: {
            properties: {
                styles: true,
                startIndex: true,
                reversed: true
            }
        }
    } )
    .then( ... )
    .catch( ... );

# Common API

The DocumentList plugin registers:

• The 'numberedList' command.
• The 'bulletedList' command.
• The 'indentList' command.
• The 'outdentList' command.
• The 'numberedList' UI button.
• The 'bulletedList' UI button.

The DocumentListProperties plugin registers:

• The documentListStyle command that accepts the type of the list style to set. If not set, is uses the default marker (usually decimal).

  editor.execute( 'documentListStyle', { type: 'lower-roman' } );
  

  The available types are:

  • For bulleted lists: 'disc', 'circle' and 'square'.
  • For numbered lists: 'decimal', 'decimal-leading-zero', 'lower-roman', 'upper-roman', 'lower-latin' and 'upper-latin'.

• The documentListStart command which is a Number and defaults to 1 (meaning a list starts with 1). If enabled, it accepts a numerical value for the start attribute.

  editor.execute( 'documentListStart', { startIndex: 3 } );
  

• The documentListReversed command which is a Boolean and defaults to false (meaning the list order is ascending).

  editor.execute( 'documentListReversed', { reversed: true } );
  

• The numberedList UI split button that overrides the UI button registered by the List plugin.

• The bulletedList UI split button that overrides the UI button registered by the List plugin.

# Contribute

The source code of the feature is available on GitHub in https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-list.