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/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

Contains the following element plugins:

  • BulletedListPlugin
  • NumberedListPlugin
  • ListItemPlugin
  • ListItemContentPlugin

Options

Collapse all

    Valid child node types for list items (besides p and ul).

    Whether Shift+Tab should reset 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

Parameters

Collapse all

    Options for toggling list.

Optionsoptions

Collapse all

    Type of list to toggle.

getHighestEmptyList

Finds highest end list that can be deleted. Returns liPath if highest end list has 2+ items.

Parameters

Collapse all

    The editor instance.

    Options for finding list.

Optionsoptions

Collapse all

    Path of list item.

    Path of different list.

ReturnsPath | undefined

    Path of highest deletable end list.

getListItemEntry

Gets nearest li and ul/ol wrapping node entries for a given path.

Parameters

Collapse all

    The editor instance.

    Options for getting entries.

Optionsoptions

Collapse all

    Location to get entries from.

    • Default: editor.selection

ReturnsElementEntry | undefined

    Nearest li and ul/ol wrapping node entries.

getListRoot

Searches upward for root list element.

Parameters

Collapse all

    The editor instance.

    Location to start search from.

    • Default: editor.selection

ReturnsElementEntry | undefined

    Root list element entry.

getListTypes

Gets array of supported list types.

Parameters

Collapse all

    The editor instance.

Returnsstring[]

    Array of supported list types.

moveListSiblingsAfterCursor

Moves list siblings after cursor to specified path.

Parameters

Collapse all

    The editor instance.

    Options for moving siblings.

Optionsoptions

Collapse all

    Cursor position path.

    Destination path.

Returnsnumber

    Number of siblings moved.

removeFirstListItem

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

Parameters

Collapse all

    The editor instance.

    Options for removal.

Optionsoptions

Collapse all

    List entry containing item.

    List item to remove.

Returnsboolean

    Whether item was removed.

removeListItem

Removes list item and moves sublist to parent if any.

Parameters

Collapse all

    The editor instance.

    Options for removal.

OptionsRemoveListItemOptions

Collapse all

    List entry containing item.

    List item to remove.

    Whether to reverse sublist items.

    • Default: true

Returnsboolean

    Whether item was removed.

someList

Checks if selection is inside list of specific type.

Parameters

Collapse all

    The editor instance.

    List type to check.

Returnsboolean

    Whether selection is in specified list type.

unindentListItems

Decreases indentation level of list items.

Parameters

Collapse all

    The editor instance.

    Target path for unindenting.

unwrapList

Removes list formatting from selected items.

Parameters

Collapse all

    The editor instance.

    Options for unwrapping.

Optionsoptions

Collapse all

    Target path for unwrapping.

Hooks

useListToolbarButton

State

Collapse all

    Button pressed state.

    List node type.

    • Default: BulletedListPlugin.key

Returnsobject

Collapse all

    Props for toolbar button.

    Optionsprops

    Collapse all

      Button pressed state.

      Handler to toggle list and focus editor.

Todo List API

getTodoListItemEntry

Gets nearest todo list and item entries.

Parameters

Collapse all

    The editor instance.

    Options for getting entries.

Optionsoptions

Collapse all

    Location to search from.

    • Default: editor.selection

Returns{ list: ElementEntry, listItem: ElementEntry } | undefined

    Todo list and item entries if found.

useTodoListElement

State

Collapse all

    Todo item checked state.

    Whether item is read-only.

    Todo list item element.

    Editor instance.

Returnsobject

Collapse all

    Props for checkbox.

    OptionscheckboxProps

    Collapse all

      Checkbox checked state.

      Handler for checkbox state changes.