List Plugin

The ListPlugin provides bullet lists, ordered (numbered) lists, and checklists with indent/outdent support up to configurable nesting depth.

Usage

import { ListPlugin } from '@notectl/core';

new ListPlugin()
// or with custom config:
new ListPlugin({ types: ['bullet', 'ordered'], maxIndent: 3 })

Configuration

interface ListConfig {
  /** Which list types to enable. Default: ['bullet', 'ordered', 'checklist'] */
  readonly types: ListType[];
  /** Maximum nesting level. Default: 4 */
  readonly maxIndent: number;
  /** Render separator after toolbar item. */
  readonly separatorAfter?: boolean;
  /** Allow checkbox toggling in read-only mode. Default: false */
  readonly interactiveCheckboxes?: boolean;
  /** Override the plugin locale independently from the global editor locale. */
  readonly locale?: ListLocale;
}

type ListType = 'bullet' | 'ordered' | 'checklist';

Example: Only bullet and ordered lists

new ListPlugin({ types: ['bullet', 'ordered'] })

Example: Deep nesting

new ListPlugin({ maxIndent: 8 })

Example: Interactive checkboxes in read-only mode

When interactiveCheckboxes is enabled, checklist checkboxes remain clickable even when the editor is in read-only mode. All other editing is still blocked.

const editor = await createEditor({
  readonly: true,
  plugins: [new ListPlugin({ interactiveCheckboxes: true })],
});

See the Read-Only Checklist guide for a full walkthrough.

Locale Override

Each plugin resolves its locale automatically from the editor’s global locale setting. To override independently:

import { ListPlugin, LIST_LOCALE_DE } from '@notectl/core';

new ListPlugin({ locale: LIST_LOCALE_DE })

See the Internationalization guide for details.

Commands

Command	Description	Returns
toggleList:bullet	Toggle bullet list on current block	boolean
toggleList:ordered	Toggle ordered list on current block	boolean
toggleList:checklist	Toggle checklist on current block	boolean
indentListItem	Increase indent level (up to maxIndent)	boolean
outdentListItem	Decrease indent level	boolean
toggleChecklistItem	Toggle checked state on checklist item (no-op in read-only mode unless interactiveCheckboxes is enabled)	boolean

// Create a bullet list
editor.executeCommand('toggleList:bullet');

// Indent a list item
editor.executeCommand('indentListItem');

// Toggle a checkbox
editor.executeCommand('toggleChecklistItem');

Keyboard Shortcuts

Shortcut	Action
Enter	Split list item; exit list if the item is empty
Backspace	Convert to paragraph when cursor is collapsed at start of item
Tab	Indent list item (increase nesting)
Shift+Tab	Outdent list item (decrease nesting)

Input Rules

Type at the beginning of a line:

Pattern	Result
- or *	Bullet list
1. (any number followed by .)	Ordered list
[ ]	Unchecked checklist item
[x]	Checked checklist item

Toolbar

Three toolbar buttons, one for each list type. Each button toggles its respective list type. The active state highlights when the cursor is inside a matching list item.

Button	Icon	List Type
Bullet list	Bullet icon	bullet
Ordered list	Number icon	ordered
Checklist	Checkbox icon	checklist

Node Spec

Type	Attributes	Description
list_item	listType, indent, checked	Single list node type for all list variants

// Attribute types
interface ListItemAttributes {
  listType: 'bullet' | 'ordered' | 'checklist';
  indent: number;    // 0-based, max is maxIndent
  checked: boolean;  // Only meaningful for checklist items
}

notectl uses a flat list model: each list_item carries its own listType and indent level. This avoids the complexity of nested <ul>/<ol> structures and simplifies indent/outdent operations.