DOM API Essentials: Structure, Traversal, and Mutation

1
// This SVG circle is an Element, but NOT an HTMLElement
2
const circle = document.querySelector("circle")
3
circle.setAttribute("r", "50") // Element method works
4
circle.classList.add("active") // Element method works
5

6
// HTMLElement methods would fail on SVG elements
7
// circle.contentEditable // undefined - this is HTML-specific
8
// circle.dataset         // undefined - this is HTML-specific

1
EventTarget (base for all event-capable objects)
2
    ↓
3
Node (tree participation)
4
    ↓
5
Element (universal element operations)
6
    ├── HTMLElement (HTML-specific: contentEditable, dataset, innerText)
7
    ├── SVGElement (SVG-specific: SVG DOM properties)
8
    └── MathMLElement (MathML-specific: mathematical markup)

1
// TypeScript enforces hierarchy
2
const element: Element = document.querySelector("div")!
3
element.classList.add("active") // ✅ Element method
4
element.setAttribute("role", "tab") // ✅ Element method
5

6
// @ts-error: Property 'dataset' does not exist on type 'Element'
7
element.dataset.userId = "123" // ❌ HTMLElement-specific
8

9
// Type narrowing required
10
if (element instanceof HTMLElement) {
11
  element.dataset.userId = "123" // ✅ Now TypeScript knows it's HTMLElement
12
  element.contentEditable = "true" // ✅ HTML-specific property
13
}
14

15
// SVG elements demonstrate the distinction
16
const svg = document.querySelector("svg")!
17
svg.classList.add("icon") // ✅ Element method works
18
svg.setAttribute("viewBox", "0 0 100 100") // ✅ Element method works
19
// svg.innerText = 'text';           // ❌ Would fail - innerText is HTMLElement-specific

1
const container = document.getElementById("list")
2
const items = container.getElementsByClassName("item")
3

4
console.log(items.length) // 3
5

6
// Add a new element with class 'item'
7
const newItem = document.createElement("div")
8
newItem.className = "item"
9
container.appendChild(newItem)
10

11
console.log(items.length) // 4 - automatically updated!

1
// ⚠️ Infinite loop: collection updates as you modify the DOM
2
const items = document.getElementsByClassName("item")
3
for (let i = 0; i < items.length; i++) {
4
  items[i].classList.remove("item") // Removes element from collection
5
  // Now items.length decreased, but i increased
6
  // You'll only process every other element
7
}
8

9
// ✅ Convert to array to capture snapshot
10
const itemsArray = Array.from(document.getElementsByClassName("item"))
11
for (const item of itemsArray) {
12
  item.classList.remove("item") // Safe: iterating over static array
13
}

1
const items = document.getElementsByClassName("item")
2

3
// ❌ TypeError: items.forEach is not a function
4
items.forEach((item) => console.log(item))
5

6
// ✅ Convert to array first
7
Array.from(items).forEach((item) => console.log(item))
8

9
// ✅ Or use spread operator
10
;[...items].forEach((item) => console.log(item))
11

12
// ✅ Traditional for loop works
13
for (let i = 0; i < items.length; i++) {
14
  console.log(items[i])
15
}
16

17
// ✅ for...of works (HTMLCollection is iterable)
18
for (const item of items) {
19
  console.log(item)
20
}

1
const items = document.querySelectorAll(".item")
2
console.log(items.length) // 3
3

4
const newItem = document.createElement("div")
5
newItem.className = "item"
6
document.body.appendChild(newItem)
7

8
console.log(items.length) // Still 3 - NodeList doesn't update
9

10
// Must re-query to see new elements
11
const updatedItems = document.querySelectorAll(".item")
12
console.log(updatedItems.length) // 4

1
const items = document.querySelectorAll(".item")
2

3
// ✅ NodeList has native forEach
4
items.forEach((item, index) => {
5
  item.dataset.index = String(index)
6
})
7

8
// ✅ Also supports for...of
9
for (const item of items) {
10
  console.log(item)
11
}
12

