Tiptap task lists: save the checked state with the document

Consider a fictional installation note with two actions: “Label the spare cable” and “Photograph the rear connections.” After checking the first action, the author closes the note. Reopening should show the first action checked and the second unchecked. Neither checkbox supplies a photograph or establishes that someone reviewed the work.

Add the two node types together

For a Tiptap 3 application with its base document, paragraph, and text extensions already installed, add these extensions to the existing configuration:

import { TaskList, TaskItem } from '@tiptap/extension-list';

const installationTasks = [
  TaskList,
  TaskItem.configure({ nested: false })
];

Spread installationTasks into that editor's extensions array. This fragment assumes compatible packages and an existing editor initialization. If the application already uses ListKit, it already includes these nodes; configure that setup instead of registering duplicate task extensions.

Tiptap renders the outer list as ul[data-type="taskList"]. Each task item carries its own checkbox and checked value. A normal bullet list with a checkbox painted beside it does not supply the same document structure. TaskItem reference

With editor referring to the initialized instance, an external toolbar action can run:

editor.chain().focus().toggleTaskList().run();

The command applies at the current selection. Check its availability and preserve the intended selection in the surrounding toolbar. For this installation note, keep nesting disabled until authors have a clear reason to group subtasks.

Inspect the value that needs to survive reopening

Enter the two installation actions and check only “Label the spare cable.” Read the current document:

const installationSnapshot = editor.getJSON();

Find the relevant task item. Its portion of the JSON should resemble:

{
  "type": "taskItem",
  "attrs": { "checked": true },
  "content": [{
    "type": "paragraph",
    "content": [{ "type": "text", "text": "Label the spare cable" }]
  }]
}

The surrounding document and list nodes remain necessary. This excerpt is an expected data shape for the example, not a complete document to load by itself. The second item's checked value should remain false.

Send the current snapshot through the existing save service. Reload it with the same task node support and inspect both checkboxes. If the interface shows the right ticks but storage does not, trace the change listener and the value captured at save time. Exporting arbitrary list HTML through another processor can discard the attributes needed to reconstruct task state.

Choose what a read-only reader may change

Without an onReadOnlyChecked handler, TaskItem's documented read-only behavior keeps checkboxes immutable. If your product deliberately allows a reader to change them, implement the handler and connect that action to the application's authorization and persistence rules. Returning false preserves the checked state. Avoid making an editorial preview appear editable when its changes cannot be saved.

Give the checkbox an accessible name appropriate to its task and keep focus visible in your application. A checked visual style should still leave the action readable. Test using the keyboard in the actual editor, including reaching the next paragraph after the list.

Finish with the saved installation note

The checklist writing guide helps define an observable completion condition. This integration solves a different problem: carrying each checkbox state through rich-document editing and storage. For records that need evidence, reviewer identity, or an approval trail, store those fields explicitly in the system responsible for them.

Reopen the installation note, confirm the cable action is checked, and leave the photograph action open until its own work is done. Then read any exported version to ensure it still communicates those two different states.