From fb94ea91d8442fd32accdaa4842a08560e4aa1f4 Mon Sep 17 00:00:00 2001 From: Tanner Linsley Date: Wed, 27 Apr 2022 16:23:45 -0600 Subject: [PATCH] fix: _notifyFoo => queueFoo, onChangeFns no longer supply pre-calcluated state, getIsColumnFiltered => getColumnIsFiltered, removed getPreFilteredRowModel, docs: added filteres API --- docs/api/README.md | 74 --- docs/api/column-ordering.md | 3 + docs/api/column-resizing.md | 3 + docs/api/core.md | 3 + docs/api/expanding.md | 3 + docs/api/filters.md | 547 ++++++++++++++++++ docs/api/grouping.md | 3 + docs/api/pagination.md | 3 + docs/api/row-selection.md | 3 + docs/api/sorting.md | 3 + docs/api/useAbsoluteLayout.md | 49 -- docs/api/useBlockLayout.md | 43 -- docs/api/useColumnOrder.md | 33 -- docs/api/useExpanded.md | 71 --- docs/api/useFilters.md | 102 ---- docs/api/useFlexLayout.md | 49 -- docs/api/useGlobalFilter.md | 68 --- docs/api/useGroupBy.md | 134 ----- docs/api/usePagination.md | 91 --- docs/api/useResizeColumns.md | 41 -- docs/api/useRowSelect.md | 78 --- docs/api/useRowState.md | 71 --- docs/api/useSortBy.md | 131 ----- docs/api/useTable.md | 284 --------- docs/api/useTokenPagination.md | 14 - docs/examples/basic.mdx | 23 + docs/examples/column-ordering.mdx | 23 + docs/examples/column-pinning.mdx | 23 + docs/examples/column-sizing.mdx | 23 + docs/examples/column-visibility.mdx | 23 + docs/examples/complex.mdx | 25 - docs/examples/controlled.mdx | 23 - docs/examples/editable-data.mdx | 23 + docs/examples/expanding.mdx | 23 + docs/examples/filters.mdx | 23 + docs/examples/fully-controlled.mdx | 23 + docs/examples/grouping.mdx | 23 + docs/examples/pagination.mdx | 23 + docs/examples/row-selection.mdx | 23 + docs/examples/simple.mdx | 108 ---- docs/examples/sorting.mdx | 23 + docs/examples/ui.mdx | 65 --- docs/guides/filters.md | 39 ++ docs/quickstart.mdx | 178 ------ examples/row-selection/src/main.tsx | 3 +- .../table-core/src/features/ColumnSizing.ts | 10 +- packages/table-core/src/features/Expanding.ts | 12 +- packages/table-core/src/features/Filters.ts | 29 +- packages/table-core/src/features/Grouping.ts | 12 +- packages/table-core/src/features/Ordering.ts | 5 +- .../table-core/src/features/Pagination.ts | 9 +- packages/table-core/src/features/Pinning.ts | 5 +- .../table-core/src/features/RowSelection.ts | 15 +- packages/table-core/src/features/Sorting.ts | 12 +- .../table-core/src/features/Visibility.ts | 5 +- packages/table-core/src/types.ts | 2 +- .../utils/getColumnFilteredRowModelAsync.ts | 2 +- .../utils/getColumnFilteredRowModelSync.ts | 2 +- .../src/utils/getCoreRowModelAsync.ts | 4 +- .../src/utils/getCoreRowModelSync.ts | 4 +- .../utils/getGlobalFilteredRowModelAsync.ts | 2 +- .../utils/getGlobalFilteredRowModelSync.ts | 2 +- .../src/utils/getGroupedRowModel.ts | 2 +- .../src/utils/getSortedRowModelAsync.ts | 2 +- .../src/utils/getSortedRowModelSync.ts | 2 +- 65 files changed, 958 insertions(+), 1824 deletions(-) delete mode 100644 docs/api/README.md create mode 100644 docs/api/column-ordering.md create mode 100644 docs/api/column-resizing.md create mode 100644 docs/api/core.md create mode 100644 docs/api/expanding.md create mode 100644 docs/api/filters.md create mode 100644 docs/api/grouping.md create mode 100644 docs/api/pagination.md create mode 100644 docs/api/row-selection.md create mode 100644 docs/api/sorting.md delete mode 100644 docs/api/useAbsoluteLayout.md delete mode 100644 docs/api/useBlockLayout.md delete mode 100644 docs/api/useColumnOrder.md delete mode 100644 docs/api/useExpanded.md delete mode 100644 docs/api/useFilters.md delete mode 100644 docs/api/useFlexLayout.md delete mode 100644 docs/api/useGlobalFilter.md delete mode 100644 docs/api/useGroupBy.md delete mode 100644 docs/api/usePagination.md delete mode 100644 docs/api/useResizeColumns.md delete mode 100644 docs/api/useRowSelect.md delete mode 100644 docs/api/useRowState.md delete mode 100644 docs/api/useSortBy.md delete mode 100644 docs/api/useTable.md delete mode 100644 docs/api/useTokenPagination.md create mode 100644 docs/examples/basic.mdx create mode 100644 docs/examples/column-ordering.mdx create mode 100644 docs/examples/column-pinning.mdx create mode 100644 docs/examples/column-sizing.mdx create mode 100644 docs/examples/column-visibility.mdx delete mode 100644 docs/examples/complex.mdx delete mode 100644 docs/examples/controlled.mdx create mode 100644 docs/examples/editable-data.mdx create mode 100644 docs/examples/expanding.mdx create mode 100644 docs/examples/filters.mdx create mode 100644 docs/examples/fully-controlled.mdx create mode 100644 docs/examples/grouping.mdx create mode 100644 docs/examples/pagination.mdx create mode 100644 docs/examples/row-selection.mdx delete mode 100644 docs/examples/simple.mdx create mode 100644 docs/examples/sorting.mdx delete mode 100644 docs/examples/ui.mdx create mode 100644 docs/guides/filters.md delete mode 100644 docs/quickstart.mdx diff --git a/docs/api/README.md b/docs/api/README.md deleted file mode 100644 index eb91794149..0000000000 --- a/docs/api/README.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -name: Overview -route: /api -menu: API ---- - -# 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 - - [`useTable`](./api/useTable) -- Plugin Hooks - - Core Plugin Hooks - - [`useGroupBy`](./api/useGroupBy) - - [`useFilters`](./api/useFilters) - - [`useGlobalFilter`](./api/useGlobalFilter) - - [`useSortBy`](./api/useSortBy) - - [`useExpanded`](./api/useExpanded) - - [`usePagination`](./api/usePagination) - - [`useTokenPagination` (Coming Soon)](./api/useTokenPagination) - - [`useRowSelect`](./api/useRowSelect) - - [`useRowState`](./api/useRowState) - - [`useColumnOrder`](./api/useColumnOrder) - - Layout Hooks - - [`useBlockLayout`](./api/useBlockLayout) - - [`useAbsoluteLayout`](./api/useAbsoluteLayout) - - [`useFlexLayout`](./api/useFlexLayout) - - [`useResizeColumns`](./api/useResizeColumns) -- 3rd Party Plugin Hooks - - Want your custom plugin hook listed here? [Submit a PR!](https://github.com/tanstack/react-table/compare) - -### 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. - -```js -const instance = useTable( - { - data: [...], - columns: [...], - }, - useGroupBy, - useFilters, - useSortBy, - useExpanded, - usePagination -) -``` - -### The stages of React Table and plugins - -1. `useTable` is called. A table instance is created. -1. The `instance.state` is resolved from either a custom user state or an automatically generated one. -1. A collection of plugin points is created at `instance.hooks`. -1. Each plugin is given the opportunity to add hooks to `instance.hook`. -1. As the `useTable` logic 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. -1. 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 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`](https://reactjs.org/docs/hooks-reference.html#usememo) (for objects) or [`React.useCallback`](https://reactjs.org/docs/hooks-reference.html#usecallback) (for functions). diff --git a/docs/api/column-ordering.md b/docs/api/column-ordering.md new file mode 100644 index 0000000000..badcb7ab76 --- /dev/null +++ b/docs/api/column-ordering.md @@ -0,0 +1,3 @@ +TODO + +Please duplicate a completed api file as a template to get started! diff --git a/docs/api/column-resizing.md b/docs/api/column-resizing.md new file mode 100644 index 0000000000..badcb7ab76 --- /dev/null +++ b/docs/api/column-resizing.md @@ -0,0 +1,3 @@ +TODO + +Please duplicate a completed api file as a template to get started! diff --git a/docs/api/core.md b/docs/api/core.md new file mode 100644 index 0000000000..badcb7ab76 --- /dev/null +++ b/docs/api/core.md @@ -0,0 +1,3 @@ +TODO + +Please duplicate a completed api file as a template to get started! diff --git a/docs/api/expanding.md b/docs/api/expanding.md new file mode 100644 index 0000000000..badcb7ab76 --- /dev/null +++ b/docs/api/expanding.md @@ -0,0 +1,3 @@ +TODO + +Please duplicate a completed api file as a template to get started! diff --git a/docs/api/filters.md b/docs/api/filters.md new file mode 100644 index 0000000000..730ff0f722 --- /dev/null +++ b/docs/api/filters.md @@ -0,0 +1,547 @@ +--- +name: Filters +route: /api/filtering +menu: API +--- + +- [Read Guide](../guides/filters) + +## Examples + +- TODO +- TODO +- TODO + +## State + +Filter state is stored on the table instance using the following shape: + +```tsx +export type FiltersTableState = { + columnFilters: ColumnFiltersState + globalFilter: any + columnFiltersProgress: number + globalFilterProgress: number +} + +export type ColumnFiltersState = ColumnFilter[] + +export type ColumnFilter = { + id: string + value: unknown +} +``` + +## Filter Functions + +The following filter functions are built-in to the table core: + +- `includesString` + - Case-insensitive string inclusion +- `includesStringSensitive` + - Case-sensitive string inclusion +- `equalsString` + - Case-insensitive string equality +- `equalsStringSensitive` + - Case-sensitive string equality +- `arrIncludes` + - Item inclusion within an array +- `arrIncludesAll` + - All items included in an array +- `equals` + - Object/referential equality `Object.is`/`===` +- `weakEquals` + - Weak object/referential equality `==` +- `betweenNumberRange` + - Number range inclusion + +Every filter function adheres to the following shape: + +```tsx +export type FilterFn = { + (rows: Row[], columnIds: string[], filterValue: any): any + autoRemove?: ColumnFilterAutoRemoveTestFn +} + +export type ColumnFilterAutoRemoveTestFn = ( + value: unknown, + column?: Column +) => boolean + +export type CustomFilterFns = Record< + string, + FilterFn +> +``` + +Filter functions can be referenced/defined in the following ways: + +- Built-in filter functions +- Custom filter functions provided via the `tableOptions.filterFns` option +- Inline-filter functions defined on `columnDefinition.filterFn` properties + +The final list of filter functions available for the `columnDefnition.filterFn` and ``tableOptions.globalFilterFn` options use the following type: + +```tsx +export type FilterFnOption = + | 'auto' + | BuiltInFilterFn + | keyof TGenerics['FilterFns'] + | FilterFn +``` + +## Column Definition Options + +### `filterFn` + +```tsx +filterFn?: FilterFn | keyof TGenerics['FilterFns'] | keyof BuiltInFilterFns +``` + +The filter function to use with this column. + +Options: + +- A `string` referencing a [built-in filter function](#filter-functions)) +- A `string` referencing a custom filter function defined on the `filterFns` table option +- A [custom filter function](#filter-functions) + +### `enableAllFilters` + +```tsx +enableAllFilters?: boolean +``` + +Enables/disables **all** filters for this column. For option priority, see [Can-Filter Option Priority](../guides/filters#can-filter-option-priority). + +### `enableColumnFilter` + +```tsx +enableColumnFilter?: boolean +``` + +Enables/disables the **column** filter for this column. For option priority, see [Can-Filter Option Priority](../guides/filters#can-filter-option-priority). + +### `enableGlobalFilter` + +```tsx +enableGlobalFilter?: boolean +``` + +Enables/disables the **global** filter for this column. For option priority, see [Can-Filter Option Priority](../guides/filters#can-filter-option-priority). + +### `defaultCanFilter` + +```tsx +defaultCanFilter?: boolean +``` + +If set, will serve as a fallback for enabling/disabling **all** filters for this column. For option priority, see [Can-Filter Option Priority](../guides/filters#can-filter-option-priority). + +### `defaultCanColumnFilter` + +```tsx +defaultCanColumnFilter?: boolean +``` + +If set, will serve as a fallback for enabling/disabling **column** filters for this column. For option priority, see [Can-Filter Option Priority](../guides/filters#can-filter-option-priority). + +### `defaultCanGlobalFilter` + +```tsx +defaultCanGlobalFilter?: boolean +``` + +If set, will serve as a fallback for enabling/disabling the **global** filter for this column. For option priority, see [Can-Filter Option Priority](../guides/filters#can-filter-option-priority). + +## Column API + +### `getCanColumnFilter` + +```tsx +getCanColumnFilter: () => boolean +``` + +Returns whether or not the column can be **column** filtered. + +### `getCanGlobalFilter` + +```tsx +getCanGlobalFilter: () => boolean +``` + +Returns whether or not the column can be **globally** filtered. + +### `getColumnFilterIndex` + +```tsx +getColumnFilterIndex: () => number +``` + +Returns the index (including `-1`) of the column filter in the table's `state.columnFilters` array. + +### `getColumnIsFiltered` + +```tsx +getColumnIsFiltered: () => boolean +``` + +Returns whether or not the column is currently filtered. + +### `getColumnFilterValue` + +```tsx +getColumnFilterValue: () => unknown +``` + +Returns the current filter value of the column. + +### `setColumnFilterValue` + +```tsx +setColumnFilterValue: (updater: Updater) => void +``` + +A function that sets the current filter value for the column. You can pass it a value or an updater function for immutability-safe operations on existing values. + +### `getPreFilteredRows` + +```tsx +getPreFilteredRows: () => (Row < TGenerics > []) | undefined +``` + +Returns the rows that were present before this column's filter has been applied. Useful for displaying faceted result counts. + +### `getPreFilteredUniqueValues` + +```tsx +getPreFilteredUniqueValues: () => Map +``` + +A function that **computes and returns** a `Map` of unique values and their occurences that were present before this column's filter was applied. Useful for displaying faceted result values. + +### `getPreFilteredMinMaxValues` + +```tsx +getPreFilteredMinMaxValues: () => Map +``` + +A function that **computes and returns** a min/max tuple derived from the values that were present before this column's filter was applied. Useful for displaying faceted result values. + +## Table Options + +### `filterFromLeafRows` + +```tsx +filterFromLeafRows?: boolean +``` + +By default, filtering is done from parent rows down (so if a parent row is filtered out, all of its children will be filtered out as well). Setting this option to `true` will cause filtering to be done from leaf rows up (which means parent rows will be included so long as one of their child or grand-child rows is also included). + +### `filterFns` + +```tsx +filterFns?: Record +``` + +Normally set ahead of time when using the `createTable()` helper, this option allows you to define custom filter functions that can be referenced by their string key. + +Example: + +```tsx +const table = createTable().setOptions({ + filterFns: { + myCustomFilterFn: (rows, columnIds, filterValue) => { + // return the filtered rows + }, + }, +}) + +const column = table.createDataColumn('key', { + filterFn: 'myCustomFilterFn', +}) +``` + +### `enableFilters` + +```tsx +enableFilters?: boolean +``` + +Enabled/disables all filters for the table. For option priority, see [Can-Filter Option Priority](../guides/filters#can-filter-option-priority). + +### `onColumnFiltersChange` + +```tsx +onColumnFiltersChange?: OnChangeFn +``` + +If provided, this function will be called with an `updaterFn` when `state.columnFilters` changes. This overrides the default internal state management, so you will need to persist the state change either fully or partially outside of the table. + +### `autoResetColumnFilters` + +```tsx +autoResetColumnFilters?: boolean +``` + +**Default: `true`** + +If set will enable/disable the automatic reset of column filters when it's dependent rows/states change. + +### `enableColumnFilters` + +```tsx +enableColumnFilters?: boolean +``` + +Enables/disables **all** column filters for the table. For option priority, see [Can-Filter Option Priority](../guides/filters#can-filter-option-priority). + +### `getColumnFilteredRowModel` + +```tsx +getColumnFilteredRowModel?: ( + instance: TableInstance +) => () => RowModel +``` + +If provided, this function is called **once** per table instance and should return a **new function** which will calculate and return the row model for the table when it's filtered. + +- For server-side filtering, this function is unnecessary and can be ignored since the server should already return the filtered row model. +- For client-side filtering, this function is required. A default implementation is provided via any table adapter's `{ getColumnFilteredRowModel }` export. + +Example: + +```tsx +import { getColumnFilteredRowModel } from 'react-table' + +useTable(table, { + getColumnFilteredRowModel: getColumnFilteredRowModel, +}) +``` + +### `globalFilterFn` + +```tsx +globalFilterFn?: FilterFn | keyof TGenerics['FilterFns'] | keyof BuiltInFilterFns +``` + +The filter function to use for global filtering. + +Options: + +- A `string` referencing a [built-in filter function](#filter-functions)) +- A `string` referencing a custom filter function defined on the `filterFns` table option +- A [custom filter function](#filter-functions) + +### `onGlobalFilterChange` + +```tsx +onGlobalFilterChange?: OnChangeFn +``` + +If provided, this function will be called with an `updaterFn` when `state.globalFilter` changes. This overrides the default internal state management, so you will need to persist the state change either fully or partially outside of the table. + +### `autoResetGlobalFilter` + +```tsx +autoResetGlobalFilter?: boolean +``` + +**Default: `true`** + +If set will enable/disable the automatic reset of the global filter when it's dependent rows/states change. + +### `enableGlobalFilter` + +```tsx +enableGlobalFilter?: boolean +``` + +Enables/disables the global filter for the table. For option priority, see [Can-Filter Option Priority](../guides/filters#can-filter-option-priority). + +### `getGlobalFilteredRowModel` + +```tsx +getGlobalFilteredRowModel?: ( + instance: TableInstance +) => () => RowModel +``` + +If provided, this function is called **once** per table instance and should return a **new function** which will calculate and return the row model for the table when it's globally filtered. + +- For server-side filtering, this function is unnecessary and can be ignored since the server should already return the globally filtered row model. +- For client-side filtering, this function is required. A default implementation is provided via any table adapter's `{ getGlobalFilteredRowModel }` export. + +Example: + +```tsx +import { getGlobalFilteredRowModel } from 'react-table' + +useTable(table, { + getGlobalFilteredRowModel: getGlobalFilteredRowModel, +}) +``` + +### `getColumnCanGlobalFilterFn` + +```tsx +getColumnCanGlobalFilterFn?: (column: Column) => boolean +``` + +If provided, this function will be called with the column and should return `true` or `false` to indicate whether this column should be used for global filtering. + +## Table Instance API + +### `queueResetFilters` + +```tsx +queueResetFilters: () => void +``` + +Queues a reset of all filters for the table. + +> ℹ️ Normally, this is called internally when memoization dependencies change and if `autoResetColumnFilters` or `autoResetGlobalFilter` is on. By queuing instead of directly resetting, you can indicate the reset in the middle of a call to methods like `getRowModel()` or during your frameworks current lifecycle event without having adverse effects. This reset will be applied as soon as possible after the current lifecycle phase (the exact implementation of this timing depends on the framework adapter). + +### `getColumnAutoFilterFn` + +```tsx +getColumnAutoFilterFn: (columnId: string) => FilterFn | undefined +``` + +Returns an automatically calculated filter function for the column based off of the columns first known value. + +### `getColumnFilterFn` + +```tsx +getColumnFilterFn: (columnId: string) => FilterFn | undefined +``` + +Returns the filter function (either user-defined or automatic, depending on configuration) for the columnId specified. + +### `setColumnFilters` + +```tsx +setColumnFilters: (updater: Updater) => void +``` + +Sets or updates the `state.columnFilters` state. + +### `setColumnFilterValue` + +```tsx +setColumnFilterValue: (columnId: string, updater: Updater) => void +``` + +Sets or updates the filter value for the columnId specified. + +### `resetColumnFilters` + +```tsx +resetColumnFilters: () => void +``` + +Resets the **column** filter state for the table. + +### `getColumnCanColumnFilter` + +```tsx +getColumnCanColumnFilter: (columnId: string) => boolean +``` + +Returns if the column with specified columnId can be filtered. + +### `getColumnIsFiltered` + +```tsx +getColumnIsFiltered: (columnId: string) => boolean +``` + +Returns if the column with the specified columnId is currently filtered. + +### `getColumnFilterValue` + +```tsx +getColumnFilterValue: (columnId: string) => unknown +``` + +Returns the current filter value of the column. + +### `getColumnFilterIndex` + +```tsx +getColumnFilterIndex: (columnId: string) => unknown +``` + +Returns the index (including `-1`) of the column filter with the specified columnId in the table's `state.columnFilters` array. + +### `getPreColumnFilteredRowModel` + +```tsx +getPreColumnFilteredRowModel: () => RowModel +``` + +Returns the row model for the table before any **column** filtering has been applied. + +### `getColumnFilteredRowModel` + +```tsx +getColumnFilteredRowModel: () => RowModel +``` + +Returns the row model for the table after **column** filtering has been applied. + +### `setGlobalFilter` + +```tsx +setGlobalFilter: (updater: Updater) => void +``` + +Sets or updates the `state.globalFilter` state. + +### `resetGlobalFilter` + +```tsx +resetGlobalFilter: () => void +``` + +Resets the **global** filter state for the table. + +### `getGlobalAutoFilterFn` + +```tsx +getGlobalAutoFilterFn: (columnId: string) => FilterFn | undefined +``` + +Currently, this function returns the built-in `includesString` filter function. In future releases, it may return more dynamic filter functions based on the nature of the data provided. + +### `getGlobalFilterFn` + +```tsx +getGlobalFilterFn: (columnId: string) => FilterFn | undefined +``` + +Returns the global filter function (either user-defined or automatic, depending on configuration) for the table. + +### `getColumnCanGlobalFilter` + +```tsx +getColumnCanGlobalFilter: (columnId: string) => boolean +``` + +Returns if the column with specified columnId can be **globally** filtered. + +### `getPreGlobalFilteredRowModel` + +```tsx +getPreGlobalFilteredRowModel: () => RowModel +``` + +Returns the row model for the table before any **global** filtering has been applied. + +### `getGlobalFilteredRowModel` + +```tsx +getGlobalFilteredRowModel: () => RowModel +``` + +Returns the row model for the table after **global** filtering has been applied. diff --git a/docs/api/grouping.md b/docs/api/grouping.md new file mode 100644 index 0000000000..badcb7ab76 --- /dev/null +++ b/docs/api/grouping.md @@ -0,0 +1,3 @@ +TODO + +Please duplicate a completed api file as a template to get started! diff --git a/docs/api/pagination.md b/docs/api/pagination.md new file mode 100644 index 0000000000..badcb7ab76 --- /dev/null +++ b/docs/api/pagination.md @@ -0,0 +1,3 @@ +TODO + +Please duplicate a completed api file as a template to get started! diff --git a/docs/api/row-selection.md b/docs/api/row-selection.md new file mode 100644 index 0000000000..badcb7ab76 --- /dev/null +++ b/docs/api/row-selection.md @@ -0,0 +1,3 @@ +TODO + +Please duplicate a completed api file as a template to get started! diff --git a/docs/api/sorting.md b/docs/api/sorting.md new file mode 100644 index 0000000000..badcb7ab76 --- /dev/null +++ b/docs/api/sorting.md @@ -0,0 +1,3 @@ +TODO + +Please duplicate a completed api file as a template to get started! diff --git a/docs/api/useAbsoluteLayout.md b/docs/api/useAbsoluteLayout.md deleted file mode 100644 index 0d7c46d516..0000000000 --- a/docs/api/useAbsoluteLayout.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -name: useAbsoluteLayout -route: /api/useAbsoluteLayout -menu: API ---- - -# `useAbsoluteLayout` - -- Plugin Hook -- Optional - -`useAbsoluteLayout` is a plugin hook that adds support for headers and cells to be rendered as absolutely positioned `div`s (or other non-table elements) with explicit `width`. Similar to the `useBlockLayout` hook, this becomes useful if and when you need to virtualize rows and cells for performance. - -**NOTE:** Although no additional options are needed for this plugin to work, the core column options `width`, `minWidth` and `maxWidth` are used to calculate column and cell widths and must be set. [See Column Options](#column-options) for more information on these options. - -### Instance Properties - -- `getTableBodyProps` - - **Usage Required** - - This core prop getter is required to to enable absolute layout for the table body - -### Row Properties - -- `getRowProps` - - **Usage Required** - - This core prop getter is required to to enable absolute layout for rows - -### Cell Properties - -- `getCellProps` - - **Usage Required** - - This core prop getter is required to to enable absolute layout for rows cells - -### HeaderGroup Properties - -- `getHeaderGroupProps` - - **Usage Required** - - This core prop getter is required to to enable absolute layout for headers - -### Header Properties - -- `getHeaderProps` - - **Usage Required** - - This core prop getter is required to to enable absolute layout for headers - -### Example - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/absolute-layout) -- [Open in CodeSandbox](https://codesandbox.io/s/github/tanstack/react-table/tree/master/examples/absolute-layout) diff --git a/docs/api/useBlockLayout.md b/docs/api/useBlockLayout.md deleted file mode 100644 index de66357bcf..0000000000 --- a/docs/api/useBlockLayout.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -name: useBlocklayout -route: /api/useBlocklayout -menu: API ---- - -# `useBlocklayout` - -- Plugin Hook -- Optional - -`useBlocklayout` is a plugin hook that adds support for headers and cells to be rendered as `inline-block` `div`s (or other non-table elements) with explicit `width`. Similar to the `useAbsoluteLayout` hook, this becomes useful if and when you need to virtualize rows and cells for performance. - -**NOTE:** Although no additional options are needed for this plugin to work, the core column options `width`, `minWidth` and `maxWidth` are used to calculate column and cell widths and must be set. [See Column Options](#column-options) for more information on these options. - -### Row Properties - -- `getRowProps` - - **Usage Required** - - This core prop getter is required to to enable absolute layout for rows - -### Cell Properties - -- `getCellProps` - - **Usage Required** - - This core prop getter is required to to enable absolute layout for rows cells - -### HeaderGroup Properties - -- `getHeaderGroupProps` - - **Usage Required** - - This core prop getter is required to to enable absolute layout for headers - -### Header Properties - -- `getHeaderProps` - - **Usage Required** - - This core prop getter is required to to enable absolute layout for headers - -### Example - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/block-layout) -- [Open in CodeSandbox](https://codesandbox.io/s/github/tanstack/react-table/tree/master/examples/block-layout) diff --git a/docs/api/useColumnOrder.md b/docs/api/useColumnOrder.md deleted file mode 100644 index 33a53c1b76..0000000000 --- a/docs/api/useColumnOrder.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -name: useColumnOrder -route: /api/useColumnOrder -menu: API ---- - -# `useColumnOrder` - -- Plugin Hook -- Optional - -`useColumnOrder` is a plugin hook that implements **basic column reordering**. As columns are reordered, their header groups are reverse-engineered so as to never have orphaned header groups. - -### Table Options - -The following options are supported via the main options object passed to `useTable(options)` - -- `initialState.columnOrder: Array` - - Optional - - Defaults to `[]` - - Any column ID's not represented in this array will be naturally ordered based on their position in the original table's `column` structure - -### Instance Properties - -The following values are provided to the table `instance`: - -- `setColumnOrder: Function(updater: Function | Array) => void` - - - Use this function to programmatically update the columnOrder. - - `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. - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/column-ordering) -- [Open in CodeSandbox](https://codesandbox.io/s/github/tanstack/react-table/tree/master/examples/column-ordering) diff --git a/docs/api/useExpanded.md b/docs/api/useExpanded.md deleted file mode 100644 index e1b78a1f30..0000000000 --- a/docs/api/useExpanded.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -name: useExpanded -route: /api/useExpanded -menu: API ---- - -# `useExpanded` - -- Plugin Hook -- Optional - -`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-like `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)` - -- `initialState.expanded: Object` - - Optional - - Must be **memoized** - - An `object` of expanded row IDs with boolean property values. - - If a row's id is set to true in this object, that row will have an expanded state. For example, if `{ '3': true }` was passed as the `expanded` state, by default the **4th row in the original data array** would be expanded, since it would have that ID - - For nested expansion, you can **use nested IDs like `1.3`** to expand sub rows. For example, if `{ '3': true, '3.5': true }` was passed as the `expanded` state, then the **the 4th row would be expanded, along with the 6th subRow of the 4th row as well**. - - This information is stored in state since the table is allowed to manipulate the filter through user interaction. -- `getSubRows: Function(row, relativeIndex) => Rows[]` - - Optional - - See the [useTable hook](#table-options) for more details -- `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 always be expanded, regardless of state. -- `expandSubRows: Bool` - - Optional - - 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. -- `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) - -### Instance Properties - -The following properties are available on the table instance returned from `useTable` - -- `rows: Array` - - An array of **expanded** rows. -- `toggleRowExpanded: Function(rowId, isExpanded?)` - - A function to toggle whether a row is expanded or not. The `isExpanded` boolean is optional, otherwise it will be a true toggle action -- `toggleAllRowsExpanded: Function(isExpanded?)` - - A function to toggle whether all of the rows in the table are expanded or not. The `isExpanded` boolean is optional, otherwise it will be a true toggle action -- `isAllRowsExpanded` -- `getToggleAllRowsExpandedProps: Function(userProps) => props` - - A prop getter function that returns all necessary props for an element to be clicked and toggle all of the rows expanded or not. - -### 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. -- `toggleRowExpanded: 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 - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/expanding) -- [Open in CodeSandbox](https://codesandbox.io/s/github/tanstack/react-table/tree/master/examples/expanding) diff --git a/docs/api/useFilters.md b/docs/api/useFilters.md deleted file mode 100644 index 390f91f475..0000000000 --- a/docs/api/useFilters.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -name: useFilters -route: /api/useFilters -menu: API ---- - -# `useFilters` - -- Plugin Hook -- Optional - -`useFilters` is the hook that implements **row filtering** and can even be used in conjunction with `useGlobalFilter`. It's also important to note that this hook can be used either **before or after** `useGlobalFilter`, depending on the performance characteristics you want to code for. - -### Table Options - -The following options are supported via the main options object passed to `useTable(options)` - -- `initialState.filters: Array>` - - Must be **memoized** - - An array of objects containing 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. -- `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` -- `filterFns: 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 -- `autoResetFilters: Boolean` - - Defaults to `true` - - When `true`, the `filters` 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) - -### 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 `filterFns` 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(filtersObjectArray) => void` - - An instance-level function used to update the values for **all** filters on the table, all at once. - - filtersObjectArray is an array of objects with id and value keys. Example: `[{ id: 'columnAccessor', value: 'valueToFilter' }]` - - Note: You must call setAllFilters with an array, even if that array is empty. eg: `setAllFilters([])`. - -### 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/tanstack/react-table/tree/master/examples/filtering) -- [Open in CodeSandbox](https://codesandbox.io/s/github/tanstack/react-table/tree/master/examples/filtering) diff --git a/docs/api/useFlexLayout.md b/docs/api/useFlexLayout.md deleted file mode 100644 index caf89cbef4..0000000000 --- a/docs/api/useFlexLayout.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -name: useFlexLayout -route: /api/useFlexLayout -menu: API ---- - -# `useFlexLayout` - -- Plugin Hook -- Optional - -`useFlexLayout` is a plugin hook that adds support for headers and cells to be rendered as `inline-block` `div`s (or other non-table elements) with `width` being used as the flex-basis and flex-grow. This hook becomes useful when implementing both virtualized and resizable tables that must also be able to stretch to fill all available space. - -**NOTE:** Although no additional options are needed for this plugin to work, the core column options `width`, `minWidth` and `maxWidth` are used to calculate column and cell widths and must be set: - -- `minWidth` is only used to limit column resizing. It does not define the minimum width for a column. -- `width` is used as both the `flex-basis` and `flex-grow`. This means that it essentially acts as both the minimum width and flex-ratio of the column. -- `maxWidth` is only used to limit column resizing. It does not define the maximum width for a column. - -[See Column Options](#column-options) for more information on these options. - -### Row Properties - -- `getRowProps` - - **Usage Required** - - This core prop getter is required to to enable absolute layout for rows - -### Cell Properties - -- `getCellProps` - - **Usage Required** - - This core prop getter is required to to enable absolute layout for rows cells - -### HeaderGroup Properties - -- `getHeaderGroupProps` - - **Usage Required** - - This core prop getter is required to to enable absolute layout for headers - -### Header Properties - -- `getHeaderProps` - - **Usage Required** - - This core prop getter is required to to enable absolute layout for headers - -### Example (Full Width Resizable Table) - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/full-width-resizable-table) -- [Open in CodeSandbox](https://codesandbox.io/s/github/tanstack/react-table/tree/master/examples/full-width-resizable-table) diff --git a/docs/api/useGlobalFilter.md b/docs/api/useGlobalFilter.md deleted file mode 100644 index bb42085035..0000000000 --- a/docs/api/useGlobalFilter.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -name: useGlobalFilter -route: /api/useGlobalFilter -menu: API ---- - -# `useGlobalFilter` - -- Plugin Hook -- Optional - -`useGlobalFilter` is the hook that implements **global row filtering** and can even be used in conjunction with `useFilters`. It's also important to note that this hook can be used either **before or after** `useFilters`, depending on the performance characteristics you want to code for. - -### Table Options - -The following options are supported via the main options object passed to `useTable(options)` - -- `initialState.globalFilter: any` - - Must be **memoized** - - An array of objects containing 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. -- `globalFilter: String | Function` - - Optional - - Defaults to `text` - - The resolved function from the this string/function will be used to filter the table's data. - - If a `string` is passed, the function with that name located on either the custom `filterFns` 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** -- `manualGlobalFilter: 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) -- `disableGlobalFilter: Bool` - - Disables global filtering for every column in the entire table. -- `filterFns: Object` - - Must be **memoized** - - Allows overriding or adding additional filter types for the table to use. If the globalFilter 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 -- `autoResetGlobalFilter: Boolean` - - Defaults to `true` - - When `true`, the `globalFilter` 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) - -### Column Options - -The following options are supported on any `Column` object passed to the `columns` option in `useTable()` - -- `disableGlobalFilter: Bool` - - Optional - - If set to `true`, will disable global filtering for this column - -### Instance Properties - -The following values are provided to the table `instance`: - -- `rows: Array` - - An array of **filtered** rows. -- `preGlobalFilteredRows: 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. -- `setGlobalFilter: Function(filterValue) => void` - - An instance-level function used to update the global filter value. - -### Example - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/filtering) -- [Open in CodeSandbox](https://codesandbox.io/s/github/tanstack/react-table/tree/master/examples/filtering) diff --git a/docs/api/useGroupBy.md b/docs/api/useGroupBy.md deleted file mode 100644 index 5a31d14011..0000000000 --- a/docs/api/useGroupBy.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -name: useGroupBy -route: /api/useGroupBy -menu: API ---- - -# `useGroupBy` - -- Plugin Hook -- Optional - -`useGroupBy` is the hook that implements **row grouping and aggregation**. - -- Each column's `getGroupByToggleProps()` function can be used to generate the props needed to make a clickable UI element that will toggle the grouping on or off for a specific column. -- Instance and column-level `toggleGroupBy` functions are also made available for programmatic grouping. - -### Table Options - -The following options are supported via the main options object passed to `useTable(options)` - -- `initialState.groupBy: Array` - - Must be **memoized** - - An array of groupBy ID strings, controlling which columns are used to calculate row grouping and aggregation. This information is stored in state since the table is allowed to manipulate the groupBy through user interaction. -- `manualGroupBy: Bool` - - Enables groupBy detection and functionality, but does not automatically perform row grouping. - - Turn this on if you wish to implement your own row grouping outside of the table (eg. server-side or manual row grouping/nesting) -- `disableGroupBy: Bool` - - Disables groupBy for the entire table. -- `aggregations: Object` - - Must be **memoized** - - Allows overriding or adding additional aggregation functions for use when grouping/aggregating row values. If an aggregation key isn't found on this object, it will default to using the built-in aggregation functions -- `groupByFn: Function` - - Must be **memoized** - - Defaults to `defaultGroupByFn` - - This function is responsible for grouping rows based on the `state.groupBy` keys provided. It's very rare you would need to customize this function. - -### Column Options - -The following options are supported on any `Column` object passed to the `columns` options in `useTable()` - -- `Aggregated: Function | React.Component => JSX` - - Optional - - Defaults to this column's `Cell` formatter - - Receives the table instance and cell model as props - - Must return valid JSX - - This function (or component) formats this column's value when it is being grouped and aggregated, eg. If this column was showing the number of visits for a user to a website and it was currently being grouped to show an **average** of the values, the `Aggregated` function for this column could format that value to `1,000 Avg. Visits` -- `aggregate: String | Function(leafValues, aggregatedValues) => any` - - Optional - - Used to aggregate values across rows, eg. `average`-ing the ages of many cells in a table" - - If a single `String` is passed, it must be the key of either a user defined or predefined `aggregations` function. - - If a `Function` is passed, this function will receive both the leaf-row values and (if the rows have already been aggregated, the previously aggregated values) to be aggregated into a single value. - - The function signature for all aggregation functions is `(leafValues, aggregatedValues) => aggregatedValue` where `leafValues` is a flat array containing all leaf rows currently grouped at the aggregation level and `aggregatedValues` is an array containing the aggregated values from the immediate child sub rows. Each has purpose in the types of aggregations they power where optimizations are made for either accuracy or performance. - - For examples on how an aggregation functions work, see the source code for the built in aggregations in the [src/aggregations.js](../../src/aggregations.js) file. -- `aggregateValue: String | Function(values, row, column) => any` - - Optional - - When attempting to group/aggregate non primitive cell values (eg. arrays of items) you will likely need to resolve a stable primitive value like a number or string to use in normal row aggregations. This property can be used to aggregate or simply access the value to be used in aggregations eg. `count`-ing the unique number of items in a cell's array value before `sum`-ing that count across the table. - - If a single `String` is passed, it must be the key of either a user defined or predefined `aggregations` function. - - If a `Function` is passed, this function will receive the cell's accessed value, the original `row` object and the `column` associated with the cell -- `disableGroupBy: Boolean` - - Defaults to `false` - - If `true`, will disable grouping for this column. - -### Instance Properties - -The following values are provided to the table `instance`: - -- `rows: Array` - - An array of **grouped and aggregated** rows. -- `preGroupedRows: Array` - - The array of rows originally used to create the grouped rows. -- `toggleGroupBy: Function(columnId: String, ?set: Bool) => void` - - This function can be used to programmatically set or toggle the groupBy state for a specific column. - -### Column Properties - -The following properties are available on every `Column` object returned by the table instance. - -- `canGroupBy: Boolean` - - If `true`, this column is able to be grouped. - - This is resolved from the column having a valid accessor / data model, and not being manually disabled via other `useGroupBy` related options -- `isGrouped: Boolean` - - If `true`, this column is currently being grouped -- `groupedIndex: Int` - - If this column is currently being grouped, this integer is the index of this column's ID in the table state's `groupBy` array. -- `toggleGroupBy: Function(?set: Bool) => void` - - This function can be used to programmatically set or toggle the groupBy state fo this column. -- `getGroupByToggleProps: Function(props) => props` - - **Required** - - This function is used to resolve any props needed for this column's UI that is responsible for toggling grouping when the user clicks it. - - You can use the `getGroupByToggleProps` hook to extend its functionality. - - Custom props may be passed. **NOTE: Custom props may override built-in sortBy props, so be careful!** - -### Row Properties - -The following properties are available on every `Row` object returned by the table instance. - -- `groupById: String` - - The column ID for which this row is being grouped. - - Will be `undefined` if the row is an original row from `data` and not a materialized one from the grouping. -- `groupByVal: any` - - If the row is a materialized group row, this will be the grouping value that was used to create it. -- `values: Object` - - Similar to a regular row, a materialized grouping row also has a `values` object - - This object contains the **aggregated** values for this row's sub rows -- `subRows: Array` - - If the row is a materialized group row, this property is the array of materialized subRows that were grouped inside of this row. -- `leafRows: Array` - - If the row is a materialized group row, this property is an array containing all leaf node rows aggregated into this row. -- `depth: Int` - - If the row is a materialized group row, this is the grouping depth at which this row was created. -- `id: String` - - The unique ID for this row. - - This ID is unique across all rows, including sub rows - - Derived from the `getRowId` function, which defaults to chaining parent IDs and joining with a `.` - - If a row is a materialized grouping row, it will have an ID in the format of `columnId:groupByVal`. -- `isAggregated: Bool` - - Will be `true` if the row is an aggregated row - -### Cell Properties - -The following additional properties are available on every `Cell` object returned in an array of `cells` on every row object. - -- `isGrouped: Bool` - - If `true`, this cell is a grouped cell, meaning it contains a grouping value and should usually display and expander. -- `isPlaceholder: Bool` - - If `true`, this cell is a repeated value cell, meaning it contains a value that is already being displayed elsewhere (usually by a parent row's cell). - - Most of the time, this cell is not required to be displayed and can safely be hidden during rendering -- `isAggregated: Bool` - - If `true`, this cell's value has been aggregated and should probably be rendered with the `Aggregated` cell renderer. - -### Example - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/grouping) -- [Open in CodeSandbox](https://codesandbox.io/s/github/tanstack/react-table/tree/master/examples/grouping) diff --git a/docs/api/usePagination.md b/docs/api/usePagination.md deleted file mode 100644 index c19e17faae..0000000000 --- a/docs/api/usePagination.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -name: usePagination -route: /api/usePagination -menu: API ---- - -# `usePagination` - -- Plugin Hook -- Optional - -`usePagination` is the hook that implements **row pagination**. It can be used for both client-side pagination or server-side pagination. For more information on pagination, see Pagination - -> **NOTE** Some server-side pagination implementations do not use page index and instead use **token based pagination**! If that's the case, please use the `useTokenPagination` plugin instead. - -### Table Options - -The following options are supported via the main options object passed to `useTable(options)` - -- `initialState.pageSize: Int` - - **Required** - - Defaults to `10` - - Determines the amount of rows on any given page -- `initialState.pageIndex: Int` - - **Required** - - Defaults to `0` - - The index of the page that should be displayed via the `page` instance value -- `pageCount: Int` - - **Required if `manualPagination` is set to `true`** - - If `manualPagination` is `true`, then this value used to determine the amount of pages available. This amount is then used to materialize the `pageOptions` and also compute the `canNextPage` values on the table instance. -- `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) -- `autoResetPage: Boolean` - - Defaults to `true` - - When `true`, the `pageIndex` 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 - - `manualGlobalFilter` is `false` and `state.globalFilter` 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` - - Optional - - Only applies when using the `useExpanded` plugin hook simultaneously - - Defaults to `true` - - If set to `true`, expanded rows are paginated along with normal rows. This results in stable page sizes across every page. - - If set to `false`, expanded rows will be spliced in after pagination. This means that the total number of rows in a page can potentially be larger than the page size, depending on how many subrows are expanded. - -### Instance Properties - -The following values are provided to the table `instance`: - -- `state.pageIndex: Int` - - This is the current `pageIndex` value, located on the state. -- `state.pageSize: Int` - - This is the current `pageSize` value, located on the state. -- `page: Array` - - An array of rows for the **current** page, determined by the current `pageIndex` value. -- `pageCount: Int` - - If `manualPagination` is set to `false`, this is the total amount of pages available in the table based on the current `pageSize` value - - if `manualPagination` is set to `true`, this is merely the same `pageCount` option that was passed in the table options. -- `pageOptions: Array` - - An array of zero-based index integers corresponding to available pages in the table. - - This can be useful for generating things like select interfaces for the user to select a page from a list, instead of manually paginating to the desired page. -- `canPreviousPage: Bool` - - If there are pages and the current `pageIndex` is greater than `0`, this will be `true` -- `canNextPage:` - - If there are pages and the current `pageIndex` is less than `pageCount`, this will be `true` -- `gotoPage: Function(pageIndex)` - - This function, when called with a valid `pageIndex`, will set `pageIndex` to that value. - - If the aginateassed index is outside of the valid `pageIndex` range, then this function will do nothing. -- `previousPage: Function` - - This function decreases `state.pageIndex` by one. - - If there are no pages or `canPreviousPage` is false, this function will do nothing. -- `nextPage: Function` - - This function increases `state.pageIndex` by one. - - If there are no pages or `canNextPage` is false, this function will do nothing. -- `setPageSize: Function(pageSize)` - - This function sets `state.pageSize` to the new value. - - As a result of a pageSize change, a new `state.pageIndex` is also calculated. It is calculated via `Math.floor(currentTopRowIndex / newPageSize)` - -### Example - -- Basic Pagination - - [Source](https://github.com/tanstack/react-table/tree/master/examples/pagination) - - [Open in CodeSandbox](https://codesandbox.io/s/github/tanstack/react-table/tree/master/examples/pagination) -- Controlled Pagination - - [Source](https://github.com/tanstack/react-table/tree/master/examples/pagination-controlled) - - [Open in CodeSandbox](https://codesandbox.io/s/github/tanstack/react-table/tree/master/examples/pagination-controlled) diff --git a/docs/api/useResizeColumns.md b/docs/api/useResizeColumns.md deleted file mode 100644 index 7aeef4de6e..0000000000 --- a/docs/api/useResizeColumns.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -name: useResizeColumns -route: /api/useResizeColumns -menu: API ---- - -# `useResizeColumns` - -- Plugin Hook -- Optional - -`useResizeColumns` is a plugin hook that adds support for resizing headers and cells when using non-table elements for layout eg. the `useBlockLayout` and `useAbsoluteLayout` hooks. It even supports resizing column groups! - -### Table Options - -- `disableResizing: Bool` - - Defaults to `false` - - When set to `true`, resizing is disabled across the entire table - -### Column Options - -The core column options `width`, `minWidth` and `maxWidth` are used to calculate column and cell widths and must be set. [See Column Options](#column-options) for more information on these options. - -- `disableResizing: Bool` - - Defaults to `false` - - When set to `true`, resizing is disabled for this column - -### Header Properties - -- `getResizerProps` - - **Usage Required** - - This core prop getter is required to to enable absolute layout for headers -- `canResize: Bool` - - Will be `true` if this column can be resized -- `isResizing: Bool` - - Will be `true` if this column is currently being resized - -### Example - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/column-resizing) -- [Open in CodeSandbox](https://codesandbox.io/s/github/tanstack/react-table/tree/master/examples/column-resizing) diff --git a/docs/api/useRowSelect.md b/docs/api/useRowSelect.md deleted file mode 100644 index 47383903ba..0000000000 --- a/docs/api/useRowSelect.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -name: useRowSelect -route: /api/useRowSelect -menu: API ---- - -# `useRowSelect` - -- Plugin Hook -- Optional - -`useRowSelect` is the hook that implements **basic row selection**. For more information on row selection, see Row Selection - -### Table Options - -The following options are supported via the main options object passed to `useTable(options)` - -- `initialState.selection: Object` - - Optional - - Defaults to `{}` - - If a row's ID is set to `true` in this object, it will have a selected state. -- `manualRowSelectedKey: String` - - Optional - - Defaults to `isSelected` - - If this key is found on the **original** data row, and it is true, this row will be manually selected -- `autoResetSelectedRows: Boolean` - - Defaults to `true` - - When `true`, the `selection` 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) - -### 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 -- `toggleAllRowsSelected: 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'` -- `isAllRowsSelected: Bool` - - Will be `true` if all rows are selected. - - If at least one row is not selected, will be `false` -- `selectedFlatRows: Array` - - The flat array of rows that are currently selected - -### Row Properties - -The following additional properties are available on every **prepared** `row` object returned by the table instance. - -- `isSelected: Bool` - - Will be `true` if the row is currently selected -- `isSomeSelected: Bool` - - Will be `true` if the row has subRows and at least one of them is currently selected -- `toggleRowSelected: Function(?set)` - - Use this function to toggle this row's selected state. - - Optionally pass `true` or `false` to set it to that state -- `getToggleRowSelectedProps: Function(props) => props` - - Use this function to get the props needed for a **select row checkbox**. - - Props: - - `onChange: Function()` - - `style.cursor: 'pointer'` - - `checked: Bool` - - `title: 'Toggle Row Selected'` - -### Example - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/row-selection) -- [Open in CodeSandbox](https://codesandbox.io/s/github/tanstack/react-table/tree/master/examples/row-selection) diff --git a/docs/api/useRowState.md b/docs/api/useRowState.md deleted file mode 100644 index 73264ff26d..0000000000 --- a/docs/api/useRowState.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -name: useRowState -route: /api/useRowState -menu: API ---- - -# `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)` - -- `initialState.rowState: Object>` - - Optional - - Defaults to `{}` - - If a row's ID 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(row) => Object` - - Optional - - Defaults to: `row => ({})` - - This function should 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` -- `initialCellStateAccessor: Function(row) => Object` - - **Optional** - - Defaults to: `cell => ({})` - - This function should return the initial state for a cell. - - If this function is defined, it will be passed a `Cell` object, from which you can return a value to use as the initial state, eg. `cell => cell.row.original.initialCellState[cell.column.id]` -- `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) - -### Instance Properties - -The following values are provided to the table `instance`: - -- `setRowState: Function(rowPath: Array, 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, 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.id]` - - 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.id].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. diff --git a/docs/api/useSortBy.md b/docs/api/useSortBy.md deleted file mode 100644 index c99186d6d1..0000000000 --- a/docs/api/useSortBy.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -name: useSortBy -route: /api/useSortBy -menu: API ---- - -# `useSortBy` - -- Plugin Hook -- Optional - -`useSortBy` is the hook that implements **row sorting**. It also support multi-sort (keyboard required). - -- Multi-sort is enabled by default -- To sort the table via UI, attach the props generated from each column's `getSortByToggleProps()`, then click any of those elements. -- To multi-sort the table via UI, hold `shift` while clicking on any of those same elements that have the props from `getSortByToggleProps()` attached. -- To programmatically sort (or multi-sort) any column, use the `toggleSortBy` method located on the instance or each individual column. - -### Table Options - -The following options are supported via the main options object passed to `useTable(options)` - -- `initialState.sortBy: Array>` - - Must be **memoized** - - An array of sorting objects. If there is more than one object in the array, multi-sorting will be enabled. Each sorting object should contain an `id` key with the corresponding column ID to sort by. An optional `desc` key may be set to true or false to indicated ascending or descending sorting for that column. This information is stored in state since the table is allowed to manipulate the filter through user interaction. -- `manualSortBy: Bool` - - Enables sorting detection functionality, but does not automatically perform row sorting. Turn this on if you wish to implement your own sorting outside of the table (eg. server-side or manual row grouping/nesting) -- `disableSortBy: Bool` - - Disables sorting for every column in the entire table. -- `defaultCanSort: Bool` - - Optional - - Defaults to `false` - - If set to `true`, all columns will be sortable, regardless if they have a valid `accessor` -- `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 pressed), 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` - - If true, the un-sorted state will not be available to multi-sorted columns. -- `orderByFn: Function` - - Must be **memoized** - - Defaults to the built-in default orderBy function - - This function is responsible for composing multiple sorting functions together for multi-sorting, and also handles both the directional sorting and stable-sorting tie breaking. Rarely would you want to override this function unless you have a very advanced use-case that requires it. -- `sortingFns: Object` - - 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 -- `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) - -### Column Options - -The following options are supported on any `Column` object passed to the `columns` options in `useTable()` - -- `defaultCanSort: Bool` - - Optional - - Defaults to `false` - - If set to `true`, this column will be sortable, regardless if it has a valid `accessor` -- `disableSortBy: Bool` - - Optional - - Defaults to `false` - - If set to `true`, the sorting for this column will be disabled -- `sortDescFirst: Bool` - - Optional - - Defaults to `false` - - If set to `true`, the first sort direction for this column will be descending instead of ascending -- `sortInverted: Bool` - - Optional - - Defaults to `false` - - If set to `true`, the underlying sorting direction will be inverted, but the UI will not. - - This may be useful in situations where positive and negative connotation is inverted, eg. a Golfing score where a lower score is considered more positive than a higher one. -- `sortingFn: String | Function(rowA: , rowB: , columnId: String, desc: Bool)` - - Used to compare 2 rows of data and order them correctly. - - If a **function** is passed, it must be **memoized** - - String options: `basic`, `datetime`, `alphanumeric`. Defaults to `alphanumeric`. - - The resolved function from the this string/function will be used to sort the this column's data. - - If a `string` is passed, the function with that name located on either the custom `sortingFns` option or the built-in sorting types object will be used. - - If a `function` is passed, it will be used. - - For more information on sort types, see Sorting - -### Instance Properties - -The following values are provided to the table `instance`: - -- `rows: Array` - - An array of **sorted** rows. -- `preSortedRows: Array` - - The array of rows that were originally sorted. -- `toggleSortBy: Function(ColumnId: String, descending: Bool, isMulti: Bool) => void` - - This function can be used to programmatically toggle the sorting for any specific column - -### Column Properties - -The following properties are available on every `Column` object returned by the table instance. - -- `canSort: Bool` - - Denotes whether a column is sortable or not depending on if it has a valid accessor/data model or is manually disabled via an option. -- `toggleSortBy: Function(descending, multi) => void` - - This function can be used to programmatically toggle the sorting for this column. - - This function is similar to the `instance`-level `toggleSortBy`, however, passing a columnId is not required since it is located on a `Column` object already. -- `getSortByToggleProps: Function(props) => props` - - **Required** - - This function is used to resolve any props needed for this column's UI that is responsible for toggling the sort direction when the user clicks it. - - You can use the `getSortByToggleProps` hook to extend its functionality. - - Custom props may be passed. **NOTE: Custom props may override built-in sortBy props, so be careful!** -- `clearSortBy: Function() => void` - - This function can be used to programmatically clear the sorting for this column. -- `isSorted: Boolean` - - Denotes whether this column is currently being sorted -- `sortedIndex: Int` - - If the column is currently sorted, this integer will be the index in the `sortBy` array from state that corresponds to this column. - - If this column is not sorted, the index will always be `-1` -- `isSortedDesc: Bool` - - If the column is currently sorted, this denotes whether the column's sort direction is descending or not. - - If `true`, the column is sorted `descending` - - If `false`, the column is sorted `ascending` - - If `undefined`, the column is not currently being sorted. - -### Example - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/sorting) -- [Open in CodeSandbox](https://codesandbox.io/s/github/tanstack/react-table/tree/master/examples/sorting) diff --git a/docs/api/useTable.md b/docs/api/useTable.md deleted file mode 100644 index e38306d69d..0000000000 --- a/docs/api/useTable.md +++ /dev/null @@ -1,284 +0,0 @@ ---- -name: useTable -route: /api/useTable -menu: API ---- - -# `useTable` - -- Required - -`useTable` is the root hook for React Table. To use it, pass it with an options object with at least a `columns` and `data` value, followed by any React Table compatible hooks you want to use. - -### Table Options - -The following options are supported via the main options object passed to `useTable(options)` - -- `columns: Array` - - Required - - Must be **memoized** - - The core columns configuration object for the entire table. - - Supports nested `columns` arrays via the column's `columns` key, eg. `[{ Header: 'My Group', columns: [...] }]` -- `data: Array` - - Required - - Must be **memoized** - - The data array that you want to display on the table. -- `initialState: Object` - - Optional - - The initial state object for the table. - - Upon table initialization, this object is **merged over the table's `defaultState` object** (eg. `{...defaultState, ...initialState}`) that React Table and its hooks use to register default state to produce the final initial state object passed to the `React.useState` hook internally. -- `initialState.hiddenColumns: Array` - - Optional - - The initial state object for hidden columns - - If a column's ID is contained in this array, it will be hidden -- `autoResetHiddenColumns: Boolean` - - Defaults to `true` - - When `true`, the `hiddenColumns` state will automatically reset if any of the following conditions are met: - - `columns` is changed - - To disable, set to `false` -- `onStateChange: Function(newState, prevState, meta) => newState` - - Optional - - With every call that is made to update the table's internal `React.useState` instance, this function is called and is allowed to inspect or modify the final state object and optionally return a new one or the previous one. - - Any meta information about the event, if available, is also passed as the third parameter - - If the previous state is returned, the new state will not be and no rerender will occur - - If the new or modified state is returned, it will be used as the final state for the update and a rerender will occur. - - This callback can be used to "control" the state of the table by sending the new state up the component tree to your own state location and returning the previous state to cancel the update and subsequent rerender. You can then manage your own state further up however you'd like and then send your controlled state back down to the table using the `state` property in `useTable`. - - See the FAQ ["How can I manually control the table state?"](/faq#how-can-i-manually-control-the-table-state) for a an example. -- `defaultColumn: Object` - - Optional - - Defaults to `{}` - - 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. -- `getSubRows: Function(row, relativeIndex) => Rows[]` - - Optional - - Must be **memoized** - - Defaults to `(row) => row.subRows || []` - - Use this function to change how React Table detects subrows. You could even use this function to generate sub rows if you want. - - By default, it will attempt to return the `subRows` property on the row, or an empty array if that is not found. -- `getRowId: Function(row, relativeIndex, ?parent) => string` - - Use this function to change how React Table detects unique rows and also how it constructs each row's underlying `id` property. - - Optional - - Must be **memoized** - - Defaults to `(row, relativeIndex, parent) => parent ? [parent.id, relativeIndex].join('.') : relativeIndex` -- `debug: Bool` - - Optional - - A flag to turn on debug mode. - - Defaults to `false` - -### Column Options - -The following options are supported on any column object you can pass to `columns`. - -- `accessor: String | Function(originalRow, rowIndex) => any` - - **Required** - - This string/function is used to build the data model for your column. - - The data returned by an accessor should be **primitive** and sortable. - - If a string is passed, the column's value will be looked up on the original row via that key, eg. If your column's accessor is `firstName` then its value would be read from `row['firstName']`. You can also specify deeply nested values with accessors like `info.hobbies` or even `address[0].street` - - If a function is passed, the column's value will be looked up on the original row using this accessor function, eg. If your column's accessor is `row => row.firstName`, then its value would be determined by passing the row to this function and using the resulting value. - - Technically speaking, this field isn't required if you have a unique `id` for a column. This is used for things like expander or row selection columns. **Warning**: Only omit `accessor` if you really know what you're doing. -- `id: String` - - **Required if `accessor` is a function** - - This is the unique ID for the column. It is used by reference in things like sorting, grouping, filtering etc. - - If a **string** accessor is used, it defaults as the column ID, but can be overridden if necessary. -- `columns: Array` - - Optional - - A nested array of columns. - - If defined, the column will act as a header group. Columns can be recursively nested as much as needed. -- `Header: String | Function | React.Component => JSX` - - Optional - - 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 }) => String(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. -- `width: Int` - - Optional - - Defaults to `150` - - Specifies the width for the column (when using non-table-element layouts) -- `minWidth: Int` - - Optional - - Defaults to `0` - - Specifies the minimum width for the column (when using non-table-element layouts) - - Specifically useful when using plugin hooks that allow the user to resize column widths -- `maxWidth: Int` - - Optional - - Defaults to `0` - - Specifies the maximum width for the column (when using non-table-element layouts) - - Specifically useful when using plugin hooks that allow the user to resize column widths - -### Instance Properties - -The following properties are available on the table instance returned from `useTable` - -- `state: Object` - - This is the internal state object of the table, and determines everything about how the table behaves. It houses all data, columns, column state, configuration options, essentially anything that can change over the course of a table instances lifecycle is here. - - `columns: Array` - - A **nested** array of final column objects, **similar in structure to the original columns configuration option**. - - See [Column Properties](#column-properties) for more information - - `rows: Array` - - An array of **materialized row objects** from the original `data` array and `columns` passed into the table options - - See [Row Properties](#row-properties) for more information -- `headerGroups: Array` - - An array of normalized header groups, each containing a flattened array of final column objects for that row. - - **Some of these headers may be materialized as placeholders** - - See [HeaderGroup Properties](#headergroup-properties) for more information -- `footerGroups: Array` - - An array of normalized header groups, but in reverse order, each containing a flattened array of final column objects for that row. - - **Some of these headers may be materialized as placeholders** - - See [HeaderGroup Properties](#headergroup-properties) for more information -- `getTableProps: Function(?props)` - - **Required** - - This function is used to resolve any props needed for your table wrapper. - - Custom props may be passed. **NOTE: Custom props will override built-in table props, so be careful!** -- `getTableBodyProps: Function(?props)` - - **Required** - - This function is used to resolve any props needed for your table body wrapper. - - Custom props may be passed. **NOTE: Custom props will override built-in table body props, so be careful!** -- `prepareRow: Function(Row)` - - **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. -- `flatRows: Array` - - 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 -- `totalColumnsWidth: Int` - - This is the total width of all visible columns (only available when using non-table-element layouts) -- `toggleHideColumn: Function(columnId: String, ?value: Boolean) => void` - - This function can be used to toggle or set a column's hidden state - - Passing a `value` is optional. If passed, the hidden state will be set to that Boolean value. - - If a `value` is not passed, the visibility for this column will be toggled. -- `setHiddenColumns: Function(Array | Function(oldHiddenColumns) => Array) => void` - - This function can be used to set the `hiddenColumns` state for the entire table. - - If a value is passed, `hiddenColumns` will be set to that value - - If a function is passed, it will received the previous `hiddenColumns` value and will be expected to return the new value. -- `toggleHideAllColumns: Function(?value: Boolean) => void` - - This function can be used to toggle or set the visibility for all columns to `true` or `false` - - If a value is not passed, the visibility for all columns will be toggled back and forth from `true` to `false` - - If `true` is passed, all columns will be hidden - - If a `false` is passed, all columns will be visible -- `getToggleHideAllColumnsProps: Function(userProps) => props` - - This function can be used to retrieve all necessary props to be placed on an `` component that will control the visibility of all columns - -### HeaderGroup Properties - -The following additional properties are available on every `headerGroup` object returned by the table instance. - -- `headers: Array` - - **Required** - - The columns in this header group. -- `getHeaderGroupProps: Function(?props)` - - **Required** - - This function is used to resolve any props needed for this header group's row. - - You can use the `getHeaderGroupProps` hook to extend its functionality. - - Custom props may be passed. **NOTE: Custom props will override built-in table props, so be careful!** -- `getFooterGroupProps: Function(?props)` - - **Required** - - This function is used to resolve any props needed for this header group's footer row. - - You can use the `getFooterGroupProps` hook to extend its functionality. - - Custom props may be passed. **NOTE: Custom props will override built-in table props, so be careful!** - -### Column Properties - -The following properties are available on every `Column` object returned by the table instance. - -- `id: String` - - The resolved column ID from either the column's `accessor` or the column's hard-coded `id` property -- `isVisible: Boolean` - - Whether the column should be currently visible or not. - - Columns that are not visible are still used for sorting, filtering, etc. -- `render: Function(type: String | Function | Component, ?props)` - - 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` and `Footer` renderers. Other renderers like `Filter` and `Aggregated` are available via plugin hooks. - - 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. -- `totalLeft: Int` - - This is the total width in pixels of all columns to the left of this column - - Specifically useful when using plugin hooks that allow the user to resize column widths -- `totalWidth: Int` - - This is the total width in pixels for this column (if it is a leaf-column) or or all of it's sub-columns (if it is a column group) - - Specifically useful when using plugin hooks that allow the user to resize column widths -- `getHeaderProps: Function(?props)` - - **Required** - - This function is used to resolve any props needed for this column's header cell. - - You can use the `getHeaderProps` hook to extend its functionality. - - Custom props may be passed. **NOTE: Custom props will override built-in table props, so be careful!** -- `getFooterProps: Function(?props)` - - **Required** - - This function is used to resolve any props needed for this column's footer cell. - - You can use the `getFooterProps` hook to extend its functionality. - - Custom props may be passed. **NOTE: Custom props will override built-in table props, so be careful!** -- `toggleHidden: Function(?hidden: Boolean) => void` - - This function can be used to hide or show this column. - - If no value is passed, the visibility of this column will be toggled. - - Optionally pass a value to set the visible. -- `getToggleHiddenProps: Function(userProps) => props` - - This function can be used to retrieve all necessary props to be placed on an `` component that will control the visibility of this column. - -### Row Properties - -The following additional properties are available on every `row` object returned by the table instance. - -- `cells: Array` - - An array of visible `Cell` objects containing properties and functions specific to the row and column it belongs to. - - These cells are normally intended for display - - See [Cell Properties](#cell-properties) for more information -- `allCells: Array` - - An array of all `Cell` objects containing properties and functions specific to the row and column it belongs to. - - Not every cell contained here is guaranteed that it should be displayed and is made available here for convenience and advanced templating purposes. - - See [Cell Properties](#cell-properties) for more information -- `values: Object` - - A map of this row's **resolved** values by columnId, eg. `{ firstName: 'Tanner', lastName: 'Linsley' }` -- `getRowProps: Function(?props)` - - **Required** - - 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. -- `subRows: Array` - - 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 - -The following additional properties are available on every `Cell` object returned in an array of `cells` on every row object. - -- `column: Column` - - The corresponding column object for this cell -- `row: Row` - - The corresponding row object for this cell -- `value: any` - - The **resolved** value for this cell. - - By default, this value is displayed on the table via the default `Cell` renderer. To override the way a cell displays -- `getCellProps: Function(?props)` - - **Required** - - This function is used to resolve any props needed for this cell. - - 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)` - - **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. - -### Example - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/basic) -- [Open in CodeSandbox](https://codesandbox.io/s/github/tanstack/react-table/tree/master/examples/basic) diff --git a/docs/api/useTokenPagination.md b/docs/api/useTokenPagination.md deleted file mode 100644 index 491fe28df7..0000000000 --- a/docs/api/useTokenPagination.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -name: useTokenPagination -route: /api/useTokenPagination -menu: API ---- - -# `useTokenPagination (Coming Soon)` - -- Plugin Hook -- Optional - -`useTokenPagination` is the hook that **aids in implementing row pagination using tokens**. It is useful for server-side pagination implementations that use **tokens** instead of page index. For more information on pagination, see Pagination - -> Documentation Coming Soon... diff --git a/docs/examples/basic.mdx b/docs/examples/basic.mdx new file mode 100644 index 0000000000..08e97a3b94 --- /dev/null +++ b/docs/examples/basic.mdx @@ -0,0 +1,23 @@ +--- +id: basic +title: Basic +toc: false +--- + +- [Open in CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/alpha/examples/basic) +- [View Source](https://github.com/tannerlinsley/react-table/tree/alpha/examples/basic) + + diff --git a/docs/examples/column-ordering.mdx b/docs/examples/column-ordering.mdx new file mode 100644 index 0000000000..ae55ce10c3 --- /dev/null +++ b/docs/examples/column-ordering.mdx @@ -0,0 +1,23 @@ +--- +id: column-ordering +title: Column Ordering +toc: false +--- + +- [Open in CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/alpha/examples/column-ordering) +- [View Source](https://github.com/tannerlinsley/react-table/tree/alpha/examples/column-ordering) + + diff --git a/docs/examples/column-pinning.mdx b/docs/examples/column-pinning.mdx new file mode 100644 index 0000000000..241f893d96 --- /dev/null +++ b/docs/examples/column-pinning.mdx @@ -0,0 +1,23 @@ +--- +id: column-pinning +title: Column Pinning +toc: false +--- + +- [Open in CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/alpha/examples/column-pinning) +- [View Source](https://github.com/tannerlinsley/react-table/tree/alpha/examples/column-pinning) + + diff --git a/docs/examples/column-sizing.mdx b/docs/examples/column-sizing.mdx new file mode 100644 index 0000000000..cdfddaa423 --- /dev/null +++ b/docs/examples/column-sizing.mdx @@ -0,0 +1,23 @@ +--- +id: column-sizing +title: Column Sizing +toc: false +--- + +- [Open in CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/alpha/examples/column-sizing) +- [View Source](https://github.com/tannerlinsley/react-table/tree/alpha/examples/column-sizing) + + diff --git a/docs/examples/column-visibility.mdx b/docs/examples/column-visibility.mdx new file mode 100644 index 0000000000..5ccd93d93f --- /dev/null +++ b/docs/examples/column-visibility.mdx @@ -0,0 +1,23 @@ +--- +id: column-visibility +title: Column Visibility +toc: false +--- + +- [Open in CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/alpha/examples/column-visibility) +- [View Source](https://github.com/tannerlinsley/react-table/tree/alpha/examples/column-visibility) + + diff --git a/docs/examples/complex.mdx b/docs/examples/complex.mdx deleted file mode 100644 index 8f8880e6e4..0000000000 --- a/docs/examples/complex.mdx +++ /dev/null @@ -1,25 +0,0 @@ ---- -name: Complex -route: /examples/complex -menu: Examples ---- - -# Complex - -These examples are more advanced because they demonstrate how to manually control and respond to the state of the table. - -## The "Kitchen Sink" - -This example includes Pagination, Sorting, Filtering, Grouping, Expandable Rows and Row Selection so it's called the _Kitchen Sink_. - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/kitchen-sink) -- [Open in CodeSandbox](https://codesandbox.io/s/github/tanstack/react-table/tree/master/examples/kitchen-sink) - - -* Want to add another example? [Submit a PR!](https://github.com/tanstack/react-table/compare) diff --git a/docs/examples/controlled.mdx b/docs/examples/controlled.mdx deleted file mode 100644 index 79de3d93b9..0000000000 --- a/docs/examples/controlled.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -name: Controlled -route: /examples/controlled -menu: Examples ---- - -# Controlled - -These examples are more advanced because they demonstrate how to manually control and respond to the state of the table. - -## Pagination (Controlled) - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/pagination-controlled) -- [Open in CodeSandbox](https://codesandbox.io/s/github/tanstack/react-table/tree/master/examples/pagination-controlled) - - -* Want to add another example? [Submit a PR!](https://github.com/tanstack/react-table/compare) diff --git a/docs/examples/editable-data.mdx b/docs/examples/editable-data.mdx new file mode 100644 index 0000000000..4faec3c945 --- /dev/null +++ b/docs/examples/editable-data.mdx @@ -0,0 +1,23 @@ +--- +id: editable-data +title: Editable Data +toc: false +--- + +- [Open in CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/alpha/examples/editable-data) +- [View Source](https://github.com/tannerlinsley/react-table/tree/alpha/examples/editable-data) + + diff --git a/docs/examples/expanding.mdx b/docs/examples/expanding.mdx new file mode 100644 index 0000000000..f4b0f4cf61 --- /dev/null +++ b/docs/examples/expanding.mdx @@ -0,0 +1,23 @@ +--- +id: expanding +title: Expanding +toc: false +--- + +- [Open in CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/alpha/examples/expanding) +- [View Source](https://github.com/tannerlinsley/react-table/tree/alpha/examples/expanding) + + diff --git a/docs/examples/filters.mdx b/docs/examples/filters.mdx new file mode 100644 index 0000000000..05da5ff123 --- /dev/null +++ b/docs/examples/filters.mdx @@ -0,0 +1,23 @@ +--- +id: filters +title: Filters +toc: false +--- + +- [Open in CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/alpha/examples/filters) +- [View Source](https://github.com/tannerlinsley/react-table/tree/alpha/examples/filters) + + diff --git a/docs/examples/fully-controlled.mdx b/docs/examples/fully-controlled.mdx new file mode 100644 index 0000000000..95cecba290 --- /dev/null +++ b/docs/examples/fully-controlled.mdx @@ -0,0 +1,23 @@ +--- +id: fully-controlled +title: Fully Controlled +toc: false +--- + +- [Open in CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/alpha/examples/fully-controlled) +- [View Source](https://github.com/tannerlinsley/react-table/tree/alpha/examples/fully-controlled) + + diff --git a/docs/examples/grouping.mdx b/docs/examples/grouping.mdx new file mode 100644 index 0000000000..72e93095f7 --- /dev/null +++ b/docs/examples/grouping.mdx @@ -0,0 +1,23 @@ +--- +id: grouping +title: Grouping +toc: false +--- + +- [Open in CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/alpha/examples/grouping) +- [View Source](https://github.com/tannerlinsley/react-table/tree/alpha/examples/grouping) + + diff --git a/docs/examples/pagination.mdx b/docs/examples/pagination.mdx new file mode 100644 index 0000000000..e36f7ea505 --- /dev/null +++ b/docs/examples/pagination.mdx @@ -0,0 +1,23 @@ +--- +id: pagination +title: Pagination +toc: false +--- + +- [Open in CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/alpha/examples/pagination) +- [View Source](https://github.com/tannerlinsley/react-table/tree/alpha/examples/pagination) + + diff --git a/docs/examples/row-selection.mdx b/docs/examples/row-selection.mdx new file mode 100644 index 0000000000..e1282476b7 --- /dev/null +++ b/docs/examples/row-selection.mdx @@ -0,0 +1,23 @@ +--- +id: row-selection +title: Row Selection +toc: false +--- + +- [Open in CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/alpha/examples/row-selection) +- [View Source](https://github.com/tannerlinsley/react-table/tree/alpha/examples/row-selection) + + diff --git a/docs/examples/simple.mdx b/docs/examples/simple.mdx deleted file mode 100644 index 65bbf20076..0000000000 --- a/docs/examples/simple.mdx +++ /dev/null @@ -1,108 +0,0 @@ ---- -name: Simple -route: /examples/simple -menu: Examples ---- - -# Simple - -All of these examples use automatic state management, meaning, they don't hoist any state out of the table or manually control anything. Start here for understanding the basics about how to build your table UI. - -## Basic - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/basic) -- [Open in CodeSandbox](https://codesandbox.io/embed/github/tanstack/react-table/tree/master/examples/basic) - - -## Footers - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/footers) -- [Open in CodeSandbox](https://codesandbox.io/embed/github/tanstack/react-table/tree/master/examples/footers) - -## Sorting - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/sorting) -- [Open in CodeSandbox](https://codesandbox.io/embed/github/tanstack/react-table/tree/master/examples/sorting) - -## Filtering - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/filtering) -- [Open in CodeSandbox](https://codesandbox.io/embed/github/tanstack/react-table/tree/master/examples/filtering) - -## Grouping - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/grouping) -- [Open in CodeSandbox](https://codesandbox.io/embed/github/tanstack/react-table/tree/master/examples/grouping) - -## Grouping (Single Column) - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/grouping-column) -- [Open in CodeSandbox](https://codesandbox.io/embed/github/tanstack/react-table/tree/master/examples/grouping-column) - -## Pagination - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/pagination) -- [Open in CodeSandbox](https://codesandbox.io/embed/github/tanstack/react-table/tree/master/examples/pagination) - -## Row Selection - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/row-selection) -- [Open in CodeSandbox](https://codesandbox.io/embed/github/tanstack/react-table/tree/master/examples/row-selection) - -## Expanding - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/expanding) -- [Open in CodeSandbox](https://codesandbox.io/embed/github/tanstack/react-table/tree/master/examples/sub-components) - -## Sub Components - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/sub-components) -- [Open in CodeSandbox](https://codesandbox.io/embed/github/tanstack/react-table/tree/master/examples/sub-components) - -## Editable Data - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/editable-data) -- [Open in CodeSandbox](https://codesandbox.io/embed/github/tanstack/react-table/tree/master/examples/editable-data) - -## Column Ordering - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/column-ordering) -- [Open in CodeSandbox](https://codesandbox.io/s/github/tanstack/react-table/tree/master/examples/column-ordering) - -## Column Hiding - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/column-hiding) -- [Open in CodeSandbox](https://codesandbox.io/s/github/tanstack/react-table/tree/master/examples/column-hiding) - -## Column Resizing - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/column-resizing) -- [Open in CodeSandbox](https://codesandbox.io/s/github/tanstack/react-table/tree/master/examples/column-resizing) - -## Data-Driven Classes and Styles - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/data-driven-classes-and-styles) -- [Open in CodeSandbox](https://codesandbox.io/s/github/tanstack/react-table/tree/master/examples/data-driven-classes-and-styles) - -## Row DnD - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/row-dnd) -- [Open in CodeSandbox](https://codesandbox.io/s/github/tanstack/react-table/tree/master/examples/row-dnd) - -## Full Width Table (Table Elements with collapsible content) - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/full-width-table) -- [Open in CodeSandbox](https://codesandbox.io/s/github/tanstack/react-table/tree/master/examples/full-width-table) - -## Full Width Resizable Table (via `useFlexLayout`) - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/full-width-resizable-table) -- [Open in CodeSandbox](https://codesandbox.io/s/github/tanstack/react-table/tree/master/examples/full-width-resizable-table) - -* Want to add another example? [Submit a PR!](https://github.com/tanstack/react-table/compare) diff --git a/docs/examples/sorting.mdx b/docs/examples/sorting.mdx new file mode 100644 index 0000000000..5fb94cddbd --- /dev/null +++ b/docs/examples/sorting.mdx @@ -0,0 +1,23 @@ +--- +id: sorting +title: Sorting +toc: false +--- + +- [Open in CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/alpha/examples/sorting) +- [View Source](https://github.com/tannerlinsley/react-table/tree/alpha/examples/sorting) + + diff --git a/docs/examples/ui.mdx b/docs/examples/ui.mdx deleted file mode 100644 index 575492c09f..0000000000 --- a/docs/examples/ui.mdx +++ /dev/null @@ -1,65 +0,0 @@ ---- -name: UI/Rendering -route: /examples/ui -menu: Examples ---- - -# UI and Rendering - -These examples demonstrate how to use React Table with your favorite UI libraries or tools! - -## Virtualized Rows (React-Window) - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/virtualized-rows) -- [Open in CodeSandbox](https://codesandbox.io/s/github/tanstack/react-table/tree/master/examples/virtualized-rows) - - -## Animated (Framer-Motion) - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/animated-framer-motion) -- [Open in CodeSandbox](https://codesandbox.io/s/github/tanstack/react-table/tree/master/examples/animated-framer-motion) - - -## Material-UI - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/material-UI-components) -- [Open in CodeSandbox](https://codesandbox.io/s/github/tanstack/react-table/tree/master/examples/material-UI-components) - - -## Material-UI Enhanced Table - -- [Source](https://github.com/tanstack/react-table/tree/master/examples/material-UI-enhanced-table) -- [Open in CodeSandbox](https://codesandbox.io/s/github/tanstack/react-table/tree/master/examples/material-UI-enhanced-table) - - -## Todo - -- [ ] Styled-Components -- [ ] CSS -- [ ] Bootstrap - -* Want to write one of these examples or add another? [Submit a PR!](https://github.com/tanstack/react-table/compare) diff --git a/docs/guides/filters.md b/docs/guides/filters.md new file mode 100644 index 0000000000..56d0f3d30e --- /dev/null +++ b/docs/guides/filters.md @@ -0,0 +1,39 @@ +# Column Filters + +Let's learn about **column filters**! + +Column filters are stored in the `state.filters` array. Each item in the array is an object containing the column id and the filter value. + +> NOTE: Filters are applied in the order they are specified, which can have various performance implications depending on how each filter is implemented and the resulting rows from each filter + +## Can-Filter Option Priority + +The ability for a column to be **column** filtered is determined by the following fallback logic: + +```tsx +const canColumnFilter = + column.enableAllFilters ?? + column.enableColumnFilter ?? + instance.options.enableFilters ?? + instance.options.enableColumnFilters ?? + column.defaultCanColumnFilter ?? + column.defaultCanFilter ?? + !!column.accessorFn +``` + +The ability for a column to be **globally** filtered is determined by the following fallback logic: + +```tsx +const canGlobalFiler = + ((instance.options.enableFilters ?? + instance.options.enableGlobalFilter ?? + column.enableAllFilters ?? + column.enableGlobalFilter ?? + column.defaultCanFilter ?? + column.defaultCanGlobalFilter ?? + !!column.accessorFn) && + instance.options.getColumnCanGlobalFilterFn?.(column)) ?? + true +``` + +Each option can be set to `true` or `false` to override the default behavior below it. diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx deleted file mode 100644 index d52ebc127a..0000000000 --- a/docs/quickstart.mdx +++ /dev/null @@ -1,178 +0,0 @@ ---- -name: Quick Start -route: /quickstart ---- - -# Quick Start - -As explained in the [Concepts](./concepts) document, react-table is a headless tool, meaning you'll have to build your own UI. We recognize this can be potentially daunting, so here's a very basic table to start with. - -## Define Row Shape - -When thinking about a table, you typically have a number of rows split into a number of columns. While table configurations can get far more complex with nested columns, subrows, etc. for this basic quick start, we need to define some data. Note that this data must be defined using [`React.useMemo`](https://reactjs.org/docs/hooks-reference.html#usememo) in order to take advantage of the power of memoization. - -```javascript -const data = React.useMemo( - () => [ - { - col1: 'Hello', - col2: 'World', - }, - { - col1: 'react-table', - col2: 'rocks', - }, - { - col1: 'whatever', - col2: 'you want', - }, - ], - [] -) -``` - -## Define Columns - -The first step to using react-table is to create a set of column definitions to pass into the `useTable` hook. These columns must be defined using `React.useMemo` in order to take advantage of the power of memoization. - -```javascript -const columns = React.useMemo( - () => [ - { - Header: 'Column 1', - accessor: 'col1', // accessor is the "key" in the data - }, - { - Header: 'Column 2', - accessor: 'col2', - }, - ], - [] -) -``` - -## Implement `useTable` hook - -Now that you have the basic `columns` and `data` defined, you can pass those into `useTable` and retrieve the properties you need. - -```javascript -const { - getTableProps, - getTableBodyProps, - headerGroups, - rows, - prepareRow, -} = useTable({ columns, data }) -``` - -If you're new to JavaScript (especially ES2015+), this syntax may look a little strange. The lefthand side of the assigment is using [object destructuring](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) to extract the properties we need that are returned from the `useTable` hook (or function). On the right hand side, at a minimum, `useTable` needs to be provided with an object containing the memoized columns and data that we created above. - -## Build a basic UI structure - -OK, so that's great, we've implemented the hook, but we still don't have a table to show, right? Let's use the properties returned from `useTable` to build a basic table structure. - -```javascript -return ( - - - {headerGroups.map(headerGroup => ( - - {headerGroup.headers.map(column => ( - - ))} - - ))} - - - {rows.map(row => { - prepareRow(row) - return ( - - {row.cells.map(cell => { - return - })} - - ) - })} - -
{column.render('Header')}
{cell.render('Cell')}
-) -``` - -Again, if you're relatively new to JavaScript (or ES2015+ syntax), you may wonder, "What is with all the ...s?". This is the [spread syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) that _spreads_ all properties of an object (or array) without having to manually extract them all. So, with the first row, `` will return a `table` element with all of the properties returned by `getTableProps()`. - -## Final Result - -If we put all of this together, we should get a very basic (boring) table. (_Styles added just to make it a little more attractive..._) - -_The following example is a live component, so as you make changes in the code, it should update the table at the top._ - -import { Playground } from 'docz' -import { useTable } from '../src/hooks/useTable' - - - {() => { - const data = React.useMemo( - () => [ - { - col1: 'Hello', - col2: 'World', - }, - { - col1: 'react-table', - col2: 'rocks', - }, - { - col1: 'whatever', - col2: 'you want', - }, - ], - [] - ) - const columns = React.useMemo( - () => [ - { - Header: 'Column 1', - accessor: 'col1', // accessor is the "key" in the data - }, - { - Header: 'Column 2', - accessor: 'col2', - }, - ], - [] - ) - const { - getTableProps, - getTableBodyProps, - headerGroups, - rows, - prepareRow, - } = useTable({ columns, data }) - return ( -
- - {headerGroups.map(headerGroup => ( - - {headerGroup.headers.map(column => ( - - ))} - - ))} - - - {rows.map(row => { - prepareRow(row) - return ( - - {row.cells.map(cell => { - return - })} - - ) - })} - -
{column.render('Header')}
{cell.render('Cell')}
- ) - }} - diff --git a/examples/row-selection/src/main.tsx b/examples/row-selection/src/main.tsx index 324aea76e0..5943375823 100644 --- a/examples/row-selection/src/main.tsx +++ b/examples/row-selection/src/main.tsx @@ -221,7 +221,8 @@ function App() {
{Object.keys(rowSelection).length} of{' '} - {instance.getPreFilteredRowModel().rows.length} Total Rows Selected + {instance.getPreColumnFilteredRowModel().rows.length} Total Rows + Selected

diff --git a/packages/table-core/src/features/ColumnSizing.ts b/packages/table-core/src/features/ColumnSizing.ts index 3c309a7bb6..17fdee90e4 100644 --- a/packages/table-core/src/features/ColumnSizing.ts +++ b/packages/table-core/src/features/ColumnSizing.ts @@ -151,15 +151,9 @@ export const ColumnSizing = { ) }, setColumnSizing: updater => - instance.options.onColumnSizingChange?.( - updater, - functionalUpdate(updater, instance.getState().columnSizing) - ), + instance.options.onColumnSizingChange?.(updater), setColumnSizingInfo: updater => - instance.options.onColumnSizingInfoChange?.( - updater, - functionalUpdate(updater, instance.getState().columnSizingInfo) - ), + instance.options.onColumnSizingInfoChange?.(updater), resetColumnSizing: () => { instance.setColumnSizing(instance.initialState.columnSizing ?? {}) }, diff --git a/packages/table-core/src/features/Expanding.ts b/packages/table-core/src/features/Expanding.ts index 3b78b16650..73aa80012f 100644 --- a/packages/table-core/src/features/Expanding.ts +++ b/packages/table-core/src/features/Expanding.ts @@ -46,7 +46,7 @@ export type ToggleExpandedProps = { } export type ExpandedInstance = { - _notifyExpandedReset: () => void + queueResetExpanded: () => void setExpanded: (updater: Updater) => void toggleRowExpanded: (rowId: string, expanded?: boolean) => void toggleAllRowsExpanded: (expanded?: boolean) => void @@ -95,8 +95,8 @@ export const Expanding = { let registered = false return { - _notifyExpandedReset: () => { - instance._notifyPageIndexReset() + queueResetExpanded: () => { + instance.queueResetPageIndex() if (!registered) { registered = true @@ -114,11 +114,7 @@ export const Expanding = { instance.resetExpanded() } }, - setExpanded: updater => - instance.options.onExpandedChange?.( - updater, - functionalUpdate(updater, instance.getState().expanded) - ), + setExpanded: updater => instance.options.onExpandedChange?.(updater), toggleRowExpanded: (rowId, expanded) => { if (!rowId) return diff --git a/packages/table-core/src/features/Filters.ts b/packages/table-core/src/features/Filters.ts index 2031f4e392..fd118f6071 100644 --- a/packages/table-core/src/features/Filters.ts +++ b/packages/table-core/src/features/Filters.ts @@ -71,9 +71,9 @@ export type FiltersColumn = { getCanColumnFilter: () => boolean getCanGlobalFilter: () => boolean getColumnFilterIndex: () => number - getIsColumnFiltered: () => boolean + getColumnIsFiltered: () => boolean getColumnFilterValue: () => unknown - setColumnFilterValue: (value: any) => void + setColumnFilterValue: (updater: Updater) => void getPreFilteredRows: () => Row[] | undefined getPreFilteredUniqueValues: () => Map getPreFilteredMinMaxValues: () => [any, any] @@ -102,24 +102,20 @@ export type FiltersOptions = { } export type FiltersInstance = { - _notifyFiltersReset: () => void + queueResetFilters: () => void getColumnAutoFilterFn: (columnId: string) => FilterFn | undefined getColumnFilterFn: (columnId: string) => FilterFn | undefined setColumnFilters: (updater: Updater) => void - setColumnFilterValue: (columnId: string, value: any) => void + setColumnFilterValue: (columnId: string, updater: Updater) => void resetColumnFilters: () => void getColumnCanColumnFilter: (columnId: string) => boolean - getColumnCanGlobalFilterFn?: (column: Column) => boolean getColumnIsFiltered: (columnId: string) => boolean getColumnFilterValue: (columnId: string) => unknown getColumnFilterIndex: (columnId: string) => number - // All - getPreFilteredRowModel: () => RowModel - // Column Filters getPreColumnFilteredRowModel: () => RowModel getColumnFilteredRowModel: () => RowModel @@ -225,7 +221,7 @@ export const Filters = { getCanColumnFilter: () => instance.getColumnCanColumnFilter(column.id), getCanGlobalFilter: () => instance.getColumnCanGlobalFilter(column.id), getColumnFilterIndex: () => instance.getColumnFilterIndex(column.id), - getIsColumnFiltered: () => instance.getColumnIsFiltered(column.id), + getColumnIsFiltered: () => instance.getColumnIsFiltered(column.id), getColumnFilterValue: () => instance.getColumnFilterValue(column.id), setColumnFilterValue: val => instance.setColumnFilterValue(column.id, val), @@ -241,8 +237,8 @@ export const Filters = { let registered = false return { - _notifyFiltersReset: () => { - instance._notifySortingReset() + queueResetFilters: () => { + instance.queueResetSorting() if (!registered) { registered = true @@ -348,17 +344,11 @@ export const Filters = { }) } - instance.options.onColumnFiltersChange?.( - updateFn, - updateFn(instance.getState().columnFilters) - ) + instance.options.onColumnFiltersChange?.(updateFn) }, setGlobalFilter: updater => { - instance.options.onGlobalFilterChange?.( - updater, - functionalUpdate(updater, instance.getState().globalFilter) - ) + instance.options.onGlobalFilterChange?.(updater) }, resetGlobalFilter: () => { @@ -472,7 +462,6 @@ export const Filters = { instance.setColumnFilters(instance.initialState?.columnFilters ?? []) }, - getPreFilteredRowModel: () => instance.getCoreRowModel(), getPreColumnFilteredRowModel: () => instance.getCoreRowModel(), getColumnFilteredRowModel: () => { if ( diff --git a/packages/table-core/src/features/Grouping.ts b/packages/table-core/src/features/Grouping.ts index f204989c74..65105d4df9 100644 --- a/packages/table-core/src/features/Grouping.ts +++ b/packages/table-core/src/features/Grouping.ts @@ -114,7 +114,7 @@ export type ToggleGroupingProps = { } export type GroupingInstance = { - _notifyGroupingReset: () => void + queueResetGrouping: () => void getColumnAutoAggregationFn: ( columnId: string ) => AggregationFn | undefined @@ -185,8 +185,8 @@ export const Grouping = { let registered = false return { - _notifyGroupingReset: () => { - instance._notifyExpandedReset() + queueResetGrouping: () => { + instance.queueResetExpanded() if (!registered) { registered = true @@ -239,11 +239,7 @@ export const Grouping = { ] as AggregationFn) }, - setGrouping: updater => - instance.options.onGroupingChange?.( - updater, - functionalUpdate(updater, instance.getState().grouping) - ), + setGrouping: updater => instance.options.onGroupingChange?.(updater), toggleColumnGrouping: columnId => { instance.setGrouping(old => { diff --git a/packages/table-core/src/features/Ordering.ts b/packages/table-core/src/features/Ordering.ts index f10c8515a9..7b40ec200a 100644 --- a/packages/table-core/src/features/Ordering.ts +++ b/packages/table-core/src/features/Ordering.ts @@ -53,10 +53,7 @@ export const Ordering = { ): ColumnOrderInstance => { return { setColumnOrder: updater => - instance.options.onColumnOrderChange?.( - updater, - functionalUpdate(updater, instance.getState().columnOrder) - ), + instance.options.onColumnOrderChange?.(updater), resetColumnOrder: () => { instance.setColumnOrder(instance.initialState.columnOrder ?? []) }, diff --git a/packages/table-core/src/features/Pagination.ts b/packages/table-core/src/features/Pagination.ts index 6634f3d917..898b51f72a 100644 --- a/packages/table-core/src/features/Pagination.ts +++ b/packages/table-core/src/features/Pagination.ts @@ -32,7 +32,7 @@ export type PaginationDefaultOptions = { } export type PaginationInstance = { - _notifyPageIndexReset: () => void + queueResetPageIndex: () => void setPagination: (updater: Updater) => void resetPagination: () => void setPageIndex: (updater: Updater) => void @@ -78,7 +78,7 @@ export const Pagination = { ): PaginationInstance => { let registered = false return { - _notifyPageIndexReset: () => { + queueResetPageIndex: () => { if (!registered) { registered = true return @@ -102,10 +102,7 @@ export const Pagination = { return newState } - return instance.options.onPaginationChange?.( - safeUpdater, - functionalUpdate(safeUpdater, instance.getState().pagination) - ) + return instance.options.onPaginationChange?.(safeUpdater) }, resetPagination: () => { instance.setPagination( diff --git a/packages/table-core/src/features/Pinning.ts b/packages/table-core/src/features/Pinning.ts index 71abcca589..2725f4dbc8 100644 --- a/packages/table-core/src/features/Pinning.ts +++ b/packages/table-core/src/features/Pinning.ts @@ -87,10 +87,7 @@ export const Pinning = { ): ColumnPinningInstance => { return { setColumnPinning: updater => - instance.options.onColumnPinningChange?.( - updater, - functionalUpdate(updater, instance.getState().columnPinning) - ), + instance.options.onColumnPinningChange?.(updater), resetColumnPinning: () => instance.setColumnPinning(instance.initialState?.columnPinning ?? {}), diff --git a/packages/table-core/src/features/RowSelection.ts b/packages/table-core/src/features/RowSelection.ts index 75c0479d41..ed8bc83a5b 100644 --- a/packages/table-core/src/features/RowSelection.ts +++ b/packages/table-core/src/features/RowSelection.ts @@ -61,7 +61,7 @@ export type RowSelectionRow = { } export type RowSelectionInstance = { - _notifyRowSelectionReset: () => void + queueResetRowSelection: () => void getToggleRowSelectedProps: >( rowId: string, userProps?: TGetter @@ -129,7 +129,7 @@ export const RowSelection = { // const pageRows = instance.getPageRows() return { - _notifyRowSelectionReset: () => { + queueResetRowSelection: () => { if (!registered) { registered = true return @@ -147,10 +147,7 @@ export const RowSelection = { } }, setRowSelection: updater => - instance.options.onRowSelectionChange?.( - updater, - functionalUpdate(updater, instance.getState().rowSelection) - ), + instance.options.onRowSelectionChange?.(updater), resetRowSelection: () => instance.setRowSelection(instance.initialState.rowSelection ?? {}), toggleAllRowsSelected: value => { @@ -288,7 +285,7 @@ export const RowSelection = { key: 'getSelectedRowModel', debug: () => instance.options.debugAll ?? instance.options.debugTable, onChange: () => { - instance.queue(() => instance._notifyExpandedReset()) + instance.queue(() => instance.queueResetExpanded()) }, } ), @@ -312,7 +309,7 @@ export const RowSelection = { { key: 'getFilteredSelectedRowModel', debug: () => instance.options.debugAll ?? instance.options.debugTable, - onChange: () => instance.queue(() => instance._notifyExpandedReset()), + onChange: () => instance.queue(() => instance.queueResetExpanded()), } ), @@ -332,7 +329,7 @@ export const RowSelection = { { key: 'getGroupedSelectedRowModel', debug: () => instance.options.debugAll ?? instance.options.debugTable, - onChange: () => instance.queue(() => instance._notifyExpandedReset()), + onChange: () => instance.queue(() => instance.queueResetExpanded()), } ), diff --git a/packages/table-core/src/features/Sorting.ts b/packages/table-core/src/features/Sorting.ts index adc1321ca9..06578987b0 100644 --- a/packages/table-core/src/features/Sorting.ts +++ b/packages/table-core/src/features/Sorting.ts @@ -100,7 +100,7 @@ export type ToggleSortingProps = { } export type SortingInstance = { - _notifySortingReset: () => void + queueResetSorting: () => void getColumnAutoSortingFn: (columnId: string) => SortingFn | undefined getColumnAutoSortDir: (columnId: string) => SortDirection @@ -179,8 +179,8 @@ export const Sorting = { let registered = false return { - _notifySortingReset: () => { - instance._notifyGroupingReset() + queueResetSorting: () => { + instance.queueResetGrouping() if (!registered) { registered = true @@ -258,11 +258,7 @@ export const Sorting = { ] as SortingFn) }, - setSorting: updater => - instance.options.onSortingChange?.( - updater, - functionalUpdate(updater, instance.getState().sorting) - ), + setSorting: updater => instance.options.onSortingChange?.(updater), toggleColumnSorting: (columnId, desc, multi) => { const column = instance.getColumn(columnId) diff --git a/packages/table-core/src/features/Visibility.ts b/packages/table-core/src/features/Visibility.ts index ed7277fdb6..e408ddc19d 100644 --- a/packages/table-core/src/features/Visibility.ts +++ b/packages/table-core/src/features/Visibility.ts @@ -157,10 +157,7 @@ export const Visibility = { ), setColumnVisibility: updater => - instance.options.onColumnVisibilityChange?.( - updater, - functionalUpdate(updater, instance.getState().columnVisibility) - ), + instance.options.onColumnVisibilityChange?.(updater), toggleColumnVisibility: (columnId, value) => { if (!columnId) return diff --git a/packages/table-core/src/types.ts b/packages/table-core/src/types.ts index ac6779ae93..c13b2a1465 100644 --- a/packages/table-core/src/types.ts +++ b/packages/table-core/src/types.ts @@ -138,7 +138,7 @@ export type Options = CoreOptions & RowSelectionOptions export type Updater = T | ((old: T) => T) -export type OnChangeFn = (updaterOrValue: Updater, value: T) => void +export type OnChangeFn = (updaterOrValue: Updater) => void export type TableState = CoreTableState & VisibilityTableState & diff --git a/packages/table-core/src/utils/getColumnFilteredRowModelAsync.ts b/packages/table-core/src/utils/getColumnFilteredRowModelAsync.ts index 1439a613a1..01ca5b586e 100644 --- a/packages/table-core/src/utils/getColumnFilteredRowModelAsync.ts +++ b/packages/table-core/src/utils/getColumnFilteredRowModelAsync.ts @@ -114,7 +114,7 @@ export function getColumnFilteredRowModelAsync< debug: () => instance.options.debugAll ?? instance.options.debugTable, onChange: () => { instance.queue(() => { - instance._notifySortingReset() + instance.queueResetSorting() }) }, } diff --git a/packages/table-core/src/utils/getColumnFilteredRowModelSync.ts b/packages/table-core/src/utils/getColumnFilteredRowModelSync.ts index cce35f285b..d1daa092c4 100644 --- a/packages/table-core/src/utils/getColumnFilteredRowModelSync.ts +++ b/packages/table-core/src/utils/getColumnFilteredRowModelSync.ts @@ -94,7 +94,7 @@ export function getColumnFilteredRowModelSync< debug: () => instance.options.debugAll ?? instance.options.debugTable, onChange: () => { instance.queue(() => { - instance._notifySortingReset() + instance.queueResetSorting() }) }, } diff --git a/packages/table-core/src/utils/getCoreRowModelAsync.ts b/packages/table-core/src/utils/getCoreRowModelAsync.ts index 017815a46a..12859bd2e3 100644 --- a/packages/table-core/src/utils/getCoreRowModelAsync.ts +++ b/packages/table-core/src/utils/getCoreRowModelAsync.ts @@ -96,8 +96,8 @@ export function getCoreRowModelAsync(opts?: { debug: () => instance.options.debugAll ?? instance.options.debugTable, onChange: () => { instance.queue(() => { - instance._notifyFiltersReset() - instance._notifyRowSelectionReset() + instance.queueResetFilters() + instance.queueResetRowSelection() }) }, } diff --git a/packages/table-core/src/utils/getCoreRowModelSync.ts b/packages/table-core/src/utils/getCoreRowModelSync.ts index 9e1a9f42a3..e847f4f989 100644 --- a/packages/table-core/src/utils/getCoreRowModelSync.ts +++ b/packages/table-core/src/utils/getCoreRowModelSync.ts @@ -98,8 +98,8 @@ export function getCoreRowModelSync(): ( debug: () => instance.options.debugAll ?? instance.options.debugTable, onChange: () => { instance.queue(() => { - instance._notifyFiltersReset() - instance._notifyRowSelectionReset() + instance.queueResetFilters() + instance.queueResetRowSelection() }) }, } diff --git a/packages/table-core/src/utils/getGlobalFilteredRowModelAsync.ts b/packages/table-core/src/utils/getGlobalFilteredRowModelAsync.ts index e8fbe1dc49..4111fb7927 100644 --- a/packages/table-core/src/utils/getGlobalFilteredRowModelAsync.ts +++ b/packages/table-core/src/utils/getGlobalFilteredRowModelAsync.ts @@ -92,7 +92,7 @@ export function getGlobalFilteredRowModelAsync< debug: () => instance.options.debugAll ?? instance.options.debugTable, onChange: () => { instance.queue(() => { - instance._notifySortingReset() + instance.queueResetSorting() }) }, } diff --git a/packages/table-core/src/utils/getGlobalFilteredRowModelSync.ts b/packages/table-core/src/utils/getGlobalFilteredRowModelSync.ts index d456f67d99..2b125e119f 100644 --- a/packages/table-core/src/utils/getGlobalFilteredRowModelSync.ts +++ b/packages/table-core/src/utils/getGlobalFilteredRowModelSync.ts @@ -71,7 +71,7 @@ export function getGlobalFilteredRowModelSync< debug: () => instance.options.debugAll ?? instance.options.debugTable, onChange: () => { instance.queue(() => { - instance._notifySortingReset() + instance.queueResetSorting() }) }, } diff --git a/packages/table-core/src/utils/getGroupedRowModel.ts b/packages/table-core/src/utils/getGroupedRowModel.ts index bad2cde813..0d4ce9329e 100644 --- a/packages/table-core/src/utils/getGroupedRowModel.ts +++ b/packages/table-core/src/utils/getGroupedRowModel.ts @@ -165,7 +165,7 @@ export function getGroupedRowModelSync(): ( debug: () => instance.options.debugAll ?? instance.options.debugTable, onChange: () => { instance.queue(() => { - instance._notifyExpandedReset() + instance.queueResetExpanded() }) }, } diff --git a/packages/table-core/src/utils/getSortedRowModelAsync.ts b/packages/table-core/src/utils/getSortedRowModelAsync.ts index 10ff160143..d57545909e 100644 --- a/packages/table-core/src/utils/getSortedRowModelAsync.ts +++ b/packages/table-core/src/utils/getSortedRowModelAsync.ts @@ -84,7 +84,7 @@ export function getSortedRowModelSync(opts?: { debug: () => instance.options.debugAll ?? instance.options.debugTable, onChange: () => { instance.queue(() => { - instance._notifyGroupingReset() + instance.queueResetGrouping() }) }, } diff --git a/packages/table-core/src/utils/getSortedRowModelSync.ts b/packages/table-core/src/utils/getSortedRowModelSync.ts index 438c1d48fb..0e3794ca45 100644 --- a/packages/table-core/src/utils/getSortedRowModelSync.ts +++ b/packages/table-core/src/utils/getSortedRowModelSync.ts @@ -110,7 +110,7 @@ export function getSortedRowModelSync(): ( debug: () => instance.options.debugAll ?? instance.options.debugTable, onChange: () => { instance.queue(() => { - instance._notifyGroupingReset() + instance.queueResetGrouping() }) }, }