or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

dom-manipulation.mdeditor-state.mdfile-handling.mdindex.mdspecialized-utilities.mdtree-traversal.md
tile.json

tessl/npm-lexical--utils

This package provides essential utility functions for the Lexical rich text editor framework, offering a comprehensive set of DOM manipulation helpers, tree traversal algorithms, and editor state management tools.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@lexical/utils@0.34.x

To install, run

npx @tessl/cli install tessl/npm-lexical--utils@0.34.0

index.mddocs/

Lexical Utils

Lexical Utils is a comprehensive TypeScript utility library providing essential functions for the Lexical rich text editor framework. It offers DOM manipulation helpers, tree traversal algorithms, file handling utilities, and editor state management tools designed to support complex editor operations while maintaining high performance and cross-browser compatibility.

Package Information

  • Package Name: @lexical/utils
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @lexical/utils
  • Dependencies: Requires lexical (core package) for types and base functionality

Core Imports

import {
  addClassNamesToElement,
  removeClassNamesFromElement,
  $dfs,
  $insertNodeToNearestRoot,
  mergeRegister,
  markSelection
} from "@lexical/utils";

For CommonJS:

const {
  addClassNamesToElement,
  removeClassNamesFromElement,
  $dfs,
  $insertNodeToNearestRoot,
  mergeRegister,
  markSelection
} = require("@lexical/utils");

Basic Usage

import {
  addClassNamesToElement,
  $dfs,
  $insertNodeToNearestRoot,
  $createParagraphNode,
  mergeRegister
} from "@lexical/utils";
import { $getRoot } from "lexical";

// DOM manipulation
const element = document.createElement('div');
addClassNamesToElement(element, 'editor-content', 'active');

// Tree traversal  
const nodes = $dfs($getRoot());
nodes.forEach(({ node, depth }) => {
  console.log(`Node at depth ${depth}:`, node);
});

// Node insertion
const paragraph = $createParagraphNode();
$insertNodeToNearestRoot(paragraph);

// Register cleanup functions
const cleanup = mergeRegister(
  editor.registerCommand(...),
  editor.registerUpdateListener(...),
  editor.registerNodeTransform(...)
);

Architecture

Lexical Utils is organized around several key functional areas:

  • DOM Manipulation: CSS class management and HTML element utilities
  • Tree Traversal: Depth-first search algorithms and node navigation functions
  • File Handling: MIME type validation and asynchronous file reading with batching
  • Editor State Management: State restoration, nested element resolution, and editor utilities
  • Specialized Utilities: Focused modules for selection marking, node positioning, and function merging
  • Environment Detection: Cross-platform browser and environment constants

Capabilities

DOM Manipulation

CSS class manipulation and HTML element utilities for managing editor presentation and styling.

function addClassNamesToElement(
  element: HTMLElement,
  ...classNames: Array<undefined | boolean | null | string>
): void;

function removeClassNamesFromElement(
  element: HTMLElement,
  ...classNames: Array<undefined | boolean | null | string>
): void;

DOM Manipulation

Tree Traversal

Comprehensive tree traversal algorithms and node navigation utilities for exploring the Lexical node tree structure.

function $dfs(
  startNode?: LexicalNode,
  endNode?: LexicalNode
): Array<DFSNode>;

function $dfsIterator(
  startNode?: LexicalNode,
  endNode?: LexicalNode
): IterableIterator<DFSNode>;

interface DFSNode {
  readonly depth: number;
  readonly node: LexicalNode;
}

Tree Traversal

File Handling

MIME type validation and asynchronous file reading utilities with support for batching and order preservation.

function isMimeType(
  file: File,
  acceptableMimeTypes: Array<string>
): boolean;

function mediaFileReader(
  files: Array<File>,
  acceptableMimeTypes: Array<string>
): Promise<Array<{file: File; result: string}>>;

File Handling

Editor State Management

Advanced editor state manipulation, node insertion, and state restoration utilities for complex editor operations.

function $insertNodeToNearestRoot<T extends LexicalNode>(node: T): T;

function $restoreEditorState(
  editor: LexicalEditor,
  editorState: EditorState
): void;

function registerNestedElementResolver<N extends ElementNode>(
  editor: LexicalEditor,
  targetNode: Klass<N>,
  cloneNode: (from: N) => N,
  handleOverlap: (from: N, to: N) => void
): () => void;

Editor State Management

Specialized Utilities

Focused utility modules providing selection marking, DOM node positioning, function merging, and CSS utilities.

function mergeRegister(...func: Array<() => void>): () => void;

function markSelection(
  editor: LexicalEditor,
  onReposition?: (node: Array<HTMLElement>) => void
): () => void;

function positionNodeOnRange(
  editor: LexicalEditor,
  range: Range,
  onReposition: (node: Array<HTMLElement>) => void
): () => void;

Specialized Utilities

Environment Constants

Cross-platform browser and environment detection constants for conditional functionality.

const CAN_USE_BEFORE_INPUT: boolean;
const CAN_USE_DOM: boolean;
const IS_ANDROID: boolean;
const IS_ANDROID_CHROME: boolean;
const IS_APPLE: boolean;
const IS_APPLE_WEBKIT: boolean;
const IS_CHROME: boolean;
const IS_FIREFOX: boolean;
const IS_IOS: boolean;
const IS_SAFARI: boolean;

Core Types

Package-Specific Types

interface DFSNode {
  readonly depth: number;
  readonly node: LexicalNode;
}

interface StateConfigWrapper<K extends string, V> {
  readonly stateConfig: StateConfig<K, V>;
  readonly $get: <T extends LexicalNode>(node: T) => V;
  readonly $set: <T extends LexicalNode>(
    node: T,
    valueOrUpdater: ValueOrUpdater<V>
  ) => T;
  readonly accessors: readonly [$get: this['$get'], $set: this['$set']];
  makeGetterMethod<T extends LexicalNode>(): (this: T) => V;
  makeSetterMethod<T extends LexicalNode>(): (
    this: T,
    valueOrUpdater: ValueOrUpdater<V>
  ) => T;
}

type DOMNodeToLexicalConversion = (element: Node) => LexicalNode;
type DOMNodeToLexicalConversionMap = Record<string, DOMNodeToLexicalConversion>;
type ObjectKlass<T> = new (...args: any[]) => T;

Re-exported Functions from Lexical Core

The following utility functions are re-exported from the core lexical package for convenience:

/**
 * Splits a node at the current selection point
 */
function $splitNode(node: ElementNode): ElementNode;

/**
 * Checks if a DOM node is a block-level element
 */
function isBlockDomNode(node: Node): boolean;

/**
 * Type guard to check if element is an HTML anchor element
 */
function isHTMLAnchorElement(x: Node | EventTarget | null): x is HTMLAnchorElement;

/**
 * Type guard to check if element is an HTML element
 */
function isHTMLElement(x: Node | EventTarget | null): x is HTMLElement;

/**
 * Checks if a DOM node is an inline element
 */
function isInlineDomNode(node: Node): boolean;

External Types from lexical Core

The following types are imported from the core lexical package and used throughout the API:

  • LexicalNode: Base class for all nodes in the editor tree
  • ElementNode: Base class for container nodes that can have children
  • LexicalEditor: The main editor instance
  • EditorState: Immutable state snapshot of the editor
  • CaretDirection: 'next' | 'previous' for tree traversal direction
  • NodeCaret, SiblingCaret, PointCaret: Caret positioning types for precise node navigation
  • Klass: Constructor type new (...args: any[]) => T
  • ValueOrUpdater: V | ((prev: V) => V) for state updates
  • StateConfig: Configuration for custom node state management