Skip to content

Commit b76e257

Browse files
committed
fix: improve accuracy of reflow claims and update broken link in DOM concept page
1 parent f78c9ea commit b76e257

1 file changed

Lines changed: 17 additions & 9 deletions

File tree

docs/concepts/dom.mdx

Lines changed: 17 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -729,32 +729,36 @@ clone.id = 'new-unique-id'
729729
When adding many elements, using a **[`DocumentFragment`](https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment)** is more efficient:
730730

731731
```javascript
732-
// Bad: Multiple reflows
732+
// Bad: Multiple DOM updates (potentially multiple reflows)
733733
const ul = document.querySelector('ul')
734734
for (let i = 0; i < 1000; i++) {
735735
const li = document.createElement('li')
736736
li.textContent = `Item ${i}`
737-
ul.appendChild(li) // Triggers reflow each time!
737+
ul.appendChild(li) // Modifies live DOM each iteration
738738
}
739739

740-
// Good: Single reflow
740+
// Good: Single DOM update
741741
const ul = document.querySelector('ul')
742742
const fragment = document.createDocumentFragment()
743743

744744
for (let i = 0; i < 1000; i++) {
745745
const li = document.createElement('li')
746746
li.textContent = `Item ${i}`
747-
fragment.appendChild(li) // No reflow (fragment is detached)
747+
fragment.appendChild(li) // No DOM update (fragment is detached)
748748
}
749749

750-
ul.appendChild(fragment) // Single reflow!
750+
ul.appendChild(fragment) // Single DOM update!
751751
```
752752

753753
A `DocumentFragment` is a lightweight container that:
754754
- Is not part of the DOM tree
755755
- Has no parent
756756
- When appended, only its **children** are inserted (the fragment itself disappears)
757757

758+
<Note>
759+
**Modern browser optimization:** Browsers may batch consecutive DOM modifications and perform a single reflow. However, using DocumentFragment is still the recommended pattern because it's explicit, works consistently across all browsers, and avoids any risk of forced synchronous layouts if you read layout properties between writes.
760+
</Note>
761+
758762
---
759763

760764
## Modifying Content
@@ -1220,15 +1224,15 @@ result.textContent = text
12201224
### Batch DOM Updates
12211225

12221226
```javascript
1223-
// Bad: 3 separate reflows
1227+
// Avoid: Multiple style changes (may trigger multiple reflows)
12241228
element.style.width = '100px'
12251229
element.style.height = '200px'
12261230
element.style.margin = '10px'
12271231

1228-
// Good: Single reflow with cssText
1232+
// Better: Single style assignment with cssText
12291233
element.style.cssText = 'width: 100px; height: 200px; margin: 10px;'
12301234

1231-
// Good: Single reflow with class
1235+
// Best: Use a CSS class (cleanest and most maintainable)
12321236
element.classList.add('my-styles')
12331237

12341238
// Good: DocumentFragment for multiple elements
@@ -1241,6 +1245,10 @@ items.forEach(item => {
12411245
ul.appendChild(fragment) // Single DOM update
12421246
```
12431247

1248+
<Tip>
1249+
**Why batch?** While modern browsers often optimize consecutive style changes into a single reflow, this optimization breaks if you read a layout property (like `offsetWidth`) between writes. Batching explicitly avoids this risk and makes your intent clear.
1250+
</Tip>
1251+
12441252
### Avoid Layout Thrashing
12451253

12461254
**Layout thrashing** occurs when you alternate between reading and writing DOM properties:
@@ -2108,7 +2116,7 @@ input.value // "hello"
21082116
<Card title="How to traverse the DOM in JavaScript" icon="newspaper" href="https://medium.com/javascript-in-plain-english/how-to-traverse-the-dom-in-javascript-d6555c335b4e">
21092117
Covers every traversal method with console output screenshots. Useful reference when you forget which property to use for siblings vs children.
21102118
</Card>
2111-
<Card title="Render Tree Construction" icon="newspaper" href="https://developers.google.com/web/fundamentals/performance/critical-rendering-path/render-tree-construction">
2119+
<Card title="Render Tree Construction" icon="newspaper" href="https://web.dev/articles/critical-rendering-path/render-tree-construction">
21122120
Google's official explanation of the Critical Rendering Path. Essential reading if you want to understand why some DOM operations are slow.
21132121
</Card>
21142122
<Card title="What, exactly, is the DOM?" icon="newspaper" href="https://bitsofco.de/what-exactly-is-the-dom/">

0 commit comments

Comments
 (0)