@ckeditor/ckeditor5-list

@ckeditor/ckeditor5-list

Version 43.2.0
Published 3 days ago
3.64 MB
8 dependencies
GPL-2.0-or-later license

Install

npm i @ckeditor/ckeditor5-list

yarn add @ckeditor/ckeditor5-list

pnpm add @ckeditor/ckeditor5-list

Overview

Ordered and unordered lists feature to CKEditor 5.

Index

Classes

class AdjacentListsSupport

class AdjacentListsSupport extends Plugin {}

property pluginName

static readonly pluginName: string;

method init

init: () => void;

class CheckTodoListCommand

class CheckTodoListCommand extends Command {}

The check to-do command.
The command is registered by the as the checkTodoList editor command.

constructor

constructor(editor: Editor);

property value

value: boolean;

A list of to-do list items selected by the .
Modifiers
- @readonly

method execute

execute: (options?: { forceValue?: boolean }) => void;

Executes the command.
Parameter
options.forceValue If set, it will force the command behavior. If true, the command will apply the attribute. Otherwise, the command will remove the attribute. If not set, the command will look for its current value to decide what it should do.

method refresh

refresh: () => void;

Updates the command's and properties based on the current selection.

class DocumentList

class DocumentList extends Plugin {}

The document list feature.
This is an obsolete plugin that exists for backward compatibility only. Use the instead.
Deprecated

constructor

constructor(editor: Editor);

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [typeof List];

class DocumentListProperties

class DocumentListProperties extends Plugin {}

The document list properties feature.
This is an obsolete plugin that exists for backward compatibility only. Use the instead.
Deprecated

constructor

constructor(editor: Editor);

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [typeof ListProperties];

class LegacyCheckTodoListCommand

class LegacyCheckTodoListCommand extends Command {}

The check to-do command.
The command is registered by the as the checkTodoList editor command and it is also available via aliased todoListCheck name.

constructor

constructor(editor: Editor);

property value

value: boolean;

A list of to-do list items selected by the .
Modifiers
- @readonly

method execute

execute: (options?: { forceValue?: boolean }) => void;

Executes the command.
Parameter
options.forceValue If set, it will force the command behavior. If true, the command will apply the attribute. Otherwise, the command will remove the attribute. If not set, the command will look for its current value to decide what it should do.

method refresh

refresh: () => void;

Updates the command's and properties based on the current selection.

class LegacyIndentCommand

class LegacyIndentCommand extends Command {}

The list indent command. It is used by the .

constructor

constructor(editor: Editor, indentDirection: 'forward' | 'backward');

Creates an instance of the command.
Parameter editor
The editor instance.
Parameter indentDirection
The direction of indent. If it is equal to backward, the command will outdent a list item.

method execute

execute: () => void;

