vhad/react-table
1
0
Fork 0
mirror of https://github.com/gosticks/react-table.git synced 2026-08-11 20:40:17 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

v7.0.0-rc.2

Browse Source
This commit is contained in:
Tanner Linsley
2019-12-06 16:30:08 -07:00
parent a152704fde
commit 562a2feaef
32 changed files with 765 additions and 808 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api/useExpanded.md
+4 -7
View File
@@ -30,13 +30,10 @@ The following options are supported via the main options object passed to `useTa
- Defaults to `true`
- If set to `true`, expanded rows are rendered along with normal rows.
- If set to `false`, expanded rows will only be available through their parent row. This could be useful if you are implementing a custom expanded row view.
- `getResetExpandedDeps: Function(instance) => [...useEffectDependencies]`
- Optional
- Defaults to resetting the `expanded` state to `[]` when the dependencies below change
- ```js
const getResetExpandedDeps = ({ data }) => [data]
```
- If set, the dependencies returned from this function will be used to determine when the effect to reset the `expanded` state is fired.
- `autoResetExpanded: Boolean`
- Defaults to `true`
- When `true`, the `expanded` state will automatically reset if any of the following conditions are met:
- `data` is changed
- To disable, set to `false`
- For more information see the FAQ ["How do I stop my table state from automatically resetting when my data changes?"](./faq#how-do-i-stop-my-table-state-from-automatically-resetting-when-my-data-changes)
docs/api/usePagination.md
+7 -12
View File
@@ -29,18 +29,13 @@ The following options are supported via the main options object passed to `useTa
- `manualPagination: Bool`
- Enables pagination functionality, but does not automatically perform row pagination.
- Turn this on if you wish to implement your own pagination outside of the table (eg. server-side pagination or any other manual pagination technique)
- `getResetPageDeps: Function(instance) => [...useEffectDependencies]`
- Optional
- Defaults to resetting the `pageIndex` to `0` when the dependencies below change
- ```js
const getResetPageDeps = ({
rows,
manualPagination,
state: { filters, groupBy, sortBy },
}) => [manualPagination ? null : rows, filters, groupBy, sortBy]
```
- Note that if `manualPagination` is set to `true`, then the pageIndex should not be reset when `rows` change
- If set, the dependencies returned from this function will be used to determine when the effect to reset the `pageIndex` state is fired.
- `autoResetPage: Boolean`
- Defaults to `true`
- When `true`, the `expanded` state will automatically reset if `manualPagination` is `false` and any of the following conditions are met:
- `data` is changed
- `manualSortBy` is `false` and `state.sortBy` is changed
- `manualFilters` is `false` and `state.filters` is changed
- `manualGroupBy` is `false` and `state.groupBy` is changed
- To disable, set to `false`
- For more information see the FAQ ["How do I stop my table state from automatically resetting when my data changes?"](./faq#how-do-i-stop-my-table-state-from-automatically-resetting-when-my-data-changes)
- `paginateExpandedRows: Bool`
docs/api/useRowSelect.md
+4 -7
View File
@@ -19,13 +19,10 @@ The following options are supported via the main options object passed to `useTa
- Optional
- Defaults to `isSelected`
- If this key is found on the **original** data row, and it is true, this row will be manually selected
- `getResetSelectedRowPathsDeps: Function(instance) => [...useEffectDependencies]`
- Optional
- Defaults to resetting the `expanded` state to `[]` when the dependencies below change
- ```js
const getResetSelectedRowPathsDeps = ({ rows }) => [rows]
```
- If set, the dependencies returned from this function will be used to determine when the effect to reset the `selectedRowPaths` state is fired.
- `autoResetSelectedRows: Boolean`
- Defaults to `true`
- When `true`, the `expanded` state will automatically reset if any of the following conditions are met:
- `data` is changed
- To disable, set to `false`
- For more information see the FAQ ["How do I stop my table state from automatically resetting when my data changes?"](./faq#how-do-i-stop-my-table-state-from-automatically-resetting-when-my-data-changes)
docs/api/useRowState.md
+4 -7
View File
@@ -21,13 +21,10 @@ The following options are supported via the main options object passed to `useTa
- 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`
- `getResetRowStateDeps: Function(instance) => [...useEffectDependencies]`
- Optional
- Defaults to resetting the `rowState` state to `{}` when the dependencies below change
- ```js
const getResetRowStateDeps = ({ data }) => [data]
```
- If set, the dependencies returned from this function will be used to determine when the effect to reset the `rowState` state is fired.
- `autoResetRowState: Boolean`
- Defaults to `true`
- When `true`, the `rowState` state will automatically reset if any of the following conditions are met:
- `data` is changed
- To disable, set to `false`
- For more information see the FAQ ["How do I stop my table state from automatically resetting when my data changes?"](./faq#how-do-i-stop-my-table-state-from-automatically-resetting-when-my-data-changes)
docs/api/useSortBy.md
+4 -101
View File
@@ -46,10 +46,10 @@ The following options are supported via the main options object passed to `useTa
- 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.
- For more information on sort types, see Sorting
- `getResetSortByDeps: Function(instance) => [...useEffectDependencies]`
- Optional
- Defaults to `false`
- If set, the dependencies returned from this function will be used to determine when the effect to reset the `sortBy` state is fired.
- `autoResetSortBy: Boolean`
- Defaults to `true`
- When `true`, the `sortBy` state will automatically reset if any of the following conditions are met:
- `data` is changed
- To disable, set to `false`
- For more information see the FAQ ["How do I stop my table state from automatically resetting when my data changes?"](./faq#how-do-i-stop-my-table-state-from-automatically-resetting-when-my-data-changes)
@@ -125,100 +125,3 @@ The following properties are available on every `Column` object returned by the
- [Source](https://github.com/tannerlinsley/react-table/tree/master/examples/sorting)
- [Open in CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/sorting)
# `useFilters`
- Plugin Hook
- Optional
`useFilters` is the hook that implements **row filtering**.
### Table Options
The following options are supported via the main options object passed to `useTable(options)`
- `state.filters: Object<columnId: filterValue>`
- Must be **memoized**
- An object of columnId's and their corresponding filter values. This information is stored in state since the table is allowed to manipulate the filter through user interaction.
- `initialState.filters`
- Identical to the `state.filters` option above
- `manualFilters: Bool`
- Enables filter detection functionality, but does not automatically perform row filtering.
- Turn this on if you wish to implement your own row filter outside of the table (eg. server-side or manual row grouping/nesting)
- `disableFilters: Bool`
- Disables filtering for every column in the entire table.
- `defaultCanFilter: Bool`
- Optional
- Defaults to `false`
- If set to `true`, all columns will be filterable, regardless if they have a valid `accessor`
- `filterTypes: Object<filterKey: filterType>`
- Must be **memoized**
- Allows overriding or adding additional filter types for columns to use. If a column's filter type isn't found on this object, it will default to using the built-in filter types.
- For more information on filter types, see Filtering
- `getResetFiltersDeps: Function(instance) => [...useEffectDependencies]`
- Optional
- Defaults to `false`
- If set, the dependencies returned from this function will be used to determine when the effect to reset the `filters` state is fired.
- To disable, set to `false`
- For more information see the FAQ ["How do I stop my table state from automatically resetting when my data changes?"](./faq#how-do-i-stop-my-table-state-from-automatically-resetting-when-my-data-changes)
### Column Options
The following options are supported on any `Column` object passed to the `columns` options in `useTable()`
- `Filter: Function | React.Component => JSX`
- **Required**
- Receives the table instance and column model as props
- Must return valid JSX
- This function (or component) is used to render this column's filter UI, eg.
- `disableFilters: Bool`
- Optional
- If set to `true`, will disable filtering for this column
- `defaultCanFilter: Bool`
- Optional
- Defaults to `false`
- If set to `true`, this column will be filterable, regardless if it has a valid `accessor`
- `filter: String | Function`
- Optional
- Defaults to `text`
- The resolved function from the this string/function will be used to filter the this column's data.
- If a `string` is passed, the function with that name located on either the custom `filterTypes` option or the built-in filtering types object will be used. If
- If a `function` is passed, it will be used directly.
- For more information on filter types, see Filtering
- If a **function** is passed, it must be **memoized**
### Instance Properties
The following values are provided to the table `instance`:
- `rows: Array<Row>`
- An array of **filtered** rows.
- `preFilteredRows: Array<Row>`
- The array of rows **used right before filtering**.
- Among many other use-cases, these rows are directly useful for building option lists in filters, since the resulting filtered `rows` do not contain every possible option.
- `setFilter: Function(columnId, filterValue) => void`
- An instance-level function used to update the filter value for a specific column.
- `setAllFilters: Function(filtersObject) => void`
- An instance-level function used to update the values for **all** filters on the table, all at once.
### Column Properties
The following properties are available on every `Column` object returned by the table instance.
- `canFilter: Bool`
- Denotes whether a column is filterable or not depending on if it has a valid accessor/data model or is manually disabled via an option.
- `setFilter: Function(filterValue) => void`
- A 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>`
- 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.
- `filteredRows: Array<row>`
- The resulting array of rows received from this columns filter **after** they were filtered.
- This array of rows can be useful if building faceted filter options.
### Example
- [Source](https://github.com/tannerlinsley/react-table/tree/master/examples/filtering)
- [Open in CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/filtering)
docs/faq.md
+69 -7
View File
@@ -26,36 +26,98 @@ useTable({
})
```
**It's important that the state override is done within a `useMemo` call to prevent the state variable from changing on every render. It's also just as important that you always use the `state` in any memoization dependencies to ensure that you do not block normal state updates.**
> **It's important that the state override is done within a `useMemo` call to prevent the state variable from changing on every render. It's also extremely important that you always use the `state` in any dependencies to ensure that you do not block normal state updates.**
## How can I debounce rapid table state changes?
React Table has a few built-in side-effects of it's own (most of which are meant for resetting parts of the state when `data` changes). By default, these state side-effects are on and when their conditions are met, they immediately fire off actions that will manipulate the table state. Sometimes, this may result in multiple rapid rerenders (usually just 2, or one more than normal), and could cause any side-effects you have watching the table state to also fire multiple times in-a-row. To alleviate this edge-case, React Table exports a `useAsyncDebounce` function that will allow you to debounce rapid side-effects and only use the latest one.
A good example of this when doing server-side pagination and sorting, a user changes the `sortBy` for a table and the `pageIndex` is automatically reset to `0` via an internal side effect. This would normally cause our effect below to fire 2 times, but with `useAsyncDebounce` we can make sure our data fetch function only gets called once:
```js
import { useTable, useAsyncDebounce } from 'react-table'
function Table({ data, onFetchData }) {
const {
state: { pageIndex, pageSize, sortBy, filters },
} = useTable({
data,
})
// Debounce our onFetchData call for 100ms
const onFetchDataDebounced = useAsyncDebounce(onFetchData, 100)
// When the these table states changes, fetch new data!
React.useEffect(() => {
// Every change will call our debounced function
onFetchDataDebounced({ pageIndex, pageSize, sortBy, filters })
// Only the last call after the 100ms debounce is over will be fired!
}, [onFetchDataDebounced, pageIndex, pageSize, sortBy, filters])
return </>
}
```
## How can I use the table state to fetch new data?
When managing your data externally or asynchronously (eg. server-side pagination/sorting/grouping/etc), you will need to fetch new data as the internal table state changes. With React Hooks, this is fantastically easier than it was before now that we have the `React.useEffect` hook. We can use this hook to "watch" the table state for specific changes and use those effects to trigger fetches for new data (or synchronize any other state you may be managing externally from your table component):
```js
function Table({ data, onFetchData }) {
const {
state: { pageIndex, pageSize, sortBy, filters },
} = useTable({
data,
})
// When the these table states change, fetch new data!
React.useEffect(() => {
onFetchData({ pageIndex, pageSize, sortBy, filters })
}, [fetchData, pageIndex, pageSize, sortBy, filters])
return </>
}
```
Using this approach, you can respond and trigger any type of side-effect using the table instance!
## How do I stop my table state from automatically resetting when my data changes?
Most plugins use state that _should_ normally reset when the data sources changes, but sometimes you need to suppress that from happening if you are filtering your data externally, or immutably editing your data while looking at it, or simply doing anything external with your data that you don't want to trigger a piece of table state to reset automatically.
For those situations, each plugin provides options like `getResetPageDeps` or `getResetExpandedDeps`, so and an so forth. These functions are provided the table `instance` and allowed to return an array of variables that will be injected into the `React.useEffect`'s dependency array that is responsible for watching and resetting those states. By returning a new array in one of these arrays, you can either stop the automatic resets from being triggered, or even trigger them more based on what you are returning. You can also return `false` for any of these options to disable the automatic resets completely, or pass `undefined` to allow the default dependendies to be used.
For those situations, each plugin provides a way to disable the state from automatically resetting internally when data or other dependencies for a piece of state change. By setting any of them to `false`, you can stop the automatic resets from being triggered.
Here is an example of completely disabling the page from resetting when data changes:
Here is an example of stopping basically every piece of state from changing as they normally do while we edit the `data` source for a table:
```js
const [data, setData] = React.useState([])
const skipPageResetRef = React.useRef()
const updateData = newData => {
// When data gets updated with this function, disable the
// page from resetting
// When data gets updated with this function, set a flag
// to disable all of the auto resetting
skipPageResetRef.current = true
setData(newData)
}
React.useEffect(() => {
// After the table has updated, always remove the flag
skipPageResetRef.current = false
})
useTable({
data,
getResetPageDeps: skipPageReset ? false : undefined,
...
autoResetPage: !skipPageReset,
autoResetExpanded: !skipPageReset,
autoResetGroupBy: !skipPageReset,
autoResetSelectedRows: !skipPageReset,
autoResetSortBy: !skipPageReset,
autoResetFilters: !skipPageReset,
autoResetRowState: !skipPageReset,
})
```
Now, when we update our data, the above table states will not automatically reset!
<!-- ## How can I hide/show columns? -->