diff --git a/docs/api/README.md b/docs/api/README.md index f076137..f5aee21 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -5,7 +5,7 @@ React Table uses React Hooks both internally and externally for almost all of it React Table is essentially a compatible collection of **custom React hooks**: - The primary React Table hook - - [`useTable`](./usetable.md) + - [`useTable`](./useTable.md) - Plugin Hooks - Core Plugin Hooks - [`useGroupBy`](./useGroupBy.md) diff --git a/docs/api/useFilters.md b/docs/api/useFilters.md new file mode 100644 index 0000000..b6e9f78 --- /dev/null +++ b/docs/api/useFilters.md @@ -0,0 +1,96 @@ +# `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` + - 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` + - 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` + - An array of **filtered** rows. +- `preFilteredRows: Array` + - 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` + - 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` + - 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) diff --git a/sizes-cjs.json b/sizes-cjs.json index e17915a..56d4826 100644 --- a/sizes-cjs.json +++ b/sizes-cjs.json @@ -1,4 +1,24 @@ [ + { + "timestamp": 1575620433902, + "files": [ + { + "filename": "index.js", + "size": 21446, + "delta": -1 + } + ] + }, + { + "timestamp": 1575607054721, + "files": [ + { + "filename": "index.js", + "size": 21447, + "delta": 26 + } + ] + }, { "timestamp": 1575605755429, "files": [ diff --git a/sizes-es.json b/sizes-es.json index 2e984af..d96165b 100644 --- a/sizes-es.json +++ b/sizes-es.json @@ -1,4 +1,24 @@ [ + { + "timestamp": 1575620442742, + "files": [ + { + "filename": "index.es.js", + "size": 21225, + "delta": -1 + } + ] + }, + { + "timestamp": 1575607059725, + "files": [ + { + "filename": "index.es.js", + "size": 21226, + "delta": 26 + } + ] + }, { "timestamp": 1575605764195, "files": [ diff --git a/src/plugin-hooks/useSortBy.js b/src/plugin-hooks/useSortBy.js index 4e78b0a..4d9d367 100755 --- a/src/plugin-hooks/useSortBy.js +++ b/src/plugin-hooks/useSortBy.js @@ -48,7 +48,7 @@ function reducer(state, action, previousState, instanceRef) { if (action.type === actions.clearSortBy) { const { sortBy } = state - const newSortBy = sortBy.filter(d => d.id !== action.columnID) + const newSortBy = sortBy.filter(d => d.id !== action.columnId) return { ...state,