13
// ⚠️ But still not a real Array
14
items.map((item) => item.textContent) // ❌ TypeError: items.map is not a function
15

16
// ✅ Convert for full array methods
17
const texts = Array.from(items).map((item) => item.textContent)

1
const parent = document.getElementById("container")
2
const children = parent.childNodes // Live NodeList
3

4
console.log(children.length) // Includes text nodes, comments, elements
5

6
parent.appendChild(document.createElement("div"))
7
console.log(children.length) // Automatically increased
8

9
// getElementsByName() also returns live NodeList (unusual exception)
10
const namedElements = document.getElementsByName("email")
11
// This NodeList updates when matching elements are added/removed

1
// ✅ Use querySelectorAll for one-time processing
2
function highlightAllWarnings() {
3
  const warnings = document.querySelectorAll(".warning")
4
  warnings.forEach((warning) => {
5
    warning.style.backgroundColor = "yellow"
6
  })
7
}
8

9
// ✅ Use getElementsByClassName when DOM changes frequently
10
function setupLiveCounter() {
11
  const items = document.getElementsByClassName("cart-item")
12

13
  function updateCount() {
14
    document.getElementById("count").textContent = String(items.length)
15
  }
16

17
  // Collection automatically reflects added/removed items
18
  document.addEventListener("DOMContentLoaded", updateCount)
19
  document.addEventListener("cartUpdate", updateCount)
20
}
21

22
// ✅ Convert live to static when iterating and modifying
23
function removeAllItems() {
24
  const items = document.getElementsByClassName("item")
25
  Array.from(items).forEach((item) => item.remove())
26
}
27

28
// ✅ Cache length for performance in loops
29
function processItems() {
30
  const items = document.querySelectorAll(".item")
31
  const length = items.length // Cache length
32

33
  for (let i = 0; i < length; i++) {
34
    // Process items[i]
35
  }
36
}

1
// 1. Create observer with callback
2
const observer = new ObserverType((entries, observer) => {
3
  entries.forEach((entry) => {
4
    // Handle changes
5
  })
6
})
7

8
// 2. Start observing targets
9
observer.observe(targetElement, options)
10

11
// 3. Stop observing specific target
12
observer.unobserve(targetElement)
13

14
// 4. Stop observing all targets
15
observer.disconnect()
16

17
// 5. Get pending notifications (some observers)
18
const records = observer.takeRecords()

1
const observer = new IntersectionObserver(
2
  (entries) => {
3
    entries.forEach((entry) => {
4
      // entry.target - the observed element
5
      // entry.isIntersecting - whether target intersects root
6
      // entry.intersectionRatio - percentage of target visible (0.0 to 1.0)
7
      // entry.intersectionRect - visible portion dimensions
8
      // entry.boundingClientRect - target's full bounding box
9
      // entry.rootBounds - root element's bounding box
10
      // entry.time - timestamp when intersection changed
11
    })
12
  },
13
  {
14
    root: null, // viewport (null) or ancestor Element
15
    rootMargin: "0px", // margin around root
16
    threshold: [0, 0.5, 1.0], // trigger at 0%, 50%, 100% visibility
17
  },
18
)
19

20
observer.observe(document.querySelector("#target"))

1
// Fire when 50% of element is visible
2
const observer = new IntersectionObserver(callback, { threshold: 0.5 })
3

4
// Common threshold values:
5
// 0    - Fire immediately when any part enters (default)
6
// 0.5  - Fire when half visible
7
// 1.0  - Fire only when fully visible

1
// Track visibility at multiple stages
2
const observer = new IntersectionObserver(
3
  (entries) => {
4
    entries.forEach((entry) => {
5
      // Callback fires at each threshold crossing
6
      console.log(`Visibility: ${Math.round(entry.intersectionRatio * 100)}%`)
7

8
      if (entry.intersectionRatio >= 0.75) {
9
        // Element is mostly visible - count as "viewed"
10
        trackImpression(entry.target)
11
      }
12
    })
13
  },
14
  { threshold: [0, 0.25, 0.5, 0.75, 1.0] },
15
)

