Intercepted Route Using TanStack Start

Current route shape:

• Public: /, /privacy, /cgv, /support
• User app: /app
• Admin: /admin (redirects to /admin/users), /admin/users, /admin/users/$userId

The examples below use a hypothetical /admin/items list/detail flow to illustrate the pattern.

1. User starts on /admin/items.
2. User clicks a row.
3. Browser URL becomes /admin/items/$itemId.
4. UI keeps the /admin/items list visible and opens a modal/sheet with the detail.
5. Back or close returns to /admin/items.
6. Refresh or direct visit on /admin/items/$itemId renders the full detail page.

<core_pattern> Navigate to the source route internally, store modal state in source route search, and mask the visible URL as the destination route.

<Link
  to="/admin/items"
  search={{ itemId: item._id }}
  mask={{
    to: "/admin/items/$itemId",
    params: { itemId: item._id },
    unmaskOnReload: true,
  }}
  resetScroll={false}
>
  View
</Link>

The source route owns modal state:

type ItemsSearch = {
  itemId?: string;
};

export const Route = createFileRoute("/admin/items")({
  validateSearch: (search: Record<string, unknown>): ItemsSearch => ({
    itemId:
      typeof search.itemId === "string" && search.itemId.length > 0
        ? search.itemId
        : undefined,
  }),
  component: AdminItemsPage,
});

The destination route remains a real route:

export const Route = createFileRoute("/admin/items/$itemId")({
  component: AdminItemDetailPage,
});

</core_pattern>

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

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

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

If the modal has an "Open full page" action, navigate directly and do not call the close handler first:

void router.navigate({
  to: "/admin/items/$itemId",
  params: { itemId },
  replace: true,
});

cd web-app && npm run typecheck
cd web-app && npm run build

Then verify manually or with browser automation:

1. Open source route.
2. Click detail link.
3. Confirm browser URL is the detail URL.
4. Confirm modal/sheet is visible over source context.
5. Use Back or close and confirm source route returns.
6. Open detail URL directly or refresh and confirm full detail page renders.