Design a pagination control

Requirements: what to ask before drawing buttons

A pagination control is the row of links under a long list that splits it into pages: Previous, a few page numbers, and Next. You click 4 and you see items 61 to 80. Google search, GitHub issues and Amazon results all end with one.

It looks like a loop from 1 to the number of pages. That breaks the moment a list has 400 pages. A senior answer treats the control as the visible end of a bigger system: the URL, the API, the total count, the cache and the focus all move when the page changes.

Start with questions. The middle column is what this guide assumes.

Functional requirements

• Previous, Next, first and last page, the current page and its neighbors, with ellipses for gaps.
• The page and page size live in the URL, so reload, Back, share and crawl all work.
• Works with exact, approximate ("about 1,200"), capped ("1,000+") and unknown totals.
• Jump to a page by number; pick a page size in tables.
• On a change: keep the old page visible while loading, move to the top of the list, never show a stale page.
• A compact phone layout: Previous, "Page 3 of 12", Next.

Non-functional requirements

• Fast: a cached page change paints in under 100 ms; an uncached one shows data in about 500 ms on 4G.
• Stable: the control never changes width while you page, so Next doesn't move under your finger.
• Accessible: WCAG 2.2 AA, targets of at least 24 by 24 CSS pixels.
• Small and crawlable: under 3 KB gzipped, every page reachable by a plain link in the server HTML.

Out of scope

• Infinite feeds: see the infinite scroll guide. We only compare the patterns.
• Sorting, filtering and the table itself (the data table guide). Here they only reset the page.
• Writing the database queries: the pagination lesson covers offset and cursor queries.

What makes it hard

Four facts drive every later decision; each gets its own chapter.

1. The list is bigger than the control. 12,400 results at 20 per page is 620 pages, and the control has room for about 9 items. It must pick which numbers to show, at the same width on page 1 and page 620.
2. The page is shared state. The router, the fetcher, the server renderer, crawlers and the person you send the link to all read it. In a useState inside the control, all of them lose it.
3. The total is often a guess or a luxury. Counting every match can cost more than fetching the page, search engines only estimate, and cursor APIs don't know it at all.
4. A page change replaces the whole list. Loading states, scroll position, focus and out-of-order responses all show up at once.

Here is the control we're building, in its two layouts.

Wide screens get Previous, the page window (numbers and ellipses), Next, and a "Go to page" field, with a summary above the list. Phones get Previous, "Page 3 of 620" (which opens the jump field), and Next.

Numbered pages, Load more, or infinite scroll

First check that numbered pages are the right pattern. Interviewers often ask "why not infinite scroll?" and want a reason.

A buyer sees a pair of shoes "on page 3, near the bottom", opens a few tabs, and comes back an hour later. With numbered pages, page 3 is a link and the item is still roughly there. With an infinite feed she scrolls from the top again.

Real products follow this split. Google search tried continuous scrolling and dropped it in June 2024: desktop went back to numbered pages, and phones got a "More results" button. GitHub, Amazon and nearly every admin tool use numbered pages; Instagram and TikTok use infinite feeds.

Numbered pages also depend on the API. Jumping to page 40 needs an offset ("skip 780 rows, take 20"). A cursor API ("20 after this id") can only step forward and back. The pagination lesson explains both; the total count chapter shows the control for each.

The page window: which numbers to show

The page window is the items between Previous and Next: page numbers and ellipses. The naive version renders range(1, totalPages): with 620 pages, a row that wraps across six lines.

The second naive version shows 5 numbers around the current page. Now there's no one-click way back to page 1, no hint how many pages exist, and the row changes length near the ends.

The three rules

1. Always show the ends. One click to page 1 or page 620.
2. Never hide just one page. In "1 … 3" the ellipsis takes the space of the 2 it hides. Use an ellipsis only for 2 or more pages.
3. Keep the item count stable. With the defaults, always 7 items once there are more than 7 pages. Near the start the block grows right: page 1 shows 1 2 3 4 5 … 620, not 1 2 … 620.

type Item = number | "gap-start" | "gap-end";
const range = (a: number, b: number) =>
  b < a ? [] : Array.from({ length: b - a + 1 }, (_, i) => a + i);