1
// Single value: applies to all sides
2
rootMargin: "50px" // Expand all sides by 50px
3

4
// Two values: vertical | horizontal
5
rootMargin: "50px 0px" // Expand top/bottom by 50px
6

7
// Four values: top | right | bottom | left
8
rootMargin: "100px 0px 50px 0px" // Expand top 100px, bottom 50px

1
// Positive: EXPAND detection zone (trigger BEFORE element is visible)
2
const preloadObserver = new IntersectionObserver(callback, {
3
  rootMargin: "200px", // Start loading 200px before entering viewport
4
})
5

6
// Negative: SHRINK detection zone (trigger AFTER element is well inside)
7
const deepVisibilityObserver = new IntersectionObserver(callback, {
8
  rootMargin: "-100px", // Only trigger when 100px inside viewport
9
})

1
// Preload content before it scrolls into view
2
const lazyLoader = new IntersectionObserver(loadContent, {
3
  rootMargin: "300px 0px", // 300px buffer above and below viewport
4
})
5

6
// Sticky header detection - trigger when element is near top
7
const stickyObserver = new IntersectionObserver(updateSticky, {
8
  rootMargin: "-80px 0px 0px 0px", // 80px from top edge (header height)
9
})
10

11
// Analytics: only count as "viewed" if visible for meaningful time
12
const impressionObserver = new IntersectionObserver(trackView, {
13
  rootMargin: "-50px", // Must be 50px inside viewport
14
  threshold: 0.5, // AND 50% visible
15
})

1
const imageObserver = new IntersectionObserver(
2
  (entries, observer) => {
3
    entries.forEach((entry) => {
4
      if (entry.isIntersecting) {
5
        const img = entry.target as HTMLImageElement
6

7
        // Load image when it enters viewport
8
        img.src = img.dataset.src!
9
        img.onload = () => img.classList.add("loaded")
10

11
        // Stop observing this image
12
        observer.unobserve(img)
13
      }
14
    })
15
  },
16
  {
17
    // Start loading slightly before image enters viewport
18
    rootMargin: "50px",
19
  },
20
)
21

22
// Observe all images with data-src attribute
23
document.querySelectorAll("img[data-src]").forEach((img) => {
24
  imageObserver.observe(img)
25
})

6 collapsed lines
1
function setupInfiniteScroll(loadMoreFn: () => Promise<void>) {
2
  // Sentinel setup (collapsed)
3
  const sentinel = document.createElement("div")
4
  sentinel.id = "scroll-sentinel"
5
  sentinel.style.height = "1px"
6
  document.querySelector("#content-container")!.appendChild(sentinel)
7

8
  let isLoading = false
9

10
  // Key pattern: IntersectionObserver triggers load before reaching end
11
  const observer = new IntersectionObserver(
12
    async (entries) => {
13
      const entry = entries[0]
14

15
      if (entry.isIntersecting && !isLoading) {
16
        isLoading = true
17

18
        try {
19
          await loadMoreFn()
20
        } finally {
21
          isLoading = false
22
        }
23
      }
24
    },
25
    {
26
      rootMargin: "200px", // Trigger 200px before reaching sentinel
27
    },
28
  )
29

30
  observer.observe(sentinel)
31

7 collapsed lines
32
  return () => observer.disconnect()
33
}
34

35
// Usage (collapsed)
36
const cleanup = setupInfiniteScroll(async () => {
37
  const newItems = await fetchNextPage()
38
  renderItems(newItems)
39
})

1
const animationObserver = new IntersectionObserver(
2
  (entries) => {
3
    entries.forEach((entry) => {
4
      if (entry.isIntersecting) {
5
        entry.target.classList.add("animate-in")
6
      } else {
7
        // Optional: reset animation when scrolling back up
8
        entry.target.classList.remove("animate-in")
9
      }
10
    })
11
  },
12
  {
13
    threshold: 0.1, // Trigger when 10% visible
14
  },
15
)
16

