v7.0.0-alpha.21

README.md

@@ -17,6 +17,11 @@ Hooks for building **lightweight, fast and extendable datagrids** for React
 <a href="https://twitter.com/tannerlinsley" target="\_parent">
   <img alt="" src="https://img.shields.io/twitter/follow/tannerlinsley.svg?style=social&label=Follow" />
 </a>
+<br />
+<br />
+<a href="https://patreon.com/tannerlinsley">
+  <img width="180" alt="" src="https://raw.githubusercontent.com/tannerlinsley/files/master/images/patreon/become-a-patron.png" />
+</a>
 
 <br />
 <br />
@@ -46,17 +51,12 @@ Hooks for building **lightweight, fast and extendable datagrids** for React
     <tr>
       <td align="center" valign="middle">
         <a href="https://patreon.com/tannerlinsley" target="_blank">
-          <img src="https://raw.githubusercontent.com/tannerlinsley/files/master/images/patreon/platinum.png">
+          <img width='200' src="https://raw.githubusercontent.com/tannerlinsley/files/master/images/patreon/platinum.png">
         </a>
       </td>
       <td align="center" valign="middle">
         <a href="https://tryretool.com/?utm_source=sponsor&utm_campaign=react_table" target="_blank">
-          <img src="https://raw.githubusercontent.com/tannerlinsley/files/master/images/patreon/sponsor-retool.png">
-        </a>
-      </td>
-      <td align="center" valign="middle">
-        <a href="https://patreon.com/tannerlinsley" target="_blank">
-          <img src="https://raw.githubusercontent.com/tannerlinsley/files/master/images/patreon/platinum-placeholder.png">
+          <img width='480' src="https://raw.githubusercontent.com/tannerlinsley/files/master/images/patreon/sponsor-retool.png">
         </a>
       </td>
     </tr>
@@ -68,22 +68,17 @@ Hooks for building **lightweight, fast and extendable datagrids** for React
     <tr>
       <td align="center" valign="middle">
         <a href="https://patreon.com/tannerlinsley" target="_blank">
-          <img src="https://raw.githubusercontent.com/tannerlinsley/files/master/images/patreon/gold.png">
+          <img width='200' src="https://raw.githubusercontent.com/tannerlinsley/files/master/images/patreon/gold.png">
         </a>
       </td>
       <td align="center" valign="middle">
         <a href="https://nozzle.io" target="_blank">
-          <img width="300" src="https://nozzle.io/img/logo-blue.png">
+          <img width='230' src="https://nozzle.io/img/logo-blue.png">
         </a>
       </td>
       <td align="center" valign="middle">
         <a href="https://zappi.com/web" target="_blank">
-          <img width="300" src="https://raw.githubusercontent.com/tannerlinsley/files/master/images/patreon/sponsor-zappi.png">
-        </a>
-      </td>
-      <td align="center" valign="middle">
-        <a href="https://patreon.com/tannerlinsley" target="_blank">
-          <img src="https://raw.githubusercontent.com/tannerlinsley/files/master/images/patreon/gold-placeholder.png">
+          <img width='230' src="https://raw.githubusercontent.com/tannerlinsley/files/master/images/patreon/sponsor-zappi.png">
         </a>
       </td>
     </tr>
@@ -95,22 +90,7 @@ Hooks for building **lightweight, fast and extendable datagrids** for React
     <tr>
       <td align="center" valign="middle">
         <a href="https://patreon.com/tannerlinsley" target="_blank">