export function pageWindow(page: number, total: number, siblings = 1, boundary = 1): Item[] {
  const slots = 2 * boundary + 2 * siblings + 3; // ends + block + two gaps
  if (total <= slots) return range(1, total);
  // The sibling block, pushed away from the ends so the count stays fixed.
  const start = Math.max(Math.min(page - siblings, total - boundary - 2 * siblings - 1), boundary + 2);
  const end = Math.min(Math.max(page + siblings, boundary + 2 * siblings + 2), total - boundary - 1);
  return [
    ...range(1, boundary),
    start > boundary + 2 ? "gap-start" : boundary + 1, // a gap of 1 is shown as the page
    ...range(start, end),
    end < total - boundary - 1 ? "gap-end" : total - boundary,
    ...range(total - boundary + 1, total),
  ];
}

Walk through 10 pages with the defaults (7 slots). The 3-page sibling block is clamped between pages 3 and 8, leaving room for each end and its neighbor slot.

Try it. The count changes only with the total, never while you page, and no ellipsis hides a single page.

A stable count isn't the whole story: "9" is narrower than "620". Give every item the same min-width (40 pixels), use font-variant-numeric: tabular-nums, and always render Previous and Next, disabled at the ends. Now a user can click Next 5 times without moving the mouse.

The two counts are a trade-off between reach and width. siblingCount 2 shows 9 items and lets users step 2 pages either way with one click; it suits wide admin tables. boundaryCount 0 drops the ends and fits phones, but then page 1 is only reachable through Previous or the jump field. Defaults of 1 and 1 are the safe middle.

The page lives in the URL, and every page is a link

The naive control keeps useState(1) and renders button elements. Then a support agent sends a link to page 7 and the colleague lands on page 1. Reload loses the page, Back leaves the list, and crawlers never find page 2, because they don't click buttons.

What happens on a click

A plain click is caught by the router's Link, which calls pushState. Cmd click, middle click and "open in new tab" skip the handler and use the href, so it must always be correct.

Each page click pushes a history entry, so Back returns to the previous page, the same as plain links on any website. A clamping redirect uses replace instead of push, so Back never lands on the invalid URL. The jump field and page size changes push, because users see them as navigation.

export function pageHref(pathname: string, params: URLSearchParams, page: number) {
  const next = new URLSearchParams(params);
  if (page <= 1) next.delete("page");
  else next.set("page", String(page));
  const qs = next.toString();
  return qs ? `${pathname}?${qs}` : pathname;
}

// pageHref("/search", new URLSearchParams("q=shoes&sort=price&page=2"), 3)
// -> "/search?q=shoes&sort=price&page=3"

Search engines: canonical URLs, not rel=prev/next

• Each page is its own canonical. Page 3's link rel="canonical" points to ?page=3. Pointing every page at page 1 marks the others as copies, so their items may never be indexed.
• Google no longer uses rel="prev" and rel="next". It said so in 2019. They're harmless and other engines may read them, but crawlable a href links are what matter.
• One URL per page, in the query string. pageHref drops page=1. Crawlers ignore everything after #, so #page=3 is invisible.
• Keep sorted and filtered copies out of the index, as Google suggests, with a noindex robots meta tag or a robots.txt rule: ?sort=price&page=3 is the same items in another order.

Invalid pages: parse, clamp, redirect

The URL is user input: ?page=abc, ?page=-2, or an old link to ?page=40 after the list shrank to 12 pages. Parse strictly on the server, before rendering.

The total count problem

The window needs totalPages, so the naive API runs two queries per request: SELECT ... LIMIT 20 OFFSET 40 for the page and SELECT COUNT(*) ... WHERE status = 'shipped' for the total.

On the 3 million row orders table the page query uses an index and takes about 5 ms. The count is different. PostgreSQL keeps no stored count per filter and must check that each matching row is visible to the transaction, so it visits every one. With 2 million matches that is the 1 to 2 seconds from our requirements, on every click.

Search has the same problem at scale. Google labels its counts "About" because they are estimates. GitHub's search API serves only the first 1,000 results of any search. Elasticsearch counts exactly only up to 10,000 hits by default (its track_total_hits setting), then reports 10,000 as a lower bound.

Compare the four on the same list: what the control can show, and what the server pays.

When the API is cursor based

A cursor is an opaque token pointing at a row. "20 rows after this one" is fast at any depth and doesn't skip rows on inserts, but there is no page 40 without walking 39 pages. The reddit guide goes deeper into cursor listings.

• The URL holds the cursor, ?after=eyJpZCI6ODgyMTN9: shareable, but not "page 5".
• The control shows Previous and Next, maybe a client-counted "Page 5" (hidden on shared links).
• Previous needs a before cursor from the API, so it works on a shared link.
• A "First page" link is cheap. "Last page" needs a reverse sort.