17
// Observe all elements with animation class
18
document.querySelectorAll(".animate-on-scroll").forEach((element) => {
19
  animationObserver.observe(element)
20
})

1
// When observing cross-origin iframe content:
2
const observer = new IntersectionObserver((entries) => {
3
  entries.forEach((entry) => {
4
    // For cross-origin targets:
5
    // - rootBounds is null (suppressed to prevent viewport probing)
6
    // - rootMargin effects are ignored
7
    // - scrollMargin effects are ignored
8

9
    if (entry.rootBounds === null) {
10
      // Cross-origin target - limited information available
11
      console.log("Cross-origin: rootBounds suppressed for privacy")
12
    }
13
  })
14
})

1
const observer = new MutationObserver((mutations, observer) => {
2
  mutations.forEach((mutation) => {
3
    // mutation.type - 'childList', 'attributes', or 'characterData'
4
    // mutation.target - the node that changed
5
    // mutation.addedNodes - NodeList of added children
6
    // mutation.removedNodes - NodeList of removed children
7
    // mutation.attributeName - changed attribute name
8
    // mutation.oldValue - previous value (if requested in options)
9
  })
10
})
11

12
observer.observe(targetNode, {
13
  // At least one of these must be true:
14
  childList: true, // Watch child node additions/removals
15
  attributes: true, // Watch attribute changes
16
  characterData: true, // Watch text content changes
17

18
  // Optional refinements:
19
  subtree: true, // Monitor all descendants too
20
  attributeOldValue: true, // Include previous attribute values
21
  characterDataOldValue: true, // Include previous text values
22
  attributeFilter: ["class", "data-state"], // Only specified attributes
23
})

1
function watchDynamicContent(container: Element, callback: (addedElements: Element[]) => void) {
2
  const observer = new MutationObserver((mutations) => {
3
    const addedElements: Element[] = []
4

5
    // Key pattern: filter for element nodes from childList mutations
6
    mutations.forEach((mutation) => {
7
      if (mutation.type === "childList") {
8
        mutation.addedNodes.forEach((node) => {
9
          if (node.nodeType === Node.ELEMENT_NODE) {
10
            addedElements.push(node as Element)
11
          }
12
        })
13
      }
14
    })
15

16
    if (addedElements.length > 0) {
17
      callback(addedElements)
18
    }
19
  })
20

21
  observer.observe(container, {
22
    childList: true,
23
    subtree: true, // Watch all descendants
24
  })
25

26
  return () => observer.disconnect()
27
}
9 collapsed lines
28

29
// Usage example (collapsed)
30
const cleanup = watchDynamicContent(document.body, (elements) => {
31
  elements.forEach((el) => {
32
    if (el.hasAttribute("data-tooltip")) {
33
      initializeTooltip(el)
34
    }
35
  })
36
})

1
function trackFormFieldState(form: HTMLFormElement) {
2
  const observer = new MutationObserver((mutations) => {
3
    mutations.forEach((mutation) => {
4
      // Key pattern: watch aria-invalid attribute for validation state changes
5
      if (mutation.type === "attributes" && mutation.attributeName === "aria-invalid") {
6
        const field = mutation.target as HTMLElement
10 collapsed lines
7
        // Error message visibility logic (collapsed)
8
        const isInvalid = field.getAttribute("aria-invalid") === "true"
9
        const errorId = field.getAttribute("aria-describedby")
10
        if (errorId) {
11
          const errorElement = document.getElementById(errorId)
12
          if (errorElement) {
13
            errorElement.hidden = !isInvalid
14
          }
15
        }
16
      }
17
    })
18
  })
19

20
  // Watch all form fields with attributeFilter for efficiency
21
  form.querySelectorAll("input, textarea, select").forEach((field) => {
22
    observer.observe(field, {
23
      attributes: true,
24
      attributeFilter: ["aria-invalid"], // Only watch this attribute
25
      attributeOldValue: true,
26
    })
27
  })
28

29
  return () => observer.disconnect()
30
}

