Search and path params in TanStack Router incompatible with `useHref`

[levrik]

Provide a general summary of the issue here

TanStack Router interpolates path params into the href:

<Link to="/projects/$id" params={{ id: '123' }}>Open</Link>

When using React Aria Components' router integration this gets turned into:

<Link href="/projects/$id" routerOptions={{ params: { id: '123' } }}>Open</Link>

As useHref of RouterProvider only receives the href but not routerOptions like navigate does, the navigation itself works correctly but the native features like Cmd+Click (or right-click "Open in new tab") navigate to the href template instead of the real link. Also the URL preview shown by the browser is wrong.

This could easily be solved by also passing routerOptions to useHref.

TanStack Router can also manage search params through a separate prop which suffers from the same issue.

I'm open to contributing this change but wanted to check upfront in case I'm missing something here. Maybe there is a reason for routerOptions not being passed to useHref that I'm unaware of.

🤔 Expected Behavior?

href on a tag to be /projects/123 with the above example.

😯 Current Behavior

href on a tag is /projects/$id with the above example.

💁 Possible Solution

Pass routerOptions to useHref as 2nd paramter.

🔦 Context

No response

[levrik]

I went ahead and created #6591 as I needed this change anyway to unblock myself at work. Let me know what you think.

[lithdew]

What do you think about making href optional for components if routerOptions is provided?

For both Tanstack Router and React Router, routerOptions is solely needed in order to be able to generate the necessary href to attach to components. RouterProvider's useHref can then solely take in routerOptions instead of the href passed in to components.

[devongovett]

You can also define the href type to accept an object instead of a string if you want.

declare module 'react-aria-components' {
  interface RouterConfig {
    href: YourRouterHref
  }
}

[levrik]

@devongovett Is there anything I can do to get a review on #6591? Maybe I missed something during the PR creation?

[devongovett]

Sorry just busy and we had the week off last week for a holiday. Will discuss with the team.

[levrik]

@devongovett Thanks! Take your time.

[devongovett]

We discussed this today. We were originally thinking that routerOptions was meant for things that affected the behavior of the navigation rather than only the URL itself (e.g. replace and resetScroll). We could add them to useHref but it would sort of mix concerns.

An alternative suggestion would be to define the href as an object corresponding to all of the options that TanStack router accepts rather than just a string.

import {ToOptions, NavigateOptions} from '@tanstack/react-router';

declare module 'react-aria-components' {
  interface RouterConfig {
    href: ToOptions;
    routerOptions: Omit<NavigateOptions, keyof ToOptions>;
  }
}

Then you can use them on a RAC component like this:

<RACLink
  href={{
    to: '/dashboard/invoices/$invoiceId',
    params: { invoiceId: 2 },
  }} />

and get autocomplete for both to and params.

This API also has the advantage that since both to and params are part of the same type, it's possible for typescript to infer the params based on the route. This would require a bit more work with TanStack Router's types to get working, but it should be possible. Also good news is that this should be possible today without any code changes.

Here's a StackBlitz example.

What do you think of this approach?

[levrik]

@devongovett That is an interesting idea. Let me try that in my codebase. Currently I'm using the patch from my PR and wrap components to fix the auto-completion but this sounds much cleaner.

[levrik]

@devongovett I gave it a try now but params are sadly not typed based on to but instead simply offer params from all routes. But I think that's what you meant by "This would require a bit more work with TanStack Router's types", right?

[devongovett]

Yeah, that's what I meant. It should be possible, but I didn't quite figure it out. You'd basically need to generate a union of objects like {to: '/foo', params: {}} | {to: '/foo/$bar', params: {bar: string}}.

I tried something like this:

type Routes = NonNullable<ToOptions['to']>;
type Href = {
  [To in Routes]: ToOptions<RegisteredRouter, string, To>
}[Routes];

but it didn't seem to work. I'm probably missing something.

[evadecker]

Succeeded in getting params to work with a small modification building on @devongovett above. Here's what I changed from the recommendation in the docs:

import {type NavigateOptions, type ToOptions, useRouter} from '@tanstack/react-router';
import {RouterProvider} from 'react-aria-components';

declare module 'react-aria-components' {
  interface RouterConfig {
-   href: ToOptions['to'];
+   href: ToOptions;
    routerOptions: Omit<NavigateOptions, keyof ToOptions>;
  }
}

function RootRoute() {
  let router = useRouter();
  return (
    <RouterProvider
-     navigate={(to, options) => router.navigate({ to, ...options })}
+     navigate={(path, options) => router.navigate({ ...path, ...options })}
-     useHref={(to) => router.buildLocation(to).href}
+     useHref={({ to }) => router.buildLocation({ to }).href}
    >
      {/* ... */}
    </RouterProvider>
  );
}

This allows passing in params using an object for href:

<Link href={{ to: "/admin/forms/$formId", params: { formId: form._id } }} />

And still supports passing in a simple string for href. Spoke too soon, this approach requires refactoring all href="string" links to href={{ to: "string" }}. Although TypeScript is satisfied, the actual routing doesn't work, which I think is due to the use of useHref here and is also the reason for this issue: #6397