export type PageTotal =
  | { kind: "exact"; totalItems: number }          // "Page 3 of 117", last page link
  | { kind: "estimate"; totalItems: number }       // "About 12,400 results"
  | { kind: "atLeast"; totalItems: number }        // "10,000+ results", no last link
  | { kind: "unknown" };                           // Previous and Next only, from hasNext

export function lastPage(total: PageTotal, pageSize: number): number | null {
  if (total.kind === "exact" || total.kind === "estimate")
    return Math.max(1, Math.ceil(total.totalItems / pageSize));
  return null; // atLeast and unknown: the window has no right end
}

When lastPage is null, the window drops the last page and the end ellipsis means "more": 1 … 6 7 8 … Next, with "10,000+ results, refine your search".

Changing pages: loading, scroll, focus and races

The naive page change clears the list, shows a spinner, fetches and renders. Four things go wrong:

• The list collapses and the footer jumps (a layout shift).
• The user is still scrolled to the bottom, far from the new rows.
• Focus was on a link that may be gone, so keyboard users restart from the top.
• Fast clicks can show page 3's rows under a control that says 4.

Keep the old page until the new one arrives

const queryClient = useQueryClient();
const { data, isPlaceholderData, isError, refetch } = useQuery({
  queryKey: ["orders", { status, sort, page, pageSize }],
  queryFn: ({ signal }) => fetchOrders({ status, sort, page, pageSize }, signal),
  placeholderData: keepPreviousData, // show page 3 while page 4 loads
  staleTime: 30_000,
});

// Prefetch the next page once this one has arrived (not while page 3 stands in for it).
useEffect(() => {
  if (isPlaceholderData || !data?.hasNext) return;
  queryClient.prefetchQuery({
    queryKey: ["orders", { status, sort, page: page + 1, pageSize }],
    queryFn: ({ signal }) => fetchOrders({ status, sort, page: page + 1, pageSize }, signal),
  });
}, [data, isPlaceholderData, page, pageSize, sort, status, queryClient]);

Prefetching makes most changes instant. Most users go next, so fetch page N+1 once page N renders. For other numbers, prefetch on pointerenter or focus: a hover usually comes a few hundred milliseconds before the click. Don't prefetch every visible number: 7 extra requests per view.

The page request as a state machine

Fast clicks and out-of-order responses

Three fast clicks request pages 4, 5 and 6. If page 5 arrives last, a naive setRows(response) shows it under a control that says 6. The fix, from the request-races lesson: only the response for the current key renders. A cache keyed by page does this for you.

Passing the query's signal to fetch also lets the cache abort requests nobody waits for, which saves server work when someone clicks through 6 pages to reach page 10. Aborting is an optimization, not the fix: abort does nothing once a body has been fully read, so the key check is still what keeps the screen correct.

Scroll and focus after the change

• Scroll to the list, not the page top. listHeading.scrollIntoView({ block: "start" }), with scroll-margin-top for any sticky header. Skip it if the list top is visible.
• Move focus to the list heading (tabindex="-1") with focus({ preventScroll: true }). Screen readers read "Orders, page 4", and Tab goes into the new rows (see the focus-management lesson).
• One rule everywhere. Some teams keep focus on Next so users can skim with Enter. Either works; mixing them doesn't.
• Respect reduced motion: smooth scrolling only without prefers-reduced-motion: reduce.
• Update document.title to "Orders, page 4 of 117" so history entries differ.

Page size and jumping to a page

Changing the page size

Admin tables offer 10, 25, 50 and 100 rows. Where is the choice stored, and where do you land after changing it?

Store it in the URL (?size=50) so links show the same rows, and in localStorage per table for the next visit. The URL wins. Accept only the offered values, on client and server, so nobody requests ?size=100000.

Jumping to a page

