Keep Your Next.js Pagination URLs Shareable Without Losing Filters

/projects?q=invoice&tag=urgent&tag=review&sort=recent&page=2

/projects?q=invoice&tag=urgent&tag=review&sort=recent&page=3

function toHref(pathname, params) {
  if (
    typeof pathname !== "string" ||
    !pathname.startsWith("/") ||
    pathname.startsWith("//") ||
    /[?#]/.test(pathname)
  ) {
    throw new TypeError("Expected a root-relative pathname");
  }

  const query = params.toString();
  return pathname + (query ? `?${query}` : "");
}

export function parsePage(raw) {
  if (typeof raw !== "string" || !/^[1-9]\d*$/.test(raw)) return 1;
  const page = Number(raw);
  return Number.isSafeInteger(page) ? page : 1;
}

export function hrefForPage(pathname, search, page) {
  if (!Number.isSafeInteger(page) || page < 1) {
    throw new RangeError("page must be a positive safe integer");
  }

  const params = new URLSearchParams(search);
  params.delete("page"); // Also removes duplicate page keys.
  if (page !== 1) params.set("page", String(page));
  return toHref(pathname, params);
}

export function hrefForSearch(pathname, search, rawQuery) {
  if (typeof rawQuery !== "string") {
    throw new TypeError("query must be a string");
  }

  const params = new URLSearchParams(search);
  const query = rawQuery.trim();
  if (query) params.set("q", query);
  else params.delete("q");
  params.delete("page"); // A new search starts on page one.
  return toHref(pathname, params);
}

import assert from "node:assert/strict";
import test from "node:test";
import { hrefForPage, hrefForSearch, parsePage } from "./pagination-url.mjs";

const current = "q=invoice&tag=urgent&tag=review&sort=recent&page=2";

test("reproduces a naive link that loses the filtered view", () => {
  const broken = `/projects?page=${3}`;
  assert.equal(broken, "/projects?page=3");
  assert.equal(
    new URL(broken, "https://example.test").searchParams.has("q"),
    false,
  );
});

test("page link preserves search, sorting and repeated tags", () => {
  assert.equal(
    hrefForPage("/projects", current, 3),
    "/projects?q=invoice&tag=urgent&tag=review&sort=recent&page=3",
  );
});

test("page one removes the default page key, not the filters", () => {
  assert.equal(
    hrefForPage("/projects", current, 1),
    "/projects?q=invoice&tag=urgent&tag=review&sort=recent",
  );
});

test("duplicate old page keys become a single requested page", () => {
  const href = hrefForPage("/projects", "page=9&tag=a&page=8&tag=b", 2);
  const url = new URL(href, "https://example.test");
  assert.deepEqual(url.searchParams.getAll("page"), ["2"]);
  assert.deepEqual(url.searchParams.getAll("tag"), ["a", "b"]);
});

test("search change resets page while preserving other choices", () => {
  assert.equal(
    hrefForSearch("/projects", current, " refund "),
    "/projects?q=refund&tag=urgent&tag=review&sort=recent",
  );
});

test("clearing search also clears its old page", () => {
  assert.equal(
    hrefForSearch("/projects", "tag=active&q=old&page=7", "  "),
    "/projects?tag=active",
  );
});

test("special characters round-trip as data", () => {
  const href = hrefForSearch("/projects", "tag=priority&page=2", "R&D / EU");
  assert.equal(
    new URL(href, "https://example.test").searchParams.get("q"),
    "R&D / EU",
  );
  assert.equal(href.includes("page="), false);
});

test("invalid page values fall back to one", () => {
  for (const raw of [null, "0", "-1", "2.5", "01", "1e2", "9007199254740992"]) {
    assert.equal(parsePage(raw), 1);
  }
  assert.equal(parsePage("12"), 12);
});

test("rejects invalid page requests and external pathnames", () => {
  for (const page of [0, -1, 1.5, Infinity, "2"]) {
    assert.throws(() => hrefForPage("/projects", current, page), RangeError);
  }
  assert.throws(() => hrefForPage("//evil.test", current, 2), TypeError);
  assert.throws(() => hrefForSearch("/projects", current, null), TypeError);
});

node --test pagination-url.test.mjs

"use client";

import Link from "next/link";
import { usePathname, useSearchParams } from "next/navigation";
import {
  Pagination,
  PaginationContent,
  PaginationEllipsis,
  PaginationItem,
  PaginationLink,
  buildPaginationRange,
} from "@pycolors/ui";
import { hrefForPage } from "./pagination-url.mjs";

export function ProjectPageLinks({ page, totalPages }) {
  const pathname = usePathname();
  const searchParams = useSearchParams();
  const tokens = buildPaginationRange({ page, totalPages });

  return (
    <Pagination aria-label="Project pages">
      <PaginationContent>
        {tokens.map((token) =>
          token.type === "ellipsis" ? (
            <PaginationItem key={token.key}>
              <PaginationEllipsis />
            </PaginationItem>
          ) : (
            <PaginationItem key={token.value}>
              <PaginationLink asChild isActive={token.isActive}>
                <Link
                  href={hrefForPage(
                    pathname,
                    searchParams.toString(),
                    token.value,
                  )}
                >
                  {token.value}
                </Link>
              </PaginationLink>
            </PaginationItem>
          ),
        )}
      </PaginationContent>
    </Pagination>
  );
}