scrollIntoView({ behavior: "smooth" }) Not Working: Check the Scroller

Identify what should move#

Use DevTools to inspect the target and its ancestors. Look for the element whose scrollTop changes when you move the scrollbar:

1
const target = document.querySelector('#details');
2
let node = target;
3

4
while (node instanceof HTMLElement) {
5
  const styles = getComputedStyle(node);
6
  console.log(node, {
7
    clientHeight: node.clientHeight,
8
    scrollHeight: node.scrollHeight,
9
    overflowY: styles.overflowY,
10
    scrollTop: node.scrollTop,
11
  });
12
  node = node.parentElement;
13
}

A useful scroll container normally has scrollHeight > clientHeight and an overflow value such as auto or scroll. If every ancestor has the same scroll height as its client height, there is no internal panel to animate; the viewport is the scrolling box instead.

For a document-level target, put scroll-behavior on the root element:

1
html {
2
  scroll-behavior: smooth;
3
}

MDN notes that scroll-behavior applies to scrolling boxes and that setting it on the root element affects the viewport. Setting it on body does not reliably propagate to the viewport, so body { scroll-behavior: smooth; } is a common reason anchor scrolling still jumps.

Check for a zero-distance scroll#

The browser may have little or nothing to animate:

• The target is already inside the visible area.
• block: 'nearest' decides that no movement is needed.
• The target is near the current scroll position.
• A layout change moves the target before the scroll starts.
• A fixed header makes the result look wrong even though the scroll happened.

Use block: 'start' temporarily when debugging:

1
target?.scrollIntoView({
2
  behavior: 'smooth',
3
  block: 'start',
4
  inline: 'nearest',
5
});

Once the movement works, choose the alignment that fits the component. nearest minimizes movement; start makes the target’s top edge align with the scrolling area’s top edge. If a fixed header covers the result, use scroll-padding-top or scroll-margin-top rather than adding a second scroll operation. The existing scrollIntoView fixed-header guide covers that visual offset boundary.

Check the selector and lifecycle#

An animation cannot start if the selector returns null, a collection, or an element that is not yet in the document:

1
const target = document.querySelector('#details');
2

3
if (!(target instanceof Element)) {
4
  throw new Error('The scroll target is not mounted');
5
}
6

7
target.scrollIntoView({ behavior: 'smooth', block: 'start' });

If the console says scrollIntoView is not a function, the issue is the selected value’s type rather than smooth scrolling. scrollIntoView Is Not a Function covers NodeList, null, and framework-ref boundaries.

In component frameworks, trigger the scroll after the target is rendered and after the panel has its final size. A call made before an async list, image, font, or accordion content expands can appear to stop at the old position. If the target is conditionally rendered, wait for the render cycle instead of adding an arbitrary timeout.

Handle reduced motion intentionally#

Respect the user’s motion preference when smooth scrolling is optional:

1
const prefersReducedMotion = window.matchMedia(
2
  '(prefers-reduced-motion: reduce)',
3
).matches;
4

5
target?.scrollIntoView({
6
  behavior: prefersReducedMotion ? 'auto' : 'smooth',
7
  block: 'start',
8
});

The MDN prefers-reduced-motion reference documents the media feature used by this check. If you are diagnosing an animation that works for some users and not others, compare this preference and the browser’s accessibility settings before blaming the selector.

Also remember that CSS scroll-behavior uses a user-agent-defined duration and easing, and user agents are allowed to ignore that CSS property. The JavaScript option is clearer for an explicit interaction, but it still should not override a deliberate reduced-motion policy.

Test the real scroll path#

Verify the page and panel separately:

1. Give the panel a fixed or constrained block size and enough content to overflow.
2. Confirm which element’s scrollTop changes.
3. Call scrollIntoView() after the target is mounted.
4. Test block: 'start' and block: 'nearest' independently.
5. Test with prefers-reduced-motion: reduce enabled.
6. Check a fixed header or nested scroll container after the movement is working.

Do not replace a one-line DOM scroll with a window.scrollTo() calculation until you know the actual scroll container. Manual coordinates often break when the layout becomes nested or responsive.

The practical rule is to debug the scrolling box before the animation option. Make the container scrollable, keep the target reference stable, handle reduced motion, and use scroll padding or margin for visual offsets.

FAQ#