Ordered and unordered lists

The list feature lets you create ordered (numbered) and unordered (bulleted) 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.

Use the editor below to see the list feature in action. You can use toolbar buttons to insert both ordered and unordered lists .

You can also use Markdown code recognized by the autoformatting feature:

• Start a line with * or - followed by a space for a bulleted list.
• Start a line with 1. or 1) followed by a space for a numbered list.

The List plugin provides the ordered (numbered) and unordered (bulleted) features for CKEditor 5. Additional list properties, such as list marker styles, start index, or reversed list order, are provided by the ListProperties plugin.

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

import { ClassicEditor, List } from 'ckeditor5';

ClassicEditor
	.create( document.querySelector( '#editor' ), {
		licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
		plugins: [ List, /* ... */ ],
		toolbar: [ 'bulletedList', 'numberedList', /* ... */ ]
		list: {
			// Configuration.
		}
	} )
	.then( /* ... */ )
	.catch( /* ... */ );

const { ClassicEditor, List } = CKEDITOR;

ClassicEditor
	.create( document.querySelector( '#editor' ), {
		licenseKey: '<YOUR_LICENSE_KEY>',
		plugins: [ List, /* ... */ ],
		toolbar: [ 'bulletedList', 'numberedList', /* ... */ ]
		list: {
			// Configuration.
		}
	} )
	.then( /* ... */ )
	.catch( /* ... */ );

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

To enable selected sub-features of the list properties, add their configuration to your editor. Set true for each feature you want to enable:

import { ClassicEditor, List, ListProperties } from 'ckeditor5';

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

const { ClassicEditor, List, ListProperties } = CKEDITOR;

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

Starting with version 45.1.1, list items (<li> elements) in the editor data output contain an additional attribute data-list-item-id. The attribute is necessary to ensure that the lists feature work correctly with other editor features and mechanisms.

<ul>
    <li data-list-item-id="e72808ee4144975064acb5d66e5cfba13">Hello</li>
    <li data-list-item-id="e5d719ab356409767e9d4358485476358">There!</li>
</ul>

If data loaded in the editor does not contain the data-list-item-id attributes on list items, they will be automatically added when data is saved.

If you wish to save the editor contents without this attribute, you can set the skipListItemIds flag to true when calling editor.getData() method. However, please note, that data without IDs should be used only for presentation purposes (such as displaying the document as HTML), and should not be used to initialize the editor.

editor.getData( { skipListItemIds: true } );

Such output will not contain data-list-item-id attribute:

<ul>
    <li>Hello</li>
    <li>There!</li>
</ul>

These CKEditor 5 features provide similar functionality:

• To-do lists – Create a list of interactive checkboxes with labels.
• Multi-level lists – Multi-level lists allow the user to set different markers (symbols, text or numbers) to display at each level of the list.
• Block indentation – Set indentation for text blocks such as paragraphs or headings and lists.
• Autoformatting – Format the text on the go with Markdown code.

The List plugin registers:

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

The ListProperties plugin registers:

• The listStyle command. It accepts the type of the list style to set. If not set, it uses the default marker (usually decimal).

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

  Copy code

  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 listStart command. It 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( 'listStart', { startIndex: 3 } );
  

  Copy code

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

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

  Copy code

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

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

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