[RFC]: Add better scroll options to links

[Tobbe]

Summary

RedwoodSDK just had a sweet PR come in for better scroll control on navigation. I want something similar for CedarJS!
Cedar already has a scroll?: boolean prop, but I like the more explicit scrollToTop name from RWSDK better. And the scrollBehavior is nice too 🤩

redwoodjs/sdk#616
https://github.com/cedarjs/cedar/blob/main/packages/router/src/history.tsx

Motivation

Users should have better control over how navigation works and feels in their application

Detailed proposal

See the linked RWSDK PR. There's also more context in their discord here https://discord.com/channels/679514959968993311/679514959968993476/1396963062111797328

Are you interested in working on this?

• I'm interested in working on this

[ChinmayMoghe]

Hi I am interested in working on this , can you assign this issue to me ?

[lisa-assistant]

Implementation Plan

The current scroll?: boolean prop on NavigateOptions scrolls to (0, 0) when true. Adding scrollBehavior would let users control how the scroll happens (instant, smooth, or auto).

Files to change

packages/router/src/history.ts

Extend NavigateOptions:

export interface NavigateOptions {
  replace?: boolean
  scroll?: boolean
  scrollBehavior?: ScrollBehavior  // 'auto' | 'instant' | 'smooth'
}

packages/router/src/location.tsx (line ~93)

Pass the behavior to scrollTo:

if (options?.scroll === true) {
  globalThis?.scrollTo({
    top: 0,
    left: 0,
    behavior: options?.scrollBehavior ?? 'instant',
  })
}

Note: default is 'instant' to preserve existing behavior — scrollTo(0, 0) is equivalent to instant.

packages/router/src/link.tsx

No changes needed — Link already passes options through to navigate() which passes it to the history listener.

Usage after the change

<Link to={routes.home()} options={{ scrollBehavior: 'smooth' }}>Home</Link>

// or programmatically:
navigate('/dashboard', { scrollBehavior: 'smooth' })

About renaming scroll → scrollToTop

Renaming is a breaking change. A safer path: keep scroll as-is and add scrollBehavior now. In a future major release, deprecate scroll in favor of a more explicit API. The RWSDK PR referenced in the issue could serve as inspiration for that v2 API.

Gotcha

ScrollBehavior is a browser-native type from lib.dom.d.ts, no import needed. But it won't be available in server/prerender contexts — the existing globalThis?.scrollTo guard already handles that.

[lisa-assistant]

Self-fix confidence: 8/10
The code change is small and well-contained. The main question is API design — specifically whether to also add a scrollToTop alias prop and whether 'instant' is the right default, which needs a call from the maintainers before coding.