URL-Params are kept even if not provided requiring TypeScript error when having `exactOptionalPropertyTypes` enabled

[SimonSimCity]

Which project does this relate to?

Router

Describe the bug

Since required parameters are also required on the params-prop of the Link component, I would expect those not being present to be removed.

In the stackblitz example, I defined a route as /users/{-$id} and added some links to it:

1. Menu - without params prop.
2. Link "User1" - having params prop setting id to 1.
3. Link "User2" - having params prop setting id to 2.
4. Link "List (not working 😬)" - having params prop with an empty object.
5. Link "List (working 🤩)" - having params prop setting id to undefined.

The last option is invalid when having exactOptionalPropertyTypes enabled in your TypeScript config.

When imagining a different scenario, where I have multiple variables, some of them required, I can actually (against the types) leave out parameters already provided by the former route. In my real-world scenario I try to build a link to and from /company/$companyId/users/{-$userId}. Based on the types I have to provide companyId, but based on the implementation, I don't have to, but I should set userId to undefined if I want to remove it, which creates a TypeScript error, because I have exactOptionalPropertyTypes enabled.

Your Example Website or App

https://stackblitz.com/edit/github-abbyhecx?file=src%2Froutes%2Fusers%2F{-%24id}.tsx,src%2Froutes%2F__root.tsx

Steps to Reproduce the Bug or Issue

1. Go to "Users".
2. Click on "User1" to set the optional parameter.
3. Try to get back to the "Users" page by clicking in the menu.

Expected behavior

The "List (not working 😬)" should work, means, parameters, not set when providing params should be omitted.

Screenshots or Videos

No response

Platform

• Router Version: 1.133.22
• OS: macOS
• Browser: Chrome
• Browser Version: 140
• Bundler: vite
• Bundler Version: 7.1.7

Additional context

• https://tanstack.com/router/v1/docs/framework/react/guide/path-params#defining-optional-parameters
• Optional params? #146

[schiller-manuel]

they are now typed explicitly as | undefined

[SimonSimCity]

@schiller-manuel, thanks for the quick response and update!

In addition to this change, I would propose to add an additional note to https://tanstack.com/router/latest/docs/framework/react/guide/path-params#navigating-with-optional-parameters mentioning, that parameters (also optional ones) which are not defined, are taken from the from route. In this regard, you are defining what should change.

Imagine a link as following:

<Link
  from="/{$companyId}/user/{-$id}"
  to="/{$companyId}/user/{-$id}"
  params={({ companyId }) => ({
    companyId: companyId,
  })}
>
  ⬅️ List (not working 😬)
</Link>

Example: https://stackblitz.com/edit/github-abbyhecx-5shqc1bs?file=src%2Froutes%2F{%24companyId}%2Fuser%2F{-%24id}.tsx

I just see this as such a common pitfall, that I think it's worth mentioning the concept over and over again, also at this place.

I was trying to find this somewhere, but couldn't see it being mentioned in https://tanstack.com/router/latest/docs/framework/react/routing/routing-concepts, but only as a small note in https://tanstack.com/router/latest/docs/framework/react/guide/navigation#navigating-with-optional-parameters.

Putting this in another perspective: This is a very powerful concept most programmers (at least all of our team here) aren't really used to, so I think it would be good to spend some more lines on this, somewhere as central as the Routing Concepts page. Yes, Everything is Relative, but I think this concept isn't as clearly communicated as I would need it to understand it fully while reading the docs.

[schiller-manuel]

absolutely, docs should reflect this. want to give it a go and create a PR for the docs?

[SimonSimCity]

@schiller-manuel, I tried to reach you through discord, but didn't have any luck - trying it here again:

I went through the docs and got the impression that docs are already quite comprehensive - I think I'm just missing a few more examples here and there.

I found the following guidelines - although maybe too inconspicuous:

• If you know the route, use it as from (safest to use Route.fullPath).
• If you don't know the route, don't provide a from and TypeScript will guide you.

I think that - equiped with these two guidelines - I can build something that's safe, except this case:

Imagine, I don't know the route (it's a shared component), and I want to create a link:

<Link
  to="/{$companyId}/user/{-$id}"
  params={{
    companyId: companyId,
  }}
>
  Open user listing
</Link>

Another example using functional style, where I skip what I get as parameters of the previous route, where one might be even more sure the id wouldn't be taken over:

<Link
  to="/{$companyId}/user/{-$id}"
  params={() => ({
    companyId: companyId,
  })}
>
  Open user listing
</Link>

This link will work in all cases, except if I'm on a route that already has the id prop. This way, I have to be quite knowledgeable about the place I am. This might have worked prior to the introduction of optional parameters, because TypeScript requires me to set the companyId (I could also have that left out and it would work, despite TypeScript complaining).

I don't know what a good solution here could be, but one thought was to make all keys of a route required in the params. This might break with existing definitions, but would at least make clear what value should be set, in the case that a user doesn't provide a from. IF he provides a from, we can expect that he knows what he's doing.