NavigateOptions always has an optional params parameter

[kam-zhan-yue]

Which project does this relate to?

Router

Describe the bug

When importing and using NavigateOptions, I found that it does not behave exactly the same as NavigateFn or the function returned from useNavigate. Notably, on a route with a parameter, e.g. test/$param, when I try to navigate using useNavigate it accurately says the params object is required.

import { useNavigate } from '@tanstack/react-router'
const navigate = useNavigate()

// below will throw a type error as params is required
navigate({ to: 'test/$param' })

However, when I have another function with NavigateOptions instead, it doesn't throw a type error.

import type { NavigateOptions } from '@tanstack/react-router'
const navigate = (options: NavigateOptions) => {}

// below will NOT throw a type error even though params is required
navigate({ to: 'test/$param' })

Your Example Website or App

https://stackblitz.com/edit/tanstack-router-kxugbqua?file=src%2Froutes%2Findex.tsx

Steps to Reproduce the Bug or Issue

Import NavigateOptions and try to navigate to a route with a param.

import type { NavigateOptions } from '@tanstack/react-router'

const wrappedNavigate = (options: NavigateOptions) => {
   // anything here
);

const onClick = useCallback(() => {
  // this should throw a type error
  wrappedNavigate({ to: '/test/$param' });
}

Expected behavior

I expect NavigateOptions to behave the same as the parameter passed into the NavigateFn. Meaning

  const wrappedNavigate = useCallback(
    (options: NavigateOptions) => {
      return navigate(options);
    },
    [navigate]
  );

  const onClick = useCallback(() => {
    // This should compile fine
    navigate({ to: '/test/$param', params: { param: 'a param' } });
    // This should throw a type error as 'param' is required
    wrappedNavigate({ to: '/test/$param' });
  }, [wrappedNavigate]);

Screenshots or Videos

Platform

• Router / Start Version: 1.43.12
• OS: macOS
• Browser: Arc
• Browser Version: V.1.78.0
• Bundler: vite
• Bundler Version: 5.0.13

Additional context

No response

[coderabbitai]

A summary of the changes CodeRabbit can apply:

• Add a JSDoc warning and examples to packages/router-core/src/link.ts and update docs/router/framework/react/api/router/NavigateOptionsType.md with a prominent warning box and correct vs incorrect usage examples (pointing users to ValidateNavigateOptions) so IDE tooltips and the API docs clearly guide users to the type-safe navigation pattern while preserving backward compatibility.

• Add developer guidance and examples clarifying that NavigateOptions should be replaced by ValidateNavigateOptions for proper type inference—update docs/router/framework/react/api/router/NavigateOptionsType.md with a prominent note and code examples, and add a detailed JSDoc block (with examples and links) above the NavigateOptions type in packages/router-core/src/link.ts.

• ✅ Create PR with these edits
• 📋 Get copyable edits

[kam-zhan-yue]

Sorry 🤖 🐇 , but ValidateNavigateOptions also has this problem.