Skip to main content

@lexical/list

Classes​

ListItemNode​

Defined in: packages/lexical-list/src/LexicalListItemNode.ts:76

Extends​

Constructors​

Constructor​

new ListItemNode(value, checked, key?): ListItemNode

Defined in: packages/lexical-list/src/LexicalListItemNode.ts:106

Parameters​
value​

number = 1

checked​

undefined | boolean

key?​

string

Returns​

ListItemNode

Overrides​

ElementNode.constructor

Methods​

afterCloneFrom()​

afterCloneFrom(prevNode): void

Defined in: packages/lexical-list/src/LexicalListItemNode.ts:116

Perform any state updates on the clone of prevNode that are not already handled by the constructor call in the static clone method. If you have state to update in your clone that is not handled directly by the constructor, it is advisable to override this method but it is required to include a call to super.afterCloneFrom(prevNode) in your implementation. This is only intended to be called by $cloneWithProperties function or via a super call.

Parameters​
prevNode​

this

Returns​

void

Example​
class ClassesTextNode extends TextNode {
  // Not shown: static getType, static importJSON, exportJSON, createDOM, updateDOM
  __classes = new Set<string>();
  static clone(node: ClassesTextNode): ClassesTextNode {
    // The inherited TextNode constructor is used here, so
    // classes is not set by this method.
    return new ClassesTextNode(node.__text, node.__key);
  }
  afterCloneFrom(node: this): void {
    // This calls TextNode.afterCloneFrom and LexicalNode.afterCloneFrom
    // for necessary state updates
    super.afterCloneFrom(node);
    this.__addClasses(node.__classes);
  }
  // This method is a private implementation detail, it is not
  // suitable for the public API because it does not call getWritable
  __addClasses(classNames: Iterable<string>): this {
    for (const className of classNames) {
      this.__classes.add(className);
    }
    return this;
  }
  addClass(...classNames: string[]): this {
    return this.getWritable().__addClasses(classNames);
  }
  removeClass(...classNames: string[]): this {
    const node = this.getWritable();
    for (const className of classNames) {
      this.__classes.delete(className);
    }
    return this;
  }
  getClasses(): Set<string> {
    return this.getLatest().__classes;
  }
}
Overrides​

ElementNode.afterCloneFrom

append()​

append(...nodes): this

Defined in: packages/lexical-list/src/LexicalListItemNode.ts:197

Parameters​
nodes​

...LexicalNode[]

Returns​

this

Overrides​

ElementNode.append

canMergeWhenEmpty()​

canMergeWhenEmpty(): true

Defined in: packages/lexical-list/src/LexicalListItemNode.ts:463

Determines whether this node, when empty, can merge with a first block of nodes being inserted.

This method is specifically called in RangeSelection.insertNodes to determine merging behavior during nodes insertion.

Returns​

true

Example​
// In a ListItemNode or QuoteNode implementation:
canMergeWhenEmpty(): true {
 return true;
}
Overrides​

ElementNode.canMergeWhenEmpty

collapseAtStart()​

collapseAtStart(selection): true

Defined in: packages/lexical-list/src/LexicalListItemNode.ts:316

Parameters​
selection​

RangeSelection

Returns​

true

Overrides​

ElementNode.collapseAtStart

createDOM()​

createDOM(config): HTMLElement

Defined in: packages/lexical-list/src/LexicalListItemNode.ts:122

Called during the reconciliation process to determine which nodes to insert into the DOM for this Lexical Node.

This method must return exactly one HTMLElement. Nested elements are not supported.

Do not attempt to update the Lexical EditorState during this phase of the update lifecycle.

Parameters​
config​

EditorConfig

Returns​

HTMLElement

Overrides​

ElementNode.createDOM

createParentElementNode()​

createParentElementNode(): ElementNode

Defined in: packages/lexical-list/src/LexicalListItemNode.ts:459

The creation logic for any required parent. Should be implemented if isParentRequired returns true.

Returns​

ElementNode

Overrides​

ElementNode.createParentElementNode

exportDOM()​

exportDOM(editor): DOMExportOutput

Defined in: packages/lexical-list/src/LexicalListItemNode.ts:171

