mirror of
https://github.com/gosticks/react-table.git
synced 2026-02-01 14:27:30 +00:00
put useFilters docs in correct file (#1723)
This commit is contained in:
ggascoigne
Tanner Linsley
parent
d1677dfebb
commit
546cb4e076
96
docs/api/useFilters.md
Normal file
96
docs/api/useFilters.md
Normal file
@ -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<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)
|
||||
@ -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)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user