1
function watchTextChanges(editableElement: HTMLElement) {
2
  const observer = new MutationObserver((mutations) => {
3
    mutations.forEach((mutation) => {
4
      if (mutation.type === "characterData") {
5
        console.log("Text changed from:", mutation.oldValue)
6
        console.log("Text changed to:", mutation.target.textContent)
7

8
        // Update character count, word count, etc.
9
        updateTextStats(editableElement)
10
      }
11
    })
12
  })
13

14
  observer.observe(editableElement, {
15
    characterData: true,
16
    subtree: true, // Watch text nodes in all descendants
17
    characterDataOldValue: true,
18
  })
19

20
  return () => observer.disconnect()
21
}

1
const target = document.getElementById("container")!
2
const observer = new MutationObserver((mutations) => {
3
  // This callback receives ALL mutations in a single batch
4
  console.log(`Received ${mutations.length} mutations`)
5
})
6

7
observer.observe(target, { childList: true })
8

9
// These three operations generate three mutation records,
10
// but callback is invoked once with all three
11
target.appendChild(document.createElement("div"))
12
target.appendChild(document.createElement("span"))
13
target.appendChild(document.createElement("p"))
14

15
// Callback invoked asynchronously with 3 mutation records

1
const observer = new ResizeObserver((entries) => {
2
  entries.forEach((entry) => {
3
    // entry.target - the observed element
4
    // entry.contentRect - DOMRect with dimensions (legacy)
5
    // entry.contentBoxSize - ReadonlyArray of ResizeObserverSize
6
    // entry.borderBoxSize - ReadonlyArray of ResizeObserverSize
7
    // entry.devicePixelContentBoxSize - Device pixel dimensions
8
  })
9
})
10

11
observer.observe(element, {
12
  box: "content-box", // 'content-box', 'border-box', or 'device-pixel-content-box'
13
})

1
interface ResizeObserverEntry {
2
  target: Element
3
  contentRect: DOMRectReadOnly // Legacy property
4
  contentBoxSize: ReadonlyArray<ResizeObserverSize>
5
  borderBoxSize: ReadonlyArray<ResizeObserverSize>
6
  devicePixelContentBoxSize: ReadonlyArray<ResizeObserverSize>
7
}
8

9
interface ResizeObserverSize {
10
  inlineSize: number // Width in horizontal writing mode
11
  blockSize: number // Height in horizontal writing mode
12
}

1
function setupResponsiveText(container: HTMLElement) {
2
  const heading = container.querySelector("h1")!
3
  const paragraph = container.querySelector("p")!
4

5
  const observer = new ResizeObserver((entries) => {
6
    entries.forEach((entry) => {
7
      // Key pattern: use contentBoxSize for modern width detection
8
      if (entry.contentBoxSize) {
9
        const contentBoxSize = Array.isArray(entry.contentBoxSize) ? entry.contentBoxSize[0] : entry.contentBoxSize
10

11
        const width = contentBoxSize.inlineSize
12

13
        // Scale font size based on container width
14
        heading.style.fontSize = `${Math.max(1.5, width / 200)}rem`
15
        paragraph.style.fontSize = `${Math.max(1, width / 600)}rem`
16
      } else {
17
        // Fallback for older browsers (collapsed)
18
        const width = entry.contentRect.width
7 collapsed lines
19
        heading.style.fontSize = `${Math.max(1.5, width / 200)}rem`
20
        paragraph.style.fontSize = `${Math.max(1, width / 600)}rem`
21
      }
22
    })
23
  })
24

25
  observer.observe(container)
26
  return () => observer.disconnect()
27
}

1
function setupAdaptiveGrid(grid: HTMLElement) {
2
  const observer = new ResizeObserver((entries) => {
3
    entries.forEach((entry) => {
4
      const width = entry.contentBoxSize?.[0]?.inlineSize ?? entry.contentRect.width
5

6
      // Adjust grid columns based on available width
7
      let columns: number
8
      if (width < 400) columns = 1
9
      else if (width < 800) columns = 2
10
      else if (width < 1200) columns = 3
11
      else columns = 4
12

13
      grid.style.gridTemplateColumns = `repeat(${columns}, 1fr)`
14
      grid.dataset.columns = String(columns)
15
    })
16
  })
17

18
  observer.observe(grid)
19
  return () => observer.disconnect()
20
}