Controls how the this node is serialized to HTML. This is important for copy and paste between Lexical and non-Lexical editors, or Lexical editors with different namespaces, in which case the primary transfer format is HTML. It's also important if you're serializing to HTML for any other reason via $generateHtmlFromNodes. You could also use this method to build your own HTML renderer.

Parameters​
editor​

LexicalEditor

Returns​

DOMExportOutput

Overrides​

ElementNode.exportDOM

exportJSON()​

exportJSON(): SerializedListItemNode

Defined in: packages/lexical-list/src/LexicalListItemNode.ts:189

Controls how the this node is serialized to JSON. This is important for copy and paste between Lexical editors sharing the same namespace. It's also important if you're serializing to JSON for persistent storage somewhere. See Serialization & Deserialization.

Returns​

SerializedListItemNode

Overrides​

ElementNode.exportJSON

extractWithChild()​

extractWithChild(child, selection): boolean

Defined in: packages/lexical-list/src/LexicalListItemNode.ts:440

Parameters​
child​

LexicalNode

selection​

BaseSelection

Returns​

boolean

Overrides​

ElementNode.extractWithChild

getChecked()​

getChecked(): undefined | boolean

Defined in: packages/lexical-list/src/LexicalListItemNode.ts:367

Returns​

undefined | boolean

getIndent()​

getIndent(): number

Defined in: packages/lexical-list/src/LexicalListItemNode.ts:391

Returns​

number

Overrides​

ElementNode.getIndent

getValue()​

getValue(): number

Defined in: packages/lexical-list/src/LexicalListItemNode.ts:355

Returns​

number

insertAfter()​

insertAfter(node, restoreSelection): LexicalNode

Defined in: packages/lexical-list/src/LexicalListItemNode.ts:257

Inserts a node after this LexicalNode (as the next sibling).

Parameters​
node​

LexicalNode

restoreSelection​

boolean = true

Whether or not to attempt to resolve the selection to the appropriate place after the operation is complete.

Returns​

LexicalNode

Overrides​

ElementNode.insertAfter

insertNewAfter()​

insertNewAfter(_, restoreSelection): ParagraphNode | ListItemNode

Defined in: packages/lexical-list/src/LexicalListItemNode.ts:303

Parameters​
_​

RangeSelection

restoreSelection​

boolean = true

Returns​

ParagraphNode | ListItemNode

Overrides​

ElementNode.insertNewAfter

isParentRequired()​

isParentRequired(): true

Defined in: packages/lexical-list/src/LexicalListItemNode.ts:455

Whether or not this node has a required parent. Used during copy + paste operations to normalize nodes that would otherwise be orphaned. For example, ListItemNodes without a ListNode parent or TextNodes with a ParagraphNode parent.

Returns​

true

Overrides​

ElementNode.isParentRequired

remove()​

remove(preserveEmptyParent?): void

Defined in: packages/lexical-list/src/LexicalListItemNode.ts:287

Removes this LexicalNode from the EditorState. If the node isn't re-inserted somewhere, the Lexical garbage collector will eventually clean it up.

Parameters​
preserveEmptyParent?​

boolean

If falsy, the node's parent will be removed if it's empty after the removal operation. This is the default behavior, subject to other node heuristics such as ElementNode#canBeEmpty

Returns​

void

Overrides​

ElementNode.remove

replace()​

replace<N>(replaceWithNode, includeChildren?): N

Defined in: packages/lexical-list/src/LexicalListItemNode.ts:213

Replaces this LexicalNode with the provided node, optionally transferring the children of the replaced node to the replacing node.

Type Parameters​
N​

N extends LexicalNode

Parameters​
replaceWithNode​

N

includeChildren?​

boolean

Whether or not to transfer the children of this node to the replacing node.

Returns​

N

Overrides​

ElementNode.replace

setChecked()​

setChecked(checked?): this

Defined in: packages/lexical-list/src/LexicalListItemNode.ts:380

Parameters​
checked?​

boolean

Returns​

this

setIndent()​

setIndent(indent): this

Defined in: packages/lexical-list/src/LexicalListItemNode.ts:408

Parameters​
indent​

number

Returns​

this

Overrides​

ElementNode.setIndent

