List

Organize nestable items in a bulleted or numbered list.

List ElementList Toolbar ButtonTodo List Element
Loading...
Files
components/list-demo.tsx
'use client';

import React from 'react';

import { withProps } from '@udecode/cn';
import { Plate, PlateElement } from '@udecode/plate-common/react';
import {
  BulletedListPlugin,
  ListItemPlugin,
  ListPlugin,
  NumberedListPlugin,
  TodoListPlugin,
} from '@udecode/plate-list/react';

import { autoformatListPlugin } from '@/components/editor/plugins/autoformat-list-plugin';
import { editorPlugins } from '@/components/editor/plugins/editor-plugins';
import { FixedToolbarListPlugin } from '@/components/editor/plugins/fixed-toolbar-list-plugin';
import { useCreateEditor } from '@/components/editor/use-create-editor';
import { listValue } from '@/components/values/list-value';
import { Editor, EditorContainer } from '@/components/plate-ui/editor';
import { ListElement } from '@/components/plate-ui/list-element';
import { TodoListElement } from '@/components/plate-ui/todo-list-element';

export default function ListDemo() {
  const editor = useCreateEditor({
    components: {
      [BulletedListPlugin.key]: withProps(ListElement, { variant: 'ul' }),
      [ListItemPlugin.key]: withProps(PlateElement, { as: 'li' }),
      [NumberedListPlugin.key]: withProps(ListElement, { variant: 'ol' }),
      [TodoListPlugin.key]: TodoListElement,
    },
    plugins: [
      ...editorPlugins,
      ListPlugin,
      TodoListPlugin,
      FixedToolbarListPlugin,
      autoformatListPlugin,
    ],
    value: listValue,
  });

  return (
    <Plate editor={editor}>
      <EditorContainer variant="demo">
        <Editor />
      </EditorContainer>
    </Plate>
  );
}

Features

  • HTML-compliant lists:

    • Standard ul/ol > li structure
    • Proper nesting and hierarchy
    • SEO-friendly markup
    • Clean HTML/markdown export

  • List types:

    • Unordered (bulleted) lists
    • Ordered (numbered) lists
    • Todo lists with checkboxes
    • Nested sublists

  • Drag & drop:

    • Currently supports root-level list items only
    • Sibling and nested items drag & drop not yet supported

  • Shortcuts:

    • Combined with the autoformat plugin, use markdown shortcuts (-, *, 1.) to create lists
    • Tab/Shift+Tab for indentation control

  • Limitations (use Indent List for these features):

    • Drag & drop only supports root-level lists
    • List items cannot be aligned

For a more flexible, Word-like approach, see the Indent List plugin.

Installation

npm install @udecode/plate-list

Usage

import { ListPlugin } from '@udecode/plate-list/react';
 
const plugins = [
  // ...otherPlugins,
  ListPlugin,
];

Keyboard Shortcuts

KeyDescription
Cmd + Opt + 4Insert a numbered list.
Cmd + Shift + 4Insert a numbered list.

Plugins

ListPlugin

  • key: 'list'
  • Contains the following element plugins:
    • BulletedListPlugin
    • NumberedListPlugin
    • ListItemPlugin
    • ListItemContentPlugin

Options

Collapse all

    Specifies valid child node types for list items, in addition to p and ul types.

    Determines whether pressing Shift+Tab should reset the list indent level.

BulletedListPlugin

Plugin for unordered (bulleted) lists.

NumberedListPlugin

Plugin for ordered (numbered) lists.

ListItemPlugin

Plugin for list items.

ListItemContentPlugin

Plugin for list item content.

API

editor.tf.toggle.list

Toggles a list in the editor.

Parameters

Collapse all

getHighestEmptyList

Finds the highest end list that can be deleted. The path of the list should be different from diffListPath. If the highest end list has 2 or more items, returns liPath. It traverses up the parent lists until:

  • The list has less than 2 items.
  • Its path is not equal to diffListPath.

Parameters

Collapse all

    The editor instance.

Returns

Collapse all

    The path of the highest end list that can be deleted.

getListItemEntry

Returns the nearest li and ul/ol wrapping node entries for a given path (default = selection).

Parameters

Collapse all

    The editor instance.

Returns

Collapse all

    The nearest li and ul/ol wrapping node entries.

getListRoot

Searches upward for the root list element.

Parameters

