v7.0.0-alpha.22

The renderer function for headers, columns, cells, aggregates, filters, etc used to mix properties
from all of those contexts, including rows. Now thow contexts are located on their own reserved
properties, eg. `Cell: ({ cell: { value}, row, column, ...instance }) => value`

BREAKING CHANGE: The renderer function for headers, columns, cells, aggregates, filters, etc used

README.md

@@ -17,32 +17,31 @@ 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 />
 
 ## Features
 
-- Lightweight
+- Lightweight (4kb - 10kb depending on features and tree-shaking)
 - Headless (100% customizable, Bring-your-own-UI)
 - Client-side & Server-side pagination support
 - Sorting (Multi and Stable)
 - Filters
 - Pivoting & Aggregation
+- Row Selection
+- Row Expansion
 - Fully controllable
-- Extensible via hooks
+- Extensible via hook-based plugin system
 - <a href="https://medium.com/@tannerlinsley/why-i-wrote-react-table-and-the-problems-it-has-solved-for-nozzle-others-445c4e93d4a8#.axza4ixba" target="\_parent">"Why I wrote React Table and the problems it has solved for Nozzle.io"</a> by Tanner Linsley
 
 ## [See Examples](#examples)
 
-## Versions
-
-- This documentation is for version 7.
-- [View the Changelog](https://github.com/tannerlinsley/react-table/blob/master/CHANGELOG.md)
-- Previous versions:
-  - [6.x.x Readme](https://github.com/tannerlinsley/react-table/tree/v6/)
-  - [5.x.x Readme](https://github.com/tannerlinsley/react-table/blob/ad7d31cd3978eb45da7c6194dbab93c1e9a8594d/README.md)
-
 ## Sponsors
 
 **React Table v7** is being built and maintained by me, @tannerlinsley and I am always in need of more Patreon support to keep this project afloat. If you would like to contribute to my Patreon goal for v7 and beyond, [visit my Patreon and help me out!](https://patreon.com/tannerlinsley).
@@ -52,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>
@@ -74,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">
+        <a href="https://zappi.io/web/" target="_blank">
+          <img width='230' src="https://raw.githubusercontent.com/tannerlinsley/files/master/images/patreon/sponsor-zappi.png">
         </a>
       </td>
     </tr>
@@ -101,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">
@@ -128,6 +102,47 @@ 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>
+        <div>Nicholas Kaufmann</div>
+        <div><a href="https://www.metso.com/">Pekka</a></div>
+        <div>Jon Eickmeier</div>
+      </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>
+        <div>Sortmy.games</div>
+        <div>Hugo Meissner</div>
+        <div>Benoit Leger-Derville</div>
+        <div>Thomas Funk</div>
+        <div>Dan Houle</div>
+        <div>David Pickut</div>
+      </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)
@@ -163,11 +178,18 @@ import {
 
 # Examples
 
-- [Basic](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/basic)
-- [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)
+- 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-data)
+- Controlled
+  - [Pagination (Controlled)](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/pagination-controlled)
 
 # Concepts
 
@@ -200,6 +222,8 @@ React Table is essentially a compatible collection of **custom React hooks**:
 
 - The primary React Table hook
   - [`useTable`](#usetable)
+- Utility Hooks
+  - [`useTableState`](#useTableState)
 - Plugin Hooks
   - Core Plugin Hooks
     - [`useTableState`](#useTableState)
@@ -209,6 +233,8 @@ React Table is essentially a compatible collection of **custom React hooks**:
     - [`useExpanded`](#useExpanded)
     - [`usePagination`](#usePagination)
     - [`useTokenPagination`](#useTokenPagination)
+    - [`useRowSelect`](#useRowSelect)
+    - [`useRowState`](#useRowState)
   - Layout Plugin Hooks
     - [`useFlexLayout`](#useFlexLayout)
     - [`useAbsoluteLayout`](#useAbsoluteLayout) (coming soon!)
@@ -272,7 +298,7 @@ The following options are supported via the main options object passed to `useTa
   - Required
   - Must be **memoized**
   - The core columns configuration object for the entire table.
-  - Supports nested `columns` arrays via the `column.children` key
+  - Supports nested `columns` arrays via the column's `columns` key, eg. `[{ Header: 'My Group', columns: [...] }]`
 - `data: Array<any>`
   - Required
   - Must be **memoized**
@@ -289,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.
@@ -320,13 +351,13 @@ The following options are supported on any column object you can pass to `column
   - The data model for hidden columns is still calculated including sorting, filters, and grouping.
 - `Header: String | Function | React.Component => JSX`
   - Optional
-  - Defaults to `({ id }) => id`
+  - Defaults to `() => null`
   - Receives the table instance and column model as props
   - Must either be a **string or return valid JSX**
   - If a function/component is passed, it will be used for formatting the header value, eg. You can use a `Header` function to dynamically format the header using any table or column state.
 - `Cell: Function | React.Component => JSX`
   - Optional
-  - Defaults to `({ value }) => value`
+  - Defaults to `({ cell: { value } }) => value`
   - Receives the table instance and cell model as props
   - Must return valid JSX
   - This function (or component) is primarily used for formatting the column value, eg. If your column accessor returns a date object, you can use a `Cell` function to format that date to a readable format.
@@ -355,6 +386,21 @@ The following properties are available on the table instance returned from `useT
   - **Required**
   - This function is responsible for lazily preparing a row for rendering. Any row that you intend to render in your table needs to be passed to this function **before every render**.
   - **Why?** Since table data could potentially be very large, it can become very expensive to compute all of the necessary state for every row to be rendered regardless if it actually is rendered or not (for example if you are paginating or virtualizing the rows, you may only have a few rows visible at any given moment). This function allows only the rows you intend to display to be computed and prepped with the correct state.
+- `rowPaths: Array<string>`
+  - An array containing the stringified `path` of every original row in the table. eg. If a row has a path of `[0, 3, 2]`, its stringified path would be `0.3.2`.
+  - This array is used by many plugin hooks including `useRowSelect` to manage row selection state
+  - Only rows that exist on the original `data` array will have a path in this array. Rows created by `useGroupBy`'s aggregations and grouping are not included in this array, since they do not reference an original data row.
+- `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
 
@@ -378,7 +424,8 @@ The following properties are available on every `Column` object returned by the
 - `visible: Boolean`
   - The resolved visible state for the column, derived from the column's `show` property
 - `render: Function(type: String | Function | Component, ?props)`
-  - This function is used to render content in context of a column.
+  - This function is used to render content with the added context of a column.
+  - The entire table `instance` will be passed to the renderer with the addition of a `column` property, containing a reference to the column
   - If `type` is a string, will render using the `column[type]` renderer. React Table ships with default `Header` renderers. Other renderers like `Filter` are available via hooks like `useFilters`.
   - If a function or component is passed instead of a string, it will be be passed the table instance and column model as props and is expected to return any valid JSX.
 - `getHeaderProps: Function(?props)`
@@ -401,6 +448,19 @@ The following additional properties are available on every `row` object returned
   - This function is used to resolve any props needed for this row.
   - You can use the `getRowProps` hook to extend its functionality.
   - Custom props may be passed. **NOTE: Custom props will override built-in table props, so be careful!**
+- `index: Int`
+  - The index of the original row in the `data` array that was passed to `useTable`. If this row is a subRow, it is the original index within the parent row's subRows array
+- `original: Object`
+  - The original row object from the `data` array that was used to materialize this row.
+- `path: Array<string>`
+  - This array is the sequential path of indices one could use to navigate to it, eg. a row path of `[3, 1, 0]` would mean that it is the **first** subRow of a parent that is the **second** subRow of a parent that is the **fourth** row in the original `data` array.
+  - 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
 
@@ -419,7 +479,9 @@ The following additional properties are available on every `Cell` object returne
   - You can use the `getCellProps` hook to extend its functionality.
   - Custom props may be passed. **NOTE: Custom props will override built-in table props, so be careful!**
 - `render: Function(type: String | Function | Component, ?props)`
-  - This function is used to render content in context of a cell.
+  - **Required**
+  - This function is used to render content with the added context of a cell.
+  - The entire table `instance` will be passed to the renderer with the addition of `column`, `row` and `cell` properties, containing a reference to each respective item.
   - If `type` is a string, will render using the `column[type]` renderer. React Table ships with a default `Cell` renderer. Other renderers like `Aggregated` are available via hooks like `useFilters`.
   - If a function or component is passed instead of a string, it will be be passed the table instance and cell model as props and is expected to return any valid JSX.
 
@@ -527,6 +589,11 @@ The following options are supported via the main options object passed to `useTa
   - Disables sorting for every column in the entire table.
 - `disableMultiSort: Bool`
   - Disables multi-sorting for the entire table.
+- `isMultiSortEvent: Function`
+  - Allows to override default multisort behaviour(i.e. multisort applies when shift key is presssed), if this function is provided then returned boolean value from this function will make decision whether newly applied sort action will be considered as multisort or not.
+  - Receives `event` as argument.
+- `maxMultiSortColCount: Number`
+  - Limit on max number of columns for multisort, e.g. if set to 3, and suppose table is sorted by `[A, B, C]` and then clicking `D` for sorting should result in table sorted by `[B, C , D]`
 - `disableSortRemove: Bool`
   - If true, the un-sorted state will not be available to columns once they have been sorted.
 - `disableMultiRemove: Bool`
@@ -538,7 +605,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
 
@@ -732,7 +799,7 @@ The following properties are available on every `Column` object returned by the
   - An column-level function used to update the filter value for this column
 - `filterValue: any`
   - The current filter value for this column, resolved from the table state's `filters` object
-- `preFilteredRows: Array<row>`
+- `preFilteredColumnRows: Array<row>`
   - The array of rows that were originally passed to this columns filter **before** they were filtered.
   - This array of rows can be useful if building faceted filter options.
 
@@ -999,7 +1066,7 @@ function App() {
             // then sum any of those counts if they are
             // aggregated further
             aggregate: ['sum', 'count'],
-            Aggregated: ({ value }) => `${value} Names`,
+            Aggregated: ({ cell: { value } }) => `${value} Names`,
           },
           {
             Header: 'Last Name',
@@ -1009,7 +1076,7 @@ function App() {
             // being aggregated, then sum those counts if
             // they are aggregated further
             aggregate: ['sum', 'uniqueCount'],
-            Aggregated: ({ value }) => `${value} Unique Names`,
+            Aggregated: ({ cell: { value } }) => `${value} Unique Names`,
           },
         ],
       },
@@ -1021,14 +1088,14 @@ function App() {
             accessor: 'age',
             // Aggregate the average age of visitors
             aggregate: 'average',
-            Aggregated: ({ value }) => `${value} (avg)`,
+            Aggregated: ({ cell: { value } }) => `${value} (avg)`,
           },
           {
             Header: 'Visits',
             accessor: 'visits',
             // Aggregate the sum of all visits
             aggregate: 'sum',
-            Aggregated: ({ value }) => `${value} (total)`,
+            Aggregated: ({ cell: { value } }) => `${value} (total)`,
           },
           {
             Header: 'Status',
@@ -1039,7 +1106,7 @@ function App() {
             accessor: 'progress',
             // Use our custom roundedMedian aggregator
             aggregate: roundedMedian,
-            Aggregated: ({ value }) => `${value} (med)`,
+            Aggregated: ({ cell: { value } }) => `${value} (med)`,
           },
         ],
       },
@@ -1058,49 +1125,169 @@ function App() {
 - Plugin Hook
 - Optional
 
-`useExpanded` is the hook that implements **row expanding**. It is most often used with `useGroupBy` to expand grouped rows, but is not limited to that use-case. It supports expanding rows both via internal table state and also via a hard-coded key on the raw row model.
+`useExpanded` is the hook that implements **row expanding**. It is most often used with `useGroupBy` to expand grouped rows or on its own with nested `subRows` in tree-li,ke `data` sets, but is not limited to these use-cases. It supports expanding rows both via internal table state and also via a hard-coded key on the raw row model.
 
 ### Table Options
 
 The following options are supported via the main options object passed to `useTable(options)`
 
 - `state[0].expanded: Object<[pathIndex]: Boolean | ExpandedStateObject>`
+  - Optional
   - Must be **memoized**
   - An nested object of expanded paths.
   - A `pathIndex` can be set as the key and its value set to `true` to expand that row's subRows into view. For example, if `{ '3': true }` was passed as the `expanded` state, the **4th row in the original data array** would be expanded.
   - For nested expansion, you may **use another object** instead of a Boolean to expand sub rows. For example, if `{ '3': { '5' : true }}` was passed as the `expanded` state, then the **6th subRow of the 4th row and the 4th row of the original data array** would be expanded.
   - This information is stored in state since the table is allowed to manipulate the filter through user interaction.
 - `subRowsKey: String`
-  - Required
-  - Defaults to `subRows`
-  - React Table will use this key when materializing the final row object. It also uses this key to infer sub-rows from the raw data.
-  - See [Grouping and Aggregation](#grouping-and-aggregation) for more information
-- `paginateSubRows: Bool`
-  - Defaults to `true`
+  - Optional
+  - See the [useTable hook](#table-options) for more details
+- `nestExpandedRows: Bool`
+  - Optional
+  - Defaults to `false`
   - If set to `false`, expanded rows will not be paginated. Thus, any expanded subrows would potentially increase the size of any given page by the amount of total expanded subrows on the page.
 - `manualExpandedKey: String`
+  - Optional
   - Defaults to `expanded`
-  - This string is used as the key to detect manual expanded state on any given row. For example, if a raw data row like `{ name: 'Tanner Linsley', friends: [...], expanded: true}` was detected, it would be forcibly expanded, regardless of state.
+  - This string is used as the key to detect manual expanded state on any given row. For example, if a raw data row like `{ name: 'Tanner Linsley', friends: [...], expanded: true}` was detected, it would always be expanded, regardless of state.
 
-### Instance Variables
+### Instance Properties
 
-The following values are provided to the table `instance`:
+The following properties are available on the table instance returned from `useTable`
 
 - `rows: Array<Row>`
   - An array of **sorted** rows.
 
+### Row Properties
+
+The following additional properties are available on every `row` object returned by the table instance.
+
+- `isExpanded: Bool`
+  - If `true`, this row is in an expanded state.
+- `toggleExpanded: Function(?isExpanded: Bool) => void`
+  - This function will toggle the expanded state of a row between `true` and `false` or, if an `isExpanded` boolean is passed to the function, it will be set as the new `isExpanded` value.
+  - Rows with a hard-coded `manualExpandedKey` (defaults to `expanded`) set to `true` are not affected by this function or the internal expanded state.
+
 ### Example
 
 ```js
-const state = useTableState({ expanded: { '3': true, '5': { '2': true } } })
+function Table({ columns: userColumns, data }) {
+  const {
+    getTableProps,
+    headerGroups,
+    rows,
+    prepareRow,
+    state: [{ expanded }],
+  } = useTable(
+    {
+      columns: userColumns,
+      data,
+    },
+    useExpanded // Use the useExpanded plugin hook
+  )
 
-const { rows } = useTable(
-  {
-    // state[0].sortBy === { '3': true, '5': { '2': true } }
-    state,
-  },
-  useExpanded
-)
+  return (
+    <>
+      <pre>
+        <code>{JSON.stringify({ expanded }, 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>
+          {rows.map(
+            (row, i) =>
+              prepareRow(row) || (
+                <tr {...row.getRowProps()}>
+                  {row.cells.map(cell => {
+                    return (
+                      <td {...cell.getCellProps()}>{cell.render('Cell')}</td>
+                    )
+                  })}
+                </tr>
+              )
+          )}
+        </tbody>
+      </table>
+      <br />
+      <div>Showing the first 20 results of {rows.length} rows</div>
+    </>
+  )
+}
+
+function App() {
+  const columns = React.useMemo(
+    () => [
+      {
+        // Build our expander column
+        Header: () => null, // No header, please
+        id: 'expander', // Make sure it has an ID
+        Cell: ({ row }) =>
+          // Use the row.canExpand and row.getExpandedToggleProps prop getter
+          // to build the toggle for expanding a row
+          row.canExpand ? (
+            <span
+              {...row.getExpandedToggleProps({
+                style: {
+                  // We can even use the row.depth property
+                  // and paddingLeft to indicate the depth
+                  // of the row
+                  paddingLeft: `${row.depth * 2}rem`,
+                },
+              })}
+            >
+              {row.isExpanded ? '👇' : '👉'}
+            </span>
+          ) : null,
+      },
+      {
+        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(5, 5, 5), [])
+
+  return <Table columns={columns} data={data} />
+}
 ```
 
 ## `usePagination`
@@ -1135,7 +1322,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`:
 
@@ -1173,18 +1360,179 @@ The following values are provided to the table `instance`:
 ### Example
 
 ```js
-const state = useTableState({ pageSize: 20, pageIndex: 1 })
+function Table({ columns, data }) {
+  // Use the state and functions returned from useTable to build your UI
+  const {
+    getTableProps,
+    headerGroups,
+    prepareRow,
+    page, // Instead of using 'rows', we'll use page,
+    // which has only the rows for the active page
 
-const { rows } = useTable(
-  {
-    // state[0] === { pageSize: 20, pageIndex: 1 }
-    state,
-  },
-  usePagination
-)
+    // The rest of these things are super handy, too ;)
+    canPreviousPage,
+    canNextPage,
+    pageOptions,
+    pageCount,
+    gotoPage,
+    nextPage,
+    previousPage,
+    setPageSize,
+    state: [{ pageIndex, pageSize }],
+  } = useTable(
+    {
+      columns,
+      data,
+    },
+    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>
+              )
+          )}
+        </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>
+    </>
+  )
+}
+
+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 = React.useMemo(() => makeData(100000), [])
+
+  return (
+    <Styles>
+      <Table columns={columns} data={data} />
+    </Styles>
+  )
+}
 ```
 
-## `useTokenPagination`
+## `useTokenPagination (Coming Soon)`
 
 - Plugin Hook
 - Optional
@@ -1193,6 +1541,225 @@ const { rows } = useTable(
 
 > 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
@@ -1209,7 +1776,7 @@ Some common use cases for this hook are:
 - Disallowing specific states via a custom state reducer
 - Enabling parent/unrelated components to manipulate the table state
 
-### Table Options
+### Hook Options
 
 The following options are supported via the main options object passed to `useTable(options)`
 
@@ -1232,14 +1799,16 @@ The following options are supported via the main options object passed to `useTa
     - Defaults to `React.useState`
     - This function, if defined will be used as the state hook internally instead of the default `React.useState`. This can be useful for implementing custom state storage hooks like useLocalStorage, etc.
 
-### Instance Variables
+### Output
 
 - `tableStateTuple: [tableState, setTableState]`
   - Similar in structure to the result of `React.useState`
-  - **Memoized**. This tuple array will not change between renders unless state or `useTableState` options change.
+  - **Memoized** - This tuple array will not change between renders unless the state or `useTableState` options change.
   - `tableState: Object`
+    - **Memoized** - This object reference will not change unless the state changes.
     - This is the final state object of the table, which is the product of the `initialState`, `overrides` and the `reducer` options (if applicable)
   - `setTableState: Function(updater, type) => void`
+    - **Memoized** - This function reference will not change unless the internal state `reducer` is changed
     - This function is used both internally by React Table, and optionally by you (the developer) to update the table state programmatically.
     - `updater: Function`
       - This function signature is **almost** (see next point) identical to the functional API exposed by `React.setState`. It is passed the previous state and is expected to return a new version of the state.

configs/tests/jest.common.js

@@ -13,4 +13,5 @@ module.exports = {
   rootDir: path.resolve(__dirname, '../../'),
   roots: ['<rootDir>/src', __dirname],
   transformIgnorePatterns: ['node_modules'],
+  snapshotSerializers: [require.resolve('snapshot-diff/serializer.js')],
 }

configs/tests/setup.common.js

@@ -1 +1,2 @@
+import '@testing-library/jest-dom/extend-expect'
 import 'snapshot-diff/extend-expect'

examples/editable-data/README.md

@@ -0,0 +1,6 @@
+This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app) and Rescripts.
+
+You can:
+
+- [Open this example in a new CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/editable-data)
+- `yarn` and `yarn start` to run and edit the example

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/expanding/README.md

@@ -2,5 +2,5 @@ This project was bootstrapped with [Create React App](https://github.com/faceboo
 
 You can:
 
-- [Open this example in a new CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/basic)
+- [Open this example in a new CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/expanding)
 - `yarn` and `yarn start` to run and edit the example

examples/expanding/src/App.js

@@ -33,20 +33,19 @@ const Styles = styled.div`
   }
 `
 
-function Table({ columns: userColumns, data, SubComponent }) {
+function Table({ columns: userColumns, data }) {
   const {
     getTableProps,
     headerGroups,
     rows,
     prepareRow,
-    columns,
     state: [{ expanded }],
   } = useTable(
     {
       columns: userColumns,
       data,
     },
-    useExpanded
+    useExpanded // Use the useExpanded plugin hook
   )
 
   return (
@@ -68,20 +67,13 @@ function Table({ columns: userColumns, data, SubComponent }) {
           {rows.map(
             (row, i) =>
               prepareRow(row) || (
-                <>
-                  <tr {...row.getRowProps()}>
-                    {row.cells.map(cell => {
-                      return (
-                        <td {...cell.getCellProps()}>{cell.render('Cell')}</td>
-                      )
-                    })}
-                  </tr>
-                  {!row.subRows.length && row.isExpanded ? (
-                    <tr>
-                      <td colSpan={columns.length}>{SubComponent({ row })}</td>
-                    </tr>
-                  ) : null}
-                </>
+                <tr {...row.getRowProps()}>
+                  {row.cells.map(cell => {
+                    return (
+                      <td {...cell.getCellProps()}>{cell.render('Cell')}</td>
+                    )
+                  })}
+                </tr>
               )
           )}
         </tbody>
@@ -96,19 +88,26 @@ function App() {
   const columns = React.useMemo(
     () => [
       {
-        Header: () => null,
-        id: 'expander',
-        Cell: ({ row }) => (
-          <span
-            style={{
-              cursor: 'pointer',
-              paddingLeft: `${row.depth * 2}rem`,
-            }}
-            onClick={() => row.toggleExpanded()}
-          >
-            {row.isExpanded ? '👇' : '👉'}
-          </span>
-        ),
+        // Build our expander column
+        Header: () => null, // No header, please
+        id: 'expander', // Make sure it has an ID
+        Cell: ({ row }) =>
+          // Use the row.canExpand and row.getExpandedToggleProps prop getter
+          // to build the toggle for expanding a row
+          row.canExpand ? (
+            <span
+              {...row.getExpandedToggleProps({
+                style: {
+                  // We can even use the row.depth property
+                  // and paddingLeft to indicate the depth
+                  // of the row
+                  paddingLeft: `${row.depth * 2}rem`,
+                },
+              })}
+            >
+              {row.isExpanded ? '👇' : '👉'}
+            </span>
+          ) : null,
       },
       {
         Header: 'Name',
@@ -152,15 +151,7 @@ function App() {
 
   return (
     <Styles>
-      <Table
-        columns={columns}
-        data={data}
-        SubComponent={({ row }) => (
-          <pre>
-            <code>{JSON.stringify({ values: row.values }, null, 2)}</code>
-          </pre>
-        )}
-      />
+      <Table columns={columns} data={data} />
     </Styles>
   )
 }

examples/filtering/README.md

@@ -2,5 +2,5 @@ This project was bootstrapped with [Create React App](https://github.com/faceboo
 
 You can:
 
-- [Open this example in a new CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/basic)
+- [Open this example in a new CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/filtering)
 - `yarn` and `yarn start` to run and edit the example

examples/filtering/src/App.js

@@ -36,14 +36,16 @@ const Styles = styled.div`
 `
 
 // Define a default UI for filtering
-function DefaultColumnFilter({ filterValue, setFilter }) {
+function DefaultColumnFilter({ filterValue, preFilteredRows, setFilter }) {
+  const count = preFilteredRows.length
+
   return (
     <input
       value={filterValue || ''}
       onChange={e => {
         setFilter(e.target.value || undefined) // Set undefined to remove the filter entirely
       }}
-      placeholder="Search..."
+      placeholder={`Search ${count} records...`}
     />
   )
 }
@@ -88,6 +90,7 @@ function SelectColumnFilter({ filterValue, setFilter, preFilteredRows, id }) {
 function SliderColumnFilter({ filterValue, setFilter, preFilteredRows, id }) {
   // Calculate the min and max
   // using the preFilteredRows
+
   const [min, max] = React.useMemo(
     () => {
       let min = 0
@@ -120,7 +123,25 @@ function SliderColumnFilter({ filterValue, setFilter, preFilteredRows, id }) {
 // This is a custom UI for our 'between' or number range
 // filter. It uses two number boxes and filters rows to
 // ones that have values between the two
-function NumberRangeColumnFilter({ filterValue = [], setFilter }) {
+function NumberRangeColumnFilter({
+  filterValue = [],
+  preFilteredRows,
+  setFilter,
+  id,
+}) {
+  const [min, max] = React.useMemo(
+    () => {
+      let min = 0
+      let max = 0
+      preFilteredRows.forEach(row => {
+        min = Math.min(row.values[id], min)
+        max = Math.max(row.values[id], max)
+      })
+      return [min, max]
+    },
+    [id, preFilteredRows]
+  )
+
   return (
     <div
       style={{
@@ -134,7 +155,7 @@ function NumberRangeColumnFilter({ filterValue = [], setFilter }) {
           const val = e.target.value
           setFilter((old = []) => [val ? parseInt(val, 10) : undefined, old[1]])
         }}
-        placeholder="Min"
+        placeholder={`Min (${min})`}
         style={{
           width: '70px',
           marginRight: '0.5rem',
@@ -148,7 +169,7 @@ function NumberRangeColumnFilter({ filterValue = [], setFilter }) {
           const val = e.target.value
           setFilter((old = []) => [old[0], val ? parseInt(val, 10) : undefined])
         }}
-        placeholder="Max"
+        placeholder={`Max (${max})`}
         style={{
           width: '70px',
           marginLeft: '0.5rem',

examples/grouping/README.md

@@ -2,5 +2,5 @@ This project was bootstrapped with [Create React App](https://github.com/faceboo
 
 You can:
 
-- [Open this example in a new CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/basic)
+- [Open this example in a new CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/grouping)
 - `yarn` and `yarn start` to run and edit the example

examples/grouping/src/App.js

@@ -49,9 +49,9 @@ function Table({ columns, data }) {
     useExpanded // useGroupBy would be pretty useless without useExpanded ;)
   )
 
-  // We don't want to render all 2000 rows for this example, so cap
+  // We don't want to render all of the rows for this example, so cap
   // it at 20 for this use case
-  const firstPageRows = rows.slice()
+  const firstPageRows = rows.slice(0, 100)
 
   return (
     <>
@@ -68,7 +68,7 @@ function Table({ columns, data }) {
                   {column.canGroupBy ? (
                     // If the column can be grouped, let's add a toggle
                     <span {...column.getGroupByToggleProps()}>
-                      {column.grouped ? '🛑' : '👊'}
+                      {column.grouped ? '🛑 ' : '👊 '}
                     </span>
                   ) : null}
                   {column.render('Header')}
@@ -102,14 +102,9 @@ function Table({ columns, data }) {
                         {cell.grouped ? (
                           // If it's a grouped cell, add an expander and row count
                           <>
-                            <span
-                              style={{
-                                cursor: 'pointer',
-                              }}
-                              onClick={() => row.toggleExpanded()}
-                            >
+                            <span {...row.getExpandedToggleProps()}>
                               {row.isExpanded ? '👇' : '👉'}
-                            </span>
+                            </span>{' '}
                             {cell.render('Cell')} ({row.subRows.length})
                           </>
                         ) : cell.aggregated ? (
@@ -129,7 +124,7 @@ function Table({ columns, data }) {
         </tbody>
       </table>
       <br />
-      <div>Showing the first 20 results of {rows.length} rows</div>
+      <div>Showing the first 100 results of {rows.length} rows</div>
     </>
   )
 }

examples/pagination-controlled/README.md

@@ -0,0 +1,6 @@
+This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app) and Rescripts.
+
+You can:
+
+- [Open this example in a new CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/pagination-controlled)
+- `yarn` and `yarn start` to run and edit the example

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

examples/pagination-controlled/src/App.test.js

@@ -0,0 +1,9 @@
+import React from 'react'
+import ReactDOM from 'react-dom'
+import App from './App'
+
+it('renders without crashing', () => {
+  const div = document.createElement('div')
+  ReactDOM.render(<App />, div)
+  ReactDOM.unmountComponentAtNode(div)
+})

examples/pagination-controlled/src/index.js

@@ -0,0 +1,12 @@
+import React from 'react'
+import ReactDOM from 'react-dom'
+import './index.css'
+import App from './App'
+import * as serviceWorker from './serviceWorker'
+
+ReactDOM.render(<App />, document.getElementById('root'))
+
+// If you want your app to work offline and load faster, you can change
+// unregister() to register() below. Note this comes with some pitfalls.
+// Learn more about service workers: https://bit.ly/CRA-PWA
+serviceWorker.unregister()

examples/pagination-controlled/src/serviceWorker.js

@@ -0,0 +1,135 @@
+// This optional code is used to register a service worker.
+// register() is not called by default.
+
+// This lets the app load faster on subsequent visits in production, and gives
+// it offline capabilities. However, it also means that developers (and users)
+// will only see deployed updates on subsequent visits to a page, after all the
+// existing tabs open on the page have been closed, since previously cached
+// resources are updated in the background.
+
+// To learn more about the benefits of this model and instructions on how to
+// opt-in, read https://bit.ly/CRA-PWA
+
+const isLocalhost = Boolean(
+  window.location.hostname === 'localhost' ||
+    // [::1] is the IPv6 localhost address.
+    window.location.hostname === '[::1]' ||
+    // 127.0.0.1/8 is considered localhost for IPv4.
+    window.location.hostname.match(
+      /^127(?:\.(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)){3}$/
+    )
+)
+
+export function register(config) {
+  if (process.env.NODE_ENV === 'production' && 'serviceWorker' in navigator) {
+    // The URL constructor is available in all browsers that support SW.
+    const publicUrl = new URL(process.env.PUBLIC_URL, window.location.href)
+    if (publicUrl.origin !== window.location.origin) {
+      // Our service worker won't work if PUBLIC_URL is on a different origin
+      // from what our page is served on. This might happen if a CDN is used to
+      // serve assets; see https://github.com/facebook/create-react-app/issues/2374
+      return
+    }
+
+    window.addEventListener('load', () => {
+      const swUrl = `${process.env.PUBLIC_URL}/service-worker.js`
+
+      if (isLocalhost) {
+        // This is running on localhost. Let's check if a service worker still exists or not.
+        checkValidServiceWorker(swUrl, config)
+
+        // Add some additional logging to localhost, pointing developers to the
+        // service worker/PWA documentation.
+        navigator.serviceWorker.ready.then(() => {
+          console.log(
+            'This web app is being served cache-first by a service ' +
+              'worker. To learn more, visit https://bit.ly/CRA-PWA'
+          )
+        })
+      } else {
+        // Is not localhost. Just register service worker
+        registerValidSW(swUrl, config)
+      }
+    })
+  }
+}
+
+function registerValidSW(swUrl, config) {
+  navigator.serviceWorker
+    .register(swUrl)
+    .then(registration => {
+      registration.onupdatefound = () => {
+        const installingWorker = registration.installing
+        if (installingWorker == null) {
+          return
+        }
+        installingWorker.onstatechange = () => {
+          if (installingWorker.state === 'installed') {
+            if (navigator.serviceWorker.controller) {
+              // At this point, the updated precached content has been fetched,
+              // but the previous service worker will still serve the older
+              // content until all client tabs are closed.
+              console.log(
+                'New content is available and will be used when all ' +
+                  'tabs for this page are closed. See https://bit.ly/CRA-PWA.'
+              )
+
+              // Execute callback
+              if (config && config.onUpdate) {
+                config.onUpdate(registration)
+              }
+            } else {
+              // At this point, everything has been precached.
+              // It's the perfect time to display a
+              // "Content is cached for offline use." message.
+              console.log('Content is cached for offline use.')
+
+              // Execute callback
+              if (config && config.onSuccess) {
+                config.onSuccess(registration)
+              }
+            }
+          }
+        }
+      }
+    })
+    .catch(error => {
+      console.error('Error during service worker registration:', error)
+    })
+}
+
+function checkValidServiceWorker(swUrl, config) {
+  // Check if the service worker can be found. If it can't reload the page.
+  fetch(swUrl)
+    .then(response => {
+      // Ensure service worker exists, and that we really are getting a JS file.
+      const contentType = response.headers.get('content-type')
+      if (
+        response.status === 404 ||
+        (contentType != null && contentType.indexOf('javascript') === -1)
+      ) {
+        // No service worker found. Probably a different app. Reload the page.
+        navigator.serviceWorker.ready.then(registration => {
+          registration.unregister().then(() => {
+            window.location.reload()
+          })
+        })
+      } else {
+        // Service worker found. Proceed as normal.
+        registerValidSW(swUrl, config)
+      }
+    })
+    .catch(() => {
+      console.log(
+        'No internet connection found. App is running in offline mode.'
+      )
+    })
+}
+
+export function unregister() {
+  if ('serviceWorker' in navigator) {
+    navigator.serviceWorker.ready.then(registration => {
+      registration.unregister()
+    })
+  }
+}

examples/pagination/.babelrc

@@ -0,0 +1,4 @@
+{
+  "presets": ["react-app"],
+  "plugins": ["styled-components"]
+}

examples/pagination/.env

@@ -0,0 +1 @@
+SKIP_PREFLIGHT_CHECK=true

examples/pagination/.eslintrc

@@ -0,0 +1,7 @@
+{
+  "extends": ["react-app", "prettier"],
+  "rules": {
+    // "eqeqeq": 0,
+    // "jsx-a11y/anchor-is-valid": 0
+  }
+}

examples/pagination/.gitignore

@@ -0,0 +1,23 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# production
+/build
+
+# misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

examples/pagination/.rescriptsrc.js

@@ -0,0 +1,29 @@
+const path = require('path')
+const resolveFrom = require('resolve-from')
+
+const fixLinkedDependencies = config => {
+  config.resolve = {
+    ...config.resolve,
+    alias: {
+      ...config.resolve.alias,
+      react$: resolveFrom(path.resolve('node_modules'), 'react'),
+      'react-dom$': resolveFrom(path.resolve('node_modules'), 'react-dom'),
+    },
+  }
+  return config
+}
+
+const includeSrcDirectory = config => {
+  config.resolve = {
+    ...config.resolve,
+    modules: [path.resolve('src'), ...config.resolve.modules],
+  }
+  return config
+}
+
+module.exports = [
+  ['use-babel-config', '.babelrc'],
+  ['use-eslint-config', '.eslintrc'],
+  fixLinkedDependencies,
+  // includeSrcDirectory,
+]

examples/pagination/README.md

@@ -0,0 +1,6 @@
+This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app) and Rescripts.
+
+You can:
+
+- [Open this example in a new CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/pagination)
+- `yarn` and `yarn start` to run and edit the example

examples/pagination/package.json

@@ -0,0 +1,35 @@
+{
+  "private": true,
+  "scripts": {
+    "start": "rescripts start",
+    "build": "rescripts build",
+    "test": "rescripts test",
+    "eject": "rescripts eject"
+  },
+  "dependencies": {
+    "namor": "^1.1.2",
+    "react": "^16.8.6",
+    "react-dom": "^16.8.6",
+    "react-scripts": "3.0.1",
+    "react-table": "next",
+    "styled-components": "^4.3.2"
+  },
+  "devDependencies": {
+    "@rescripts/cli": "^0.0.11",
+    "@rescripts/rescript-use-babel-config": "^0.0.8",
+    "@rescripts/rescript-use-eslint-config": "^0.0.9",
+    "babel-eslint": "10.0.1"
+  },
+  "browserslist": {
+    "production": [
+      ">0.2%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ]
+  }
+}

examples/pagination/public/index.html

@@ -0,0 +1,38 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <link rel="shortcut icon" href="%PUBLIC_URL%/favicon.ico" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="theme-color" content="#000000" />
+    <!--
+      manifest.json provides metadata used when your web app is installed on a
+      user's mobile device or desktop. See https://developers.google.com/web/fundamentals/web-app-manifest/
+    -->
+    <link rel="manifest" href="%PUBLIC_URL%/manifest.json" />
+    <!--
+      Notice the use of %PUBLIC_URL% in the tags above.
+      It will be replaced with the URL of the `public` folder during the build.
+      Only files inside the `public` folder can be referenced from the HTML.
+
+      Unlike "/favicon.ico" or "favicon.ico", "%PUBLIC_URL%/favicon.ico" will
+      work correctly both with client-side routing and a non-root public URL.
+      Learn how to configure a non-root public URL by running `npm run build`.
+    -->
+    <title>React App</title>
+  </head>
+  <body>
+    <noscript>You need to enable JavaScript to run this app.</noscript>
+    <div id="root"></div>
+    <!--
+      This HTML file is a template.
+      If you open it directly in the browser, you will see an empty page.
+
+      You can add webfonts, meta tags, or analytics to this file.
+      The build step will place the bundled scripts into the <body> tag.
+
+      To begin the development, run `npm start` or `yarn start`.
+      To create a production bundle, use `npm run build` or `yarn build`.
+    -->
+  </body>
+</html>

examples/pagination/public/manifest.json

@@ -0,0 +1,15 @@
+{
+  "short_name": "React App",
+  "name": "Create React App Sample",
+  "icons": [
+    {
+      "src": "favicon.ico",
+      "sizes": "64x64 32x32 24x24 16x16",
+      "type": "image/x-icon"
+    }
+  ],
+  "start_url": ".",
+  "display": "standalone",
+  "theme_color": "#000000",
+  "background_color": "#ffffff"
+}

examples/pagination/sandbox.config.json

@@ -0,0 +1,3 @@
+{
+  "infiniteLoopProtection": false
+}