setValue()​

setValue(value): this

Defined in: packages/lexical-list/src/LexicalListItemNode.ts:361

Parameters​
value​

number

Returns​

this

toggleChecked()​

toggleChecked(): this

Defined in: packages/lexical-list/src/LexicalListItemNode.ts:386

Returns​

this

updateDOM()​

updateDOM(prevNode, dom, config): boolean

Defined in: packages/lexical-list/src/LexicalListItemNode.ts:151

Called when a node changes and should update the DOM in whatever way is necessary to make it align with any changes that might have happened during the update.

Returning "true" here will cause lexical to unmount and recreate the DOM node (by calling createDOM). You would need to do this if the element tag changes, for instance.

Parameters​
prevNode​

ListItemNode

dom​

HTMLElement

config​

EditorConfig

Returns​

boolean

Overrides​

ElementNode.updateDOM

updateFromJSON()​

updateFromJSON(serializedNode): this

Defined in: packages/lexical-list/src/LexicalListItemNode.ts:162

Update this LexicalNode instance from serialized JSON. It's recommended to implement as much logic as possible in this method instead of the static importJSON method, so that the functionality can be inherited in subclasses.

The LexicalUpdateJSON utility type should be used to ignore any type, version, or children properties in the JSON so that the extended JSON from subclasses are acceptable parameters for the super call.

If overridden, this method must call super.

Parameters​
serializedNode​

LexicalUpdateJSON<SerializedListItemNode>

Returns​

this

Example​
class MyTextNode extends TextNode {
  // ...
  static importJSON(serializedNode: SerializedMyTextNode): MyTextNode {
    return $createMyTextNode()
      .updateFromJSON(serializedNode);
  }
  updateFromJSON(
    serializedNode: LexicalUpdateJSON<SerializedMyTextNode>,
  ): this {
    return super.updateFromJSON(serializedNode)
      .setMyProperty(serializedNode.myProperty);
  }
}
Overrides​

ElementNode.updateFromJSON

updateListItemDOM()​

updateListItemDOM(prevNode, dom, config): void

Defined in: packages/lexical-list/src/LexicalListItemNode.ts:129

Parameters​
prevNode​

null | ListItemNode

dom​

HTMLLIElement

config​

EditorConfig

Returns​

void

ListNode​

Defined in: packages/lexical-list/src/LexicalListNode.ts:54

Extends​

Constructors​

Constructor​

new ListNode(listType, start, key?): ListNode

Defined in: packages/lexical-list/src/LexicalListNode.ts:83

Parameters​
listType​

ListType = 'number'

start​

number = 1

key?​

string

Returns​

ListNode

Overrides​

ElementNode.constructor

Methods​

afterCloneFrom()​

afterCloneFrom(prevNode): void

Defined in: packages/lexical-list/src/LexicalListNode.ts:91

Perform any state updates on the clone of prevNode that are not already handled by the constructor call in the static clone method. If you have state to update in your clone that is not handled directly by the constructor, it is advisable to override this method but it is required to include a call to super.afterCloneFrom(prevNode) in your implementation. This is only intended to be called by $cloneWithProperties function or via a super call.

Parameters​
prevNode​

this

Returns​

void

Example​
class ClassesTextNode extends TextNode {
  // Not shown: static getType, static importJSON, exportJSON, createDOM, updateDOM
  __classes = new Set<string>();
  static clone(node: ClassesTextNode): ClassesTextNode {
    // The inherited TextNode constructor is used here, so
    // classes is not set by this method.
    return new ClassesTextNode(node.__text, node.__key);
  }
  afterCloneFrom(node: this): void {
    // This calls TextNode.afterCloneFrom and LexicalNode.afterCloneFrom
    // for necessary state updates
    super.afterCloneFrom(node);
    this.__addClasses(node.__classes);
  }
  // This method is a private implementation detail, it is not
  // suitable for the public API because it does not call getWritable
  __addClasses(classNames: Iterable<string>): this {
    for (const className of classNames) {
      this.__classes.add(className);
    }
    return this;
  }
  addClass(...classNames: string[]): this {
    return this.getWritable().__addClasses(classNames);
  }
  removeClass(...classNames: string[]): this {
    const node = this.getWritable();
    for (const className of classNames) {
      this.__classes.delete(className);
    }
    return this;
  }
  getClasses(): Set<string> {
    return this.getLatest().__classes;
  }
}
Overrides​

