Skip to main content
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 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...
      ],
    },
  ],
})

​
Source Code

View the source code on GitHub: packages/extension-list/src/item/list-item.ts

Build docs developers (and LLMs) love

Get started for freeTalk to us