Intercepted Route Using TanStack Start

Use this skill when a UI should open as a modal during client navigation while the browser URL shows the real destination path, and a refresh or direct visit should render the destination as a full page.

This is the TanStack Start equivalent of a Next.js intercepted route. Do not use ?modal=... as the visible URL for this UX.

Desired Behavior

For a list-to-detail flow:

1. User starts on /items.
2. User clicks an item.
3. Browser URL becomes /items/$id.
4. UI still shows /items context with a modal on top.
5. Back closes the modal and returns to /items.
6. Refresh or direct visit on /items/$id renders the full detail page.

For a global modal like sign-in:

1. User starts on /docs.
2. User clicks Sign in.
3. Browser URL becomes /auth/signin.
4. UI shows the sign-in modal over /docs.
5. Back or close returns to /docs.
6. Refresh on /auth/signin renders the full sign-in page.

Core Pattern

Navigate to the source route internally, store modal state in that source route's search, and mask the browser URL as the real destination route.

<Link
  to="/changelog"
  search={{ entry: changelog.slug }}
  mask={{
    to: "/changelog/$slug",
    params: { slug: changelog.slug },
    unmaskOnReload: true,
  }}
  resetScroll={false}
>
  {changelog.attributes.title}
</Link>

The source route owns the modal state:

type ChangelogSearch = {
  entry?: string;
};

export const Route = createFileRoute("/(layout)/changelog/")({
  validateSearch: (search: Record<string, unknown>): ChangelogSearch => ({
    entry:
      typeof search.entry === "string" && search.entry.length > 0
        ? search.entry
        : undefined,
  }),
  loader: changelogLoader,
  component: ChangelogPage,
  pendingComponent: ChangelogPageSkeleton,
});

function ChangelogPage() {
  const { changelogs } = Route.useLoaderData();
  const { entry } = Route.useSearch();

  return <ChangelogTimeline changelogs={changelogs} selectedSlug={entry} />;
}

The destination route remains a normal route. It must be usable on direct visit and refresh:

export const Route = createFileRoute("/(layout)/changelog/$slug/")({
  loader: async ({ params }) => {
    const item = await loadItem(params.slug);
    if (!item) throw notFound();
    return item;
  },
  component: ChangelogDetailPage,
  pendingComponent: ChangelogDetailPageSkeleton,
});

Closing the Modal

Do not blindly call router.history.back() for every close. Only do that when the current location is masked.

const router = useRouter();
const location = useLocation();

const closeModal = () => {
  if (location.maskedLocation) {
    router.history.back();
    return;
  }

  void router.navigate({
    to: "/changelog",
    search: {},
    replace: true,
  });
};

Use this close handler for dialog onOpenChange.

Opening the Full Page from the Modal

If the modal has an "Open page" action, avoid firing the close handler first. Closing a masked modal usually calls history.back(), which races with the full-page navigation and can return to the source page.

void router.navigate({
  to: "/changelog/$slug",
  params: { slug },
  replace: true,
});

If the same dialog component is also used outside an intercepted route, add explicit props:

<ChangelogDialog
  changelog={selectedChangelog}
  openPageReplace
  closeOnOpenPage={false}
  onOpenChange={(open) => {
    if (!open) closeModal();
  }}
/>

Global Modal Variant

For global modals mounted at the root, keep the visible URL masked but the internal state on the current route:

<Link
  to="."
  search={(previous) => ({ ...previous, modal: "signin" })}
  mask={{ to: "/auth/signin", unmaskOnReload: true }}
>
  Sign in
</Link>

The root/global dialog reads the internal search state:

const search = useSearch({ strict: false }) as { modal?: string };
const isOpen = search.modal === "signin";

Close with the same masked-location guard:

const closeDialog = () => {
  if (location.maskedLocation) {
    router.history.back();
    return;
  }

  void router.navigate({
    to: ".",
    search: (previous) => ({ ...previous, modal: undefined }),
    replace: true,
  });
};

Rules

• Always keep the destination route as a real route with its own loader, SEO/head metadata when needed, and pendingComponent.
• Use mask={{ to: realDestination, unmaskOnReload: true }} for refresh-to-full-page behavior.
• Keep modal state internal to the source route search, not visible as ?modal=... in the browser URL.
• Use location.maskedLocation before deciding whether close should call history.back().
• Do not call a modal close handler immediately before "open full page" navigation from inside the modal.
• Preserve callback/search data in the internal route search when the modal flow needs it.
• Add or update e2e coverage for click, close/back, refresh, and direct destination visit.

Verification

For routes/UI flows, use the repo workflow:

pnpm ts
pnpm lint:ci
pnpm start-all -p <port>
PLAYWRIGHT_TEST_BASE_URL=http://localhost:<port> HEADLESS=TRUE pnpm exec playwright test e2e/<spec>.ts

Also verify manually with dev-browser when behavior matters:

1. Visit the source page.
2. Click the masked/intercepted link.
3. Confirm the browser URL is the destination URL.
4. Confirm the modal is visible.
5. Refresh.
6. Confirm the modal is gone and the full destination page is visible.

Existing References

• Changelog route mask: src/features/changelog/changelog-timeline.tsx
• Changelog source route search: src/routes/(layout)/changelog/index.tsx
• Changelog destination route: src/routes/(layout)/changelog/$slug/index.tsx
• Sign-in global modal mask: src/features/auth/sign-in-button.tsx
• Sign-in global dialog close behavior: src/features/auth/sign-in-dialog.tsx
• E2E examples: e2e/changelog.spec.ts, e2e/signin-modal.spec.ts