{
"$schema": "https://ui.shadcn.com/schema/registry-item.json",
"name": "list-classic-docs",
"title": "List Classic",
"description": "Documentation for List Classic",
"files": [
{
"path": "../../content/docs/(plugins)/(elements)/list-classic.mdx",
"content": "---\ntitle: List Classic\ndocs:\n - route: /docs/components/list-classic-node\n title: List Nodes\n - route: /docs/components/list-classic-toolbar-button\n title: List Toolbar Button\n---\n\n\n\n\n Plate offers two approaches for implementing lists:\n\n 1. **This List Classic plugin** - Traditional HTML-spec lists with strict nesting rules:\n - Follows standard HTML list structure (`ul`/`ol` > `li`)\n - Maintains consistent list hierarchy\n - Best for content that may be exported to HTML/markdown\n - Highest complexity\n\n 2. The [**List plugin**](/docs/list) - Flexible indentation-based lists:\n - More like Word/Google Docs behavior\n - Any block can be indented to create list-like structures\n - Used in the [AI editor](/editors#editor-ai)\n - Supports nested todo lists\n - Better for free-form content organization\n\n Choose based on your needs:\n - Use the **List Classic plugin** when you need standard HTML list compatibility\n - Use the **List plugin** when you want more flexible indentation behavior\n\n\n\n\n\n\n## Features\n\n- **HTML-compliant lists**:\n - Standard `ul`/`ol` > `li` structure\n - Proper nesting and hierarchy\n - SEO-friendly markup\n - Clean HTML/markdown export\n\n- **List types**:\n - Unordered (bulleted) lists\n - Ordered (numbered) lists\n - Task lists with checkboxes\n - Nested sublists\n\n- **Drag & drop**:\n - Currently supports root-level list items only\n - Sibling and nested items drag & drop not yet supported\n\n- **Shortcuts**:\n - Register the shipped input rules to use markdown shortcuts (**`-`**, **`*`**, **`1.`**, **`[ ]`**) to create lists\n - Tab/Shift+Tab for indentation control\n\n- **Limitations (use the [List plugin](/docs/list) for these features)**:\n - Drag & drop only supports root-level lists\n - List items cannot be aligned\n\nFor a more flexible, Word-like approach, see the [List plugin](/docs/list).\n\n\n\n## Kit Usage\n\n\n\n### Installation\n\nThe 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.\n\n\n\n- [`BulletedListElement`](/docs/components/list-classic-node): Renders unordered list elements.\n- [`NumberedListElement`](/docs/components/list-classic-node): Renders ordered list elements.\n- [`TaskListElement`](/docs/components/list-classic-node): Renders task list elements with checkboxes.\n\n### Add Kit\n\nAdd the kit to your plugins:\n\n```tsx\nimport { createPlateEditor } from 'platejs/react';\nimport { ListKit } from '@/components/editor/plugins/list-classic-kit';\n\nconst editor = createPlateEditor({\n plugins: [\n // ...otherPlugins,\n ...ListKit,\n ],\n});\n```\n\n\n\nThe 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.\n\n## Manual Usage\n\n\n\n### Installation\n\n```bash\nnpm install @platejs/list-classic\n```\n\n### Add Plugins\n\nInclude the list plugins in your Plate plugins array when creating the editor.\n\n```tsx\nimport { ListPlugin, BulletedListPlugin, NumberedListPlugin, TaskListPlugin, ListItemPlugin } from '@platejs/list-classic/react';\nimport { createPlateEditor } from 'platejs/react';\n\nconst editor = createPlateEditor({\n plugins: [\n // ...otherPlugins,\n ListPlugin,\n BulletedListPlugin,\n NumberedListPlugin,\n TaskListPlugin,\n ListItemPlugin,\n ],\n});\n```\n\n### Configure Plugins\n\nConfigure the plugins with custom components and keyboard shortcuts.\n\n```tsx\nimport {\n BulletedListRules,\n OrderedListRules,\n TaskListRules,\n} from '@platejs/list-classic';\nimport { ListPlugin, BulletedListPlugin, NumberedListPlugin, TaskListPlugin, ListItemPlugin } from '@platejs/list-classic/react';\nimport { createPlateEditor } from 'platejs/react';\nimport { BulletedListElement, NumberedListElement, TaskListElement } from '@/components/ui/list-classic-node';\n\nconst editor = createPlateEditor({\n plugins: [\n // ...otherPlugins,\n ListPlugin.configure({\n inputRules: [\n BulletedListRules.markdown({ variant: '-' }),\n BulletedListRules.markdown({ variant: '*' }),\n OrderedListRules.markdown({ variant: '.' }),\n OrderedListRules.markdown({ variant: ')' }),\n TaskListRules.markdown({ checked: false }),\n TaskListRules.markdown({ checked: true }),\n ],\n }),\n BulletedListPlugin.configure({\n node: { component: BulletedListElement },\n shortcuts: { toggle: { keys: 'mod+alt+5' } },\n }),\n NumberedListPlugin.configure({\n node: { component: NumberedListElement },\n shortcuts: { toggle: { keys: 'mod+alt+6' } },\n }),\n TaskListPlugin.configure({\n node: { component: TaskListElement },\n shortcuts: { toggle: { keys: 'mod+alt+7' } },\n }),\n ListItemPlugin,\n ],\n});\n```\n\n- `inputRules`: Registers the classic markdown entry rules for bulleted, ordered, and task lists.\n- `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.\n- `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).\n\n### Add Toolbar Button\n\nYou can add [`ListToolbarButton`](/docs/components/list-classic-toolbar-button) to your [Toolbar](/docs/toolbar) to create and manage lists.\n\n### Turn Into Toolbar Button\n\nWhen 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).\n\n### Insert Toolbar Button\n\nWhen 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).\n\n\n\n## Plugins\n\n### `ListPlugin`\n\n\nContains the following element plugins:\n- `BulletedListPlugin`\n- `NumberedListPlugin`\n- `TaskListPlugin`\n- `ListItemPlugin`\n- `ListItemContentPlugin`\n\n\n \n Valid child node types for list items (besides `p` and `ul`).\n \n \n Whether Shift+Tab should reset list indent level.\n \n \n Whether to inherit the checked state of above node after insert break at the end. Only applies to task lists.\n - **Default:** `false`\n \n \n Whether to inherit the checked state of below node after insert break at the start. Only applies to task lists.\n - **Default:** `false`\n \n\n\n\n### `BulletedListPlugin`\n\nPlugin for unordered (bulleted) lists.\n\n### `NumberedListPlugin`\n\nPlugin for ordered (numbered) lists.\n\n### `TaskListPlugin`\n\nPlugin for task lists with checkboxes.\n\n### `ListItemPlugin`\n\nPlugin for list items.\n\n### `ListItemContentPlugin`\n\nPlugin for list item content.\n\n## Transforms\n\n### `tf.ul.toggle()`\n\nToggles a bulleted list (ul).\n\nExample Shortcut: `Mod+Alt+5`\n\n### `tf.ol.toggle()`\n\nToggles an ordered list (ol).\n\nExample Shortcut: `Mod+Alt+6`\n\n### `tf.taskList.toggle()`\n\nToggles a task list with checkboxes.\n\nExample Shortcut: `Mod+Alt+7`\n\n## API\n\n### `getHighestEmptyList`\n\nFinds 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:\n- The list has less than 2 items\n- Its path is not equal to `diffListPath`\n\n\n\n \n Path of list item.\n \n \n Path of different list.\n \n\n\n\n Path of highest deletable end list.\n\n\n\n### `getListItemEntry`\n\nReturns the nearest `li` and `ul`/`ol` wrapping node entries for a given path (`default = selection`).\n\n\n\n \n Location to get entries from.\n - **Default:** `editor.selection`\n \n\n\n\n Nearest `li` and `ul`/`ol` wrapping node entries.\n\n\n\n### `getListRoot`\n\nSearches upward for root list element.\n\n\n\n \n Location to start search from.\n - **Default:** `editor.selection`\n \n\n\n\n Root list element entry.\n\n\n\n### `getListTypes`\n\nGets array of supported list types.\n\n\n\n Array of supported list types.\n\n\n\n### `moveListSiblingsAfterCursor`\n\nMoves list siblings after cursor to specified path.\n\n\n\n \n Cursor position path.\n \n \n Destination path.\n \n\n\n\n Number of siblings moved.\n\n\n\n### `removeFirstListItem`\n\nRemoves first list item if not nested and not first child.\n\n\n\n \n List entry containing item.\n \n \n List item to remove.\n \n\n\n\n Whether item was removed.\n\n\n\n### `removeListItem`\n\nRemoves list item and moves sublist to parent if any.\n\n\n\n \n List entry containing item.\n \n \n List item to remove.\n \n \n Whether to reverse sublist items.\n - **Default:** `true`\n \n\n\n\n Whether item was removed.\n\n\n\n### `someList`\n\nChecks if selection is inside list of specific type.\n\n\n\n \n List type to check.\n \n\n\n\n Whether selection is in specified list type.\n\n\n\n### `unindentListItems`\n\nDecreases indentation level of list items.\n\n\n\n Target path for unindenting.\n\n\n\n### `unwrapList`\n\nRemoves list formatting from selected items.\n\n\n\n \n Target path for unwrapping.\n \n\n\n\n## Hooks\n\n### `useListToolbarButton`\n\nA behavior hook for a list toolbar button.\n\n\n\n \n Button pressed state.\n \n \n List node type.\n - **Default:** `BulletedListPlugin.key`\n \n\n\n\n \n Props for toolbar button.\n \n \n \n Button pressed state.\n \n \n Handler to toggle list and focus editor.\n \n \n\n\n\n### `useTodoListElementState`\n\nHook to manage task list item state.\n\n\n\n \n Task list item element.\n \n\n\n\n \n Whether the task item is checked.\n \n \n Whether the editor is in read-only mode.\n \n \n Handler to toggle the checked state.\n \n\n\n\n### `useTodoListElement`\n\nHook to get props for task list item checkbox.\n\n\n\n \n Whether the task item is checked.\n \n \n Whether the editor is in read-only mode.\n \n \n Handler to toggle the checked state.\n \n\n\n\n \n Props to be spread on the checkbox component.\n \n\n\n",
"type": "registry:file",
"target": "content/docs/plate/(plugins)/(elements)/list-classic.mdx"
}
],
"type": "registry:file"
}