1
function setupAutoResize(textarea: HTMLTextAreaElement) {
2
  const observer = new ResizeObserver((entries) => {
3
    // Prevent infinite loops by checking if size actually changed
4
    entries.forEach((entry) => {
5
      const target = entry.target as HTMLTextAreaElement
6

7
      // Reset height to measure scrollHeight
8
      target.style.height = "auto"
9

10
      // Set height to content height
11
      const newHeight = target.scrollHeight + 2 // +2 for border
12
      target.style.height = `${newHeight}px`
13
    })
14
  })
15

16
  // Observe the textarea
17
  observer.observe(textarea)
18

19
  // Also trigger on input
20
  textarea.addEventListener("input", () => {
21
    textarea.style.height = "auto"
22
    textarea.style.height = `${textarea.scrollHeight + 2}px`
23
  })
24

25
  return () => observer.disconnect()
26
}

1
// ❌ Infinite loop: callback increases size, triggering more callbacks
2
const observer = new ResizeObserver((entries) => {
3
  entries.forEach((entry) => {
4
    const target = entry.target as HTMLElement
5
    // Each resize triggers another observation
6
    target.style.width = `${entry.contentRect.width + 10}px`
7
  })
8
})
9

10
observer.observe(element)
11
// Error: ResizeObserver loop completed with undelivered notifications

1
// ✅ Solution 1: Use requestAnimationFrame to defer changes
2
const observer = new ResizeObserver((entries) => {
3
  requestAnimationFrame(() => {
4
    entries.forEach((entry) => {
5
      const target = entry.target as HTMLElement
6
      target.style.width = `${entry.contentRect.width + 10}px`
7
    })
8
  })
9
})
10

11
// ✅ Solution 2: Track expected size to avoid redundant updates
12
const expectedSizes = new WeakMap<Element, number>()
13

14
const observer = new ResizeObserver((entries) => {
15
  entries.forEach((entry) => {
16
    const expectedSize = expectedSizes.get(entry.target)
17
    const currentSize = entry.contentBoxSize?.[0]?.inlineSize ?? entry.contentRect.width
18

19
    // Only update if not at expected size
20
    if (currentSize !== expectedSize) {
21
      const newSize = currentSize + 10
22
      ;(entry.target as HTMLElement).style.width = `${newSize}px`
23
      expectedSizes.set(entry.target, newSize)
24
    }
25
  })
26
})

1
// ❌ Expensive: scroll handler runs on every scroll event
2
window.addEventListener("scroll", () => {
3
  document.querySelectorAll(".lazy-image").forEach((img) => {
4
    const rect = img.getBoundingClientRect()
5
    if (rect.top < window.innerHeight) {
6
      loadImage(img)
7
    }
8
  })
9
})
10

11
// ✅ Efficient: IntersectionObserver uses browser internals
12
const observer = new IntersectionObserver((entries) => {
13
  entries.forEach((entry) => {
14
    if (entry.isIntersecting) {
15
      loadImage(entry.target)
16
      observer.unobserve(entry.target)
17
    }
18
  })
19
})
20

21
document.querySelectorAll(".lazy-image").forEach((img) => {
22
  observer.observe(img)
23
})

1
// Demonstrate batching behavior
2
const element = document.getElementById("container")!
3
const observer = new ResizeObserver((entries) => {
4
  console.log(`Callback invoked with ${entries.length} entries`)
5
  console.log("All size changes processed in one batch")
6
})
7

8
observer.observe(element)
9

10
// Rapidly change size multiple times
11
element.style.width = "100px"
12
element.style.width = "200px"
13
element.style.width = "300px"
14

15
// Output (single callback invocation):
16
// "Callback invoked with 1 entries"
17
// "All size changes processed in one batch"