Skip to main content

Node Cloning

Understanding how to properly clone and modify nodes is crucial for working with Lexical. This guide explains the different cloning mechanisms and when to use each one.

Types of Node Cloning​

Lexical provides several ways to clone nodes, each serving a different purpose:

  1. static clone() - Internal API for state management
  2. $copyNode() - Public API for creating new nodes
  3. $deepCopy() - Public API for copying a node together with its subtree
  4. getWritable() - Public API for node modifications

The clone Method​

What is clone?​

The clone method is a static method that creates the next version of a node. A node that declares $config() has one synthesized for it and need not implement it — a hand-written clone is only required for a node that does not use $config(), or whose constructor has required arguments. Either way, it's important to understand that this is an internal API used by Lexical's state management system.

class MyCustomNode extends ElementNode {
static clone(node: MyCustomNode): MyCustomNode {
// ✅ Correct implementation
return new MyCustomNode(node.__someData, node.__key);
}
}

When is clone Used?​

  1. Internal State Management

    • Used by Lexical internally
    • Part of the editor's state update system
    • Called by getWritable()
  2. Node Mutations

    // Example of a node method implementation
    class MyCustomNode extends ElementNode {
    setData(data: string): this {
    const self = this.getWritable();
    self.__data = data;
    return self;
    }
    }

    node.setData("new data");

When NOT to Use clone?​

// ❌ Never do this
function $duplicateNode(node: MyCustomNode) {
return MyCustomNode.clone(node); // Don't call clone directly
}

The afterCloneFrom Method​

What is afterCloneFrom?​

afterCloneFrom(prevNode) runs on every clone, right after it is constructed, and copies over whatever the constructor did not. The base implementation carries the node's links to its parent and siblings and its NodeState, and ElementNode and TextNode carry their own built-in properties such as format, style, and indent. A property that is copied neither by the constructor nor by some afterCloneFrom silently reverts to its default on the node's next write.

When you don't need it​

With the modern APIs you usually don't write one at all:

  • Serialization schema. A property declared as a field in a $config json schema (withField(stringValue(), {field: '__label'})) is carried across the clone for you, because the schema says where it is stored. Available in Lexical v0.51.0 and later.
  • NodeState. State created with createState and stored with $setState is carried by the base afterCloneFrom, so a node whose extra data lives only in NodeState needs nothing.
// At module scope, above the class, so TypeScript checks it against the class
const calloutSchema = nodeSchema<CalloutNode>()({
label: withField(stringValue(), {field: '__label'}),
});

class CalloutNode extends ElementNode {
__label: string = '';

// No afterCloneFrom: `__label` is declared as a field in calloutSchema, so
// it is carried across every clone.
$config() {
return this.config('callout', {extends: ElementNode, json: calloutSchema});
}
}

When you still need it​

Override afterCloneFrom for a property that neither of those covers: a field that isn't in the node's schema, one declared only through accessor methods (see Carrying properties across a clone), or any property of a node written without a schema. Always call super.afterCloneFrom(prevNode) first so the inherited properties and NodeState are still carried:

class MyCustomNode extends ElementNode {
__data: string = '';

afterCloneFrom(prevNode: this): void {
super.afterCloneFrom(prevNode);
this.__data = prevNode.__data;
}
}

Like clone, afterCloneFrom is called by Lexical; don't call it yourself except through super.

Using $copyNode​

What is $copyNode?​

$copyNode is the public API for creating a copy of a node with a new key. Use this when you need to create a duplicate node. By default, all properties and NodeState will be copied to the new node, and then resetOnCopyNodeFrom will be called to allow the node to optionally reset certain properties (and NodeState configured with resetOnCopyNode: true) to defaults (such as the checked state of a ListItemNode).

// ✅ Correct: Using $copyNode
const copy = $copyNode(existingNode);

When to Use $copyNode?​

  1. Creating Duplicates
    // ✅ Correct: Duplicating a node
    const duplicate = $copyNode(originalNode);
    someParent.append(duplicate);

$copyNode is shallow: the copy has no children. To copy a node together with everything inside it, use $deepCopy.

Using $deepCopy​

What is $deepCopy?​

$deepCopy returns a copy of a node, its children and its named slots, recursively, all with new keys. It works by serializing the subtree to Lexical JSON and parsing it back, so the copy keeps everything a Lexical JSON paste keeps, including NodeState. Like $copyNode, the copy is detached and you insert it yourself.

Because the copy is made from JSON, only what the node's exportJSON writes is copied; anything it keeps only in memory is not.

Unlike $copyNode, the copy is not reset: resetOnCopyNodeFrom is not called, and NodeState declared with resetOnCopyNode keeps its value. A copied list item stays checked and a copied block keeps its block id, just as it would when pasted; an extension that needs unique values (such as BlockIdExtension) fixes them when the copy is inserted.

A descendant element whose excludeFromCopy('clone') returns true is left out of the copy and its children take its place, the same as when copying to the clipboard; that element's own NodeState and slots are not copied. The node you pass in, and the value of each slot, are always copied.

The RootNode cannot be copied; to copy a whole document, copy each of the root's children.

// ✅ Correct: Duplicating a block with its content
const duplicate = $deepCopy(paragraph);
paragraph.insertAfter(duplicate);

$copyNode or $deepCopy?​

  • Use $copyNode when you want the node alone, for example to wrap or replace a node and then move its existing children into the new one.
  • Use $deepCopy when you want an independent duplicate of the whole subtree, for example for a "Duplicate block" command.

Using getWritable​

What is getWritable?​

getWritable is an internal API used within node method implementations to get a mutable version of a node. Node consumers should use the node's public methods instead.

// ✅ Correct: Implementation of a node method
class MyCustomNode extends ElementNode {
setData(data: string): this {
const self = this.getWritable();
self.__data = data;
return self;
}
}

// ✅ Correct: Using the node
const node = new MyCustomNode();
node.setData("new value");

Common Patterns​

Modifying Nodes​

// ✅ Correct: Modifying a node
function $updateNodeData(node: MyCustomNode, newData: string): MyCustomNode {
return node.setData(newData);
}

// ❌ Incorrect: Don't clone manually
function $updateNodeDataWrong(node: MyCustomNode, newData: string): MyCustomNode {
const clone = MyCustomNode.clone(node);
clone.setData(newData);
return clone;
}

Copying Nodes​

// ✅ Correct: Copying a node
function $duplicateNode(node: MyCustomNode): MyCustomNode {
return $copyNode(node);
}

// ✅ Correct: Copying a node and its children
function $duplicateBlock(node: ElementNode): ElementNode {
return $deepCopy(node);
}

// ❌ Incorrect: Don't use clone
function $duplicateNodeWrong(node: MyCustomNode): MyCustomNode {
return node.constructor.clone(node);
}

Performance Considerations​

  1. Referential Integrity

    • getWritable() ensures proper EditorState updates with new clones
    • Prevents "orphaned" nodes that won't be rendered
  2. State Management

    class MyCustomNode extends ElementNode {
    setData(data: string): this {
    const self = this.getWritable();
    self.__data = data; // Properly tracked by editor
    return self;
    }
    }

Testing​

test('node modification', async () => {
await editor.update(() => {
const node = new MyCustomNode("test");

node.setData("new data");

// ✅ Correct: Use $copyNode for duplication
const copy = $copyNode(node);
});
});
  • Editor State - How cloning affects editor state
  • Nodes - Core concepts about Lexical nodes

Common Questions​

Q: How do I duplicate a node? A: Use $copyNode(node) to create a new copy with a new key.

Q: When should I use clone? A: Never directly. Use $copyNode() or getWritable() instead.