---
title: "TaskItem extension"
description: "Use the TaskItem extension to add support for task items rendered as with checkboxes. More in our docs!"
canonical_url: "https://tiptap.dev/docs/editor/extensions/nodes/task-item"
---

# TaskItem extension

Use the TaskItem extension to add support for task items rendered as with checkboxes. More in our docs!

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.

> **Interactive demo:** [TaskItem](https://embed.tiptap.dev/preview/Nodes/TaskItem)

## Install

```bash
npm install @tiptap/extension-list
```

This extension requires the [`TaskList`](https://tiptap.dev/docs/editor/extensions/nodes/task-list.md) node.

## Usage

```js
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.

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

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

## Settings

### HTMLAttributes

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

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

### nested

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

```js
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`).

```js
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.

```js
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.

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

## Keyboard shortcuts

| Command         | Windows/Linux | macOS       |
| --------------- | ------------- | ----------- |
| splitListItem() | Enter         | Enter       |
| sinkListItem()  | Tab           | Tab         |
| liftListItem()  | Shift + Tab   | Shift + Tab |

## Source code

[packages/extension-list/src/task-item/](https://github.com/ueberdosis/tiptap/blob/main/packages/extension-list/src/task-item/)

## Minimal Install

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

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