0
# DOM Manipulation
1

2
CSS class manipulation and HTML element utilities for managing editor presentation and styling. These functions provide safe, type-aware methods for managing CSS classes on HTML elements with automatic filtering of invalid values.
3

4
## Capabilities
5

6
### Add CSS Classes
7

8
Adds CSS class names to HTML elements, ignoring any non-string types and automatically handling space-separated multiple classes.
9

10
```typescript { .api }
11
/**
12
 * Takes an HTML element and adds the classNames passed within an array,
13
 * ignoring any non-string types. A space can be used to add multiple classes
14
 * e.g. addClassNamesToElement(element, ['element-inner active', true, null])
15
 * will add both 'element-inner' and 'active' as classes to that element.
16
 * @param element - The element in which the classes are added
17
 * @param classNames - An array defining the class names to add to the element
18
 */
19
function addClassNamesToElement(
20
  element: HTMLElement,
21
  ...classNames: Array<typeof undefined | boolean | null | string>
22
): void;
23
```
24

25
**Usage Examples:**
26

27
```typescript
28
import { addClassNamesToElement } from "@lexical/utils";
29

30
const divElement = document.createElement('div');
31

32
// Add single class
33
addClassNamesToElement(divElement, 'editor-content');
34

35
// Add multiple classes
36
addClassNamesToElement(divElement, 'editor-content', 'active', 'focused');
37

38
// Add space-separated classes (automatically parsed)
39
addClassNamesToElement(divElement, 'editor-content active focused');
40

41
// Mixed with invalid types (non-strings are filtered out)
42
addClassNamesToElement(divElement, 'valid-class', true, null, undefined, 'another-class');
43
// Only 'valid-class' and 'another-class' will be added
44

45
// Conditional class addition
46
const isActive = true;
47
addClassNamesToElement(divElement, 'base-class', isActive && 'active-class');
48
```
49

50
### Remove CSS Classes
51

52
Removes CSS class names from HTML elements, ignoring any non-string types and automatically handling space-separated multiple classes.
53

54
```typescript { .api }
55
/**
56
 * Takes an HTML element and removes the classNames passed within an array,
57
 * ignoring any non-string types. A space can be used to remove multiple classes
58
 * e.g. removeClassNamesFromElement(element, ['active small', true, null])
59
 * will remove both the 'active' and 'small' classes from that element.
60
 * @param element - The element in which the classes are removed
61
 * @param classNames - An array defining the class names to remove from the element
62
 */
63
function removeClassNamesFromElement(
64
  element: HTMLElement,
65
  ...classNames: Array<typeof undefined | boolean | null | string>
66
): void;
67
```
68

69
**Usage Examples:**
70

71
```typescript
72
import { removeClassNamesFromElement } from "@lexical/utils";
73

74
const divElement = document.createElement('div');
75
divElement.className = 'editor-content active focused small';
76

77
// Remove single class
78
removeClassNamesFromElement(divElement, 'active');
79

80
// Remove multiple classes
81
removeClassNamesFromElement(divElement, 'active', 'focused');
82

83
// Remove space-separated classes (automatically parsed)
84
removeClassNamesFromElement(divElement, 'active focused');
85

86
// Mixed with invalid types (non-strings are filtered out)
87
removeClassNamesFromElement(divElement, 'active', true, null, undefined, 'focused');
88
// Only 'active' and 'focused' will be removed
89

90
// Conditional class removal
91
const shouldRemoveActive = true;
92
removeClassNamesFromElement(divElement, shouldRemoveActive && 'active');
93
```
94

95
### Cross-Window Object Class Equality
96

97
Checks if an object is an instance of a specific class, working across different window contexts (useful for iframe scenarios).
98

99
```typescript { .api }
100
/**
101
 * @param object - The instance of the type
102
 * @param objectClass - The class of the type
103
 * @returns Whether the object has the same Klass of the objectClass, ignoring the difference across window (e.g. different iframes)
104
 */
105
function objectKlassEquals<T>(
106
  object: unknown,
107
  objectClass: ObjectKlass<T>
108
): object is T;
109

110
type ObjectKlass<T> = new (...args: any[]) => T;
111
```
112

113
**Usage Examples:**
114

115
```typescript
116
import { objectKlassEquals } from "@lexical/utils";
117

118
class MyCustomElement extends HTMLElement {}
119

120
// Check if element is instance of custom class across windows
121
const element = document.createElement('div');
122
const customElement = new MyCustomElement();
123

124
if (objectKlassEquals(element, HTMLDivElement)) {
125
  // Safe to use as HTMLDivElement
126
  element.innerHTML = 'Content';
127
}
128

129
if (objectKlassEquals(customElement, MyCustomElement)) {
130
  // Safe to use as MyCustomElement even across iframe boundaries
131
  customElement.customMethod();
132
}
133

134
// Works with any constructor function
135
if (objectKlassEquals(someObject, Array)) {
136
  // Safe to use array methods
137
  someObject.push(newItem);
138
}
139
```
140

141
### CSS Zoom Level Calculation
142

143
Calculates the accumulated zoom level of an element based on CSS zoom properties for browsers that require manual zoom calculations.
144

145
```typescript { .api }
146
/**
147
 * Calculates the zoom level of an element as a result of using
148
 * css zoom property. For browsers that implement standardized CSS
149
 * zoom (Firefox, Chrome >= 128), this will always return 1.
150
 * @param element - The element to calculate zoom level for
151
 * @returns The accumulated zoom level
152
 */
153
function calculateZoomLevel(element: Element | null): number;
154
```
155

156
**Usage Examples:**
157

158
```typescript
159
import { calculateZoomLevel } from "@lexical/utils";
160

161
const editorElement = document.querySelector('.editor');
162

163
// Get current zoom level
164
const zoomLevel = calculateZoomLevel(editorElement);
165

166
// Adjust measurements based on zoom
167
const rect = editorElement.getBoundingClientRect();
168
const actualWidth = rect.width / zoomLevel;
169
const actualHeight = rect.height / zoomLevel;
170

171
// Use in position calculations
172
function getAdjustedPosition(element: Element, clientX: number, clientY: number) {
173
  const zoom = calculateZoomLevel(element);
174
  return {
175
    x: clientX / zoom,
176
    y: clientY / zoom
177
  };
178
}
179
```
180

181
### CSS Pixel String Helper
182

183
Converts a numeric value to a CSS pixel string.
184

185
```typescript { .api }
186
/**
187
 * Converts number to CSS pixel string
188
 * @param value - Numeric value to convert
189
 * @returns CSS pixel string (e.g., "10px")
190
 */
191
function px(value: number): string;
192
```
193

194
**Usage Examples:**
195

196
```typescript
197
import { px } from "@lexical/utils";
198

199
const element = document.createElement('div');
200

201
// Set CSS properties with pixel values
202
element.style.width = px(200);        // "200px"
203
element.style.height = px(100);       // "100px"
204
element.style.marginTop = px(-5);     // "-5px"
205
element.style.left = px(0);           // "0px"
206

207
// Use in dynamic styling
208
function setElementSize(el: HTMLElement, width: number, height: number) {
209
  el.style.width = px(width);
210
  el.style.height = px(height);
211
}
212

213
// Use with calculations
214
const baseSize = 16;
215
const scaleFactor = 1.5;
216
element.style.fontSize = px(baseSize * scaleFactor); // "24px"
217
```