scrollIntoView Is Not a Function: Fix NodeList, null, and Framework Refs

Fix querySelectorAll() returning a NodeList#

querySelectorAll() always returns a static NodeList, even when only one element matches. A NodeList does not have the element method directly:

1
const headings = document.querySelectorAll('h2');
2

3
// Wrong: the receiver is a NodeList.
4
headings.scrollIntoView();

Choose one element before scrolling:

1
const headings = document.querySelectorAll('h2');
2
const firstHeading = headings.item(0);
3

4
firstHeading?.scrollIntoView({
5
  behavior: 'smooth',
6
  block: 'center',
7
});

Or use querySelector() when the selector should target one element:

1
document.querySelector('h2')?.scrollIntoView({ block: 'center' });

If the intention is to scroll every matching element, iterate over the list explicitly. Usually that produces a series of scroll operations and the last element wins, so confirm that this is really the interaction you want:

1
for (const heading of document.querySelectorAll('h2')) {
2
  heading.scrollIntoView({ behavior: 'smooth' });
3
}

Handle querySelector() returning null#

querySelector() returns null when there is no matching element. The resulting error is often Cannot read properties of null, but the fix is the same: check the selector, timing, and value before calling the method.

1
function scrollToSection(id) {
2
  const section = document.getElementById(id);
3

4
  if (!section) {
5
    console.warn(`Section not found: ${id}`);
6
    return;
7
  }
8

9
  section.scrollIntoView({ behavior: 'smooth', block: 'start' });
10
}

Common causes of a null result include a typo in the ID, a selector that runs before the component renders, and a route that is expected to contain a section but does not. Put the call after the DOM update that creates the target; do not paper over a missing element with a timeout unless the timeout is part of a documented rendering boundary.

Unwrap a framework ref before calling the API#

Framework refs are containers around a DOM node, not DOM nodes themselves. Use the framework’s element property and keep the null check:

1
// React
2
const headingRef = useRef<HTMLHeadingElement>(null);
3

4
headingRef.current?.scrollIntoView({
5
  behavior: 'smooth',
6
  block: 'center',
7
});

1
// Vue
2
const heading = ref<HTMLElement | null>(null);
3

4
heading.value?.scrollIntoView({
5
  behavior: 'smooth',
6
  block: 'center',
7
});

In Svelte or another component system, the same rule applies: keep a reference to the rendered element and call scrollIntoView() on that element after it exists. If the framework updates the DOM asynchronously, run the scroll after the update hook rather than during initial state setup.

Add a fixed-header offset with CSS#

scrollIntoView() controls alignment, not a custom pixel offset argument. If a fixed header covers the target after scrolling, set scroll-margin-top on the target elements:

1
[data-scroll-target] {
2
  scroll-margin-top: 5rem;
3
}

Then keep the JavaScript focused on selecting the element and choosing an alignment:

1
document
2
  .querySelector('[data-scroll-target="pricing"]')
3
  ?.scrollIntoView({ behavior: 'smooth', block: 'start' });

This preserves the browser’s scroll container behavior and keeps the header height in CSS, where responsive layout rules already belong. If the page has nested scroll containers, verify which container is moving before changing the offset.

Debug the receiver instead of the options#

When the error is unclear, log the value and compare it with the expected shape:

1
const value = getTargetSomehow();
2

3
console.log({
4
  value,
5
  constructor: value?.constructor?.name,
6
  isElement: value instanceof Element,
7
  isNodeList: value instanceof NodeList,
8
});

Then map the result to the fix:

• Element or HTMLElement: call scrollIntoView(); if it still behaves oddly, inspect the scroll container and CSS.
• NodeList: select one item with .item(0) or iterate intentionally.
• null or undefined: fix the selector or run after the target renders.
• Framework ref object: unwrap .current, .value, or the equivalent element property.
• A plain object: inspect the API that returned it; a data record is not a DOM node.

Use optional chaining for an expected missing target, but do not use it to hide a selector that must exist for the page to work. A warning or assertion is better for required navigation targets.

FAQ#