With 117 pages, reaching page 63 takes about 30 clicks. Add a "Go to page" form past about 10 pages (Ant Design's quick jumper).

• A real form with a labelled input type="text" inputmode="numeric": a number keyboard on phones, without the number input's scroll wheel quirks.
• Submit navigates to the page link, through the same URL and clamping path as a click.
• Validate digits from 1 to the last page; show "Enter a page from 1 to 117" via aria-describedby and keep focus in the field.
• With capped or unknown totals, limit or hide it.

Architecture, data model and component API

The rule that shapes everything: the control is a pure view of the URL and the total. It doesn't fetch, store the page, or know which list it's under, so one component serves every list.

How data flows

Read path: the URL gives page=4, the hook calls GET /api/orders?status=shipped&page=4&size=25, and the list and control render from the rows and total. Write path: a click changes the URL, nothing else.

Data model and API

// URL (source of truth): /orders?status=shipped&sort=-date&page=4&size=25
type ListParams = { status?: string; sort: string; page: number; size: 10 | 25 | 50 | 100 };

// Server cache, keyed by ListParams: one entry per page.
type PageResponse<T> = {
  items: T[];
  page: number;          // the page the server actually served, after clamping
  size: number;
  total: PageTotal;      // exact, estimate, atLeast, or unknown
  hasNext: boolean;      // the server fetched size + 1 rows
  nextCursor?: string;   // only on cursor endpoints
};

// localStorage: the user's preferred size per table, e.g. "orders.pageSize" = "50".

The response echoes page: if the client asked for 40 and got 12, it replaces the URL with ?page=12.

The component API

type PaginationProps = {
  page: number;                         // controlled; from the URL
  total: PageTotal;                     // see chapter 6
  pageSize: number;
  getHref?: (page: number) => string;   // links (default)
  onChange?: (page: number) => void;    // buttons, for in-memory lists
  siblingCount?: number;                // default 1
  boundaryCount?: number;               // default 1
  linkComponent?: React.ElementType;    // the router's Link
  renderItem?: (item: PaginationItem) => React.ReactNode;
  "aria-label"?: string;                // default "Pagination"
};

Notice what's missing: no internal page state, no fetch function, no useEffect. The component renders the same HTML on the server and the client, so it hydrates without a mismatch, and it works with JavaScript disabled because every item is a link.

Mobile, accessibility and right-to-left

Compact mode on phones

The full row needs about 450 pixels; a 360 pixel phone has about 328 inside its margins. Shrinking links makes them hard to tap, and wrapping puts page 7 under page 2.

• Compact layout: Previous, "Page 3 of 117", Next, with 44 pixel arrows. The label opens the jump field, or a native select under about 50 pages.
• Switch with a container query, since the same table may sit in a narrow side panel. @container (max-width: 480px) swaps layouts; both are in the server HTML, so there's no flash.
• Or drop siblings first: siblingCount 0 gives 1 … 5 … 117, 5 items.

Accessibility

<nav aria-label="Pagination">
  <ul>
    <li><a href="/orders?page=2" aria-label="Previous page" rel="prev">Previous</a></li>
    <li><a href="/orders" aria-label="Page 1">1</a></li>
    <li><a href="/orders?page=2" aria-label="Page 2">2</a></li>
    <li><a href="/orders?page=3" aria-label="Page 3" aria-current="page">3</a></li>
    <li><a href="/orders?page=4" aria-label="Page 4">4</a></li>
    <li><a href="/orders?page=5" aria-label="Page 5">5</a></li>
    <li aria-hidden="true">…</li>
    <li><a href="/orders?page=117" aria-label="Page 117, last page">117</a></li>
    <li><a href="/orders?page=4" aria-label="Next page" rel="next">Next</a></li>
  </ul>
</nav>

• A named landmark. nav with aria-label="Pagination" appears in the landmarks list. Two on a page need different labels.
• aria-current="page" on the current link, plus a style beyond color. Screen readers announce it as the current page (see the aria-patterns lesson).
• Names that stand alone. "4, link" means little in a links list; aria-label="Page 4" fixes it and still contains the visible text.
• Disabled, not hidden, at the ends. On page 1, Previous stays in place as an a with no href, role="link" and aria-disabled="true": not focusable, still announced as unavailable.
• Ellipses are decoration: aria-hidden="true".
• Target size. WCAG 2.2 criterion 2.5.8 (AA) asks for at least 24 by 24 CSS pixels or enough spacing. We use 40, and 44 on touch.
• Keyboard. Links are Tab stops opened with Enter. No arrow keys: this is a set of links, not a composite widget (see the keyboard-navigation lesson).

Designers often want the control above and below a long table. Two landmarks named "Pagination" confuse screen reader users, so label them "Pagination, top" and "Pagination, bottom", or show only the result summary on top. Both render from the same URL, so they can never disagree.

Right-to-left languages

In Arabic and Hebrew page 1 is on the right and Next points left. A flex row with logical properties (padding-inline) reverses on its own, but arrow icons don't: mirror them with transform: scaleX(-1) under :dir(rtl). Format totals with Intl.NumberFormat(locale) ("12.400" in German). The rtl-layouts lesson covers which icons to mirror.

Running it in the interview

This question usually gets 30 minutes. It's easy, so the bar is depth: the window algorithm without hesitation, then how far past it you go.

Draw the wireframe first, then the architecture with the URL in the middle. Saying "the URL owns the page, not the control" early shortens every later answer.

Follow-up questions