Skip to main content

​
Overview

The List extension provides support for flexible list structures including bullet lists, ordered lists, task lists, and collapsible toggle lists. Built on top of prosemirror-flat-list, it offers a flat list structure that simplifies nested list operations.

​
Installation

import { defineList } from '@prosekit/extensions'

​
Basic Usage

import { defineList } from '@prosekit/extensions'
import { createEditor } from '@prosekit/core'

const editor = createEditor({
  extensions: [
    defineList(),
    // ... other extensions
  ],
})

​
List Types

The extension supports four types of lists:

​
Bullet Lists

Unordered lists with bullet points. 
editor.commands.toggleList({ kind: 'bullet' })

​
Ordered Lists

Numbered lists with optional custom starting numbers. 
editor.commands.toggleList({ kind: 'ordered', order: 1 })

​
Task Lists

Checkable task items with checked/unchecked states. 
editor.commands.toggleList({ kind: 'task', checked: false })

​
Toggle Lists

Collapsible lists that can be expanded or collapsed. 
editor.commands.toggleList({ kind: 'toggle', collapsed: false })

​
Commands

The List extension provides the following commands:

​
toggleList

Toggles a list on or off at the current selection. 
editor.commands.toggleList(attrs?: ListAttributes)
Parameters:
  • kind: 'bullet' | 'ordered' | 'task' | 'toggle' - The type of list
  • order: number | null - Optional starting number for ordered lists
  • checked: boolean - Whether task list items are checked
  • collapsed: boolean - Whether toggle lists are collapsed

​
wrapInList

Wraps the current selection in a list. 
editor.commands.wrapInList(attrs?: ListAttributes)

​
insertList

Inserts a new list node. 
editor.commands.insertList(attrs?: ListAttributes)

​
indentList

Indents the current list item. 
editor.commands.indentList(options?: IndentListOptions)

​
dedentList

Dedents (unindents) the current list item. 
editor.commands.dedentList(options?: DedentListOptions)

​
splitList

Splits the current list item at the cursor position. 
editor.commands.splitList()

​
unwrapList

Removes the list wrapper from the current selection. 
editor.commands.unwrapList(options?: UnwrapListOptions)

​
moveList

Moves the current list item up or down. 
editor.commands.moveList(direction: 'up' | 'down')

​
toggleCollapsed

Toggles the collapsed state of a toggle list. 
editor.commands.toggleCollapsed(options?: ToggleCollapsedOptions)

​
Attributes

List nodes support the following attributes: 
interface ListAttrs {
  /**
   * The kind of list node.
   */
  kind?: 'bullet' | 'ordered' | 'task' | 'toggle'
  
  /**
   * The optional order of the list node.
   */
  order?: number | null
  
  /**
   * Whether the list node is checked if its kind is "task".
   */
  checked?: boolean
  
  /**
   * Whether the list node is collapsed if its kind is "toggle".
   */
  collapsed?: boolean
}

​
Input Rules

The extension automatically applies input rules for quick list creation:
  • Type - or * at the start of a line to create a bullet list
  • Type 1. or 1) to create an ordered list
  • Type [ ] to create an unchecked task list
  • Type [x] to create a checked task list

​
Keyboard Shortcuts

The extension includes default keyboard shortcuts:
  • Tab: Indent list item
  • Shift+Tab: Dedent list item
  • Enter: Split list item or exit list
  • Mod+Shift+8: Toggle bullet list
  • Mod+Shift+9: Toggle ordered list

​
Serialization

The extension includes a DOM serializer for proper HTML output: 
import { ListDOMSerializer } from '@prosekit/extensions'

​
Advanced Features

​
Drag and Drop

The extension includes a drop indicator for visual feedback when dragging list items.

​
Nested Lists

Lists can be nested to any depth using the indent and dedent commands: 
// Create nested structure
editor.commands.indentList()
editor.commands.dedentList()

​
Complete Example

import { createEditor } from '@prosekit/core'
import { defineList } from '@prosekit/extensions'

const editor = createEditor({
  extensions: [defineList()],
})

// Create a bullet list
editor.commands.toggleList({ kind: 'bullet' })

// Convert to ordered list
editor.commands.toggleList({ kind: 'ordered', order: 1 })

// Create a task list
editor.commands.toggleList({ kind: 'task', checked: false })

// Indent current item
editor.commands.indentList()

// Move item up
editor.commands.moveList('up')
  • Use with defineDoc() and defineParagraph() for complete document structure
  • Combine with text formatting extensions like defineBold() and defineItalic()