feat: pagination row count apis, new pagination docs (#5377)

* feat: pagination row count apis, new pagination docs

* same version of react query in every example

* merge main

* upgrade faker

docs/api/features/pagination.md

@@ -38,7 +38,15 @@ Enables manual pagination. If this option is set to `true`, the table will not a
 pageCount?: number
 ```
 
-When manually controlling pagination, you should supply a total `pageCount` value to the table if you know it. If you do not know how many pages there are, you can set this to `-1`.
+When manually controlling pagination, you can supply a total `pageCount` value to the table if you know it. If you do not know how many pages there are, you can set this to `-1`. Alternatively, you can provide a `rowCount` value and the table will calculate the `pageCount` internally.
+
+### `rowCount`
+
+```tsx
+rowCount?: number
+```
+
+When manually controlling pagination, you can supply a total `rowCount` value to the table if you know it. `pageCount` will be calculated internally from `rowCount` and `pageSize`.
 
 ### `autoResetPageIndex`
 
@@ -118,14 +126,6 @@ resetPageSize: (defaultState?: boolean) => void
 
 Resets the page size to its initial state. If `defaultState` is `true`, the page size will be reset to `10` regardless of initial state.
 
-### `setPageCount`
-
-```tsx
-setPageCount: (updater: Updater<number>) => void
-```
-
-Updates the page count using the provided function or value.
-
 ### `getPageOptions`
 
 ```tsx
@@ -166,6 +166,22 @@ nextPage: () => void
 
 Increments the page index by one, if possible.
 
+### `firstPage`
+
+```tsx
+firstPage: () => void
+```
+
+Sets the page index to `0`.
+
+### `lastPage`
+
+```tsx
+lastPage: () => void
+```
+
+Sets the page index to the last available page.
+
 ### `getPageCount`
 
 ```tsx

docs/guide/pagination.md

@@ -7,7 +7,7 @@ title: Pagination Guide
 Want to skip to the implementation? Check out these examples:
 
 - [pagination](../framework/react/examples/pagination)
-- [pagination-controlled](../framework/react/examples/pagination-controlled)
+- [pagination-controlled (React Query)](../framework/react/examples/pagination-controlled)
 - [editable-data](../framework/react/examples/editable-data)
 - [expanding](../framework/react/examples/expanding)
 - [filters](../framework/react/examples/filters)
@@ -18,4 +18,207 @@ Want to skip to the implementation? Check out these examples:
 
 [Pagination API](../api/features/pagination)
 
-## Pagination Guide
+## Pagination Guide
+
+TanStack Table has great support for both client-side and server-side pagination. This guide will walk you through the different ways to implement pagination in your table.
+
+### Client-Side Pagination
+
+Using client-side pagination means that the `data` that you fetch will contain ***ALL*** of the rows for the table, and the table instance will handle pagination logic in the front-end.
+
+#### Should You Use Client-Side Pagination?
+
+Client-side pagination is usually the simplest way to implement pagination when using TanStack Table, but it might not be practical for very large datasets.
+
+However, a lot of people underestimate just how much data can be handled client-side. If your table will only ever have a few thousand rows or less, client-side pagination can still be a viable option. TanStack Table is designed to scale up to 10s of thousands of rows with decent performance for pagination, filtering, sorting, and grouping. The [official pagination example](../framework/react/examples/pagination) loads 100,000 rows and still performs well, albeit with only handful of columns.
+
+Every use-case is different and will depend on the complexity of the table, how many columns you have, how large every piece of data is, etc. The main bottlenecks to pay attention to are:
+
+1. Can your server query all of the data in a reasonable amount of time (and cost)?
+2. What is the total size of the fetch? (This might not scale as badly as you think if you don't have many columns.)
+3. Is the client's browser using too much memory if all of the data is loaded at once?
+
+If you're not sure, you can always start with client-side pagination and then switch to server-side pagination in the future as your data grows.
+
+#### Should You Use Virtualization Instead?
+
+Alternatively, instead of paginating the data, you can render all rows of a large dataset on the same page, but only use the browser's resources to render the rows that are visible in the viewport. This strategy is often called "virtualization" or "windowing". TanStack offers a virtualization library called [TanStack Virtual](https://tanstack.com/virtual/latest) that can work well with TanStack Table. The UI/UX of both virtualization and pagination have their own trade-offs, so see which one works best for your use-case.
+
+#### Pagination Row Model
+
+If you want to take advantage of the built-in client-side pagination in TanStack Table, you first need to pass in the pagination row model.
+
+```jsx
+import { useReactTable, getCoreRowModel, getPaginationRowModel } from '@tanstack/react-table';
+//...
+const table = useReactTable({
+  columns,
+  data,
+  getCoreRowModel: getCoreRowModel(),
+  getPaginationRowModel: getPaginationRowModel(), //load client-side pagination code
+});
+```
+
+### Manual Server-Side Pagination
+
+If you decide that you need to use server-side pagination, here is how you can implement it.
+
+No pagination row model is needed for server-side pagination, but if you have provided it for other tables that do need it in a shared component, you can still turn off the client-side pagination by setting the `manualPagination` option to `true`. Setting to the `manualPagination` option to `true` will tell the table instance to use the `table.getPrePaginationRowModel` row model under the hood, and it will make the table instance assume that the `data` that you pass in is already paginated.
+
+#### Page Count and Row Count
+
+Also, the table instance will have no way of knowing how many rows/pages there are in total in your back-end unless you tell it. Provide either the `rowCount` or `pageCount` table option to let the table instance know how many pages there are in total. If you provide a `rowCount`, the table instance will calculate the `pageCount` internally from `rowCount` and `pageSize`. Otherwise, you can directly provide the `pageCount` if you already have it. If you don't know the page count, you can just pass in `-1` for the `pageCount`, but the `getCanNextPage` and `getCanPreviousPage` row model functions will always return `true` in this case.
+
+```jsx
+import { useReactTable, getCoreRowModel, getPaginationRowModel } from '@tanstack/react-table';
+//...
+const table = useReactTable({
+  columns,
+  data,
+  getCoreRowModel: getCoreRowModel(),
+  // getPaginationRowModel: getPaginationRowModel(), //not needed for server-side pagination
+  manualPagination: true, //turn off client-side pagination
+  rowCount: dataQuery.data?.rowCount, //pass in the total row count so the table knows how many pages there are (pageCount calculated internally if not provided)
+  // pageCount: dataQuery.data?.pageCount, //alternatively directly pass in pageCount instead of rowCount
+});
+```
+
+> **Note**: Setting the `manualPagination` option to `true` will make the table instance assume that the `data` that you pass in is already paginated.
+
+### Pagination State
+
+Whether or not you are using client-side or manual server-side pagination, you can use the built-in `pagination` state state and APIs.
+
+The `pagination` state is an object that contains the following properties:
+
+- `pageIndex`: The current page index (zero-based).
+- `pageSize`: The current page size.
+
+You can manage the `pagination` state just like any other state in the table instance.
+
+```jsx
+import { useReactTable, getCoreRowModel, getPaginationRowModel } from '@tanstack/react-table';
+//...
+const [pagination, setPagination] = useState({
+  pageIndex: 0, //initial page index
+  pageSize: 10, //default page size
+});
+
+const table = useReactTable({
+  columns,
+  data,
+  getCoreRowModel: getCoreRowModel(),
+  getPaginationRowModel: getPaginationRowModel(),
+  onPaginationChange: setPagination, //update the pagination state when internal APIs mutate the pagination state
+  state: {
+    //...
+    pagination,
+  },
+});
+```
+
+Alternatively, if you have no need for managing the `pagination` state in your own scope, but you need to set different initial values for the `pageIndex` and `pageSize`, you can use the `initialState` option.
+
+```jsx
+const table = useReactTable({
+  columns,
+  data,
+  getCoreRowModel: getCoreRowModel(),
+  getPaginationRowModel: getPaginationRowModel(),
+  initialState: {
+    pagination: {
+      pageIndex: 2, //custom initial page index
+      pageSize: 25, //custom default page size
+    },
+  },
+});
+```
+
+> **Note**: Do NOT pass the `pagination` state to both the `state` and `initialState` options. `state` will overwrite `initialState`. Only use one or the other.
+
+### Pagination Options
+
+Besides the `manualPagination`, `pageCount`, and `rowCount` options which are useful for manual server-side pagination (and discussed [above](#manual-server-side-pagination)), there is one other table option that is useful to understand.
+
+#### Auto Reset Page Index
+
+The `autoResetPageIndex` table option is true by default, and it will reset the `pageIndex` to `0` when page-altering state changes occur, such as when the `data` is updated, filters change, grouping changes, etc. This is useful to prevent the table from showing an empty page when the `pageIndex` is out of range.
+
+However, you can opt out of this behavior by setting the `autoResetPageIndex` option to `false`.
+
+```jsx
+const table = useReactTable({
+  columns,
+  data,
+  getCoreRowModel: getCoreRowModel(),
+  getPaginationRowModel: getPaginationRowModel(),
+  autoResetPageIndex: false, //turn off auto reset of pageIndex
+});
+```
+
+Be aware, however, that if you turn off `autoResetPageIndex`, you may need to add some logic to handle resetting the `pageIndex` yourself to avoid showing empty pages.
+
+### Pagination APIs
+
+There are several pagination table instance APIs that are useful for hooking up your pagination UI components.
+
+#### Pagination Button APIs
+
+- `getCanPreviousPage`: Useful for disabling the "previous page" button when on the first page.
+- `getCanNextPage`: Useful for disabling the "next page" button when there are no more pages.
+- `previousPage`: Useful for going to the previous page. (Button click handler)
+- `nextPage`: Useful for going to the next page. (Button click handler)
+- `firstPage`: Useful for going to the first page. (Button click handler)
+- `lastPage`: Useful for going to the last page. (Button click handler)
+- `setPageIndex`: uUseful for a "go to page" input.
+- `resetPageIndex`: Useful for resetting the table state to the original page index.
+- `setPageSize`: Useful for a "page size" input/select
+- `resetPageSize`: Useful for resetting the table state to the original page size.
+- `setPagination`: Useful for setting all of the pagination state at once.
+- `resetPagination`: Useful for resetting the table state to the original pagination state.
+
+> **Note**: Some of these APIs are new in `v8.13.0`
+
+```jsx
+<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>
+```
+
+#### Pagination Info APIs
+
+- `getPageCount`: Useful for showing the total number of pages.
+- `getRowCount`: Useful for showing the total number of rows.

examples/react/bootstrap/package.json

@@ -16,7 +16,7 @@
     "react-dom": "^18.2.0"
   },
   "devDependencies": {
-    "@faker-js/faker": "^8.3.1",
+    "@faker-js/faker": "^8.4.1",
     "@rollup/plugin-replace": "^5.0.5",
     "@types/bootstrap": "^5.2.10",
     "@types/react": "^18.2.48",

examples/react/column-dnd/package.json

@@ -13,7 +13,7 @@
     "@dnd-kit/modifiers": "^7.0.0",
     "@dnd-kit/sortable": "^8.0.0",
     "@dnd-kit/utilities": "^3.2.2",
-    "@faker-js/faker": "^8.3.1",
+    "@faker-js/faker": "^8.4.1",
     "@tanstack/react-table": "^8.12.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"

examples/react/column-ordering/package.json

@@ -9,7 +9,7 @@
     "start": "vite"
   },
   "dependencies": {
-    "@faker-js/faker": "^8.3.1",
+    "@faker-js/faker": "^8.4.1",
     "@tanstack/react-table": "^8.12.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"

examples/react/column-pinning-sticky/package.json

@@ -9,7 +9,7 @@
     "start": "vite"
   },
   "dependencies": {
-    "@faker-js/faker": "^8.3.1",
+    "@faker-js/faker": "^8.4.1",
     "@tanstack/react-table": "^8.12.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"

examples/react/column-pinning/package.json

@@ -9,7 +9,7 @@
     "start": "vite"
   },
   "dependencies": {
-    "@faker-js/faker": "^8.3.1",
+    "@faker-js/faker": "^8.4.1",
     "@tanstack/react-table": "^8.12.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"

examples/react/column-resizing-performant/package.json

@@ -9,7 +9,7 @@
     "start": "vite"
   },
   "dependencies": {
-    "@faker-js/faker": "^8.3.1",
+    "@faker-js/faker": "^8.4.1",
     "@tanstack/react-table": "^8.12.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"

examples/react/editable-data/package.json

@@ -9,7 +9,7 @@
     "start": "vite"
   },
   "dependencies": {
-    "@faker-js/faker": "^8.3.1",
+    "@faker-js/faker": "^8.4.1",
     "@tanstack/react-table": "^8.12.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"

examples/react/expanding/package.json

@@ -9,7 +9,7 @@
     "start": "vite"
   },
   "dependencies": {
-    "@faker-js/faker": "^8.3.1",
+    "@faker-js/faker": "^8.4.1",
     "@tanstack/react-table": "^8.12.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"

examples/react/filters/package.json

@@ -9,7 +9,7 @@
     "start": "vite"
   },
   "dependencies": {
-    "@faker-js/faker": "^8.3.1",
+    "@faker-js/faker": "^8.4.1",
     "@tanstack/match-sorter-utils": "^8.11.8",
     "@tanstack/react-table": "^8.12.0",
     "react": "^18.2.0",

examples/react/full-width-resizable-table/package.json

@@ -9,7 +9,7 @@
     "start": "vite"
   },
   "dependencies": {
-    "@faker-js/faker": "^8.3.1",
+    "@faker-js/faker": "^8.4.1",
     "@tanstack/react-table": "^8.12.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"

examples/react/full-width-table/package.json

@@ -9,7 +9,7 @@
     "start": "vite"
   },
   "dependencies": {
-    "@faker-js/faker": "^8.3.1",
+    "@faker-js/faker": "^8.4.1",
     "@tanstack/react-table": "^8.12.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"

examples/react/fully-controlled/package.json

@@ -9,7 +9,7 @@
     "start": "vite"
   },
   "dependencies": {
-    "@faker-js/faker": "^8.3.1",
+    "@faker-js/faker": "^8.4.1",
     "@tanstack/react-table": "^8.12.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"

examples/react/grouping/package.json

@@ -9,7 +9,7 @@
     "start": "vite"
   },
   "dependencies": {
-    "@faker-js/faker": "^8.3.1",
+    "@faker-js/faker": "^8.4.1",
     "@tanstack/react-table": "^8.12.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"

examples/react/kitchen-sink/package.json

@@ -19,7 +19,7 @@
   "devDependencies": {
     "@emotion/babel-plugin": "^11.11.0",
     "@emotion/babel-plugin-jsx-pragmatic": "^0.2.1",
-    "@faker-js/faker": "^8.3.1",
+    "@faker-js/faker": "^8.4.1",
     "@rollup/plugin-replace": "^5.0.5",
     "@types/react": "^18.2.48",
     "@types/react-dom": "^18.2.18",