Collapse all

    The editor instance.

    The location to start the search from. If not provided, uses the current selection.

    • Default: editor.selection

Returns

Collapse all

    The root list element entry.

getListTypes

Returns an array of list types supported by the editor.

Parameters

Collapse all

    The editor instance.

Returns

Collapse all

    The list types.

hasListChild

Checks if a node has a list child.

Parameters

Collapse all

    The editor instance.

    The node to check.

Returns

Collapse all

    true if the node has a list child, false otherwise.

indentListItems

Indents the list items in the editor.

Parameters

Collapse all

    The editor instance.

insertListItem

Inserts a list item if the selection is in an li>p element.

Parameters

Collapse all

    The editor instance.

Returns

Collapse all

    true if the list items were indented, false otherwise.

insertTodoListItem

Inserts a todo list item if the selection is in an li>p element.

Parameters

Collapse all

    The editor instance.

Returns

Collapse all

    true if the list items were indented, false otherwise.

isAcrossListItems

Checks if the selection is across blocks with list items.

Parameters

Collapse all

    The editor instance.

Returns

Collapse all

    true if the selection is across blocks with list items, false otherwise.

isListNested

Checks if the list is nested, i.e., its parent is a list item.

Parameters

Collapse all

    The editor instance.

    The path of the list.

Returns

Collapse all

    true if the list is nested, false otherwise.

isListRoot

Checks if a node is the root of a list.

Parameters

Collapse all

    The editor instance.

    The node to check.

Returns

Collapse all

    true if the node is the root of a list, false otherwise.

moveListItemDown

Moves a list item down to the next list item.

Parameters

Collapse all

    The editor instance.

Returns

Collapse all

    true if the list item was moved, false otherwise.

moveListItemSublistItemsToListItemSublist

Moves sublist items from one list item to another list item's sublist.

Parameters

Collapse all

    The editor instance.

Returns

Collapse all

    The number of sublist items moved.

moveListItemUp

Moves a list item up.

Parameters

Collapse all

    The editor instance.

Returns

Collapse all

    true if the list item was moved, false otherwise.

moveListItems

Moves the selected list items up or down within their respective lists or increases/decreases their indentation level.

Parameters

Collapse all

    The editor instance.

Returns

Collapse all

    true if the list items were moved, false otherwise.

moveListItemsToList

Moves the list items from a sublist or a list to another list.

Parameters

Collapse all

    The editor instance.

Returns

Collapse all

    true if the list items were moved, false otherwise.

moveListSiblingsAfterCursor

Moves the list siblings after the cursor position to a specified path.

Parameters

Collapse all

    The editor instance.

Returns

Collapse all

    The number of list siblings moved.

removeFirstListItem

Removes the first list item if the list is not nested and the list item is not the first child.

Parameters

Collapse all

    The editor instance.

Returns

Collapse all

    true if the list item was removed, false otherwise.

removeListItem

Removes a list item and moves its sublist to the parent list if any.

Parameters

Collapse all

    The editor instance.

Returns

Collapse all

    true if the list item was removed, false otherwise.

someList

Checks if the current selection is inside a list of a specific type.

Parameters

Collapse all

    The editor instance.

    The type of list to check.

Returns

Collapse all

    true if the selection is inside a list of the specified type, false otherwise.

unindentListItems

Decreases the indentation level of the list items in the editor.

Parameters

Collapse all

    The editor instance.

    The target path at which to unindent the list items. If not provided, the list items will be unindented at the current selection.

unwrapList

Removes the list formatting from the selected list items or the list items at the specified path.

Parameters

Collapse all

    The editor instance.

API Components

useListToolbarButton

A behavior hook for a list toolbar button.

State

Collapse all

    The pressed state of the button.

    The node type of the list.

    • Default: BulletedListPlugin.key

Returns

Collapse all

API Todo List

getTodoListItemEntry

Returns the nearest list and list item node entries for a given path (default = selection) in a todo list.

Parameters

Collapse all

    The editor instance.

Returns

    • If a list item is found at the given location, it returns an object with the list and listItem node entries.

    • If no list item is found, it returns undefined.

useTodoListElement

A behavior hook a todo list item element.

State

Collapse all

    The checked state of the todo list item.

    Whether the todo list item is read-only.

    The todo list item element.

    The editor instance.

Returns

Collapse all

LinkMedia