ElementNode.afterCloneFrom

canBeEmpty()​

canBeEmpty(): false

Defined in: packages/lexical-list/src/LexicalListNode.ts:183

Returns​

false

Overrides​

ElementNode.canBeEmpty

canIndent()​

canIndent(): false

Defined in: packages/lexical-list/src/LexicalListNode.ts:187

Returns​

false

Overrides​

ElementNode.canIndent

createDOM()​

createDOM(config, _editor?): HTMLElement

Defined in: packages/lexical-list/src/LexicalListNode.ts:125

Called during the reconciliation process to determine which nodes to insert into the DOM for this Lexical Node.

This method must return exactly one HTMLElement. Nested elements are not supported.

Do not attempt to update the Lexical EditorState during this phase of the update lifecycle.

Parameters​
config​

EditorConfig

_editor?​

LexicalEditor

allows access to the editor for context during reconciliation.

Returns​

HTMLElement

Overrides​

ElementNode.createDOM

exportDOM()​

exportDOM(editor): DOMExportOutput

Defined in: packages/lexical-list/src/LexicalListNode.ts:159

Controls how the this node is serialized to HTML. This is important for copy and paste between Lexical and non-Lexical editors, or Lexical editors with different namespaces, in which case the primary transfer format is HTML. It's also important if you're serializing to HTML for any other reason via $generateHtmlFromNodes. You could also use this method to build your own HTML renderer.

Parameters​
editor​

LexicalEditor

Returns​

DOMExportOutput

Overrides​

ElementNode.exportDOM

exportJSON()​

exportJSON(): SerializedListNode

Defined in: packages/lexical-list/src/LexicalListNode.ts:174

Controls how the this node is serialized to JSON. This is important for copy and paste between Lexical editors sharing the same namespace. It's also important if you're serializing to JSON for persistent storage somewhere. See Serialization & Deserialization.

Returns​

SerializedListNode

Overrides​

ElementNode.exportJSON

extractWithChild()​

extractWithChild(child): boolean

Defined in: packages/lexical-list/src/LexicalListNode.ts:213

Parameters​
child​

LexicalNode

Returns​

boolean

Overrides​

ElementNode.extractWithChild

getListType()​

getListType(): ListType

Defined in: packages/lexical-list/src/LexicalListNode.ts:109

Returns​

ListType

getStart()​

getStart(): number

Defined in: packages/lexical-list/src/LexicalListNode.ts:113

Returns​

number

getTag()​

getTag(): ListNodeTagType

Defined in: packages/lexical-list/src/LexicalListNode.ts:98

Returns​

ListNodeTagType

setListType()​

setListType(type): this

Defined in: packages/lexical-list/src/LexicalListNode.ts:102

Parameters​
type​

ListType

Returns​

this

setStart()​

setStart(start): this

Defined in: packages/lexical-list/src/LexicalListNode.ts:117

Parameters​
start​

number

Returns​

this

splice()​

splice(start, deleteCount, nodesToInsert): this

Defined in: packages/lexical-list/src/LexicalListNode.ts:191

Parameters​
start​

number

deleteCount​

number

nodesToInsert​

LexicalNode[]

Returns​

this

Overrides​

ElementNode.splice

updateDOM()​

updateDOM(prevNode, dom, config): boolean

Defined in: packages/lexical-list/src/LexicalListNode.ts:139

Called when a node changes and should update the DOM in whatever way is necessary to make it align with any changes that might have happened during the update.

Returning "true" here will cause lexical to unmount and recreate the DOM node (by calling createDOM). You would need to do this if the element tag changes, for instance.

Parameters​
prevNode​

this

dom​

HTMLElement

config​

EditorConfig

Returns​

boolean

Overrides​

ElementNode.updateDOM

updateFromJSON()​

updateFromJSON(serializedNode): this

Defined in: packages/lexical-list/src/LexicalListNode.ts:152

