CKEditor Ecosystem Documentation
Search
Contribute to this guide
Home/CKEditor 5/Features

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

Since version 41.0.0, the list support plugin has changed for CKEditor 5. You can read more about this change in the Update to CKEditor 41.0.0 guide.

# Demo

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

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.

This demo presents a limited set of features. Visit the feature-rich editor example to see more in action.

# List properties

Besides the basic functionality of creating ordered and unordered lists, CKEditor 5 offers formatting tools that let you control the lists. You can enable features such as more styles for list markers, setting the start index, or reversing the list order separately or all at once. Check out the individual demos below or see all list properties working together in the full-featured editor example.

The list properties feature is enabled by default in the document editor build.

See the list properties installation section to learn how to enable these in your editor.

# List styles

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. It opens when you click the arrow next to the appropriate list button in the toolbar.

# Demo

In the editor below, use the ordered Insert ordered list or unordered list dropdown Insert unordered list to choose the desired marker type for each list.

# List start index

The list start index feature allows the user to choose the starting point of an ordered list. By default, this would be 1 (or A, or I – see the list styles section). Sometimes you may want to start a list with some other digit or letter, though.

When this feature is enabled, an extra dropdown option is available in the ordered list toolbar button. Thanks to it, the user may set or change the starting marker.

# Demo

In the editor below, notice how the ordering continues in the second list. To achieve continuous numbering of all spaceships from the example, go to the first item of the last list. Then use the ordered list Insert ordered list dropdown input field to set the start index.

# Reversed list

The reversed list feature lets the user reverse the numbering order of a list, changing it from ascending to descending. This is useful in countdowns and things-to-do lists that need to reproduce steps in a reversed order (for example, in disassembly instructions).

When this feature is enabled, an extra dropdown switch is available in the ordered list toolbar button. Thanks to it, the user may reverse the order of a list with a single click.

# Demo

Click the second list and use the ordered list Insert ordered list dropdown switch to choose whether to reverse the numbering order.

You can see all the list properties together in action in the Feature-rich editor and Document editor examples.

These CKEditor 5 features 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 List plugin registers:

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' } );

    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 } );

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

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

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

# Contribute

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