To-do lists

The to-do list feature lets you create a list of interactive checkboxes with labels. It supports all features of bulleted and numbered lists, so you can nest a to-do list together with any combination of other lists.

# Demo

Use the to-do list toolbar button to add a list to the editor content.

# Additional feature information

You can add to-do lists using a dedicated toolbar button. Thanks to the integration with the autoformatting feature, they can also be added with Markdown code. Simply start a line with [ ] or [x] followed by a space to insert an unchecked or checked list item, respectively.

After reading this guide, you may find additional interesting details and examples in the Lists in CKEditor 5 blog post.

# Keyboard support

You can check and uncheck a list item by using the Ctrl + Enter (Cmd + Enter on Mac) shortcut when the selection is in that item.

# Installation

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

npm install --save @ckeditor/ckeditor5-list

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

import { TodoList } from '@ckeditor/ckeditor5-list';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ TodoList, /* ... */ ],
        toolbar: [ 'todoList', /* ... */ ],
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# HTML structure

When you call editor.getData(), a to-do list will be represented as the following HTML:

<ul class="todo-list">
    <li>
        <label class="todo-list__label">
            <input type="checkbox" disabled [checked] />
            <span class="todo-list__label__description">Foo</span>
        </label>
    </li>
</ul>

For nested lists:

<ul class="todo-list">
    <li>
        <label class="todo-list__label">
            <input type="checkbox" disabled [checked] />
            <span class="todo-list__label__description">Foo</span>
        </label>
        <ul class="todo-list">
            <li>
                <label class="todo-list__label">
                    <input type="checkbox" disabled [checked] />
                    <span class="todo-list__label__description">Bar</span>
                </label>
            </li>
        </ul>
    </li>
</ul>

# Model representation

From the technical point of view, to-do lists are built on top of the list feature. In the CKEditor 5 data model they are represented as a special listType, with an optional todoListChecked attribute:

<listItem listType="todo">Foo</listItem>

<listItem listType="todo" todoListChecked="true">Bar</listItem>

# Related features

These features provide similar functionality:

• Ordered and unordered lists – Create ordered and unordered list with configurable markers.
• Autoformatting – Format the text on the go with Markdown code.

# Contribute

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