Skip to main content

​
Lists Plugin

The Lists plugin provides three types of list blocks: bulleted lists, numbered lists, and todo lists with checkbox support.

​
Installation

npm install @yoopta/lists

​
Usage

import { BulletedList, NumberedList, TodoList } from '@yoopta/lists';
import { createYooptaEditor } from '@yoopta/editor';

const plugins = [
  BulletedList,
  NumberedList,
  TodoList,
];

const editor = createYooptaEditor({ plugins });
You can also import all lists together: 
import LISTS from '@yoopta/lists';

const plugins = [
  LISTS.BulletedList,
  LISTS.NumberedList,
  LISTS.TodoList,
];

​
Features

  • Three list types: bulleted, numbered, and todo
  • Keyboard shortcuts for quick insertion
  • Nested list support via depth
  • HTML, Markdown, and Email export
  • Enter key handling for list continuation
  • Supports all text marks

​
Bulleted List

​
Options

{
  type: 'BulletedList',
  options: {
    display: {
      title: 'Bulleted List',
      description: 'Create bullet list',
    },
    shortcuts: ['-'],
  },
}

​
Element Type

import type { BulletedListElement } from '@yoopta/lists';

type BulletedListElement = SlateElement<'bulleted-list'>;

​
Commands

import { BulletedListCommands } from '@yoopta/lists';

editor.commands.BulletedList.insertBulletedList();

​
HTML Output

<ul data-meta-align="left" data-meta-depth="0" 
    style="margin-left: 0px; text-align: left">
  <li>List item content</li>
</ul>

​
Markdown Output

- List item content
  - Nested item (depth: 1)

​
Numbered List

​
Options

{
  type: 'NumberedList',
  options: {
    display: {
      title: 'Numbered List',
      description: 'Create list with numbering',
    },
    shortcuts: ['1.'],
  },
}

​
Element Type

import type { NumberedListElement } from '@yoopta/lists';

type NumberedListElement = SlateElement<'numbered-list'>;

​
Commands

import { NumberedListCommands } from '@yoopta/lists';

editor.commands.NumberedList.insertNumberedList();

​
HTML Output

<ol data-meta-align="left" data-meta-depth="0" 
    style="margin-left: 0px; text-align: left">
  <li>List item content</li>
</ol>

​
Markdown Output

1. List item content
  1. Nested item (depth: 1)

​
Utility Hook

import { useNumberListCount } from '@yoopta/lists';

// Get the current number/index for a numbered list item
const count = useNumberListCount(editor, blockId);

​
Todo List

​
Options

{
  type: 'TodoList',
  options: {
    display: {
      title: 'Todo List',
      description: 'Track tasks',
    },
    shortcuts: ['[]'],
  },
}

​
Element Type

import type { TodoListElement, TodoListElementProps } from '@yoopta/lists';

type TodoListElementProps = {
  checked: boolean;
};

type TodoListElement = SlateElement<'todo-list', TodoListElementProps>;

​
Default Props

{
  checked: false
}

​
Commands

import { TodoListCommands } from '@yoopta/lists';

editor.commands.TodoList.insertTodoList();
// Toggle checkbox state
editor.commands.TodoList.toggleChecked(blockId);

​
HTML Output

<ul data-meta-align="left" data-meta-depth="0" 
    style="margin-left: 0px; text-align: left">
  <li>[ ] Unchecked task</li>
</ul>

<ul data-meta-align="left" data-meta-depth="0" 
    style="margin-left: 0px; text-align: left">
  <li>[x] Completed task</li>
</ul>

​
Markdown Output

- [ ] Unchecked task
- [x] Completed task
  - [ ] Nested subtask (depth: 1)

​
Keyboard Behavior

All list types share common keyboard behaviors:
  • Enter: Creates a new list item below
  • Backspace (on empty item): Removes the list item or decreases depth
  • Tab: Increases list depth (nesting)
  • Shift+Tab: Decreases list depth

​
Examples

​
Basic Usage

import YooptaEditor, { createYooptaEditor } from '@yoopta/editor';
import { BulletedList, NumberedList, TodoList } from '@yoopta/lists';

function Editor() {
  const editor = useMemo(() => 
    createYooptaEditor({ 
      plugins: [
        BulletedList,
        NumberedList,
        TodoList,
      ] 
    }), 
    []
  );

  return <YooptaEditor editor={editor} />;
}

​
Creating a Todo List Programmatically

import { Blocks } from '@yoopta/editor';
import { generateId } from '@yoopta/editor';

// Insert todo list with checkbox
Blocks.insertBlock(editor, {
  type: 'TodoList',
  value: [
    {
      id: generateId(),
      type: 'todo-list',
      props: { checked: false },
      children: [{ text: 'Complete documentation' }],
    },
  ],
});

​
Nested List Structure

// Create nested bulleted list using depth
Blocks.insertBlock(editor, {
  type: 'BulletedList',
  value: [
    {
      id: generateId(),
      type: 'bulleted-list',
      children: [{ text: 'Parent item' }],
    },
  ],
  meta: { depth: 0 },
});

Blocks.insertBlock(editor, {
  type: 'BulletedList',
  value: [
    {
      id: generateId(),
      type: 'bulleted-list',
      children: [{ text: 'Nested child item' }],
    },
  ],
  meta: { depth: 1 },
});

​
Using Keyboard Shortcuts

Type these shortcuts at the start of an empty paragraph:
  • - + Space → Converts to bulleted list
  • 1. + Space → Converts to numbered list
  • [] + Space → Converts to todo list

Build docs developers (and LLMs) love

Get started for freeTalk to us