Indents or outdents (depending on the 's indentDirection parameter) selected list items.
execute

method refresh

refresh: () => void;

class LegacyList

class LegacyList extends Plugin {}

The legacy list feature.
This is a "glue" plugin that loads the and .

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [typeof LegacyListEditing, typeof ListUI];

class LegacyListCommand

class LegacyListCommand extends Command {}

The list command. It is used by the .

constructor

constructor(editor: Editor, type: ListType);

Creates an instance of the command.
Parameter editor
The editor instance.
Parameter type
List type that will be handled by this command.

property type

readonly type: ListType;

The type of the list created by the command.

property value

value: boolean;

A flag indicating whether the command is active, which means that the selection starts in a list of the same type.
Modifiers
- @readonly

method execute

execute: (options?: { forceValue?: boolean }) => void;

Executes the list command.
execute
Parameter options
Command options.
Parameter
options.forceValue If set, it will force the command behavior. If true, the command will try to convert the selected items and potentially the neighbor elements to the proper list items. If set to false, it will convert selected elements to paragraphs. If not set, the command will toggle selected elements to list items or paragraphs, depending on the selection.

method refresh

refresh: () => void;

class LegacyListEditing

class LegacyListEditing extends Plugin {}

The engine of the list feature. It handles creating, editing and removing lists and list items.
It registers the 'numberedList', 'bulletedList', 'indentList' and 'outdentList' commands.

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [any, any, typeof LegacyListUtils];

method afterInit

afterInit: () => void;

method init

init: () => void;

class LegacyListProperties

class LegacyListProperties extends Plugin {}

The legacy list properties feature.
This is a "glue" plugin that loads the and the .

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [
    typeof LegacyListPropertiesEditing,
    typeof ListPropertiesUI
];

class LegacyListPropertiesEditing

class LegacyListPropertiesEditing extends Plugin {}

The engine of the list properties feature.
It sets the value for the listItem attribute of the element that allows modifying the list style type.
It registers the 'listStyle', 'listReversed' and 'listStart' commands if they are enabled in the configuration. Read more in .

constructor

constructor(editor: Editor);

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [typeof LegacyListEditing];

method afterInit

afterInit: () => void;

method init

init: () => void;

class LegacyListReversedCommand

class LegacyListReversedCommand extends Command {}

The reversed list command. It changes the listReversed attribute of the selected list items. As a result, the list order will be reversed. It is used by the .

property value

value: boolean;

method execute

execute: (options?: { reversed?: boolean }) => void;

Executes the command.
execute
Parameter
options.reversed Whether the list should be reversed.

method refresh

refresh: () => void;

class LegacyListStartCommand

class LegacyListStartCommand extends Command {}

The list start index command. It changes the listStart attribute of the selected list items. It is used by the .

property value

value: number;

method execute

execute: ({ startIndex }?: { startIndex?: number }) => void;

Executes the command.
execute
Parameter
options.startIndex The list start index.

method refresh

refresh: () => void;

class LegacyListStyleCommand

class LegacyListStyleCommand extends Command {}

The list style command. It changes the listStyle attribute of the selected list items.
If the list type (numbered or bulleted) can be inferred from the passed style type, the command tries to convert selected items to a list of that type. It is used by the .

constructor

constructor(editor: Editor, defaultType: string);

Creates an instance of the command.
Parameter editor
The editor instance.
Parameter defaultType
The list type that will be used by default if the value was not specified during the command execution.

property defaultType

readonly defaultType: string;

The default type of the list style.

property isStyleTypeSupported

isStyleTypeSupported: undefined;

property value

value: string;

Modifiers
- @readonly

method execute

execute: (options?: { type?: string | null }) => void;

Executes the command.
execute
Parameter
options.type The type of the list style, e.g. 'disc' or 'square'. If null is specified, the default style will be applied.

method refresh

refresh: () => void;

class LegacyListUtils

class LegacyListUtils extends Plugin {}

A set of helpers related to legacy lists.

property pluginName

static readonly pluginName: string;

method getListTypeFromListStyleType

getListTypeFromListStyleType: (
    listStyleType: string
) => 'bulleted' | 'numbered' | null;

Checks whether the given list-style-type is supported by numbered or bulleted list.

method getSelectedListItems

getSelectedListItems: (model: Model) => Array<Element>;

Returns an array with all listItem elements in the model selection.
It returns all the items even if only a part of the list is selected, including items that belong to nested lists. If no list is selected, it returns an empty array. The order of the elements is not specified.

method getSiblingNodes

getSiblingNodes: (
    position: Position,
    direction: 'forward' | 'backward'
) => Array<Element>;

Returns an array with all listItem elements that represent the same list.
It means that values of listIndent, listType, listStyle, listReversed and listStart for all items are equal.
Additionally, if the position is inside a list item, that list item will be returned as well.
Parameter position
Starting position.
Parameter direction
Walking direction.

class LegacyTodoList

class LegacyTodoList extends Plugin {}

The legacy to-do list feature.
This is a "glue" plugin that loads the and the .

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [
    typeof LegacyTodoListEditing,
    typeof TodoListUI
];

class LegacyTodoListEditing

class LegacyTodoListEditing extends Plugin {}

The engine of the to-do list feature. It handles creating, editing and removing to-do lists and their items.
It registers the entire functionality of the and extends it with the commands:
- 'todoList', - 'checkTodoList', - 'todoListCheck' as an alias for checkTodoList command.

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [typeof LegacyListEditing];

method init

init: () => void;

class List

class List extends Plugin {}

The list feature.
This is a "glue" plugin that loads the and .

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [typeof ListEditing, typeof ListUI];

class ListCommand

class ListCommand extends Command {}

The list command. It is used by the .

constructor

constructor(editor: Editor, type: ListType, options?: { multiLevel?: boolean });

Creates an instance of the command.
Parameter editor
The editor instance.
Parameter type
List type that will be handled by this command.

property type

readonly type: ListType;

The type of the list created by the command.

property value

value: boolean;

A flag indicating whether the command is active, which means that the selection starts in a list of the same type.
Modifiers
- @readonly

method execute

execute: (options?: {
    forceValue?: boolean;
    additionalAttributes?: Record<string, unknown>;
}) => void;

Executes the list command.
execute afterExecute
Parameter options
Command options.
Parameter
options.forceValue If set, it will force the command behavior. If true, the command will try to convert the selected items and potentially the neighbor elements to the proper list items. If set to false it will convert selected elements to paragraphs. If not set, the command will toggle selected elements to list items or paragraphs, depending on the selection.
Parameter
options.additionalAttributes Additional attributes that are set for list items when the command is executed.

method refresh

refresh: () => void;

class ListEditing

class ListEditing extends Plugin {}

The editing part of the document-list feature. It handles creating, editing and removing lists and list items.

constructor

constructor(editor: Editor);

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [any, any, typeof ListUtils, any];

method afterInit

afterInit: () => void;

method getListAttributeNames

getListAttributeNames: () => Array<string>;

Returns list of model attribute names that should affect downcast conversion.

method init

init: () => void;

method registerDowncastStrategy

registerDowncastStrategy: (strategy: DowncastStrategy) => void;

Registers a downcast strategy.
**Note**: Strategies must be registered in the Plugin#init() phase so that it can be applied in the ListEditing#afterInit().
Parameter strategy
The downcast strategy to register.

class ListIndentCommand

class ListIndentCommand extends Command {}

The document list indent command. It is used by the .

constructor

constructor(editor: Editor, indentDirection: 'forward' | 'backward');

Creates an instance of the command.
Parameter editor
The editor instance.
Parameter indentDirection
The direction of indent. If it is equal to backward, the command will outdent a list item.

method execute

execute: () => void;

Indents or outdents (depending on the 's indentDirection parameter) selected list items.
execute afterExecute

method refresh

refresh: () => void;

class ListMergeCommand

class ListMergeCommand extends Command {}

The document list merge command. It is used by the .

constructor

constructor(editor: Editor, direction: 'forward' | 'backward');

Creates an instance of the command.
Parameter editor
The editor instance.
Parameter direction
Whether list item should be merged before or after the selected block.

method execute

execute: ({
    shouldMergeOnBlocksContentLevel,
}?: {
    shouldMergeOnBlocksContentLevel?: boolean;
}) => void;

Merges list blocks together (depending on the 's direction parameter).
execute afterExecute
Parameter options
Command options.
Parameter
options.shouldMergeOnBlocksContentLevel When set true, merging will be performed together with to get rid of the inline content in the selection or take advantage of the heuristics in deleteContent() that helps convert lists into paragraphs in certain cases.

method refresh

refresh: () => void;

class ListProperties

class ListProperties extends Plugin {}

The list properties feature.
This is a "glue" plugin that loads the and the .

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [
    typeof ListPropertiesEditing,
    typeof ListPropertiesUI
];

class ListPropertiesEditing

class ListPropertiesEditing extends Plugin {}

The document list properties engine feature.
It registers the 'listStyle', 'listReversed' and 'listStart' commands if they are enabled in the configuration. Read more in .

constructor

constructor(editor: Editor);

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [
    typeof ListEditing,
    typeof ListPropertiesUtils
];

method init

init: () => void;

class ListPropertiesUI

class ListPropertiesUI extends Plugin {}

The list properties UI plugin. It introduces the extended 'bulletedList' and 'numberedList' toolbar buttons that allow users to control such aspects of list as the marker, start index or order.
**Note**: Buttons introduced by this plugin override implementations from the (because they share the same names).

property pluginName

static readonly pluginName: string;

method init

init: () => void;

class ListPropertiesUtils

class ListPropertiesUtils extends Plugin {}

A set of helpers related to document lists.

property pluginName

static readonly pluginName: string;

method getAllSupportedStyleTypes

getAllSupportedStyleTypes: () => Array<string>;

Gets all the style types supported by given list type.

method getListStyleTypeFromTypeAttribute

getListStyleTypeFromTypeAttribute: (value: string) => string | null;

Converts type attribute of <ul> or <ol> elements to list-style-type equivalent.

method getListTypeFromListStyleType

getListTypeFromListStyleType: (
    listStyleType: string
) => 'bulleted' | 'numbered' | null;

Checks whether the given list-style-type is supported by numbered or bulleted list.

method getTypeAttributeFromListStyleType

getTypeAttributeFromListStyleType: (value: string) => string | null;

Converts list-style-type style to type attribute of <ul> or <ol> elements.

class ListReversedCommand

class ListReversedCommand extends Command {}

The list reversed command. It changes the listReversed attribute of the selected list items, letting the user to choose the order of an ordered list. It is used by the .

property value

value: boolean;

method execute

execute: (options?: { reversed?: boolean }) => void;

Executes the command.
execute
Parameter
options.reversed Whether the list should be reversed.

method refresh

refresh: () => void;

class ListSplitCommand

class ListSplitCommand extends Command {}

The document list split command that splits the list item at the selection.
It is used by the .

constructor

constructor(editor: Editor, direction: 'before' | 'after');

Creates an instance of the command.
Parameter editor
The editor instance.
Parameter direction
Whether list item should be split before or after the selected block.

method execute

execute: () => void;

Splits the list item at the selection.
execute afterExecute

method refresh

refresh: () => void;

class ListStartCommand

class ListStartCommand extends Command {}

The list start index command. It changes the listStart attribute of the selected list items, letting the user to choose the starting point of an ordered list. It is used by the .

property value

value: number;

method execute

execute: ({ startIndex }?: { startIndex?: number }) => void;

Executes the command.
execute
Parameter
options.startIndex The list start index.

method refresh

refresh: () => void;

class ListStyleCommand

class ListStyleCommand extends Command {}

The list style command. It changes listStyle attribute of the selected list items, letting the user choose styles for the list item markers. It is used by the .

constructor

constructor(editor: Editor, defaultType: string, supportedTypes?: string[]);

Creates an instance of the command.
Parameter editor
The editor instance.
Parameter defaultType
The list type that will be used by default if the value was not specified during the command execution.
Parameter supportedTypes
The list of supported style types by this command.

property defaultType

readonly defaultType: string;

The default type of the list style.

property value

value: string;

method execute

execute: (options?: { type?: string | null }) => void;

Executes the command.
execute
Parameter
options.type The type of the list style, e.g. 'disc' or 'square'. If null is specified, the default style will be applied.

method isStyleTypeSupported

isStyleTypeSupported: (value: string) => boolean;

Checks if the given style type is supported by this plugin.

method refresh

refresh: () => void;

class ListUI

class ListUI extends Plugin {}

The list UI feature. It introduces the 'numberedList' and 'bulletedList' buttons that allow to convert paragraphs to and from list items and indent or outdent them.

property pluginName

static readonly pluginName: string;

method init

init: () => void;

class ListUtils

class ListUtils extends Plugin {}

A set of helpers related to document lists.

property pluginName

static readonly pluginName: string;

method expandListBlocksToCompleteItems

expandListBlocksToCompleteItems: (
    blocks: ArrayOrItem<Element>,
    options?: { withNested?: boolean }
) => Array<Element>;

Expands the given list of selected blocks to include the leading and tailing blocks of partially selected list items.
Parameter blocks
The list of selected blocks.
Parameter
options.withNested Whether should include nested list items.

method expandListBlocksToCompleteList

expandListBlocksToCompleteList: (blocks: ArrayOrItem<Element>) => Array<Element>;

Expands the given list of selected blocks to include all the items of the lists they're in.
Parameter blocks
The list of selected blocks.

method isFirstBlockOfListItem

isFirstBlockOfListItem: (listBlock: Element) => boolean;

Check if the given block is the first in the list item.
Parameter listBlock
The list block element.

method isListItemBlock

isListItemBlock: (node: Node | null) => node is ListElement;

Returns true if the given model node is a list item block.
Parameter node
A model node.

method isNumberedListType

isNumberedListType: (listType: ListType) => boolean;

Returns true if listType is of type numbered or customNumbered.

class TodoDocumentList

class TodoDocumentList extends Plugin {}

The to-do list feature.
This is an obsolete plugin that exists for backward compatibility only. Use the instead.
Deprecated

constructor

constructor(editor: Editor);

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [typeof TodoList];

class TodoList

class TodoList extends Plugin {}

The to-do list feature.
This is a "glue" plugin that loads the and the .

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [typeof TodoListEditing, typeof TodoListUI];

class TodoListEditing

class TodoListEditing extends Plugin {}

The engine of the to-do list feature. It handles creating, editing and removing to-do lists and their items.
It registers the entire functionality of the and extends it with the commands:
- 'todoList', - 'checkTodoList',

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [typeof ListEditing];

method init

init: () => void;

class TodoListUI

class TodoListUI extends Plugin {}

The to-do list UI feature. It introduces the 'todoList' button that allows to convert elements to and from to-do list items and to indent or outdent them.

property pluginName

static readonly pluginName: string;

method init

init: () => void;

Interfaces

interface ListConfig

interface ListConfig {}

The configuration of the feature and the feature.

ClassicEditor
	.create( editorElement, {
		list:  ... // The list feature configuration.
	} )
	.then( ... )
	.catch( ... );

See .

ListConfig

property multiBlock

multiBlock?: boolean;

Allows multiple blocks in single list item.
With this option enabled you can have block widgets, for example images or even tables, within a list item.
**Note:** This is enabled by default.
true

property properties

properties?: ListPropertiesConfig;

The configuration of the feature and the feature.
Read more in .

interface ListPropertiesConfig

interface ListPropertiesConfig {}

The configuration of the feature and the feature.
This configuration controls the individual list properties. For instance, it enables or disables specific editor commands operating on lists (, , , or on the legacy lists , , ), the look of the UI ('numberedList' and 'bulletedList' dropdowns), and the editor data pipeline (allowed HTML attributes).
ClassicEditor .create( editorElement, { list: { properties: { styles: true, startIndex: true, reversed: true } } } ) .then( ... ) .catch( ... );

property reversed

reversed?: boolean;

When set, the reversed list feature will be enabled. It allows changing the reversed HTML attribute of the numbered lists. As a result, it will be possible to make the list order descending instead of ascending.
**Note**: This configuration does not affect bulleted and to-do lists.
false

property startIndex

startIndex?: boolean;

When set, the list start index feature will be enabled. It allows changing the start HTML attribute of the numbered lists. As a result, it will be possible to specify the start value of the first item in an ordered list.
**Note**: This configuration does not affect bulleted and to-do lists.
false

property styles

styles?:
    | boolean
    | ListPropertiesStyleConfig
    | ArrayOrItem<ListPropertiesStyleListType>;

When set, the list style feature will be enabled. It allows changing the list-style-type style or the type HTML attribute of a list.
**Note**: Styling using the type HTML attribute is only available in ().
true

Type Aliases

type ListType

type ListType =
    | 'numbered'
    | 'bulleted'
    | 'todo'
    | 'customNumbered'
    | 'customBulleted';

Package Files (38)

Dependencies (8)

Dev Dependencies (0)

No dev dependencies.

Peer Dependencies (0)

No peer dependencies.

Badge

To add a badge like this oneto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@ckeditor/ckeditor5-list.

Markdown

[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@ckeditor/ckeditor5-list)

HTML

<a href="https://www.jsdocs.io/package/@ckeditor/ckeditor5-list"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>

Updated just now.
Package analyzed in 6564 ms.
Missing or incorrect documentation? Open an issue for this package.

@ckeditor/ckeditor5-list

Install

Overview

Index

Classes

Interfaces

Type Aliases

Classes

class AdjacentListsSupport

property pluginName

method init

class CheckTodoListCommand

property value

Modifiers

method execute

Parameter

method refresh

class DocumentList

Deprecated

property pluginName

property requires

class DocumentListProperties

Deprecated

property pluginName

property requires

class LegacyCheckTodoListCommand

property value

Modifiers

method execute

Parameter

method refresh

class LegacyIndentCommand

Parameter editor

Parameter indentDirection

method execute

method refresh

class LegacyList

property pluginName

property requires

class LegacyListCommand

Parameter editor

Parameter type

property type

property value

Modifiers

method execute

Parameter options

Parameter

method refresh

class LegacyListEditing

property pluginName

property requires

method afterInit

method init

class LegacyListProperties

property pluginName

property requires

class LegacyListPropertiesEditing

property pluginName

property requires

method afterInit

method init

class LegacyListReversedCommand

property value

method execute

Parameter

method refresh

class LegacyListStartCommand

property value

method execute

Parameter

method refresh

class LegacyListStyleCommand

Parameter editor

Parameter defaultType

property defaultType

property isStyleTypeSupported

property value

Modifiers

method execute