Update this LexicalNode instance from serialized JSON. It's recommended to implement as much logic as possible in this method instead of the static importJSON method, so that the functionality can be inherited in subclasses.

The LexicalUpdateJSON utility type should be used to ignore any type, version, or children properties in the JSON so that the extended JSON from subclasses are acceptable parameters for the super call.

If overridden, this method must call super.

Parameters​
serializedNode​

LexicalUpdateJSON<SerializedListNode>

Returns​

this

Example​
class MyTextNode extends TextNode {
  // ...
  static importJSON(serializedNode: SerializedMyTextNode): MyTextNode {
    return $createMyTextNode()
      .updateFromJSON(serializedNode);
  }
  updateFromJSON(
    serializedNode: LexicalUpdateJSON<SerializedMyTextNode>,
  ): this {
    return super.updateFromJSON(serializedNode)
      .setMyProperty(serializedNode.myProperty);
  }
}
Overrides​

ElementNode.updateFromJSON

Type Aliases​

ListNodeTagType​

ListNodeTagType = "ul" | "ol"

Defined in: packages/lexical-list/src/LexicalListNode.ts:51

ListType​

ListType = "number" | "bullet" | "check"

Defined in: packages/lexical-list/src/LexicalListNode.ts:49

SerializedListItemNode​

SerializedListItemNode = Spread<{ checked: boolean | undefined; value: number; }, SerializedElementNode>

Defined in: packages/lexical-list/src/LexicalListItemNode.ts:47

SerializedListNode​

SerializedListNode = Spread<{ listType: ListType; start: number; tag: ListNodeTagType; }, SerializedElementNode>

Defined in: packages/lexical-list/src/LexicalListNode.ts:40

Variables​

INSERT_CHECK_LIST_COMMAND​

const INSERT_CHECK_LIST_COMMAND: LexicalCommand<void>

Defined in: packages/lexical-list/src/checkList.ts:37

INSERT_ORDERED_LIST_COMMAND​

const INSERT_ORDERED_LIST_COMMAND: LexicalCommand<void>

Defined in: packages/lexical-list/src/index.ts:69

INSERT_UNORDERED_LIST_COMMAND​

const INSERT_UNORDERED_LIST_COMMAND: LexicalCommand<void>

Defined in: packages/lexical-list/src/index.ts:67

REMOVE_LIST_COMMAND​

const REMOVE_LIST_COMMAND: LexicalCommand<void>

Defined in: packages/lexical-list/src/index.ts:72

UPDATE_LIST_START_COMMAND​

const UPDATE_LIST_START_COMMAND: LexicalCommand<{ listNodeKey: NodeKey; newStart: number; }>

Defined in: packages/lexical-list/src/index.ts:63

Functions​

$createListItemNode()​

$createListItemNode(checked?): ListItemNode

Defined in: packages/lexical-list/src/LexicalListItemNode.ts:591

Creates a new List Item node, passing true/false will convert it to a checkbox input.

Parameters​

checked?​

boolean

Is the List Item a checkbox and, if so, is it checked? undefined/null: not a checkbox, true/false is a checkbox and checked/unchecked, respectively.

Returns​

ListItemNode

The new List Item.

$createListNode()​

$createListNode(listType, start): ListNode

Defined in: packages/lexical-list/src/LexicalListNode.ts:355

Creates a ListNode of listType.

Parameters​

listType​

ListType = 'number'

The type of list to be created. Can be 'number', 'bullet', or 'check'.

start​

number = 1

Where an ordered list starts its count, start = 1 if left undefined.

Returns​

ListNode

The new ListNode

$getListDepth()​

$getListDepth(listNode): number

Defined in: packages/lexical-list/src/utils.ts:27

Checks the depth of listNode from the root node.

Parameters​

listNode​

ListNode

The ListNode to be checked.

Returns​

number

The depth of the ListNode.

$handleListInsertParagraph()​

$handleListInsertParagraph(): boolean

Defined in: packages/lexical-list/src/formatList.ts:494

Attempts to insert a ParagraphNode at selection and selects the new node. The selection must contain a ListItemNode or a node that does not already contain text. If its grandparent is the root/shadow root, it will get the ListNode (which should be the parent node) and insert the ParagraphNode as a sibling to the ListNode. If the ListNode is nested in a ListItemNode instead, it will add the ParagraphNode after the grandparent ListItemNode. Throws an invariant if the selection is not a child of a ListNode.

