or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-tiptap--extension-task-item

Task item extension for Tiptap - enables interactive checkbox list items in rich text editors

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/@tiptap/extension-task-item@3.4.x

To install, run

npx @tessl/cli install tessl/npm-tiptap--extension-task-item@3.4.0

@tiptap/extension-task-item

Task item extension for Tiptap - enables interactive checkbox list items in rich text editors. This extension allows developers to create todo lists, project management interfaces, and interactive documentation systems within Tiptap rich text editors.

Package Information

Package Name: @tiptap/extension-task-item
Package Type: npm
Language: TypeScript
Installation: npm install @tiptap/extension-task-item

Core Imports

import TaskItem, { TaskItemOptions } from '@tiptap/extension-task-item';

For CommonJS:

const TaskItem = require('@tiptap/extension-task-item').default;
const { TaskItemOptions } = require('@tiptap/extension-task-item');

Named imports:

import { TaskItem, TaskItemOptions } from '@tiptap/extension-task-item';

Basic Usage

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

const editor = new Editor({
  extensions: [
    TaskItem.configure({
      nested: true,
      HTMLAttributes: {
        class: 'my-task-item',
      },
    }),
  ],
  content: `
    <li data-type="taskItem" data-checked="false">
      <p>Unchecked task item</p>
    </li>
    <li data-type="taskItem" data-checked="true">
      <p>Checked task item</p>
    </li>
  `,
});

Architecture

The @tiptap/extension-task-item package is built around:

Re-export Pattern: This package is a convenience wrapper that re-exports TaskItem and TaskItemOptions from @tiptap/extension-list. The actual implementation resides in the extension-list package.
Tiptap Node Extension: TaskItem is created using Tiptap's Node.create() method, integrating with the ProseMirror document model
Interactive DOM Rendering: Custom node view creates interactive checkboxes that update the document state
Markdown Input Rules: Automatic parsing of markdown-style task item syntax (- [ ] and - [x])
Accessibility Support: Built-in keyboard navigation and customizable aria labels
Flexible Configuration: Extensive options for customization including nesting, HTML attributes, and readonly behavior

Capabilities

TaskItem Node Extension

The main extension constant for creating task item nodes with interactive checkboxes. TaskItem is created using Tiptap's Node.create() method.

const TaskItem: Node<TaskItemOptions>;

Usage Examples:

import TaskItem from '@tiptap/extension-task-item';

// Basic usage
const taskItem = TaskItem;

// With configuration
const configuredTaskItem = TaskItem.configure({
  nested: true,
  HTMLAttributes: {
    class: 'task-item',
    'data-test': 'task-item-element',
  },
  taskListTypeName: 'myTaskList',
});

// Extended with custom behavior
const extendedTaskItem = TaskItem.extend({
  addKeyboardShortcuts() {
    return {
      ...this.parent?.(),
      'Ctrl-Enter': () => {
        // Custom keyboard shortcut
        return this.editor.commands.splitListItem(this.name);
      },
    };
  },
});

TaskItem Configuration

Configuration options interface for customizing TaskItem behavior.

interface TaskItemOptions {
  /** Callback for checkbox clicks in readonly mode */
  onReadOnlyChecked?: (node: ProseMirrorNode, checked: boolean) => boolean;
  
  /** Controls whether task items can be nested */
  nested: boolean;
  
  /** HTML attributes to add to the task item element */
  HTMLAttributes: Record<string, any>;
  
  /** Node type name for taskList nodes */
  taskListTypeName: string;
  
  /** Accessibility options for the task item */
  a11y?: {
    checkboxLabel?: (node: ProseMirrorNode, checked: boolean) => string;
  };
}

Configuration Examples:

// Basic configuration
const basicOptions: TaskItemOptions = {
  nested: false,
  HTMLAttributes: {},
  taskListTypeName: 'taskList',
};

