4f:I[314491,["/_next/static/immutable/chunks/3arlv5bvukoo2.js","/_next/static/immutable/chunks/39v64hmfyo-sr.js","/_next/static/immutable/chunks/2nvof3-29tvc3.js","/_next/static/immutable/chunks/3tjobt77z_9dj.js","/_next/static/immutable/chunks/04j_o97cgxn2x.js","/_next/static/immutable/chunks/3upr08c9vtj8w.js","/_next/static/immutable/chunks/1ww0328si-u8x.js","/_next/static/immutable/chunks/11mfl5ymqld9-.js","/_next/static/immutable/chunks/2xxcqy6ppds3l.js","/_next/static/immutable/chunks/3j06ow7w40nxu.js","/_next/static/immutable/chunks/31nn7jwsjvqii.js","/_next/static/immutable/chunks/43_s7jweyypoh.js","/_next/static/immutable/chunks/0p6vao205o1jc.js","/_next/static/immutable/chunks/1_kyvgkyokw92.js","/_next/static/immutable/chunks/1lo-zn37dolb5.js","/_next/static/immutable/chunks/1v8k6yxw1rg0u.js"],"FilesView"] 50:T3474,--- title: List Classic docs: - route: /docs/components/list-classic-node title: List Nodes - route: /docs/components/list-classic-toolbar-button title: List Toolbar Button --- Plate offers two approaches for implementing lists: 1. **This List Classic plugin** - Traditional HTML-spec lists with strict nesting rules: - Follows standard HTML list structure (`ul`/`ol` > `li`) - Maintains consistent list hierarchy - Best for content that may be exported to HTML/markdown - Highest complexity 2. The [**List plugin**](/docs/list) - Flexible indentation-based lists: - More like Word/Google Docs behavior - Any block can be indented to create list-like structures - Used in the [AI editor](/editors#editor-ai) - Supports nested todo lists - Better for free-form content organization Choose based on your needs: - Use the **List Classic plugin** when you need standard HTML list compatibility - Use the **List plugin** when you want more flexible indentation behavior ## 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 - Task lists with checkboxes - Nested sublists - **Drag & drop**: - Currently supports root-level list items only - Sibling and nested items drag & drop not yet supported - **Shortcuts**: - Register the shipped input rules to use markdown shortcuts (**`-`**, **`*`**, **`1.`**, **`[ ]`**) to create lists - Tab/Shift+Tab for indentation control - **Limitations (use the [List plugin](/docs/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 [List plugin](/docs/list). ## Kit Usage ### Installation The fastest way to add list functionality is with the `ListKit` export from `list-classic-kit`, which includes pre-configured list plugins, the classic markdown entry rules, [Plate UI](/docs/installation/plate-ui) components, and keyboard shortcuts. - [`BulletedListElement`](/docs/components/list-classic-node): Renders unordered list elements. - [`NumberedListElement`](/docs/components/list-classic-node): Renders ordered list elements. - [`TaskListElement`](/docs/components/list-classic-node): Renders task list elements with checkboxes. ### Add Kit Add the kit to your plugins: ```tsx import { createPlateEditor } from 'platejs/react'; import { ListKit } from '@/components/editor/plugins/list-classic-kit'; const editor = createPlateEditor({ plugins: [ // ...otherPlugins, ...ListKit, ], }); ``` The shipped `ListKit` also wires the classic markdown entry rules for bulleted, ordered, and task lists. See [Plugin Input Rules](/docs/plugin-input-rules) for the runtime model. ## Manual Usage ### Installation ```bash npm install @platejs/list-classic ``` ### Add Plugins Include the list plugins in your Plate plugins array when creating the editor. ```tsx import { ListPlugin, BulletedListPlugin, NumberedListPlugin, TaskListPlugin, ListItemPlugin } from '@platejs/list-classic/react'; import { createPlateEditor } from 'platejs/react'; const editor = createPlateEditor({ plugins: [ // ...otherPlugins, ListPlugin, BulletedListPlugin, NumberedListPlugin, TaskListPlugin, ListItemPlugin, ], }); ``` ### Configure Plugins Configure the plugins with custom components and keyboard shortcuts. ```tsx import { BulletedListRules, OrderedListRules, TaskListRules, } from '@platejs/list-classic'; import { ListPlugin, BulletedListPlugin, NumberedListPlugin, TaskListPlugin, ListItemPlugin } from '@platejs/list-classic/react'; import { createPlateEditor } from 'platejs/react'; import { BulletedListElement, NumberedListElement, TaskListElement } from '@/components/ui/list-classic-node'; const editor = createPlateEditor({ plugins: [ // ...otherPlugins, ListPlugin.configure({ inputRules: [ BulletedListRules.markdown({ variant: '-' }), BulletedListRules.markdown({ variant: '*' }), OrderedListRules.markdown({ variant: '.' }), OrderedListRules.markdown({ variant: ')' }), TaskListRules.markdown({ checked: false }), TaskListRules.markdown({ checked: true }), ], }), BulletedListPlugin.configure({ node: { component: BulletedListElement }, shortcuts: { toggle: { keys: 'mod+alt+5' } }, }), NumberedListPlugin.configure({ node: { component: NumberedListElement }, shortcuts: { toggle: { keys: 'mod+alt+6' } }, }), TaskListPlugin.configure({ node: { component: TaskListElement }, shortcuts: { toggle: { keys: 'mod+alt+7' } }, }), ListItemPlugin, ], }); ``` - `inputRules`: Registers the classic markdown entry rules for bulleted, ordered, and task lists. - `node.component`: Assigns [`BulletedListElement`](/docs/components/list-classic-node), [`NumberedListElement`](/docs/components/list-classic-node), and [`TaskListElement`](/docs/components/list-classic-node) to render list elements. - `shortcuts.toggle`: Defines keyboard [shortcuts](/docs/plugin-shortcuts) to toggle list types (`mod+alt+5` for bulleted, `mod+alt+6` for numbered, `mod+alt+7` for task lists). ### Add Toolbar Button You can add [`ListToolbarButton`](/docs/components/list-classic-toolbar-button) to your [Toolbar](/docs/toolbar) to create and manage lists. ### Turn Into Toolbar Button When using the `ListPlugin`, use the [`turn-into-toolbar-classic-button`](/docs/components/turn-into-toolbar-classic-button) which includes all list types (bulleted, numbered, and task lists). ### Insert Toolbar Button When using the `ListPlugin`, use the [`insert-toolbar-classic-button`](/docs/components/insert-toolbar-classic-button) which includes all list types (bulleted, numbered, and task lists). ## Plugins ### `ListPlugin` Contains the following element plugins: - `BulletedListPlugin` - `NumberedListPlugin` - `TaskListPlugin` - `ListItemPlugin` - `ListItemContentPlugin` Valid child node types for list items (besides `p` and `ul`). Whether Shift+Tab should reset list indent level. Whether to inherit the checked state of above node after insert break at the end. Only applies to task lists. - **Default:** `false` Whether to inherit the checked state of below node after insert break at the start. Only applies to task lists. - **Default:** `false` ### `BulletedListPlugin` Plugin for unordered (bulleted) lists. ### `NumberedListPlugin` Plugin for ordered (numbered) lists. ### `TaskListPlugin` Plugin for task lists with checkboxes. ### `ListItemPlugin` Plugin for list items. ### `ListItemContentPlugin` Plugin for list item content. ## Transforms ### `tf.ul.toggle()` Toggles a bulleted list (ul). Example Shortcut: `Mod+Alt+5` ### `tf.ol.toggle()` Toggles an ordered list (ol). Example Shortcut: `Mod+Alt+6` ### `tf.taskList.toggle()` Toggles a task list with checkboxes. Example Shortcut: `Mod+Alt+7` ## API ### `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` Path of list item. Path of different list. Path of highest deletable end list. ### `getListItemEntry` Returns the nearest `li` and `ul`/`ol` wrapping node entries for a given path (`default = selection`). Location to get entries from. - **Default:** `editor.selection` Nearest `li` and `ul`/`ol` wrapping node entries. ### `getListRoot` Searches upward for root list element. Location to start search from. - **Default:** `editor.selection` Root list element entry. ### `getListTypes` Gets array of supported list types. Array of supported list types. ### `moveListSiblingsAfterCursor` Moves list siblings after cursor to specified path. Cursor position path. Destination path. Number of siblings moved. ### `removeFirstListItem` Removes first list item if not nested and not first child. List entry containing item. List item to remove. Whether item was removed. ### `removeListItem` Removes list item and moves sublist to parent if any. List entry containing item. List item to remove. Whether to reverse sublist items. - **Default:** `true` Whether item was removed. ### `someList` Checks if selection is inside list of specific type. List type to check. Whether selection is in specified list type. ### `unindentListItems` Decreases indentation level of list items. Target path for unindenting. ### `unwrapList` Removes list formatting from selected items. Target path for unwrapping. ## Hooks ### `useListToolbarButton` A behavior hook for a list toolbar button. Button pressed state. List node type. - **Default:** `BulletedListPlugin.key` Props for toolbar button. Button pressed state. Handler to toggle list and focus editor. ### `useTodoListElementState` Hook to manage task list item state. Task list item element. Whether the task item is checked. Whether the editor is in read-only mode. Handler to toggle the checked state. ### `useTodoListElement` Hook to get props for task list item checkbox. Whether the task item is checked. Whether the editor is in read-only mode. Handler to toggle the checked state. Props to be spread on the checkbox component. 4e:["$","div",null,{"className":"mt-3 flex min-h-0 min-w-0 flex-1 flex-col gap-3","children":[null,["$","$L4f",null,{"files":[{"path":"../../content/docs/(plugins)/(elements)/list-classic.mdx","content":"$50","type":"registry:file","target":"content/docs/plate/(plugins)/(elements)/list-classic.mdx"}],"className":"h-[70svh] min-h-80"}]]}]