ListItem

The container node for list items in bullet and ordered lists.

The ListItem extension represents individual items within bullet lists and ordered lists. It’s required for both BulletList and OrderedList extensions to function properly.

Installation

npm

npm install @tiptap/extension-list-item

Usage

The ListItem extension is included in the StarterKit by default:

import { Editor } from '@tiptap/core'
import StarterKit from '@tiptap/starter-kit'

const editor = new Editor({
  extensions: [StarterKit],
})

To use it standalone with list extensions:

import { Editor } from '@tiptap/core'
import Document from '@tiptap/extension-document'
import BulletList from '@tiptap/extension-bullet-list'
import OrderedList from '@tiptap/extension-ordered-list'
import ListItem from '@tiptap/extension-list-item'
import Paragraph from '@tiptap/extension-paragraph'
import Text from '@tiptap/extension-text'

const editor = new Editor({
  extensions: [
    Document,
    Paragraph,
    Text,
    BulletList,
    OrderedList,
    ListItem,
  ],
})

Configuration

HTMLAttributes

Custom HTML attributes to add to the list item element.

HTMLAttributes · Record<string, any> · default: "{}"

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

ListItem.configure({
  HTMLAttributes: {
    class: 'my-list-item',
  },
})

bulletListTypeName

The node type name for bullet list nodes.

bulletListTypeName · string · default: "'bulletList'"

Specifies which node type represents bullet lists.

ListItem.configure({
  bulletListTypeName: 'bulletList',
})

orderedListTypeName

The node type name for ordered list nodes.

orderedListTypeName · string · default: "'orderedList'"

Specifies which node type represents ordered lists.

ListItem.configure({
  orderedListTypeName: 'orderedList',
})

Keyboard Shortcuts

• Enter: Split the current list item into two
• Tab: Sink the list item (indent/nest it)
• Shift-Tab: Lift the list item (outdent/unnest it)

Content Structure

A list item contains:

• One paragraph (required)
• Zero or more additional block-level nodes (optional)

This allows for complex list items with multiple paragraphs or nested lists:

editor.commands.insertContent({
  type: 'listItem',
  content: [
    {
      type: 'paragraph',
      content: [{ type: 'text', text: 'First paragraph' }],
    },
    {
      type: 'paragraph',
      content: [{ type: 'text', text: 'Second paragraph' }],
    },
    {
      type: 'bulletList',
      content: [
        // nested list items...
      ],
    },
  ],
})

Related Extensions

• BulletList - For unordered lists
• OrderedList - For numbered lists

Source Code

View the source code on GitHub:

packages/extension-list/src/item/list-item.ts