ddfa0fa227
- Fixed an issue where dependency hooks were not being reduced properly, thus the table would rerender unnecessarily - Renamed `toggleRowSelectedAll` to `toggleAllRowsSelected`. Duh... - Added an `indeterminate` boolean prop to the default props for row selection toggle prop getters - Renamed `selectedRowPaths` to `selectedRowIds`, which also no longer contains paths, but row IDs - Grouped or nested row selection actions and state are now derived, instead of tracked in state. - Rows now have a new property called `id`, which existed before and was derived from the `getRowId` option - Rows now also have an `isSomeSelected` prop when using the `useRowSelect` hook, which denotes that at least one subRow is selected (if applicable) - Rows' `path` property has been deprecated in favor of `id` - Expanded state is now tracked with row IDs instead of paths - RowState is now tracked with row IDs instead of paths - `toggleExpandedByPath` has been renamed to `toggleExpandedById`, and thus accepts a row ID now, instead of a row path |
||
|---|---|---|
| .. | ||
| README.md | ||
| useAbsoluteLayout.md | ||
| useBlockLayout.md | ||
| useColumnOrder.md | ||
| useExpanded.md | ||
| useFilters.md | ||
| useGroupBy.md | ||
| usePagination.md | ||
| useResizeColumns.md | ||
| useRowSelect.md | ||
| useRowState.md | ||
| useSortBy.md | ||
| useTable.md | ||
| useTokenPagination.md | ||
API
React Table uses React Hooks both internally and externally for almost all of its configuration and lifecycle management. Naturally, this is what allows React Table to be headless and lightweight while still having a concise and simple API.
React Table is essentially a compatible collection of custom React hooks:
- The primary React Table hook
- Plugin Hooks
- 3rd Party Plugin Hooks
- Want your custom plugin hook listed here? Submit a PR!
Hook Usage
useTable is the primary hook used to build a React Table. It serves as the starting point for every option and every plugin hook that React Table supports. The options passed into useTable are supplied to every plugin hook after it in the order they are supplied, eventually resulting in a final instance object that you can use to build your table UI and interact with the table's state.
const instance = useTable(
{
data: [...],
columns: [...],
},
useGroupBy,
useFilters,
useSortBy,
useExpanded,
usePagination
)
The stages of React Table and plugins
useTableis called. A table instance is created.- The
instance.stateis resolved from either a custom user state or an automatically generated one. - A collection of plugin points is created at
instance.hooks. - Each plugin is given the opportunity to add hooks to
instance.hook. - As the
useTablelogic proceeds to run, each plugin hook type is used at a specific point in time with each individual hook function being executed the order it was registered. - The final instance object is returned from
useTable, which the developer then uses to construct their table.
This multi-stage process is the secret sauce that allows React Table plugin hooks to work together and compose nicely, while not stepping on each others toes.
To dive deeper into plugins, see Plugins](TODO) and the [Plugin Guide
Plugin Hook Order & Consistency
The order and usage of plugin hooks must follow The Laws of Hooks, just like any other custom hook. They must always be unconditionally called in the same order.
NOTE: In the event that you want to programmatically enable or disable plugin hooks, most of them provide options to disable their functionality, eg.
options.disableSortBy
Option Memoization
React Table relies on memoization to determine when state and side effects should update or be calculated. This means that every option you pass to useTable should be memoized either via React.useMemo (for objects) or React.useCallback (for functions).