Document lists
The document list feature lets you create ordered and unordered lists. The unique thing about them is that you can put any content inside each list item (including block elements like paragraphs and tables), retaining the continuity of numbering and indentation.
The document lists feature will become the default list feature for CKEditor 5 in the upcoming releases and will replace the current one. This plugin will then be withdrawn at the beginning of 2024.
See #14767 for more details.
# Demo
Use the demo below to add block elements like tables, images, or nested lists. Notice that the document retains the ordering and list styles. Use the toolbar buttons to insert new ordered
and unordered lists .Top five places to visit this summer
...and stay on the budget.
-
Gran Canaria, Spain
Gran Canaria is a popular tourist destination. The island is often called “a miniature continent”. This is because it offers a great variety of climates and landscapes, from golden sandy beaches through rocky ravines and white dunes to charming villages. In the mid-2010s, over 3.5 million tourists visited Gran Canaria each year.
-
Florence, Italy
Florence, established in 59 BC 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:
- Piazza della Signoria
- Mercato Centrale and the San Lorenzo Market
- Museum of Zoology and Natural History “La Specola”
Florence is also regarded as one of the top 15 fashion capitals of the world.
-
Porto, Portugal
Porto, located at the Duero river estuary in northern Portugal, is the country’s second-largest city. It is regarded as one of the oldest European centers, which was recognized in 1996 when 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, one of the most prestigious architecture schools in the world.
-
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, the picturesque river, and the Gellért Hill citadel are only a few things worth considering while planning your trip to Hungary.
They said that, of course, Budapest is beautiful. But it is in fact almost ludicrously beautiful. – Anthony Bourdain
-
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 to this day.
This demo only presents a limited set of features. Visit the feature-rich editor example to see more in action.
# List styles
Document lists offer additional formatting tools, 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.
# Installation
There are currently two plugins providing list support for CKEditor 5: the regular lists feature and this new document lists feature.
The document lists feature is not enabled in any builds, so you need to install it by hand.
# 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';
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';
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
.
# List merging
By default, two lists of the same type (ordered and unordered) that are next to each other are merged together. This is done so that lists that visually appear to be one continuous list actually are, even if the user has accidentally created several of them.
Unfortunately, in some cases this can be undesirable behavior. For example, two adjacent numbered lists, each with two items, will merge into a single list with the numbers 1 through 4.
To prevent this behavior, enable the AdjacentListsSupport
plugin.
import AdjacentListsSupport from '@ckeditor/ckeditor5-list/src/documentlist/adjacentlistssupport.js';
ClassicEditor
.create( document.querySelector( '#editor' ), {
plugins: [
AdjacentListsSupport,
/* Other plugins */
],
} )
.then( /* ... */ )
.catch( /* ... */ );
# 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.
# 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 thetype
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'
.
- For bulleted lists:
-
The
documentListStart
command which is a Number and defaults to1
(meaning a list starts with1
). If enabled, it accepts a numerical value for thestart
attribute.editor.execute( 'documentListStart', { startIndex: 3 } );
-
The
documentListReversed
command which is a Boolean and defaults tofalse
(meaning the list order is ascending).editor.execute( 'documentListReversed', { reversed: true } );
-
The
numberedList
UI split button that overrides the UI button registered by theList
plugin. -
The
bulletedList
UI split button that overrides the UI button registered by theList
plugin.
# Contribute
The source code of the feature is available on GitHub at https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-list.
Every day, we work hard to keep our documentation complete. Have you spotted outdated information? Is something missing? Please report it via our issue tracker.