Pagination

Qué patrón#

"use client";

import { useState } from "react";
import { Pagination } from "@/registry/ds/pagination";

export default function PaginationPatterns() {
  const [page, setPage] = useState(1);
  const from = (page - 1) * 10 + 1;
  return (
    <div className="flex w-full max-w-xl flex-col gap-8">
      <Pagination label="Paginación con resumen" variant="prev-next" page={page} count={10} onPageChange={setPage} summary={`Mostrando ${from} a ${Math.min(from + 9, 97)} de 97 resultados`} />
      <div className="flex flex-wrap items-center justify-between gap-6">
        <Pagination label="Paginación compacta" variant="compact" size="sm" page={page} count={10} onPageChange={setPage} />
        <Pagination label="Paginación con flechas" variant="arrows" shape="circle" page={page} count={10} onPageChange={setPage} />
      </div>
    </div>
  );
}

Forma y tamaño#

"use client";

import { useState } from "react";
import { Pagination } from "@/registry/ds/pagination";

export default function PaginationShapes() {
  const [page, setPage] = useState(2);
  return (
    <div className="flex flex-col items-center gap-5">
      <Pagination label="Paginación chica" size="sm" page={page} count={5} onPageChange={setPage} />
      <Pagination label="Paginación circular" shape="circle" page={page} count={5} onPageChange={setPage} />
    </div>
  );
}

Reglas#

• Es neutro a propósito. La página actual se marca con fondo gris y peso Medium, no con el verde de marca: la paginación no compite con los CTAs.
• Siempre visibles la primera y la última página; en el medio, elipsis.
• Anterior en la página 1 y Siguiente en la última quedan deshabilitados, no desaparecen: que el control no salte de lugar.
• Al cambiar de página, llevá el scroll al inicio de la lista.
• Menos de ~25 ítems: no pagines. Feeds y descubrimiento: "Cargar más".

Medidas#

Gap entre celdas spacing-xs (4). Circle: radius-full. Botones Anterior / Siguiente: alto de la celda, padding X 12 / 14.

Tokens por estado#

En Figma#

Cinco piezas: .Page item y un componente por patrón.

Instalación#

npx shadcn@latest add https://polen.cdc.cool/r/pagination.json

Playground#

Configurá el componente y copiá el snippet: se genera del mismo estado que renderiza el preview.

const [page, setPage] = useState(1);

<Pagination page={page} count={10} onPageChange={setPage} />

Uso#

Es un componente controlado: vos guardás la página.

const [page, setPage] = useState(1);

<Pagination page={page} count={totalPages} onPageChange={setPage} />

Props#

También se exporta pageRange(page, count, siblings) por si necesitás armar una paginación propia con la misma lógica de elipsis.

• <nav aria-label="Paginación">: aparece en la lista de regiones del lector de pantalla.
• Cada número se anuncia como "Página 6"; la actual lleva aria-current="page".
• Las flechas tienen nombre ("Página anterior" / "Página siguiente") y se deshabilitan de verdad en los extremos.
• En compact, el cambio "6 / 20" se anuncia con aria-live.
• La celda sm mide 32: cumple el mínimo de 24, pero en mobile preferí md.
• Después de cambiar de página, mové el foco al inicio de los resultados.