Returns​

boolean

true if a ParagraphNode was inserted successfully, false if there is no selection or the selection does not contain a ListItemNode or the node already holds text.

$insertList()​

$insertList(listType): void

Defined in: packages/lexical-list/src/formatList.ts:65

Inserts a new ListNode. If the selection's anchor node is an empty ListItemNode and is a child of the root/shadow root, it will replace the ListItemNode with a ListNode and the old ListItemNode. Otherwise it will replace its parent with a new ListNode and re-insert the ListItemNode and any previous children. If the selection's anchor node is not an empty ListItemNode, it will add a new ListNode or merge an existing ListNode, unless the the node is a leaf node, in which case it will attempt to find a ListNode up the branch and replace it with a new ListNode, or create a new ListNode at the nearest root/shadow root.

Parameters​

listType​

ListType

The type of list, "number" | "bullet" | "check".

Returns​

void

$isListItemNode()​

$isListItemNode(node): node is ListItemNode

Defined in: packages/lexical-list/src/LexicalListItemNode.ts:600

Checks to see if the node is a ListItemNode.

Parameters​

node​

The node to be checked.

undefined | null | LexicalNode

Returns​

node is ListItemNode

true if the node is a ListItemNode, false otherwise.

$isListNode()​

$isListNode(node): node is ListNode

Defined in: packages/lexical-list/src/LexicalListNode.ts:367

Checks to see if the node is a ListNode.

Parameters​

node​

The node to be checked.

undefined | null | LexicalNode

Returns​

node is ListNode

true if the node is a ListNode, false otherwise.

$removeList()​

$removeList(): void

Defined in: packages/lexical-list/src/formatList.ts:238

Searches for the nearest ancestral ListNode and removes it. If selection is an empty ListItemNode it will remove the whole list, including the ListItemNode. For each ListItemNode in the ListNode, removeList will also generate new ParagraphNodes in the removed ListNode's place. Any child node inside a ListItemNode will be appended to the new ParagraphNodes.

Returns​

void

insertList()​

insertList(editor, listType): void

Defined in: packages/lexical-list/src/index.ts:265

Parameters​

editor​

LexicalEditor

The lexical editor.

listType​

ListType

The type of list, "number" | "bullet" | "check".

Returns​

void

Deprecated​

use $insertList from an update or command listener.

Inserts a new ListNode. If the selection's anchor node is an empty ListItemNode and is a child of the root/shadow root, it will replace the ListItemNode with a ListNode and the old ListItemNode. Otherwise it will replace its parent with a new ListNode and re-insert the ListItemNode and any previous children. If the selection's anchor node is not an empty ListItemNode, it will add a new ListNode or merge an existing ListNode, unless the the node is a leaf node, in which case it will attempt to find a ListNode up the branch and replace it with a new ListNode, or create a new ListNode at the nearest root/shadow root.

registerCheckList()​

registerCheckList(editor): () => void

Defined in: packages/lexical-list/src/checkList.ts:41

Parameters​

editor​

LexicalEditor

Returns​

(): void

Returns​

void

registerList()​

registerList(editor): () => void

Defined in: packages/lexical-list/src/index.ts:76

Parameters​

editor​

LexicalEditor

Returns​

(): void

Returns​

void

registerListStrictIndentTransform()​

registerListStrictIndentTransform(editor): () => void

Defined in: packages/lexical-list/src/index.ts:170

Parameters​

editor​

LexicalEditor

Returns​

(): void

Returns​

void

removeList()​

removeList(editor): void

Defined in: packages/lexical-list/src/index.ts:278

Parameters​

editor​

LexicalEditor

The lexical editor.

Returns​

void

Deprecated​

use $removeList from an update or command listener.

Searches for the nearest ancestral ListNode and removes it. If selection is an empty ListItemNode it will remove the whole list, including the ListItemNode. For each ListItemNode in the ListNode, removeList will also generate new ParagraphNodes in the removed ListNode's place. Any child node inside a ListItemNode will be appended to the new ParagraphNodes.