List

PreviousNext
List Toolbar Button
Loading...

Features

  • Flexible Block Indentation: Transform any block type (paragraphs, headings, etc.) into list items through indentation.
  • Simplified Structure: Flat DOM structure where each indented block is independent, unlike List Classic plugin.
  • List Types: Support for bulleted lists (unordered) and numbered lists (ordered).
  • Markdown Shortcuts: Combined with autoformat plugin, use markdown shortcuts (-, *, 1.) to create lists.

For more information about the underlying indentation system, see the Indent plugin.

Kit Usage

Installation

The fastest way to add list functionality is with the ListKit, which includes pre-configured ListPlugin along with the required Indent plugin targeting paragraph, heading, blockquote, code block, and toggle elements.

  • BlockList: Renders list wrapper elements with support for todo lists.
  • Includes IndentKit for the underlying indentation system.
  • Configures Paragraph, Heading, Blockquote, CodeBlock, and Toggle elements to support list functionality.

Add Kit

Add the kit to your plugins:

import { createPlateEditor } from 'platejs/react';
import { ListKit } from '@/components/editor/plugins/list-kit';
 
const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...ListKit,
  ],
});

Add Toolbar Button

You can add ListToolbarButton to your Toolbar to create and manage lists.

Turn Into Toolbar Button

You can add these items to the Turn Into Toolbar Button to convert blocks into lists:

{
  icon: <ListIcon />,
  label: 'Bulleted list',
  value: KEYS.ul,
}
{
  icon: <ListOrderedIcon />,
  label: 'Numbered list',
  value: KEYS.ol,
}
{
  icon: <SquareIcon />,
  label: 'To-do list',
  value: KEYS.listTodo,
}

Manual Usage

Installation

pnpm add @platejs/list @platejs/indent

Add Plugins

Include both IndentPlugin and ListPlugin in your Plate plugins array when creating the editor. The List plugin depends on the Indent plugin.

import { IndentPlugin } from '@platejs/indent/react';
import { ListPlugin } from '@platejs/list/react';
import { createPlateEditor } from 'platejs/react';
 
const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    IndentPlugin,
    ListPlugin,
  ],
});

Configure Plugins

You can configure both plugins to target specific elements and customize list behavior.

import { IndentPlugin } from '@platejs/indent/react';
import { ListPlugin } from '@platejs/list/react';
import { KEYS } from 'platejs';
import { createPlateEditor } from 'platejs/react';
import { BlockList } from '@/components/ui/block-list';
 
const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    IndentPlugin.configure({
      inject: {
        targetPlugins: [...KEYS.heading, KEYS.p, KEYS.blockquote, KEYS.codeBlock],
      },
    }),
    ListPlugin.configure({
      inject: {
        targetPlugins: [...KEYS.heading, KEYS.p, KEYS.blockquote, KEYS.codeBlock],
      },
      render: {
        belowNodes: BlockList,
      },
    }),
  ],
});
  • inject.targetPlugins: An array of plugin keys indicating which element types can become list items.
  • render.belowNodes: Assigns BlockList to render list wrapper elements.

Plugins

ListPlugin

Plugin for creating and managing lists. It works with the Indent plugin to provide flexible list functionality where any block can be transformed into a list item through indentation.

Options

  • getSiblingListOptions optional GetSiblingListOptions<TElement>

    Function to determine indent list options for sibling elements.

  • getListStyleType optional (element: HTMLElement) => ListStyleType

    Function mapping HTML elements to list style types.

API

getNextList

Gets the next sibling entry with an indent list.

Parameters

Collapse all

  • entry ElementEntryOf

    Entry of the current element.

  • options optional Partial<GetSiblingListOptions>

    Options for getting next indent list.

ReturnsNodeEntry | undefined

    Entry of the next sibling with an indent list, or undefined if not found.

getPreviousList

Gets the previous sibling entry with an indent list.

Parameters

Collapse all

  • entry ElementEntryOf

    Entry of the current element.

  • options optional Partial<GetSiblingListOptions>

    Options for getting previous indent list.

ReturnsNodeEntry | undefined

    Entry of the previous sibling with an indent list, or undefined if not found.

indentList

Increases the indentation of the selected blocks.

OptionsListOptions

Collapse all

  • listStyleType optional ListStyleType | string

    List style type to use.

    • Default: ListStyleType.Disc

outdentList

Decreases the indentation of the selected blocks.

OptionsListOptions

Collapse all

  • listStyleType optional ListStyleType | string

    List style type to use.

    • Default: ListStyleType.Disc

someList

Checks if some of the selected blocks have a specific list style type.

Parameters

Collapse all

  • type string | string[]

    List style type to check.

toggleList

Toggles the indent list.

OptionsListOptions

Collapse all

  • listStyleType optional ListStyleType | string

    List style type to use.

  • listRestart optional number

    Override the number of the list item.

  • listRestartPolite optional number

    Override the number of the list item, only taking effect if the list item is the first in the list.

Types

GetSiblingListOptions

Used to provide options for getting the sibling indent list in a block of text.

Options

Collapse all

  • getPreviousEntry function

    This function is used to get the previous sibling entry from a given entry.

  • getNextEntry function

    This function is used to get the next sibling entry from a given entry.

  • query function

    This function is used to validate a sibling node during the lookup process. If it returns false, the next sibling is checked.

  • eqIndent boolean

    Indicates whether to break the lookup when the sibling node has an indent level equal to the current node. If true, the lookup stops when a sibling node with the same indent level is found.

  • breakQuery (node: TNode) => boolean | undefined

    A function that takes a TNode and returns a boolean value or undefined. This function is used to specify a condition under which the lookup process should be stopped.

  • breakOnLowerIndent boolean

    Indicates whether to break the lookup when a sibling node with a lower indent level is found. If true, the lookup stops when a sibling node with a lower indent level is found.

  • breakOnEqIndentNeqListStyleType boolean

    Indicates whether to break the lookup when a sibling node with the same indent level but a different list style type is found. If true, the lookup stops when such a sibling node is found.

Hooks

useListToolbarButton

A behavior hook for the indent list toolbar button.

State

Collapse all

  • nodeType string

    The list style type.

  • pressed boolean

    Whether the button is pressed.

Returnsobject

Collapse all

  • props object

    Props for the toolbar button.

列表文本对齐