// Advanced configuration with accessibility
const advancedOptions: TaskItemOptions = {
  nested: true,
  HTMLAttributes: {
    class: 'interactive-task-item',
    'data-testid': 'task-item',
  },
  taskListTypeName: 'customTaskList',
  onReadOnlyChecked: (node, checked) => {
    console.log(`Task "${node.textContent}" ${checked ? 'checked' : 'unchecked'}`);
    return true; // Allow the change
  },
  a11y: {
    checkboxLabel: (node, checked) => 
      `${checked ? 'Completed' : 'Incomplete'} task: ${node.textContent || 'empty task'}`,
  },
};

Node Attributes

The TaskItem node includes a single attribute for tracking checkbox state.

interface TaskItemAttributes {
  /** Boolean indicating if the task item is checked */
  checked: boolean;
}

Input Pattern Recognition

Regular expression constant for matching markdown-style task item input.

const inputRegex: RegExp; // /^\s*(\[([( |x])?\])\s$/

The input regex matches patterns like:

- [ ] (unchecked task item)
- [x] (checked task item)
- [X] (checked task item - case insensitive)
- [ ] with extra whitespace

Extension Methods

Core methods available on the TaskItem extension for editor integration. These are internal methods that define the extension's behavior.

interface TaskItemExtensionMethods {
  /** Defines allowed content structure based on nesting option */
  content(): string;
  
  /** Returns default configuration options */
  addOptions(): TaskItemOptions;
  
  /** Defines node attributes schema */
  addAttributes(): Record<string, Attribute>;
  
  /** HTML parsing rules for task item elements */
  parseHTML(): Array<{ tag: string; priority?: number }>;
  
  /** Renders task item node to HTML structure */
  renderHTML(props: { node: ProseMirrorNode; HTMLAttributes: Record<string, any> }): DOMOutputSpec;
  
  /** Keyboard shortcuts for task item navigation */
  addKeyboardShortcuts(): Record<string, KeyboardShortcutCommand>;
  
  /** Custom DOM node view with interactive checkbox */
  addNodeView(): NodeViewRenderer;
  
  /** Input rules for markdown-style task items */
  addInputRules(): Array<InputRule>;
}

Keyboard Shortcuts

Built-in keyboard shortcuts for task item navigation and manipulation.

Enter: Split the current task item into two items
Shift-Tab: Lift (unindent) the current task item
Tab: Sink (indent) the current task item (only when nested: true)

HTML Structure

The TaskItem node renders to the following HTML structure:

<li data-type="taskItem" data-checked="false">
  <label>
    <input type="checkbox" />
    <span></span>
  </label>
  <div>
    <!-- Task item content goes here -->
  </div>
</li>

Error Handling

The extension handles several edge cases:

Readonly Mode: When the editor is not editable, checkbox clicks are prevented unless onReadOnlyChecked callback is provided
Invalid State Changes: The onReadOnlyChecked callback can return false to reject state changes
Node Type Validation: The node view update method validates that updated nodes are of the correct type

Types

// Core type imports
import type { Node as ProseMirrorNode } from '@tiptap/pm/model';
import type { Node, KeyboardShortcutCommand, NodeViewRenderer, InputRule, DOMOutputSpec, Attribute } from '@tiptap/core';

// TaskItem configuration interface
interface TaskItemOptions {
  /** Callback for checkbox clicks in readonly mode */
  onReadOnlyChecked?: (node: ProseMirrorNode, checked: boolean) => boolean;
  /** Controls whether task items can be nested */
  nested: boolean;
  /** HTML attributes to add to the task item element */
  HTMLAttributes: Record<string, any>;
  /** Node type name for taskList nodes */
  taskListTypeName: string;
  /** Accessibility options for the task item */
  a11y?: {
    checkboxLabel?: (node: ProseMirrorNode, checked: boolean) => string;
  };
}

// TaskItem node extension constant
const TaskItem: Node<TaskItemOptions>;

// Input pattern constant for markdown-style task items
const inputRegex: RegExp;

// TaskItem node attributes
interface TaskItemAttributes {
  checked: boolean;
}