Skip to main content

Guía de Paginación

Ejemplos​

¿Quieres ir directamente a la implementación? Echa un vistazo a estos ejemplos:

API​

Pagination API

Guía de Paginación​

TanStack Table tiene un gran soporte tanto para la paginación del lado del cliente como del lado del servidor. Esta guía te mostrará las diferentes formas de implementar la paginación en tu tabla.

Paginación del Lado del Cliente​

Usar la paginación del lado del cliente significa que los data que recuperes contendrán TODAS las filas de la tabla, y la instancia de la tabla manejará la lógica de paginación en el front-end.

¿Deberías Usar la Paginación del Lado del Cliente?​

La paginación del lado del cliente suele ser la forma más sencilla de implementar la paginación al usar TanStack Table, pero podría no ser práctica para conjuntos de datos muy grandes.

Sin embargo, muchas personas subestiman la cantidad de datos que se pueden manejar del lado del cliente. Si tu tabla solo tendrá unos pocos miles de filas o menos, la paginación del lado del cliente aún puede ser una opción viable. TanStack Table está diseñada para escalar hasta decenas de miles de filas con un rendimiento decente para paginación, filtrado, ordenación y agrupación. El ejemplo oficial de paginación carga 100,000 filas y aún funciona bien, aunque con solo un puñado de columnas.

Cada caso de uso es diferente y dependerá de la complejidad de la tabla, cuántas columnas tengas, qué tan grande sea cada pieza de datos, etc. Los principales cuellos de botella a los que prestar atención son:

  1. ¿Puede tu servidor consultar todos los datos en un tiempo (y costo) razonable?
  2. ¿Cuál es el tamaño total de la recuperación de datos? (Esto podría no escalar tan mal como piensas si no tienes muchas columnas.)
  3. ¿Está usando el navegador del cliente demasiada memoria si todos los datos se cargan a la vez?

Si no estás seguro, siempre puedes empezar con la paginación del lado del cliente y luego cambiar a la paginación del lado del servidor en el futuro a medida que tus datos crezcan.

¿Deberías Usar Virtualización en su Lugar?​

Alternativamente, en lugar de paginar los datos, puedes renderizar todas las filas de un gran conjunto de datos en la misma página, pero solo usar los recursos del navegador para renderizar las filas que son visibles en la ventana gráfica. Esta estrategia a menudo se denomina "virtualización" o "windowing". TanStack ofrece una biblioteca de virtualización llamada TanStack Virtual que puede funcionar bien con TanStack Table. La UI/UX tanto de la virtualización como de la paginación tienen sus propias ventajas y desventajas, así que mira cuál funciona mejor para tu caso de uso.

Modelo de Fila de Paginación​

Si quieres aprovechar la paginación del lado del cliente integrada en TanStack Table, primero necesitas pasar el modelo de fila de paginación.

import {
  useReactTable,
  getCoreRowModel,
  getPaginationRowModel,
} from "@tanstack/react-table";
//...
const table = useReactTable({
  columns,
  data,
  getCoreRowModel: getCoreRowModel(),
  getPaginationRowModel: getPaginationRowModel(), // cargar código de paginación del lado del cliente
});

Paginación Manual del Lado del Servidor​

Si decides que necesitas usar la paginación del lado del servidor, así es como puedes implementarla.

No se necesita un modelo de fila de paginación para la paginación del lado del servidor, pero si lo has proporcionado para otras tablas que sí lo necesitan en un componente compartido, aún puedes desactivar la paginación del lado del cliente configurando la opción manualPagination a true. Establecer la opción manualPagination a true le dirá a la instancia de la tabla que use el modelo de fila table.getPrePaginationRowModel internamente, y hará que la instancia de la tabla asuma que los data que pasas ya están paginados.

Conteo de Páginas y Conteo de Filas​

La instancia de la tabla no tendrá forma de saber cuántas filas/páginas hay en total en tu back-end a menos que se lo digas. Proporciona la opción de tabla rowCount o pageCount para que la instancia de la tabla sepa cuántas páginas hay en total. Si proporcionas un rowCount, la instancia de la tabla calculará el pageCount internamente a partir de rowCount y pageSize. De lo contrario, puedes proporcionar directamente el pageCount si ya lo tienes. Si no conoces el conteo de páginas, puedes simplemente pasar -1 para el pageCount, pero las funciones del modelo de fila getCanNextPage y getCanPreviousPage siempre devolverán true en este caso.

import {
  useReactTable,
  getCoreRowModel,
  getPaginationRowModel,
} from "@tanstack/react-table";
//...
const table = useReactTable({
  columns,
  data,
  getCoreRowModel: getCoreRowModel(),
  // getPaginationRowModel: getPaginationRowModel(), // no es necesario para la paginación del lado del servidor
  manualPagination: true, // desactivar la paginación del lado del cliente
  rowCount: dataQuery.data?.rowCount, // pasar el número total de filas para que la tabla sepa cuántas páginas hay (pageCount calculado internamente si no se proporciona)
  // pageCount: dataQuery.data?.pageCount, // alternativamente, pasar directamente pageCount en lugar de rowCount
});

