Contribute to this guide

guideDocument 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.

There are currently two plugins providing lists support for CKEditor 5: the regular lists feature and this new document lists feature.

The document lists feature is not enabled in any builds, you need to install it by hand.

# 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 Insert ordered list and unordered lists Insert unordered list list items.

Top five places to visit this summer

...and stay on the budget.

  1. Gran Canaria, Spain

    Gran Canaria is a popular tourist destination. The island is often called "a miniature continent". This is owed to the fact, that it offers a great variety of climates and landscapes, from golden, sandy beaches, through rocky ravines, to white dunes, and charming villages. In the mid-2010s over 3.5 million tourists visited Gran Canaria annually.

  2. Florence, Italy

    Florence, established in 59BC by Julius Caesar himself got its name from two rivers that surrounded the settlement. Thanks to centuries of history, the capital of Tuscany has plenty to offer to tourists hungry for sightseeing. Some of the most interesting places to visit include:

    Florence is also regarded as one of the top 15 fashion capitals of the world.

  3. Porto, Portugal

    Porto, located at the Duero river estuary in northern Portugal, is the second-largest city in this country. It is regarded to be one of the oldest European centers, which was notably emphasized in 1996 when UNESCO deemed the city's historic center a World Heritage Site.

    The old town of Porto is a UNESCO World Heritage site.

    In 2014 and 2017, Porto was elected The Best European Destination by the Best European Destinations Agency. The city is also home to the Porto School of Architecture regarded to be one of the most prestigious architecture schools in the world.

  4. Budapest, Hungary

    The capital of Hungary, a spa city sitting across the Danube river, is alive with Roman, Turkish, and European history and cultural heritage. Thermal baths, a picturesque river, and the Gellért Hill citadel are only a few things worth mentioning while planning your trip to Hungary.

    They said that, of course, Budapest is beautiful. But it is in fact almost ludicrously beautiful. – Anthony Bourdain

  5. The Peloponnese, Greece

    The Peloponnese peninsula was already inhabited in prehistoric times. During the bronze age, the first European highly developed culture – the Mycenaean civilization – started there. Roman, Byzantine, Slavic, and Ottoman rules left a significant mark on the place with numerous architectural and cultural relics worth visiting till this day.

This demo only presents a limited set of features. Visit the full-featured editor example to see more in action.

# 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.

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( ... );

Read more about installing plugins.

The DocumentListProperties feature overrides UI button implementations from the ListUI.

# Common API

The DocumentList plugin registers:

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.