Declarative route masks are ignoring params

[hakanshehu]

Which project does this relate to?

Router

Describe the bug

When using custom params with declarative route masks, the mask params are ignored and the router falls back to the original URL params. This is not noticeable unless the mask params differ from the original ones.

In my case, users can have multiple accounts with access to multiple workspaces. Internally, I include the account ID in the URL but mask it so only the workspace ID is shown. Routing still works correctly, but since the masked params are ignored, the masked URL displays undefined for the dynamic segment that doesn’t exist in the original params.

Your Example Website or App

https://stackblitz.com/edit/github-qkndtvzh?file=src%2Fmain.tsx

Steps to Reproduce the Bug or Issue

An illustration of the issue

// this is the route which is being used internally
const workspacePrivateRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/workspace/$privateId',
  component: function About() {
    const { privateId } = workspacePrivateRoute.useParams();
    const workspace = workspaces.find((w) => w.privateId === privateId);
    if (!workspace) {
      return <div>Workspace not found</div>;
    }

    return (
      <div className="p-2">
        Workspace {workspace.name} | Private ID: {workspace.privateId} | Public
        ID: {workspace.publicId}
      </div>
    );
  },
});

//this is the masked route which is shown to the user
const workspacePublicRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/$publicId',
  beforeLoad: (ctx) => {
    const workspace = workspaces.find(
      (w) => w.publicId === ctx.params.publicId
    );

    if (!workspace) {
      throw notFound();
    }

    throw redirect({
      to: '/workspace/$privateId',
      params: {
        privateId: workspace.privateId,
      },
    });
  },
});

const routeTree = rootRoute.addChildren([
  workspacePrivateRoute,
  workspacePublicRoute,
]);


//here is the declarative mask definition
export const workspaceRouteMask = createRouteMask({
  routeTree: routeTree,
  from: '/workspace/$privateId',
  to: '/$publicId',
  params: (ctx) => {
    const workspace = workspaces.find((w) => w.privateId === ctx.privateId);
    if (!workspace) {
      throw notFound();
    }

    return {
      publicId: workspace.publicId,
    };
  },
});

The routing works as expected, but the URL shows 'undefined' instead of the public id of the workspace.

Expected behavior

The final route should take into account the custom params in the declarative route definition.

Screenshots or Videos

No response

Platform

• Router Version: 1.134.12
• OS: Mac
• Browser: Chrome
• Browser Version: 142
• Bundler: vite
• Bundler Version: 7.1.10

Additional context

I will propose a PR that tries to solve this issue.

[coderabbitai]

A summary of the changes CodeRabbit can apply:

• Update packages/router-core/src/router.ts (buildWithMatches, ~lines 1797–1811) to preserve mask-defined params (use maskProps.params when present, fall back to matched params only if undefined), fixing declarative route masks to respect custom params (functions/objects) without breaking changes.

• Update packages/router-core/src/router.ts to make route-mask handling respect maskProps.params (supporting undefined/true/false/function/object), use the mask's params when provided or fall back to extracted params, and replace the previous unconditional params propagation with a conditioned maskParams assignment so masked destinations build with the correct params.

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