Nota: Establecer la opción manualPagination a true hará que la instancia de la tabla asuma que los data que pasas ya están paginados.

Estado de Paginación​

Ya sea que estés usando paginación del lado del cliente o paginación manual del lado del servidor, puedes usar el estado pagination y las APIs integradas.

El estado pagination es un objeto que contiene las siguientes propiedades:

  • pageIndex: El índice de la página actual (basado en cero).
  • pageSize: El tamaño de página actual.

Puedes gestionar el estado pagination como cualquier otro estado en la instancia de la tabla.

import {
  useReactTable,
  getCoreRowModel,
  getPaginationRowModel,
} from "@tanstack/react-table";
//...
const [pagination, setPagination] = useState({
  pageIndex: 0, // índice de página inicial
  pageSize: 10, // tamaño de página predeterminado
});

const table = useReactTable({
  columns,
  data,
  getCoreRowModel: getCoreRowModel(),
  getPaginationRowModel: getPaginationRowModel(),
  onPaginationChange: setPagination, // actualizar el estado de paginación cuando las APIs internas mutan el estado de paginación
  state: {
    //...
    pagination,
  },
});

Alternativamente, si no necesitas gestionar el estado pagination en tu propio ámbito, pero necesitas establecer diferentes valores iniciales para pageIndex y pageSize, puedes usar la opción initialState.

const table = useReactTable({
  columns,
  data,
  getCoreRowModel: getCoreRowModel(),
  getPaginationRowModel: getPaginationRowModel(),
  initialState: {
    pagination: {
      pageIndex: 2, // índice de página inicial personalizado
      pageSize: 25, // tamaño de página predeterminado personalizado
    },
  },
});

Nota: NO pases el estado pagination a las opciones state e initialState a la vez. state sobrescribirá a initialState. Usa solo una de ellas.

Opciones de Paginación​

Además de las opciones manualPagination, pageCount y rowCount que son útiles para la paginación manual del lado del servidor (y discutidas anteriormente), hay otra opción de tabla que es útil entender.

Restablecimiento Automático del Índice de Página​

Por defecto, pageIndex se restablece a 0 cuando ocurren cambios de estado que alteran la página, como cuando los data se actualizan, los filtros cambian, los agrupamientos cambian, etc. Este comportamiento se deshabilita automáticamente cuando manualPagination es true, pero se puede anular asignando explícitamente un valor booleano a la opción de tabla autoResetPageIndex.

const table = useReactTable({
  columns,
  data,
  getCoreRowModel: getCoreRowModel(),
  getPaginationRowModel: getPaginationRowModel(),
  autoResetPageIndex: false, // desactivar el restablecimiento automático de pageIndex
});

Ten en cuenta, sin embargo, que si desactivas autoResetPageIndex, es posible que necesites añadir alguna lógica para manejar el restablecimiento de pageIndex por ti mismo para evitar mostrar páginas vacías.

APIs de Paginación​

Existen varias APIs de instancia de tabla de paginación que son útiles para conectar tus componentes de UI de paginación.

APIs de Botones de Paginación​

  • getCanPreviousPage: Útil para deshabilitar el botón "página anterior" cuando se está en la primera página.
  • getCanNextPage: Útil para deshabilitar el botón "página siguiente" cuando no hay más páginas.
  • previousPage: Útil para ir a la página anterior. (Manejador de clic de botón)
  • nextPage: Útil para ir a la página siguiente. (Manejador de clic de botón)
  • firstPage: Útil para ir a la primera página. (Manejador de clic de botón)
  • lastPage: Útil para ir a la última página. (Manejador de clic de botón)
  • setPageIndex: Útil para un campo de entrada "ir a página".
  • resetPageIndex: Útil para restablecer el estado de la tabla al índice de página original.
  • setPageSize: Útil para un campo de entrada/selección de "tamaño de página".
  • resetPageSize: Útil para restablecer el estado de la tabla al tamaño de página original.
  • setPagination: Útil para establecer todo el estado de paginación a la vez.
  • resetPagination: Útil para restablecer el estado de la tabla al estado de paginación original.

Nota: Algunas de estas APIs son nuevas en v8.13.0.

<Button
  onClick={() => table.firstPage()}
  disabled={!table.getCanPreviousPage()}
>
  {'<<'}
</Button>
<Button
  onClick={() => table.previousPage()}
  disabled={!table.getCanPreviousPage()}
>
  {'<'}
</Button>
<Button
  onClick={() => table.nextPage()}
  disabled={!table.getCanNextPage()}
>
  {'>'}
</Button>
<Button
  onClick={() => table.lastPage()}
  disabled={!table.getCanNextPage()}
>
  {'>>'}
</Button>
<select
  value={table.getState().pagination.pageSize}
  onChange={e => {
    table.setPageSize(Number(e.target.value))
  }}
>
  {[10, 20, 30, 40, 50].map(pageSize => (
    <option key={pageSize} value={pageSize}>
      {pageSize}
    </option>
  ))}
</select>

APIs de Información de Paginación​

  • getPageCount: Útil para mostrar el número total de páginas.
  • getRowCount: Útil para mostrar el número total de filas.