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

Optionsobject

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

Toggles a list in the editor.

Optionsobject

Collapse all

    Type of list to toggle.

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

Optionsobject

Collapse all

    Path of list item.

    Path of different list.

ReturnsPath | undefined

    Path of highest deletable end list.

getListItemEntry

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

Optionsobject

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

    Location to start search from.

    • Default: editor.selection

ReturnsElementEntry | undefined

    Root list element entry.

getListTypes

Gets array of supported list types.

Returnsstring[]

    Array of supported list types.

moveListSiblingsAfterCursor

Moves list siblings after cursor to specified path.

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.

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.

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

    List type to check.

Returnsboolean

    Whether selection is in specified list type.

unindentListItems

Decreases indentation level of list items.

OptionsUnindentListItemsOptions

    Target path for unindenting.

unwrapList

Removes list formatting from selected items.

Optionsoptions

Collapse all

    Target path for unwrapping.

Hooks

useListToolbarButton

A behavior hook for a list toolbar button.

State

Collapse all

    Button pressed state.

    List node type.

    • Default: BulletedListPlugin.key

Returnsobject

Collapse all

    Props for toolbar button.

Todo List API

getTodoListItemEntry

Gets nearest todo list and item 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

A behavior hook a todo list item element.

State

Collapse all

    Todo item checked state.

    Whether item is read-only.

    Todo list item element.

Returnsobject

Collapse all

    Props for checkbox.