React Router 7.13.1: URL Masking for Modal PDPs in Hydrogen

URL masking for modal navigation in React Router 7.13.1

The Problem

You want a product quick-view modal that:

Opens on top of your collection page
Shows a shareable URL (/products/sneakers)
Keeps the collection visible in the background
Works with deep links and browser history

Until now, this required manual backgroundLocation management—a clunky pattern that felt like fighting the framework.

Route and URL strategy planning for shareable modal states

The Solution

React Router 7.13.1 introduces unstable_mask on <Link>. First-class URL masking for Framework/Data Mode.

// routes/collection.tsx
export default function Collection({ loaderData }) {
  return (
    <div className="collection-grid">
      {loaderData.products.map((product) => (
        <Link
          key={product.id}
          to={`/collection?product=${product.id}`}  // Router state
          unstable_mask={`/products/${product.handle}`} // Browser URL
        >
          <ProductCard product={product} />
        </Link>
      ))}

      {/* Modal overlay */}
      {loaderData.modalProduct && (
        <dialog open>
          <ProductQuickView product={loaderData.modalProduct} />
        </dialog>
      )}
    </div>
  )
}

tsx

How It Works

Router navigates to /collection?product=123 (internal state)
Browser shows /products/sneakers (masked URL)
Deep link /products/sneakers works normally (mask stripped on SSR)
Back button closes modal, restores collection

Detecting Masked State

import { useLocation } from 'react-router'

function ProductModal() {
  const location = useLocation()
  
  // Are we in a modal context?
  if (location.unstable_mask) {
    return <ModalProduct />
  }
  
  // Direct navigation - full page
  return <FullProductPage />
}