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

guideTo-do lists

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

To-do lists can be introduced using the 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.

The To-do list feature is enabled by default in the superbuild only. See the installation section to learn how to enable it in your editor.

# Demo

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

Waffles

Waffles with raspberries and whipped cream.

Ingredients

Directions

Prep Cook Ready In
5 m 15 m 20 m

Preheat waffle iron. Beat eggs in large bowl with hand beater until fluffy. Beat in flour, milk, vegetable oil, sugar, baking powder, salt and vanilla, just until smooth.

Spray preheated waffle iron with non-stick cooking spray. Pour mix onto hot waffle iron. Cook until golden brown. Serve hot.

Source: allrecipes

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

# 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/src/todolist';

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

Read more about installing plugins.

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

# Ordered and unordered lists

You can read more about these features in the lists feature guide.

# Contribute

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