-          <img src="https://raw.githubusercontent.com/tannerlinsley/files/master/images/patreon/silver.png">
-        </a>
-      </td>
-      <td align="center" valign="middle">
-        <a href="https://patreon.com/tannerlinsley" target="_blank">
-          <img src="https://raw.githubusercontent.com/tannerlinsley/files/master/images/patreon/silver-placeholder.png">
-        </a>
-      </td>
-      <td align="center" valign="middle">
-        <a href="https://patreon.com/tannerlinsley" target="_blank">
-          <img src="https://raw.githubusercontent.com/tannerlinsley/files/master/images/patreon/silver-placeholder.png">
-        </a>
-      </td>
-      <td align="center" valign="middle">
-        <a href="https://patreon.com/tannerlinsley" target="_blank">
-          <img src="https://raw.githubusercontent.com/tannerlinsley/files/master/images/patreon/silver-placeholder.png">
+          <img width='200' src="https://raw.githubusercontent.com/tannerlinsley/files/master/images/patreon/silver.png">
         </a>
       </td>
       <td align="center" valign="middle">
@@ -122,6 +102,51 @@ Hooks for building **lightweight, fast and extendable datagrids** for React
   </tbody>
 </table>
 
+<table>
+  <tbody>
+    <tr>
+      <td valign="top">
+        <a href="https://patreon.com/tannerlinsley">
+          <img width='200' src="https://raw.githubusercontent.com/tannerlinsley/files/master/images/patreon/supporters.png" />
+        </a>
+      </td>
+      <td>
+        <ul>
+          <li>Nicholas Kaufmann</li>
+          <li>Pekka</li>
+          <li>Jon Eickmeier</li>
+        </ul>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+<table>
+  <tbody>
+    <tr>
+      <td valign="top">
+        <a href="https://patreon.com/tannerlinsley">
+          <img width='200' src="https://raw.githubusercontent.com/tannerlinsley/files/master/images/patreon/fans.png" />
+        </a>
+      </td>
+      <td>
+        <ul>
+          <li>Sortmy.games</li>
+          <li>Hugo Meissner</li>
+          <li>Benoit Leger-Derville</li>
+          <li>Thomas Funk</li>
+          <li>Dan Houle</li>
+          <li>David Pickut</li>
+        </ul>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+<a href="https://patreon.com/tannerlinsley">
+  <img width="150" alt="" src="https://raw.githubusercontent.com/tannerlinsley/files/master/images/patreon/become-a-patron.png" />
+</a>
+
 # Documentation
 
 - [Installation](#installation)
@@ -157,14 +182,18 @@ import {
 
 # Examples
 
-- [Basic - Client Side](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/basic-client-side)
-- [Sorting - Client Side](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/sorting-client-side)
-- [Filtering - Client Side](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/filtering-client-side)
-- [Grouping - Client Side](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/grouping-client-side)
-- [Pagination - Client Side](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/pagination-client-side)
-- [Row Selection - Client Side](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/row-selection-client-side)
-- [Expanding - Client Side](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/expanding-client-side)
-- [Sub Components](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/sub-components)
+- Simple
+  - [Basic](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/basic)
+  - [Sorting](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/sorting)
+  - [Filtering](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/filtering)
+  - [Grouping](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/grouping)
+  - [Pagination](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/pagination)
+  - [Row Selection](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/row-selection)
+  - [Expanding](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/expanding)
+  - [Sub Components](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/sub-components)
+  - [Editable Data](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/editable-cells)
+- Controlled
+  - [Pagination (Controlled)](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/pagination-controlled)
 
 # Concepts
 
@@ -286,6 +315,11 @@ The following options are supported via the main options object passed to `useTa
   - The default column object for every column passed to React Table.
   - Column-specific properties will override the properties in this object, eg. `{ ...defaultColumn, ...userColumn }`
   - This is particularly useful for adding global column properties. For instance, when using the `useFilters` plugin hook, add a default `Filter` renderer for every column, eg.`{ Filter: MyDefaultFilterComponent }`
+- `initialRowStateKey: String`
+  - Optional
+  - Defaults to `initialState`
+  - This key is used to look for the initial state of a row when initializing the `rowState` for a`data` array.
+  - If the value located at `row[initialRowStateKey]` is falsey, `{}` will be used instead.
 - `debug: Bool`
   - Optional
   - A flag to turn on debug mode.
@@ -359,6 +393,14 @@ The following properties are available on the table instance returned from `useT
 - `flatRows: Array<Row>`
   - An array of all rows, including subRows which have been flattened into the order in which they were detected (depth first)
   - This can be helpful in calculating total row counts that must include subRows
+- `setRowState: Function(rowPath, updater: Function | any) => void`
+  - This function can be used to update the internal state for any row.
+  - Pass it a valid `rowPath` array and `updater`. The `updater` may be a value or function, similar to `React.useState`'s usage.
+  - If `updater` is a function, it will be passed the previous value
+- `setCellState: Function(rowPath, columnID, updater: Function | any) => void`
+  - This function can be used to update the internal state for any cell.
+  - Pass it a valid `rowPath` array, `columnID` and `updater`. The `updater` may be a value or function, similar to `React.useState`'s usage.
+  - If `updater` is a function, it will be passed the previous value
 
 ### `HeaderGroup` Properties
 
@@ -414,6 +456,10 @@ The following additional properties are available on every `row` object returned
   - This array is used with plugin hooks like `useExpanded` and `useGroupBy` to compute expanded states for individual rows.
 - `subRows: Array<Row>`
   - If subRows were detect on the original data object, this will be an array of those materialized row objects.
+- `state: Object`
+
+  - The current state of the row. It's lifespan is attached to that of the original `data` array. When the raw `data` is changed, this state value is reset to the row's initial value (using the `initialRowStateKey` option).
+  - Can be updated via `instance.setRowState` or the row's `setState` function.
 
 ### Cell Properties
 
@@ -552,7 +598,7 @@ The following options are supported via the main options object passed to `useTa
 - `sortTypes: Object<sortKey: sortType>`
   - Must be **memoized**
   - Allows overriding or adding additional sort types for columns to use. If a column's sort type isn't found on this object, it will default to using the [built-in sort types](TODO).
-  - For mor information on sort types, see [Sorting](TODO)
+  - For more information on sort types, see [Sorting](TODO)
 
 ### Column Options
 
@@ -1269,7 +1315,7 @@ The following options are supported via the main options object passed to `useTa
   - Normally, any changes detected to `rows`, `state.filters`, `state.groupBy`, or `state.sortBy` will trigger the `pageIndex` to be reset to `0`
   - If set to `true`, the `pageIndex` will not be automatically set to `0` when these dependencies change.
 
-### Instance Variables
+### Instance Properties
 
 The following values are provided to the table `instance`:
 
@@ -1488,6 +1534,225 @@ function App() {
 
 > Documentation Coming Soon...
 
+## `useRowSelect`
+
+- Plugin Hook
+- Optional
+
+`useRowSelect` is the hook that implements **basic row selection**. For more information on row selection, see [Row Selection](TODO)
+
+### Table Options
+
+The following options are supported via the main options object passed to `useTable(options)`
+
+- `state[0].selectedRows: Array<RowPathKey>`
+  - Optional
+  - Defaults to `[]`
+  - If a row's path key (eg. a row path of `[1, 3, 2]` would have a path key of `1.3.2`) is found in this array, it will have a selected state.
+- `manualRowSelectedKey: String`
+  - Optional
+  - Defaults to `selected`
+  - If this key is found on the **original** data row, and it is true, this row will be manually selected
+
+### Instance Properties
+
+The following values are provided to the table `instance`:
+
+- `toggleRowSelected: Function(rowPath: String, ?set: Bool) => void`
+  - Use this function to toggle a row's selected state.
+  - Optionally pass `true` or `false` to set it to that state
+- `toggleRowSelectedAll: Function(?set: Bool) => void`
+  - Use this function to toggle all rows as select or not
+  - Optionally pass `true` or `false` to set all rows to that state
+- `getToggleAllRowsSelectedProps: Function(props) => props`
+  - Use this function to get the props needed for a **select all checkbox**.
+  - Props:
+    - `onChange: Function()`
+    - `style.cursor: 'pointer'`
+    - `checked: Bool`
+    - `title: 'Toggle All Rows Selected'`
+- `allRowsSelected: Bool`
+  - Will be `true` if all rows are selected.
+  - If at least one row is not selected, will be `false`
+
+### Example
+
+```js
+function Table({ columns, data }) {
+  // Use the state and functions returned from useTable to build your UI
+  const {
+    getTableProps,
+    headerGroups,
+    rows,
+    prepareRow,
+    state: [{ selectedRows }],
+  } = useTable(
+    {
+      columns,
+      data,
+    },
+    useRowSelect
+  )
+
+  // Render the UI for your table
+  return (
+    <>
+      <table {...getTableProps()}>
+        <thead>
+          {headerGroups.map(headerGroup => (
+            <tr {...headerGroup.getHeaderGroupProps()}>
+              {headerGroup.headers.map(column => (
+                <th {...column.getHeaderProps()}>{column.render('Header')}</th>
+              ))}
+            </tr>
+          ))}
+        </thead>
+        <tbody>
+          {rows.map(
+            (row, i) =>
+              prepareRow(row) || (
+                <tr {...row.getRowProps()}>
+                  {row.cells.map(cell => {
+                    return (
+                      <td {...cell.getCellProps()}>{cell.render('Cell')}</td>
+                    )
+                  })}
+                </tr>
+              )
+          )}
+        </tbody>
+      </table>
+      <p>Selected Rows: {selectedRows.length}</p>
+      <pre>
+        <code>{JSON.stringify({ selectedRows }, null, 2)}</code>
+      </pre>
+    </>
+  )
+}
+
+function App() {
+  const columns = React.useMemo(
+    () => [
+      // Let's make a column for selection
+      {
+        id: 'selection',
+        // The header can use the table's getToggleAllRowsSelectedProps method
+        // to render a checkbox
+        Header: ({ getToggleAllRowsSelectedProps }) => (
+          <div>
+            <input type="checkbox" {...getToggleAllRowsSelectedProps()} />
+          </div>
+        ),
+        // The cell can use the individual row's getToggleRowSelectedProps method
+        // to the render a checkbox
+        Cell: ({ row }) => (
+          <div>
+            <input type="checkbox" {...row.getToggleRowSelectedProps()} />
+          </div>
+        ),
+      },
+      {
+        Header: 'Name',
+        columns: [
+          {
+            Header: 'First Name',
+            accessor: 'firstName',
+          },
+          {
+            Header: 'Last Name',
+            accessor: 'lastName',
+          },
+        ],
+      },
+      {
+        Header: 'Info',
+        columns: [
+          {
+            Header: 'Age',
+            accessor: 'age',
+          },
+          {
+            Header: 'Visits',
+            accessor: 'visits',
+          },
+          {
+            Header: 'Status',
+            accessor: 'status',
+          },
+          {
+            Header: 'Profile Progress',
+            accessor: 'progress',
+          },
+        ],
+      },
+    ],
+    []
+  )
+
+  const data = React.useMemo(() => makeData(10), [])
+
+  return <Table columns={columns} data={data} />
+}
+```
+
+## `useRowState`
+
+- Plugin Hook
+- Optional
+
+`useRowState` is a plugin hook that implements **basic state management for _prepared_ rows and their cells**.
+
+### Table Options
+
+The following options are supported via the main options object passed to `useTable(options)`
+
+- `state[0].rowState: Object<RowPathKey:Object<any, cellState: {columnID: Object}>>`
+  - Optional
+  - Defaults to `{}`
+  - If a row's path key (eg. a row path of `[1, 3, 2]` would have a path key of `1.3.2`) is found in this array, it will have the state of the value corresponding to that key.
+  - Individual row states can contain anything, but they also contain a `cellState` key, which provides cell-level state based on column ID's to every
+    **prepared** cell in the table.
+- `initialRowStateAccessor: Function`
+  - Optional
+  - This function may optionally return the initial state for a row.
+  - If this function is defined, it will be passed a `Row` object, from which you can return a value to use as the initial state, eg. `row => row.original.initialState`
+
+### Instance Properties
+
+The following values are provided to the table `instance`:
+
+- `setRowState: Function(rowPath: Array<string>, updater: Function | Any) => void`
+  - Use this function to programmatically update the state of a row.
+  - `updater` can be a function or value. If a `function` is passed, it will receive the current value and expect a new one to be returned.
+- `setCellState: Function(rowPath: Array<string>, columnID: String, updater: Function | Any) => void`
+  - Use this function to programmatically update the cell of a row.
+  - `updater` can be a function or value. If a `function` is passed, it will receive the current value and expect a new one to be returned.
+
+### Row Properties
+
+The following additional properties are available on every **prepared** `row` object returned by the table instance.
+
+- `state: Object`
+  - This is the state object for each row, pre-mapped to the row from the table state's `rowState` object via `rowState[row.path.join('.')]`
+  - May also contain a `cellState` key/value pair, which is used to provide individual cell states to this row's cells
+- `setState: Function(updater: Function | any)`
+  - Use this function to programmatically update the state of a row.
+  - `updater` can be a function or value. If a `function` is passed, it will receive the current value and expect a new one to be returned.
+
+### Cell Properties
+
+The following additional properties are available on every `Cell` object returned in an array of `cells` on every row object.
+
+- `state: Object`
+  - This is the state object for each cell, pre-mapped to the cell from the table state's `rowState` object via `rowState[row.path.join('.')].cellState[columnID]`
+- `setState: Function(updater: Function | any)`
+  - Use this function to programmatically update the state of a cell.
+  - `updater` can be a function or value. If a `function` is passed, it will receive the current value and expect a new one to be returned.
+
+### Example
+
+> Have an example of using useRowState? Submit a PR to add it here!
+
 ## `useTableState`
 
 - Optional

examples/editable-data/src/App.js

@@ -0,0 +1,275 @@
+import React from 'react'
+import styled from 'styled-components'
+import { useTable, usePagination } from 'react-table'
+
+import makeData from './makeData'
+
+const Styles = styled.div`
+  padding: 1rem;
+
+  table {
+    border-spacing: 0;
+    border: 1px solid black;
+
+    tr {
+      :last-child {
+        td {
+          border-bottom: 0;
+        }
+      }
+    }
+
+    th,
+    td {
+      margin: 0;
+      padding: 0.5rem;
+      border-bottom: 1px solid black;
+      border-right: 1px solid black;
+
+      :last-child {
+        border-right: 0;
+      }
+
+      input {
+        font-size: 1rem;
+        padding: 0;
+        margin: 0;
+        border: 0;
+      }
+    }
+  }
+
+  .pagination {
+    padding: 0.5rem;
+  }
+`
+
+// Create an editable cell renderer
+const EditableCell = ({
+  value: initialValue,
+  row: { index },
+  column: { id },
+  updateMyData, // This is a custom function that we supplied to our table instance
+}) => {
+  // We need to keep and update the state of the cell normally
+  const [value, setValue] = React.useState(initialValue)
+  const onChange = e => {
+    setValue(e.target.value)
+  }
+  // We'll only update the external data when the input is blurred
+  const onBlur = () => {
+    updateMyData(index, id, value)
+  }
+  return <input value={value} onChange={onChange} onBlur={onBlur} />
+}
+
+// Set our editable cell renderer as the default Cell renderer
+const defaultColumn = {
+  Cell: EditableCell,
+}
+
+// Be sure to pass our updateMyData and the disablePageResetOnDataChange option
+function Table({ columns, data, updateMyData, disablePageResetOnDataChange }) {
+  // For this example, we're using pagination to illustrate how to stop
+  // the current page from resetting when our data changes
+  // Otherwise, nothing is different here.
+  const {
+    getTableProps,
+    headerGroups,
+    prepareRow,
+    page,
+    canPreviousPage,
+    canNextPage,
+    pageOptions,
+    pageCount,
+    gotoPage,
+    nextPage,
+    previousPage,
+    setPageSize,
+    state: [{ pageIndex, pageSize }],
+  } = useTable(
+    {
+      columns,
+      data,
+      defaultColumn,
+      disablePageResetOnDataChange,
+      // updateMyData isn't part of the API, but
+      // anything we put into these options will
+      // automatically be available on the instance.
+      // That way we can call this function from our
+      // cell renderer!
+      updateMyData,
+    },
+    usePagination
+  )
+
+  // Render the UI for your table
+  return (
+    <>
+      <table {...getTableProps()}>
+        <thead>
+          {headerGroups.map(headerGroup => (
+            <tr {...headerGroup.getHeaderGroupProps()}>
+              {headerGroup.headers.map(column => (
+                <th {...column.getHeaderProps()}>{column.render('Header')}</th>
+              ))}
+            </tr>
+          ))}
+        </thead>
+        <tbody>
+          {page.map(
+            (row, i) =>
+              prepareRow(row) || (
+                <tr {...row.getRowProps()}>
+                  {row.cells.map(cell => {
+                    return (
+                      <td {...cell.getCellProps()}>{cell.render('Cell')}</td>
+                    )
+                  })}
+                </tr>
+              )
+          )}
+        </tbody>
+      </table>
+      <div className="pagination">
+        <button onClick={() => gotoPage(0)} disabled={!canPreviousPage}>
+          {'<<'}
+        </button>{' '}
+        <button onClick={() => previousPage()} disabled={!canPreviousPage}>
+          {'<'}
+        </button>{' '}
+        <button onClick={() => nextPage()} disabled={!canNextPage}>
+          {'>'}
+        </button>{' '}
+        <button onClick={() => gotoPage(pageCount - 1)} disabled={!canNextPage}>
+          {'>>'}
+        </button>{' '}
+        <span>
+          Page{' '}
+          <strong>
+            {pageIndex + 1} of {pageOptions.length}
+          </strong>{' '}
+        </span>
+        <span>
+          | Go to page:{' '}
+          <input
+            type="number"
+            defaultValue={pageIndex + 1}
+            onChange={e => {
+              const page = e.target.value ? Number(e.target.value) - 1 : 0
+              gotoPage(page)
+            }}
+            style={{ width: '100px' }}
+          />
+        </span>{' '}
+        <select
+          value={pageSize}
+          onChange={e => {
+            setPageSize(Number(e.target.value))
+          }}
+        >
+          {[10, 20, 30, 40, 50].map(pageSize => (
+            <option key={pageSize} value={pageSize}>
+              Show {pageSize}
+            </option>
+          ))}
+        </select>
+      </div>
+    </>
+  )
+}
+
+function App() {
+  const columns = React.useMemo(
+    () => [
+      {
+        Header: 'Name',
+        columns: [
+          {
+            Header: 'First Name',
+            accessor: 'firstName',
+          },
+          {
+            Header: 'Last Name',
+            accessor: 'lastName',
+          },
+        ],
+      },
+      {
+        Header: 'Info',
+        columns: [
+          {
+            Header: 'Age',
+            accessor: 'age',
+          },
+          {
+            Header: 'Visits',
+            accessor: 'visits',
+          },
+          {
+            Header: 'Status',
+            accessor: 'status',
+          },
+          {
+            Header: 'Profile Progress',
+            accessor: 'progress',
+          },
+        ],
+      },
+    ],
+    []
+  )
+
+  const [data, setData] = React.useState(() => makeData(20))
+
+  // We need to keep the table from resetting the pageIndex when we
+  // Update data. So we can keep track of that flag with a ref.
+  const skipPageResetRef = React.useRef(false)
+
+  // When our cell renderer calls updateMyData, we'll use
+  // the rowIndex, columnID and new value to update the
+  // original data
+  const updateMyData = (rowIndex, columnID, value) => {
+    // We also turn on the flag to not reset the page
+    skipPageResetRef.current = true
+    setData(old => {
+      return old.filter((row, index) => {
+        if (index === rowIndex) {
+          return {
+            ...old[rowIndex],
+            [columnID]: value,
+          }
+        }
+        return row
+      })
+    })
+  }
+
+  // After data chagnes, we turn the flag back off
+  // so that if data actually changes when we're not
+  // editing it, the page is reset
+  React.useEffect(
+    () => {
+      skipPageResetRef.current = false
+    },
+    [data]
+  )
+
+  // Let's add a data resetter/randomizer to help
+  // illustrate that flow...
+  const resetData = () => setData(makeData(20))
+
+  return (
+    <Styles>
+      <button onClick={resetData}>Reset Data</button>
+      <Table
+        columns={columns}
+        data={data}
+        updateMyData={updateMyData}
+        disablePageResetOnDataChange={skipPageResetRef.current}
+      />
+    </Styles>
+  )
+}
+
+export default App

examples/pagination-controlled/src/App.js

@@ -0,0 +1,276 @@
+import React from 'react'
+import styled from 'styled-components'
+import { useTable, useTableState, usePagination } from 'react-table'
+
+import makeData from './makeData'
+
+const Styles = styled.div`
+  padding: 1rem;
+
+  table {
+    border-spacing: 0;
+    border: 1px solid black;
+
+    tr {
+      :last-child {
+        td {
+          border-bottom: 0;
+        }
+      }
+    }
+
+    th,
+    td {
+      margin: 0;
+      padding: 0.5rem;
+      border-bottom: 1px solid black;
+      border-right: 1px solid black;
+
+      :last-child {
+        border-right: 0;
+      }
+    }
+  }
+
+  .pagination {
+    padding: 0.5rem;
+  }
+`
+
+// Let's add a fetchData method to our Table component that will be used to fetch
+// new data when pagination state changes
+// We can also add a loading state to let our table know it's loading new data
+function Table({
+  columns,
+  data,
+  fetchData,
+  loading,
+  pageCount: controlledPageCount,
+}) {
+  // Use useTableState to hoist the state (and state updater) out of the table and control it
+  const tableState = useTableState({ pageIndex: 0 })
+
+  // Now we can get our table state from the hoisted table state tuple
+  const [{ pageIndex, pageSize }] = tableState
+
+  // Listen for changes in pagination and use the state to fetch our new data
+  React.useEffect(
+    () => {
+      fetchData({ pageIndex, pageSize })
+    },
+    [fetchData, pageIndex, pageSize]
+  )
+
+  const {
+    getTableProps,
+    headerGroups,
+    prepareRow,
+    page,
+    canPreviousPage,
+    canNextPage,
+    pageOptions,
+    pageCount,
+    gotoPage,
+    nextPage,
+    previousPage,
+    setPageSize,
+  } = useTable(
+    {
+      columns,
+      data,
+      state: tableState, // Pass our hoisted table state
+      manualPagination: true, // Tell the usePagination
+      // hook that we'll handle our own data fetching
+      // This means we'll also have to provide our own
+      // pageCount.
+      pageCount: controlledPageCount,
+    },
+    usePagination
+  )
+
+  // Render the UI for your table
+  return (
+    <>
+      <pre>
+        <code>
+          {JSON.stringify(
+            {
+              pageIndex,
+              pageSize,
+              pageCount,
+              canNextPage,
+              canPreviousPage,
+            },
+            null,
+            2
+          )}
+        </code>
+      </pre>
+      <table {...getTableProps()}>
+        <thead>
+          {headerGroups.map(headerGroup => (
+            <tr {...headerGroup.getHeaderGroupProps()}>
+              {headerGroup.headers.map(column => (
+                <th {...column.getHeaderProps()}>{column.render('Header')}</th>
+              ))}
+            </tr>
+          ))}
+        </thead>
+        <tbody>
+          {page.map(
+            (row, i) =>
+              prepareRow(row) || (
+                <tr {...row.getRowProps()}>
+                  {row.cells.map(cell => {
+                    return (
+                      <td {...cell.getCellProps()}>{cell.render('Cell')}</td>
+                    )
+                  })}
+                </tr>
+              )
+          )}
+          {loading ? (
+            // Use our custom loading state to show a loading indicator
+            <tr>
+              <td>Loading...</td>
+            </tr>
+          ) : null}
+        </tbody>
+      </table>
+      {/* 
+        Pagination can be built however you'd like. 
+        This is just a very basic UI implementation:
+      */}
+      <div className="pagination">
+        <button onClick={() => gotoPage(0)} disabled={!canPreviousPage}>
+          {'<<'}
+        </button>{' '}
+        <button onClick={() => previousPage()} disabled={!canPreviousPage}>
+          {'<'}
+        </button>{' '}
+        <button onClick={() => nextPage()} disabled={!canNextPage}>
+          {'>'}
+        </button>{' '}
+        <button onClick={() => gotoPage(pageCount - 1)} disabled={!canNextPage}>
+          {'>>'}
+        </button>{' '}
+        <span>
+          Page{' '}
+          <strong>
+            {pageIndex + 1} of {pageOptions.length}
+          </strong>{' '}
+        </span>
+        <span>
+          | Go to page:{' '}
+          <input
+            type="number"
+            defaultValue={pageIndex + 1}
+            onChange={e => {
+              const page = e.target.value ? Number(e.target.value) - 1 : 0
+              gotoPage(page)
+            }}
+            style={{ width: '100px' }}
+          />
+        </span>{' '}
+        <select
+          value={pageSize}
+          onChange={e => {
+            setPageSize(Number(e.target.value))
+          }}
+        >
+          {[10, 20, 30, 40, 50].map(pageSize => (
+            <option key={pageSize} value={pageSize}>
+              Show {pageSize}
+            </option>
+          ))}
+        </select>
+      </div>
+    </>
+  )
+}
+
+// Let's simulate a large dataset on the server (outside of our component)
+const serverData = makeData(10000)
+
+function App() {
+  const columns = React.useMemo(
+    () => [
+      {
+        Header: 'Name',
+        columns: [
+          {
+            Header: 'First Name',
+            accessor: 'firstName',
+          },
+          {
+            Header: 'Last Name',
+            accessor: 'lastName',
+          },
+        ],
+      },
+      {
+        Header: 'Info',
+        columns: [
+          {
+            Header: 'Age',
+            accessor: 'age',
+          },
+          {
+            Header: 'Visits',
+            accessor: 'visits',
+          },
+          {
+            Header: 'Status',
+            accessor: 'status',
+          },
+          {
+            Header: 'Profile Progress',
+            accessor: 'progress',
+          },
+        ],
+      },
+    ],
+    []
+  )
+
+  // We'll start our table without any data
+  const [data, setData] = React.useState([])
+  const [loading, setLoading] = React.useState(false)
+  const [pageCount, setPageCount] = React.useState(0)
+
+  const fetchData = React.useCallback(({ pageSize, pageIndex }) => {
+    // This will get called when the table needs new data
+    // You could fetch your data from literally anywhere,
+    // even a server. But for this example, we'll just fake it.
+
+    // Set the loading state
+    setLoading(true)
+
+    // We'll even set a delay to simulate a server here
+    setTimeout(() => {
+      const startRow = pageSize * pageIndex
+      const endRow = startRow + pageSize
+      setData(serverData.slice(startRow, endRow))
+
+      // Your server could send back total page count.
+      // For now we'll just fake it, too
+      setPageCount(Math.ceil(serverData.length / pageSize))
+
+      setLoading(false)
+    }, 1000)
+  }, [])
+
+  return (
+    <Styles>
+      <Table
+        columns={columns}
+        data={data}
+        fetchData={fetchData}
+        loading={loading}
+        pageCount={pageCount}
+      />
+    </Styles>
+  )
+}
+
+export default App