TaskItem extension

This extension renders a task item list element, which is a <li> tag with a data-type attribute set to taskItem. It also renders a checkbox inside the list element, which updates a checked attribute.

This extension doesn’t require any JavaScript framework, it’s based on Vanilla JavaScript.

Install

npm install @tiptap/extension-list

This extension requires the TaskList node.

Usage

import { Editor } from '@tiptap/core'
import { TaskItem } from '@tiptap/extension-list'

new Editor({
  extensions: [TaskItem],
})

This extension is installed by default with the ListKit extension, so you don’t need to install it separately.

import { Editor } from '@tiptap/core'
import { ListKit } from '@tiptap/extension-list-kit'

new Editor({
  extensions: [ListKit],
})

Settings

HTMLAttributes

Custom HTML attributes that should be added to the rendered HTML tag.

TaskItem.configure({
  HTMLAttributes: {
    class: 'my-custom-class',
  },
})

nested

Whether the task items are allowed to be nested within each other.

TaskItem.configure({
  nested: true,
})

onReadOnlyChecked

A handler for when the task item is checked or unchecked while the editor is set to readOnly. If this is not supplied, the task items are immutable while the editor is readOnly. If this function returns false, the check state will be preserved (readOnly).

TaskItem.configure({
  onReadOnlyChecked: (node, checked) => {
    // do something
  },
})

taskListTypeName

The type name of the task list that this task item belongs to. This is used to determine the parent task list type.

TaskItem.configure({
  taskListTypeName: 'taskList',
})

a11y

a11y specific settings for the task item. It includes the following options:

• checkboxLabel: A function that returns the aria-label for the checkbox based on the checked state of the task item. This is useful for screen readers to announce the state of the checkbox.
  • Parameters:
    • node: The task item node.
    • checked: A boolean indicating whether the task item is checked or not.
  • Returns: A string that will be used as the aria-label for the checkbox.

TaskItem.configure({
  a11y: {
    // the aria-label for the checkbox
    checkboxLabel: (node, checked) => {
      return checked ? 'Task completed' : 'Task not completed'
    },
  },
})

Keyboard shortcuts

Source code

packages/extension-list/src/task-item/

Minimal Install

import { Editor } from '@tiptap/core'
import { TaskItem } from '@tiptap/extension-list/task-item'

new Editor({
  extensions: [TaskItem],
})