feat(react-router): implement hash change "Scroll Into View" option

[joshuaslate]

I am working on an API documentation page that has a number of anchor links. The sidebar contains Link elements that expand/collapse sections based on if its hash is active. It works like a table of contents. I also update the hash based on the user's scroll position. If they've scrolled past an anchor, it updates the hash. The issue I was hitting is that updating the hash with navigate or a number of other methods actually runs scrollIntoView, which takes over the user's scrolling in these cases.

The change I'm proposing is to add an option to navigate and Link that will allow the consumer to choose to opt out of the default scrollIntoView behavior, or even allow them to customize the scroll behavior if they would like to (e.g., for smooth scrolling instead of instant).

Discussed in Discord here: https://discord.com/channels/719702312431386674/1316559407919796334

Another relevant discussion: #1155

[schiller-manuel]

this looks great. let's wait for @SeanCassiere to review

[schiller-manuel]

LGTM

[SeanCassiere]

I'm not at home at the moment, so I'll have to check the sandbox locally at home tomorrow.

I'd also like us to think a bit more on the property name. The name hashChangeScrollIntoView just feels a bit off. Maybe even hashScrollIntoView?

Approving for now, but I'd like to get a chance to play with the sandbox before merging in.

[joshuaslate]

I believe I've addressed all of the feedback that's come in so far, please let me know if anything else comes up. I added the /anchor route to the basic-file-based example for easy manual testing in addition to the e2e tests.

[SeanCassiere]

Would this (the ?? true) break any existing apps?

[joshuaslate]

These options are new, so the value will default to true if they aren't provided.

I read on MDN for scrollIntoView that true is the default argument value, so passing true by default should maintain the behavior that exists today. I don't believe this is a breaking change.

I'm not at my computer right now, but I believe I added a test case and Link on the example that use the default behavior, and it seems to function the same as the released version does for me.

[SeanCassiere]

Tried out the sandbox and it looks good.

@schiller-manuel OK to merge from my side.

[nx-cloud]

☁️ Nx Cloud Report

CI is running/has finished running commands for commit 72339b6. As they complete they will appear below. Click to see the status, the terminal output, and the build insights.

📂 See all runs for this CI Pipeline Execution

---

✅ Successfully ran 1 target

• nx affected --targets=test:eslint,test:unit,test:e2e,test:types,test:build,build --parallel=3

---

Sent with 💌 from NxCloud.

[pkg-pr-new]

Open in Stackblitz

More templates

• tanstack-router-react-example-authenticated-routes
• tanstack-router-react-example-basic
• tanstack-router-react-example-basic-default-search-params
• tanstack-router-react-example-basic-file-based
• tanstack-router-react-example-basic-file-based-codesplitting
• tanstack-router-react-example-react-query
• tanstack-router-react-example-basic-react-query-file-based
• tanstack-router-react-example-basic-ssr-file-based
• tanstack-router-react-example-basic-ssr-streaming-file-based
• tanstack-router-react-example-basic-virtual-file-based
• tanstack-router-react-example-basic-virtual-inside-file-based
• tanstack-router-react-example-deferred-data
• tanstack-router-react-example-kitchen-sink
• tanstack-router-react-example-kitchen-sink-file-based
• tanstack-router-react-example-kitchen-sink-react-query
• tanstack-router-react-example-kitchen-sink-react-query-file-based
• tanstack-router-react-example-large-file-based
• tanstack-router-react-example-location-masking
• tanstack-router-react-example-navigation-blocking
• tanstack-router-react-example-quickstart
• tanstack-router-react-example-quickstart-esbuild-file-based
• tanstack-router-react-example-quickstart-file-based
• tanstack-router-react-example-quickstart-rspack-file-based
• tanstack-router-react-example-quickstart-webpack-file-based
• router-monorepo-react-query
• router-mono-simple
• tanstack-router-react-example-scroll-restoration
• tanstack-search-validator-adapters
• tanstack-start-example-basic
• tanstack-start-example-basic-auth
• tanstack-start-example-basic-react-query
• tanstack-start-example-basic-rsc
• tanstack-start-example-clerk-basic
• tanstack-start-example-convex-trellaux
• tanstack-start-example-counter
• tanstack-start-example-large
• tanstack-start-example-supabase-basic
• tanstack-start-example-trellaux
• tanstack-router-react-example-with-framer-motion
• tanstack-router-react-example-with-trpc
• tanstack-router-react-example-with-trpc-react-query

@tanstack/arktype-adapter

npm i https://pkg.pr.new/@tanstack/arktype-adapter@2996

@tanstack/create-router

npm i https://pkg.pr.new/@tanstack/create-router@2996

@tanstack/history

npm i https://pkg.pr.new/@tanstack/history@2996

@tanstack/eslint-plugin-router

npm i https://pkg.pr.new/@tanstack/eslint-plugin-router@2996

@tanstack/react-cross-context

npm i https://pkg.pr.new/@tanstack/react-cross-context@2996

@tanstack/react-router

npm i https://pkg.pr.new/@tanstack/react-router@2996

@tanstack/react-router-with-query

npm i https://pkg.pr.new/@tanstack/react-router-with-query@2996

@tanstack/router-cli

npm i https://pkg.pr.new/@tanstack/router-cli@2996

@tanstack/router-devtools

npm i https://pkg.pr.new/@tanstack/router-devtools@2996

@tanstack/router-generator

npm i https://pkg.pr.new/@tanstack/router-generator@2996

@tanstack/router-plugin

npm i https://pkg.pr.new/@tanstack/router-plugin@2996

@tanstack/router-vite-plugin

npm i https://pkg.pr.new/@tanstack/router-vite-plugin@2996

@tanstack/start

npm i https://pkg.pr.new/@tanstack/start@2996

@tanstack/start-vite-plugin

npm i https://pkg.pr.new/@tanstack/start-vite-plugin@2996

@tanstack/valibot-adapter

npm i https://pkg.pr.new/@tanstack/valibot-adapter@2996

@tanstack/virtual-file-routes

npm i https://pkg.pr.new/@tanstack/virtual-file-routes@2996

@tanstack/zod-adapter

npm i https://pkg.pr.new/@tanstack/zod-adapter@2996

commit: 72339b6

[joshuaslate]

I was investigating the test failure from scroll restoration and found that if browser (not router)-controlled navigation happens, the router.state.location.state.__hashScrollIntoViewOptions option isn't being set, because it doesn't run through commitLocation.

I could add another nullish coalescing operator to set the value if it's undefined, like so:

if (typeof document !== 'undefined' && (document as any).querySelector) {
        const hashScrollIntoViewOptions =
          router.state.location.state.__hashScrollIntoViewOptions ?? true

        if (hashScrollIntoViewOptions && router.state.location.hash !== '') {
          const el = document.getElementById(router.state.location.hash)
          if (el) {
            el.scrollIntoView(hashScrollIntoViewOptions)
          }
        }
      }

This fixes the test and is working for me in the scroll restoration sandbox.

@SeanCassiere, does that sound ok to you?

[SeanCassiere]

@SeanCassiere, does that sound ok to you?

Worth giving it a try.
I'll also be investigating what's going on here.

[SeanCassiere]

cc @schiller-manuel