or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-tiptap--extension-list-item

Tiptap extension that provides list item functionality for rich text editors

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

To install, run

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

Tiptap Extension List Item

The @tiptap/extension-list-item package provides list item functionality for Tiptap rich text editors. It enables creation and management of list items (<li> elements) that work seamlessly with bullet lists and ordered lists.

Package Information

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

Core Imports

import { ListItem } from '@tiptap/extension-list-item';
import type { ListItemOptions } from '@tiptap/extension-list-item';

Default import:

import ListItem from '@tiptap/extension-list-item';

CommonJS:

const { ListItem } = require('@tiptap/extension-list-item');

Basic Usage

import { Editor } from '@tiptap/core';
import { ListItem } from '@tiptap/extension-list-item';
import { BulletList } from '@tiptap/extension-bullet-list';
import { OrderedList } from '@tiptap/extension-ordered-list';

const editor = new Editor({
  extensions: [
    ListItem,
    BulletList,
    OrderedList,
  ],
  content: `
    <ul>
      <li>First item</li>
      <li>Second item</li>
    </ul>
  `,
});

Architecture

The ListItem extension is built on Tiptap's Node architecture and provides:

Node Definition: Defines the listItem node type with proper parsing and rendering
Content Model: Supports paragraph followed by zero or more block elements (paragraph block*)
Keyboard Shortcuts: Built-in shortcuts for Enter, Tab, and Shift-Tab
List Integration: Works with BulletList and OrderedList extensions

Capabilities

ListItem Node Extension

Creates a Tiptap node extension that handles list item functionality.

import type { Node } from '@tiptap/core';

/**
 * List item node extension for Tiptap editors
 * Enables creation and management of <li> elements
 */
const ListItem: Node<ListItemOptions>;

Configuration Options

Options interface for configuring the ListItem extension.

interface ListItemOptions {
  /**
   * The HTML attributes for a list item node.
   * @default {}
   * @example { class: 'custom-list-item' }
   */
  HTMLAttributes: Record<string, any>;

  /**
   * The node type for bulletList nodes
   * @default 'bulletList'
   * @example 'myCustomBulletList'
   */
  bulletListTypeName: string;

  /**
   * The node type for orderedList nodes  
   * @default 'orderedList'
   * @example 'myCustomOrderedList'
   */
  orderedListTypeName: string;
}

Usage Examples:

import { Editor } from '@tiptap/core';
import { ListItem } from '@tiptap/extension-list-item';

// Basic configuration
const editor = new Editor({
  extensions: [
    ListItem,
  ],
});

// Custom configuration
const editor = new Editor({
  extensions: [
    ListItem.configure({
      HTMLAttributes: {
        class: 'my-list-item',
      },
      bulletListTypeName: 'customBulletList',
      orderedListTypeName: 'customOrderedList',
    }),
  ],
});

Node Properties

The ListItem node has the following built-in properties:

interface ListItemNode {
  /** Node name identifier */
  name: 'listItem';
  
  /** Content expression - allows paragraph followed by zero or more blocks */
  content: 'paragraph block*';
  
  /** Defining property - this node defines its content structure */
  defining: boolean;
  
  /** Parse HTML configuration - recognizes <li> tags */
  parseHTML(): Array<{ tag: string }>;
  
  /** Render HTML configuration - outputs <li> elements */
  renderHTML(options: { HTMLAttributes: Record<string, any> }): [string, Record<string, any>, number];
}

Keyboard Shortcuts

Built-in keyboard shortcuts for list item management:

interface ListItemKeyboardShortcuts {
  /** Split list item at cursor position */
  'Enter': () => boolean;
  
  /** Indent/nest list item */
  'Tab': () => boolean;
  
  /** Outdent/lift list item */
  'Shift-Tab': () => boolean;
}

Keyboard Shortcut Behaviors:

Enter: Splits the current list item, creating a new list item below
Tab: Indents the current list item (requires parent list to support nesting)
Shift-Tab: Outdents the current list item, moving it up one level

Editor Commands Integration

When ListItem is installed, it enables these commands on the editor:

// Split current list item
editor.commands.splitListItem('listItem');

// Indent current list item  
editor.commands.sinkListItem('listItem');

// Outdent current list item
editor.commands.liftListItem('listItem');

Error Handling

The ListItem extension handles common edge cases:

Invalid nesting: Prevents invalid list structures
Content validation: Ensures list items contain valid content
Command failures: Commands return boolean indicating success/failure

Dependencies

Peer Dependencies

@tiptap/extension-list: Required for the actual ListItem implementation
@tiptap/core: Provides the Node base class and editor functionality

Typical Usage Dependencies

@tiptap/extension-bullet-list: For unordered lists
@tiptap/extension-ordered-list: For ordered lists
@tiptap/extension-paragraph: For paragraph content within list items