Off-screen <Command /> mount can scroll the window unexpectedly

[thevuong]

Describe the bug

Mounting cmdk's <Command /> off-screen can trigger Element.scrollIntoView() internally and unexpectedly scroll the page window to that off-screen location.

In our case, this happened even though no hash navigation was used and no explicit app-level scroll logic ran.

Reproduction steps

1. Render a long page.
2. Place <Command> in a section far below the fold.
3. Navigate to that page from another route while currently at scrollY = 0.
4. Observe that the page jumps down automatically near the <Command> section.

Expected behavior

The page should stay at top (or keep router/browser restoration behavior), and Command internals should not force-window-scroll when mounted off-screen.

Actual behavior

Window scroll jumps down on mount.

Runtime evidence

When instrumenting Element.prototype.scrollIntoView, the call stack points to cmdk internals:

• Element.scrollIntoView
• ne (.../cmdk.js:160:152)
• .../cmdk.js:451:28

Environment

• cmdk: 1.1.1
• React: 19.2.6
• Browser: Chromium (via Cursor embedded browser)
• Router: TanStack Router

Workaround

Delaying/lazy-mounting the off-screen <Command> section avoids the jump, which further suggests the mount-time scrollIntoView path is the trigger.

[thevuong]

I dug into source (cmdk/src/index.tsx) and found the exact path causing the page jump.

Source-level root cause

scrollSelectedIntoView() always runs item.scrollIntoView({ block: 'nearest' }):

function scrollSelectedIntoView() {
  const item = getSelectedItem()

  if (item) {
    if (item.parentElement?.firstChild === item) {
      item.closest(GROUP_SELECTOR)?.querySelector(GROUP_HEADING_SELECTOR)?.scrollIntoView({ block: 'nearest' })
    }

    item.scrollIntoView({ block: 'nearest' })
  }
}

And it is scheduled from setState('value', ...) (schedule(5, scrollSelectedIntoView)) when selection changes.

So on mount / first selection, if the command list itself is not a constrained scroll container, scrollIntoView can bubble to the viewport and scroll the window.

Why this reproduces in real apps

If <CommandList> doesn't currently overflow (or isn't constrained), scrollIntoView has no inner scroll area to adjust, so the viewport is the thing that moves.

Potential fix direction

Only auto-scroll when the list can actually scroll:

function scrollSelectedIntoView() {
  const item = getSelectedItem()
  const list = listInnerRef.current
  if (!item || !list) return

  // prevent viewport scrolling when list is not scrollable
  if (list.scrollHeight <= list.clientHeight) return

  if (item.parentElement?.firstChild === item) {
    item.closest(GROUP_SELECTOR)?.querySelector(GROUP_HEADING_SELECTOR)?.scrollIntoView({ block: 'nearest' })
  }

  item.scrollIntoView({ block: 'nearest' })
}

Happy to test a patch/PR if this direction makes sense.

[shaah1d]

I dug into source (cmdk/src/index.tsx) and found the exact path causing the page jump.

Source-level root cause

scrollSelectedIntoView() always runs item.scrollIntoView({ block: 'nearest' }):

function scrollSelectedIntoView() {
const item = getSelectedItem()

if (item) {
if (item.parentElement?.firstChild === item) {
item.closest(GROUP_SELECTOR)?.querySelector(GROUP_HEADING_SELECTOR)?.scrollIntoView({ block: 'nearest' })
}

item.scrollIntoView({ block: 'nearest' })

}
}
And it is scheduled from setState('value', ...) (schedule(5, scrollSelectedIntoView)) when selection changes.

So on mount / first selection, if the command list itself is not a constrained scroll container, scrollIntoView can bubble to the viewport and scroll the window.

Why this reproduces in real apps

If <CommandList> doesn't currently overflow (or isn't constrained), scrollIntoView has no inner scroll area to adjust, so the viewport is the thing that moves.

Potential fix direction

Only auto-scroll when the list can actually scroll:

function scrollSelectedIntoView() {
const item = getSelectedItem()
const list = listInnerRef.current
if (!item || !list) return

// prevent viewport scrolling when list is not scrollable
if (list.scrollHeight <= list.clientHeight) return

if (item.parentElement?.firstChild === item) {
item.closest(GROUP_SELECTOR)?.querySelector(GROUP_HEADING_SELECTOR)?.scrollIntoView({ block: 'nearest' })
}

item.scrollIntoView({ block: 'nearest' })
}
Happy to test a patch/PR if this direction makes sense.

Thank you for the detailed writeup. this solution is guarding the item.scrollIntoView() but the group heading scrollIntoView() is left unguarded. In my fix I moved the scrollHeight <= clientHeight to the top of the function so both calls are skipped when the list isnt scrollable.