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

Tiptap extension that provides list item functionality for rich text editors

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Tiptap Extension List Item

Name: tessl/npm-tiptap--extension-list-item
Author: tessl

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

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