diff --git a/.prettierignore b/.prettierignore index fe4bf24ffd..63dd7224e6 100644 --- a/.prettierignore +++ b/.prettierignore @@ -6,6 +6,7 @@ **/dist **/docs **/old-examples +**/examples/**/*.svelte pnpm-lock.yaml .angular diff --git a/.vscode/extensions.json b/.vscode/extensions.json index 113575312c..1d7ac851ea 100644 --- a/.vscode/extensions.json +++ b/.vscode/extensions.json @@ -1,7 +1,3 @@ { - "recommendations": [ - "vitest.explorer", - "dbaeumer.vscode-eslint", - "esbenp.prettier-vscode" - ] + "recommendations": ["dbaeumer.vscode-eslint", "esbenp.prettier-vscode"] } diff --git a/docs/api/core/cell.md b/docs/api/core/cell.md deleted file mode 100644 index aa2041f5bf..0000000000 --- a/docs/api/core/cell.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Cell APIs ---- - -These are **core** options and API properties for all cells. More options and API properties are available for other [table features](../../../guide/features). - -## Cell API - -All cell objects have the following properties: - -### `id` - -```tsx -id: string -``` - -The unique ID for the cell across the entire table. - -### `getValue` - -```tsx -getValue: () => any -``` - -Returns the value for the cell, accessed via the associated column's accessor key or accessor function. - -### `renderValue` - -```tsx -renderValue: () => any -``` - -Renders the value for a cell the same as `getValue`, but will return the `renderFallbackValue` if no value is found. - -### `row` - -```tsx -row: Row -``` - -The associated Row object for the cell. - -### `column` - -```tsx -column: Column -``` - -The associated Column object for the cell. - -### `getContext` - -```tsx -getContext: () => { - table: Table - column: Column - row: Row - cell: Cell - getValue: () => TTValue - renderValue: () => TTValue | null -} -``` - -Returns the rendering context (or props) for cell-based components like cells and aggregated cells. Use these props with your framework's `flexRender` utility to render these using the template of your choice: - -```tsx -flexRender(cell.column.columnDef.cell, cell.getContext()) -``` diff --git a/docs/api/core/column-def.md b/docs/api/core/column-def.md deleted file mode 100644 index 04ea925b87..0000000000 --- a/docs/api/core/column-def.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: ColumnDef APIs ---- - -Column definitions are plain objects with the following options: - -## Options - -### `id` - -```tsx -id: string -``` - -The unique identifier for the column. - -> 🧠 A column ID is optional when: -> -> - An accessor column is created with an object key accessor -> - The column header is defined as a string - -### `accessorKey` - -```tsx -accessorKey?: string & typeof TData -``` - -The key of the row object to use when extracting the value for the column. - -### `accessorFn` - -```tsx -accessorFn?: (originalRow: TData, index: number) => any -``` - -The accessor function to use when extracting the value for the column from each row. - -### `columns` - -```tsx -columns?: ColumnDef[] -``` - -The child column defs to include in a group column. - -### `header` - -```tsx -header?: - | string - | ((props: { - table: Table - header: Header - column: Column - }) => unknown) -``` - -The header to display for the column. If a string is passed, it can be used as a default for the column ID. If a function is passed, it will be passed a props object for the header and should return the rendered header value (the exact type depends on the adapter being used). - -### `footer` - -```tsx -footer?: - | string - | ((props: { - table: Table - header: Header - column: Column - }) => unknown) -``` - -The footer to display for the column. If a function is passed, it will be passed a props object for the footer and should return the rendered footer value (the exact type depends on the adapter being used). - -### `cell` - -```tsx -cell?: - | string - | ((props: { - table: Table - row: Row - column: Column - cell: Cell - getValue: () => any - renderValue: () => any - }) => unknown) -``` - -The cell to display each row for the column. If a function is passed, it will be passed a props object for the cell and should return the rendered cell value (the exact type depends on the adapter being used). - -### `meta` - -```tsx -meta?: ColumnMeta // This interface is extensible via declaration merging. See below! -``` - -The meta data to be associated with the column. We can access it anywhere when the column is available via `column.columnDef.meta`. This type is global to all tables and can be extended like so: - -```tsx -import '@tanstack/react-table' //or vue, svelte, solid, etc. - -declare module '@tanstack/react-table' { - interface ColumnMeta { - foo: string - } -} -``` diff --git a/docs/api/core/column.md b/docs/api/core/column.md deleted file mode 100644 index d4ad77bc07..0000000000 --- a/docs/api/core/column.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: Column APIs ---- - -These are **core** options and API properties for all columns. More options and API properties are available for other [table features](../../../guide/features). - -## Column API - -All column objects have the following properties: - -### `id` - -```tsx -id: string -``` - -The resolved unique identifier for the column resolved in this priority: - -- A manual `id` property from the column def -- The accessor key from the column def -- The header string from the column def - -### `depth` - -```tsx -depth: number -``` - -The depth of the column (if grouped) relative to the root column def array. - -### `accessorFn` - -```tsx -accessorFn?: AccessorFn -``` - -The resolved accessor function to use when extracting the value for the column from each row. Will only be defined if the column def has a valid accessor key or function defined. - -### `columnDef` - -```tsx -columnDef: ColumnDef -``` - -The original column def used to create the column. - -### `columns` - -```tsx -type columns = ColumnDef[] -``` - -The child column (if the column is a group column). Will be an empty array if the column is not a group column. - -### `parent` - -```tsx -parent?: Column -``` - -The parent column for this column. Will be undefined if this is a root column. - -### `getFlatColumns` - -```tsx -type getFlatColumns = () => Column[] -``` - -Returns the flattened array of this column and all child/grand-child columns for this column. - -### `getLeafColumns` - -```tsx -type getLeafColumns = () => Column[] -``` - -Returns an array of all leaf-node columns for this column. If a column has no children, it is considered the only leaf-node column. diff --git a/docs/api/core/header-group.md b/docs/api/core/header-group.md deleted file mode 100644 index 221b65cdf7..0000000000 --- a/docs/api/core/header-group.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: HeaderGroup APIs ---- - -These are **core** options and API properties for all header groups. More options and API properties may be available for other [table features](../../../guide/features). - -## Header Group API - -All header group objects have the following properties: - -### `id` - -```tsx -id: string -``` - -The unique identifier for the header group. - -### `depth` - -```tsx -depth: number -``` - -The depth of the header group, zero-indexed based. - -### `headers` - -```tsx -type headers = Header[] -``` - -An array of [Header](../header) objects that belong to this header group diff --git a/docs/api/core/header.md b/docs/api/core/header.md deleted file mode 100644 index ac1ca7c8b2..0000000000 --- a/docs/api/core/header.md +++ /dev/null @@ -1,243 +0,0 @@ ---- -title: Header APIs ---- - -These are **core** options and API properties for all headers. More options and API properties may be available for other [table features](../../../guide/features). - -## Header API - -All header objects have the following properties: - -### `id` - -```tsx -id: string -``` - -The unique identifier for the header. - -### `index` - -```tsx -index: number -``` - -The index for the header within the header group. - -### `depth` - -```tsx -depth: number -``` - -The depth of the header, zero-indexed based. - -### `column` - -```tsx -column: Column -``` - -The header's associated [Column](../column) object - -### `headerGroup` - -```tsx -headerGroup: HeaderGroup -``` - -The header's associated [HeaderGroup](../header-group) object - -### `subHeaders` - -```tsx -type subHeaders = Header[] -``` - -The header's hierarchical sub/child headers. Will be empty if the header's associated column is a leaf-column. - -### `colSpan` - -```tsx -colSpan: number -``` - -The col-span for the header. - -### `rowSpan` - -```tsx -rowSpan: number -``` - -The row-span for the header. - -### `getLeafHeaders` - -```tsx -type getLeafHeaders = () => Header[] -``` - -Returns the leaf headers hierarchically nested under this header. - -### `isPlaceholder` - -```tsx -isPlaceholder: boolean -``` - -A boolean denoting if the header is a placeholder header - -### `placeholderId` - -```tsx -placeholderId?: string -``` - -If the header is a placeholder header, this will be a unique header ID that does not conflict with any other headers across the table - -### `getContext` - -```tsx -getContext: () => { - table: Table - header: Header - column: Column -} -``` - -Returns the rendering context (or props) for column-based components like headers, footers and filters. Use these props with your framework's `flexRender` utility to render these using the template of your choice: - -```tsx -flexRender(header.column.columnDef.header, header.getContext()) -``` - -## Table API - -### `getHeaderGroups` - -```tsx -type getHeaderGroups = () => HeaderGroup[] -``` - -Returns all header groups for the table. - -### `getLeftHeaderGroups` - -```tsx -type getLeftHeaderGroups = () => HeaderGroup[] -``` - -If pinning, returns the header groups for the left pinned columns. - -### `getCenterHeaderGroups` - -```tsx -type getCenterHeaderGroups = () => HeaderGroup[] -``` - -If pinning, returns the header groups for columns that are not pinned. - -### `getRightHeaderGroups` - -```tsx -type getRightHeaderGroups = () => HeaderGroup[] -``` - -If pinning, returns the header groups for the right pinned columns. - -### `getFooterGroups` - -```tsx -type getFooterGroups = () => HeaderGroup[] -``` - -Returns all footer groups for the table. - -### `getLeftFooterGroups` - -```tsx -type getLeftFooterGroups = () => HeaderGroup[] -``` - -If pinning, returns the footer groups for the left pinned columns. - -### `getCenterFooterGroups` - -```tsx -type getCenterFooterGroups = () => HeaderGroup[] -``` - -If pinning, returns the footer groups for columns that are not pinned. - -### `getRightFooterGroups` - -```tsx -type getRightFooterGroups = () => HeaderGroup[] -``` - -If pinning, returns the footer groups for the right pinned columns. - -### `getFlatHeaders` - -```tsx -type getFlatHeaders = () => Header[] -``` - -Returns headers for all columns in the table, including parent headers. - -### `getLeftFlatHeaders` - -```tsx -type getLeftFlatHeaders = () => Header[] -``` - -If pinning, returns headers for all left pinned columns in the table, including parent headers. - -### `getCenterFlatHeaders` - -```tsx -type getCenterFlatHeaders = () => Header[] -``` - -If pinning, returns headers for all columns that are not pinned, including parent headers. - -### `getRightFlatHeaders` - -```tsx -type getRightFlatHeaders = () => Header[] -``` - -If pinning, returns headers for all right pinned columns in the table, including parent headers. - -### `getLeafHeaders` - -```tsx -type getLeafHeaders = () => Header[] -``` - -Returns headers for all leaf columns in the table, (not including parent headers). - -### `getLeftLeafHeaders` - -```tsx -type getLeftLeafHeaders = () => Header[] -``` - -If pinning, returns headers for all left pinned leaf columns in the table, (not including parent headers). - -### `getCenterLeafHeaders` - -```tsx -type getCenterLeafHeaders = () => Header[] -``` - -If pinning, returns headers for all columns that are not pinned, (not including parent headers). - -### `getRightLeafHeaders` - -```tsx -type getRightLeafHeaders = () => Header[] -``` - -If pinning, returns headers for all right pinned leaf columns in the table, (not including parent headers). diff --git a/docs/api/core/row.md b/docs/api/core/row.md deleted file mode 100644 index 72c01d3422..0000000000 --- a/docs/api/core/row.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: Row APIs ---- - -These are **core** options and API properties for all rows. More options and API properties are available for other [table features](../../../guide/features). - -## Row API - -All row objects have the following properties: - -### `id` - -```tsx -id: string -``` - -The resolved unique identifier for the row resolved via the `options.getRowId` option. Defaults to the row's index (or relative index if it is a subRow) - -### `depth` - -```tsx -depth: number -``` - -The depth of the row (if nested or grouped) relative to the root row array. - -### `index` - -```tsx -index: number -``` - -The index of the row within its parent array (or the root data array) - -### `original` - -```tsx -original: TData -``` - -The original row object provided to the table. - -> 🧠 If the row is a grouped row, the original row object will be the first original in the group. - -### `parentId` - -```tsx -parentId?: string -``` - -If nested, this row's parent row id. - -### `getValue` - -```tsx -getValue: (columnId: string) => TValue -``` - -Returns the value from the row for a given columnId - -### `renderValue` - -```tsx -renderValue: (columnId: string) => TValue -``` - -Renders the value from the row for a given columnId, but will return the `renderFallbackValue` if no value is found. - -### `getUniqueValues` - -```tsx -getUniqueValues: (columnId: string) => TValue[] -``` - -Returns a unique array of values from the row for a given columnId. - -### `subRows` - -```tsx -type subRows = Row[] -``` - -An array of subRows for the row as returned and created by the `options.getSubRows` option. - -### `getParentRow` - -```tsx -type getParentRow = () => Row | undefined -``` - -Returns the parent row for the row, if it exists. - -### `getParentRows` - -```tsx -type getParentRows = () => Row[] -``` - -Returns the parent rows for the row, all the way up to a root row. - -### `getLeafRows` - -```tsx -type getLeafRows = () => Row[] -``` - -Returns the leaf rows for the row, not including any parent rows. - -### `originalSubRows` - -```tsx -originalSubRows?: TData[] -``` - -An array of the original subRows as returned by the `options.getSubRows` option. - -### `getAllCells` - -```tsx -type getAllCells = () => Cell[] -``` - -Returns all of the [Cells](../cell) for the row. diff --git a/docs/api/core/table.md b/docs/api/core/table.md deleted file mode 100644 index dc00a0182f..0000000000 --- a/docs/api/core/table.md +++ /dev/null @@ -1,385 +0,0 @@ ---- -title: Table APIs ---- - -## `createTable` / `useTable` / `injectTable` - -```tsx -type useTable = ( - options: TableOptions -) => Table -``` - -These functions are used to create a table. Which one you use depends on which framework adapter you are using. - -## Options - -These are **core** options and API properties for the table. More options and API properties are available for other [table features](../../../guide/features). - -### `data` - -```tsx -data: TData[] -``` - -The data for the table to display. This array should match the type you provided to `table.setRowType<...>`, but in theory could be an array of anything. It's common for each item in the array to be an object of key/values but this is not required. Columns can access this data via string/index or a functional accessor to return anything they want. - -When the `data` option changes reference (compared via `Object.is`), the table will reprocess the data. Any other data processing that relies on the core data model (such as grouping, sorting, filtering, etc) will also be reprocessed. - -> 🧠 Make sure your `data` option is only changing when you want the table to reprocess. Providing an inline `[]` or constructing the data array as a new object every time you want to render the table will result in a _lot_ of unnecessary re-processing. This can easily go unnoticed in smaller tables, but you will likely notice it in larger tables. - -### `columns` - -```tsx -type columns = ColumnDef[] -``` - -The array of column defs to use for the table. See the [Column Defs Guide](../../docs/guide/column-defs) for more information on creating column definitions. - -### `defaultColumn` - -```tsx -defaultColumn?: Partial> -``` - -Default column options to use for all column defs supplied to the table. This is useful for providing default cell/header/footer renderers, sorting/filtering/grouping options, etc. All column definitions passed to `options.columns` are merged with this default column definition to produce the final column definitions. - -### `initialState` - -```tsx -initialState?: Partial< - VisibilityTableState & - ColumnOrderTableState & - ColumnPinningTableState & - FiltersTableState & - SortingTableState & - ExpandedTableState & - GroupingTableState & - ColumnSizingTableState & - PaginationTableState & - RowSelectionTableState -> -``` - -Use this option to optionally pass initial state to the table. This state will be used when resetting various table states either automatically by the table (eg. `options.autoResetPageIndex`) or via functions like `table.resetRowSelection()`. Most reset function allow you optionally pass a flag to reset to a blank/default state instead of the initial state. - -> 🧠 Table state will not be reset when this object changes, which also means that the initial state object does not need to be stable. - -### `autoResetAll` - -```tsx -autoResetAll?: boolean -``` - -Set this option to override any of the `autoReset...` feature options. - -### `meta` - -```tsx -meta?: TableMeta // This interface is extensible via declaration merging. See below! -``` - -You can pass any object to `options.meta` and access it anywhere the `table` is available via `table.options.meta` This type is global to all tables and can be extended like so: - -```tsx -declare module '@tanstack/table-core' { - interface TableMeta { - foo: string - } -} -``` - -> 🧠 Think of this option as an arbitrary "context" for your table. This is a great way to pass arbitrary data or functions to your table without having to pass it to every thing the table touches. A good example is passing a locale object to your table to use for formatting dates, numbers, etc or even a function that can be used to update editable data like in the [editable-data example](../../../framework/react/examples/editable-data). - -### `state` - -```tsx -state?: Partial< - VisibilityTableState & - ColumnOrderTableState & - ColumnPinningTableState & - FiltersTableState & - SortingTableState & - ExpandedTableState & - GroupingTableState & - ColumnSizingTableState & - PaginationTableState & - RowSelectionTableState -> -``` - -The `state` option can be used to optionally _control_ part or all of the table state. The state you pass here will merge with and overwrite the internal automatically-managed state to produce the final state for the table. You can also listen to state changes via the `onStateChange` option. - -### `onStateChange` - -```tsx -onStateChange: (updater: Updater) => void -``` - -The `onStateChange` option can be used to optionally listen to state changes within the table. If you provide this options, you will be responsible for controlling and updating the table state yourself. You can provide the state back to the table with the `state` option. - -### `debugAll` - -> ⚠️ Debugging is only available in development mode. - -```tsx -debugAll?: boolean -``` - -Set this option to true to output all debugging information to the console. - -### `debugTable` - -> ⚠️ Debugging is only available in development mode. - -```tsx -debugTable?: boolean -``` - -Set this option to true to output table debugging information to the console. - -### `debugHeaders` - -> ⚠️ Debugging is only available in development mode. - -```tsx -debugHeaders?: boolean -``` - -Set this option to true to output header debugging information to the console. - -### `debugColumns` - -> ⚠️ Debugging is only available in development mode. - -```tsx -debugColumns?: boolean -``` - -Set this option to true to output column debugging information to the console. - -### `debugRows` - -> ⚠️ Debugging is only available in development mode. - -```tsx -debugRows?: boolean -``` - -Set this option to true to output row debugging information to the console. - -### `_features` - -```tsx -_features?: TableFeature[] -``` - -An array of extra features that you can add to the table instance. - -### `render` - -> ⚠️ This option is only necessary if you are implementing a table adapter. - -```tsx -type render = (template: Renderable, props: TProps) => any -``` - -The `render` option provides a renderer implementation for the table. This implementation is used to turn a table's various column header and cell templates into a result that is supported by the user's framework. - -### `mergeOptions` - -> ⚠️ This option is only necessary if you are implementing a table adapter. - -```tsx -type mergeOptions = (defaultOptions: T, options: Partial) => T -``` - -This option is used to optionally implement the merging of table options. Some framework like solid-js use proxies to track reactivity and usage, so merging reactive objects needs to be handled carefully. This option inverts control of this process to the adapter. - -### `getCoreRowModel` - -```tsx -getCoreRowModel: (table: Table) => () => RowModel -``` - -This required option is a factory for a function that computes and returns the core row model for the table. It is called **once** per table and should return a **new function** which will calculate and return the row model for the table. - -A default implementation is provided via any table adapter's `{ getCoreRowModel }` export. - -### `getSubRows` - -```tsx -getSubRows?: ( - originalRow: TData, - index: number -) => undefined | TData[] -``` - -This optional function is used to access the sub rows for any given row. If you are using nested rows, you will need to use this function to return the sub rows object (or undefined) from the row. - -### `getRowId` - -```tsx -getRowId?: ( - originalRow: TData, - index: number, - parent?: Row -) => string -``` - -This optional function is used to derive a unique ID for any given row. If not provided the rows index is used (nested rows join together with `.` using their grandparents' index eg. `index.index.index`). If you need to identify individual rows that are originating from any server-side operations, it's suggested you use this function to return an ID that makes sense regardless of network IO/ambiguity eg. a userId, taskId, database ID field, etc. - -## Table API - -These properties and methods are available on the table object: - -### `initialState` - -```tsx -initialState: VisibilityTableState & - ColumnOrderTableState & - ColumnPinningTableState & - FiltersTableState & - SortingTableState & - ExpandedTableState & - GroupingTableState & - ColumnSizingTableState & - PaginationTableState & - RowSelectionTableState -``` - -This is the resolved initial state of the table. - -### `reset` - -```tsx -reset: () => void -``` - -Call this function to reset the table state to the initial state. - -### `getState` - -```tsx -getState: () => TableState -``` - -Call this function to get the table's current state. It's recommended to use this function and its state, especially when managing the table state manually. It is the exact same state used internally by the table for every feature and function it provides. - -> 🧠 The state returned by this function is the shallow-merged result of the automatically-managed internal table-state and any manually-managed state passed via `options.state`. - -### `setState` - -```tsx -setState: (updater: Updater) => void -``` - -Call this function to update the table state. It's recommended you pass an updater function in the form of `(prevState) => newState` to update the state, but a direct object can also be passed. - -> 🧠 If `options.onStateChange` is provided, it will be triggered by this function with the new state. - -### `options` - -```tsx -options: TableOptions -``` - -A read-only reference to the table's current options. - -> ⚠️ This property is generally used internally or by adapters. It can be updated by passing new options to your table. This is different per adapter. For adapters themselves, table options must be updated via the `setOptions` function. - -### `setOptions` - -```tsx -setOptions: (newOptions: Updater>) => void -``` - -> ⚠️ This function is generally used by adapters to update the table options. It can be used to update the table options directly, but it is generally not recommended to bypass your adapters strategy for updating table options. - -### `getCoreRowModel` - -```tsx -getCoreRowModel: () => { - rows: Row[], - flatRows: Row[], - rowsById: Record>, -} -``` - -Returns the core row model before any processing has been applied. - -### `getRowModel` - -```tsx -getRowModel: () => { - rows: Row[], - flatRows: Row[], - rowsById: Record>, -} -``` - -Returns the final model after all processing from other used features has been applied. - -### `getAllColumns` - -```tsx -type getAllColumns = () => Column[] -``` - -Returns all columns in the table in their normalized and nested hierarchy, mirrored from the column defs passed to the table. - -### `getAllFlatColumns` - -```tsx -type getAllFlatColumns = () => Column[] -``` - -Returns all columns in the table flattened to a single level. This includes parent column objects throughout the hierarchy. - -### `getAllLeafColumns` - -```tsx -type getAllLeafColumns = () => Column[] -``` - -Returns all leaf-node columns in the table flattened to a single level. This does not include parent columns. - -### `getColumn` - -```tsx -type getColumn = (id: string) => Column | undefined -``` - -Returns a single column by its ID. - -### `getHeaderGroups` - -```tsx -type getHeaderGroups = () => HeaderGroup[] -``` - -Returns the header groups for the table. - -### `getFooterGroups` - -```tsx -type getFooterGroups = () => HeaderGroup[] -``` - -Returns the footer groups for the table. - -### `getFlatHeaders` - -```tsx -type getFlatHeaders = () => Header[] -``` - -Returns a flattened array of Header objects for the table, including parent headers. - -### `getLeafHeaders` - -```tsx -type getLeafHeaders = () => Header[] -``` - -Returns a flattened array of leaf-node Header objects for the table. diff --git a/docs/api/features/column-faceting.md b/docs/api/features/column-faceting.md deleted file mode 100644 index b80629037f..0000000000 --- a/docs/api/features/column-faceting.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Column Faceting APIs -id: column-faceting ---- - -## Column API - -### `getFacetedRowModel` - -```tsx -type getFacetedRowModel = () => RowModel -``` - -> ⚠️ Requires that you pass a valid `getFacetedRowModel` function to `options.facetedRowModel`. A default implementation is provided via the exported `getFacetedRowModel` function. - -Returns the row model with all other column filters applied, excluding its own filter. Useful for displaying faceted result counts. - -### `getFacetedUniqueValues` - -```tsx -getFacetedUniqueValues: () => Map -``` - -> ⚠️ Requires that you pass a valid `getFacetedUniqueValues` function to `options.getFacetedUniqueValues`. A default implementation is provided via the exported `getFacetedUniqueValues` function. - -A function that **computes and returns** a `Map` of unique values and their occurrences derived from `column.getFacetedRowModel`. Useful for displaying faceted result values. - -### `getFacetedMinMaxValues` - -```tsx -getFacetedMinMaxValues: () => Map -``` - -> ⚠️ Requires that you pass a valid `getFacetedMinMaxValues` function to `options.getFacetedMinMaxValues`. A default implementation is provided via the exported `getFacetedMinMaxValues` function. - -A function that **computes and returns** a min/max tuple derived from `column.getFacetedRowModel`. Useful for displaying faceted result values. - -## Table Options - -### `getColumnFacetedRowModel` - -```tsx -getColumnFacetedRowModel: (columnId: string) => RowModel -``` - -Returns the faceted row model for a given columnId. diff --git a/docs/api/features/column-filtering.md b/docs/api/features/column-filtering.md deleted file mode 100644 index f8201b5653..0000000000 --- a/docs/api/features/column-filtering.md +++ /dev/null @@ -1,395 +0,0 @@ ---- -title: Column Filtering APIs -id: column-filtering ---- - -## Can-Filter - -The ability for a column to be **column** filtered is determined by the following: - -- The column was defined with a valid `accessorKey`/`accessorFn`. -- `column.enableColumnFilter` is not set to `false` -- `options.enableColumnFilters` is not set to `false` -- `options.enableFilters` is not set to `false` - -## State - -Filter state is stored on the table using the following shape: - -```tsx -export interface ColumnFiltersTableState { - columnFilters: ColumnFiltersState -} - -export type ColumnFiltersState = ColumnFilter[] - -export interface 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 -- `arrIncludesSome` - - Some items included in an array -- `equals` - - Object/referential equality `Object.is`/`===` -- `weakEquals` - - Weak object/referential equality `==` -- `inNumberRange` - - Number range inclusion - -Every filter function receives: - -- The row to filter -- The columnId to use to retrieve the row's value -- The filter value - -and should return `true` if the row should be included in the filtered rows, and `false` if it should be removed. - -This is the type signature for every filter function: - -```tsx -export type FilterFn = { - ( - row: Row, - columnId: string, - filterValue: any, - addMeta: (meta: any) => void - ): boolean - resolveFilterValue?: TransformFilterValueFn - autoRemove?: ColumnFilterAutoRemoveTestFn - addMeta?: (meta?: any) => void -} - -export type TransformFilterValueFn = ( - value: any, - column?: Column -) => unknown - -export type ColumnFilterAutoRemoveTestFn = ( - value: any, - column?: Column -) => boolean - -export type CustomFilterFns = Record< - string, - FilterFn -> -``` - -### `filterFn.resolveFilterValue` - -This optional "hanging" method on any given `filterFn` allows the filter function to transform/sanitize/format the filter value before it is passed to the filter function. - -### `filterFn.autoRemove` - -This optional "hanging" method on any given `filterFn` is passed a filter value and expected to return `true` if the filter value should be removed from the filter state. eg. Some boolean-style filters may want to remove the filter value from the table state if the filter value is set to `false`. - -#### Using Filter Functions - -Filter functions can be used/referenced/defined by passing the following to `columnDefinition.filterFn`: - -- A `string` that references a built-in filter function -- A function directly provided to the `columnDefinition.filterFn` option - -The final list of filter functions available for the `columnDef.filterFn` option use the following type: - -```tsx -export type FilterFnOption = - | 'auto' - | BuiltInFilterFn - | FilterFn -``` - -#### Filter Meta - -Filtering data can often expose additional information about the data that can be used to aid other future operations on the same data. A good example of this concept is a ranking-system like that of [`match-sorter`](https://github.com/kentcdodds/match-sorter) that simultaneously ranks, filters and sorts data. While utilities like `match-sorter` make a lot of sense for single-dimensional filter+sort tasks, the decoupled filtering/sorting architecture of building a table makes them very difficult and slow to use. - -To make a ranking/filtering/sorting system work with tables, `filterFn`s can optionally mark results with a **filter meta** value that can be used later to sort/group/etc the data to your liking. This is done by calling the `addMeta` function supplied to your custom `filterFn`. - -Below is an example using our own `match-sorter-utils` package (a utility fork of `match-sorter`) to rank, filter, and sort the data - -```tsx -import { sortFns } from '@tanstack/react-table' -import { rankItem, compareItems } from '@tanstack/match-sorter-utils' - -const fuzzyFilter = (row, columnId, value, addMeta) => { - // Rank the item - const itemRank = rankItem(row.getValue(columnId), value) - - // Store the ranking info - addMeta(itemRank) - - // Return if the item should be filtered in/out - return itemRank.passed -} - -const fuzzySort = (rowA, rowB, columnId) => { - let dir = 0 - - // Only sort by rank if the column has ranking information - if (rowA.columnFiltersMeta[columnId]) { - dir = compareItems( - rowA.columnFiltersMeta[columnId]!, - rowB.columnFiltersMeta[columnId]! - ) - } - - // Provide an alphanumeric fallback for when the item ranks are equal - return dir === 0 ? sortFns.alphanumeric(rowA, rowB, columnId) : dir -} -``` - -## Column Def Options - -### `filterFn` - -```tsx -filterFn?: FilterFn | keyof FilterFns | keyof BuiltInFilterFns -``` - -The filter function to use with this column. - -Options: - -- A `string` referencing a [built-in filter function](#filter-functions)) -- A [custom filter function](#filter-functions) - -### `enableColumnFilter` - -```tsx -enableColumnFilter?: boolean -``` - -Enables/disables the **column** filter for this column. - -## Column API - -### `getCanFilter` - -```tsx -getCanFilter: () => boolean -``` - -Returns whether or not the column can be **column** filtered. - -### `getFilterIndex` - -```tsx -getFilterIndex: () => number -``` - -Returns the index (including `-1`) of the column filter in the table's `state.columnFilters` array. - -### `getIsFiltered` - -```tsx -getIsFiltered: () => boolean -``` - -Returns whether or not the column is currently filtered. - -### `getFilterValue` - -```tsx -getFilterValue: () => unknown -``` - -Returns the current filter value of the column. - -### `setFilterValue` - -```tsx -setFilterValue: (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. - -### `getAutoFilterFn` - -```tsx -getAutoFilterFn: (columnId: string) => FilterFn | undefined -``` - -Returns an automatically calculated filter function for the column based off of the columns first known value. - -### `getFilterFn` - -```tsx -getFilterFn: (columnId: string) => FilterFn | undefined -``` - -Returns the filter function (either user-defined or automatic, depending on configuration) for the columnId specified. - -## Row API - -### `columnFilters` - -```tsx -columnFilters: Record -``` - -The column filters map for the row. This object tracks whether a row is passing/failing specific filters by their column ID. - -### `columnFiltersMeta` - -```tsx -columnFiltersMeta: Record -``` - -The column filters meta map for the row. This object tracks any filter meta for a row as optionally provided during the filtering process. - -## Table Options - -### `filterFns` - -```tsx -filterFns?: Record -``` - -This option allows you to define custom filter functions that can be referenced in a column's `filterFn` option by their key. -Example: - -```tsx -declare module '@tanstack/[adapter]-table' { - interface FilterFns { - myCustomFilter: FilterFn - } -} - -const column = columnHelper.data('key', { - filterFn: 'myCustomFilter', -}) - -const table = useTable({ - columns: [column], - filterFns: { - myCustomFilter: (rows, columnIds, filterValue) => { - // return the filtered rows - }, - }, -}) -``` - -### `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). - -### `maxLeafRowFilterDepth` - -```tsx -maxLeafRowFilterDepth?: number -``` - -By default, filtering is done for all rows (max depth of 100), no matter if they are root level parent rows or the child leaf rows of a parent row. Setting this option to `0` will cause filtering to only be applied to the root level parent rows, with all sub-rows remaining unfiltered. Similarly, setting this option to `1` will cause filtering to only be applied to child leaf rows 1 level deep, and so on. - -This is useful for situations where you want a row's entire child hierarchy to be visible regardless of the applied filter. - -### `enableFilters` - -```tsx -enableFilters?: boolean -``` - -Enables/disables all filters for the table. - -### `manualFiltering` - -```tsx -manualFiltering?: boolean -``` - -Disables the `getFilteredRowModel` from being used to filter data. This may be useful if your table needs to dynamically support both client-side and server-side filtering. - -### `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. - -### `enableColumnFilters` - -```tsx -enableColumnFilters?: boolean -``` - -Enables/disables **all** column filters for the table. - -### `getFilteredRowModel` - -```tsx -getFilteredRowModel?: ( - table: Table -) => () => RowModel -``` - -If provided, this function is called **once** per table 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 `{ getFilteredRowModel }` export. - -Example: - -```tsx -import { getFilteredRowModel } from '@tanstack/[adapter]-table' - - - getFilteredRowModel: createFilteredRowModel(filterFns), -}) -``` - -## Table API - -### `setColumnFilters` - -```tsx -setColumnFilters: (updater: Updater) => void -``` - -Sets or updates the `state.columnFilters` state. - -### `resetColumnFilters` - -```tsx -resetColumnFilters: (defaultState?: boolean) => void -``` - -Resets the **columnFilters** state to `initialState.columnFilters`, or `true` can be passed to force a default blank state reset to `[]`. - -### `getPreFilteredRowModel` - -```tsx -getPreFilteredRowModel: () => RowModel -``` - -Returns the row model for the table before any **column** filtering has been applied. - -### `getFilteredRowModel` - -```tsx -getFilteredRowModel: () => RowModel -``` - -Returns the row model for the table after **column** filtering has been applied. diff --git a/docs/api/features/column-ordering.md b/docs/api/features/column-ordering.md deleted file mode 100644 index 37bfb95337..0000000000 --- a/docs/api/features/column-ordering.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: Column Ordering APIs -id: column-ordering ---- - -## State - -Column ordering state is stored on the table using the following shape: - -```tsx -export type ColumnOrderTableState = { - columnOrder: ColumnOrderState -} - -export type ColumnOrderState = string[] -``` - -## Table Options - -### `onColumnOrderChange` - -```tsx -onColumnOrderChange?: OnChangeFn -``` - -If provided, this function will be called with an `updaterFn` when `state.columnOrder` 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. - -## Table API - -### `setColumnOrder` - -```tsx -setColumnOrder: (updater: Updater) => void -``` - -Sets or updates the `state.columnOrder` state. - -### `resetColumnOrder` - -```tsx -resetColumnOrder: (defaultState?: boolean) => void -``` - -Resets the **columnOrder** state to `initialState.columnOrder`, or `true` can be passed to force a default blank state reset to `[]`. - -## Column API - -### `getIndex` - -```tsx -getIndex: (position?: ColumnPinningPosition) => number -``` - -Returns the index of the column in the order of the visible columns. Optionally pass a `position` parameter to get the index of the column in a sub-section of the table. - -### `getIsFirstColumn` - -```tsx -getIsFirstColumn: (position?: ColumnPinningPosition) => boolean -``` - -Returns `true` if the column is the first column in the order of the visible columns. Optionally pass a `position` parameter to check if the column is the first in a sub-section of the table. - -### `getIsLastColumn` - -```tsx -getIsLastColumn: (position?: ColumnPinningPosition) => boolean -``` - -Returns `true` if the column is the last column in the order of the visible columns. Optionally pass a `position` parameter to check if the column is the last in a sub-section of the table. \ No newline at end of file diff --git a/docs/api/features/column-pinning.md b/docs/api/features/column-pinning.md deleted file mode 100644 index 6adc0b1afe..0000000000 --- a/docs/api/features/column-pinning.md +++ /dev/null @@ -1,266 +0,0 @@ ---- -title: Column Pinning APIs -id: column-pinning ---- - -## Can-Pin - -The ability for a column to be **pinned** is determined by the following: - -- `options.enablePinning` is not set to `false` -- `options.enableColumnPinning` is not set to `false` -- `columnDefinition.enablePinning` is not set to `false` - -## State - -Pinning state is stored on the table using the following shape: - -```tsx -export type ColumnPinningPosition = false | 'left' | 'right' - -export type ColumnPinningState = { - left?: string[] - right?: string[] -} - - -export type ColumnPinningTableState = { - columnPinning: ColumnPinningState -} -``` - -## Table Options - -### `enableColumnPinning` - -```tsx -enableColumnPinning?: boolean -``` - -Enables/disables column pinning for all columns in the table. - -### `onColumnPinningChange` - -```tsx -onColumnPinningChange?: OnChangeFn -``` - -If provided, this function will be called with an `updaterFn` when `state.columnPinning` changes. This overrides the default internal state management, so you will also need to supply `state.columnPinning` from your own managed state. - -## Column Def Options - -### `enablePinning` - -```tsx -enablePinning?: boolean -``` - -Enables/disables pinning for the column. - -## Table API - -### `setColumnPinning` - -```tsx -setColumnPinning: (updater: Updater) => void -``` - -Sets or updates the `state.columnPinning` state. - -### `resetColumnPinning` - -```tsx -resetColumnPinning: (defaultState?: boolean) => void -``` - -Resets the **columnPinning** state to `initialState.columnPinning`, or `true` can be passed to force a default blank state reset to `{ left: [], right: [], }`. - -### `getIsSomeColumnsPinned` - -```tsx -getIsSomeColumnsPinned: (position?: ColumnPinningPosition) => boolean -``` - -Returns whether or not any columns are pinned. Optionally specify to only check for pinned columns in either the `left` or `right` position. - -_Note: Does not account for column visibility_ - -### `getLeftHeaderGroups` - -```tsx -getLeftHeaderGroups: () => HeaderGroup[] -``` - -Returns the left pinned header groups for the table. - -### `getCenterHeaderGroups` - -```tsx -getCenterHeaderGroups: () => HeaderGroup[] -``` - -Returns the unpinned/center header groups for the table. - -### `getRightHeaderGroups` - -```tsx -getRightHeaderGroups: () => HeaderGroup[] -``` - -Returns the right pinned header groups for the table. - -### `getLeftFooterGroups` - -```tsx -getLeftFooterGroups: () => HeaderGroup[] -``` - -Returns the left pinned footer groups for the table. - -### `getCenterFooterGroups` - -```tsx -getCenterFooterGroups: () => HeaderGroup[] -``` - -Returns the unpinned/center footer groups for the table. - -### `getRightFooterGroups` - -```tsx -getRightFooterGroups: () => HeaderGroup[] -``` - -Returns the right pinned footer groups for the table. - -### `getLeftFlatHeaders` - -```tsx -getLeftFlatHeaders: () => Header[] -``` - -Returns a flat array of left pinned headers for the table, including parent headers. - -### `getCenterFlatHeaders` - -```tsx -getCenterFlatHeaders: () => Header[] -``` - -Returns a flat array of unpinned/center headers for the table, including parent headers. - -### `getRightFlatHeaders` - -```tsx -getRightFlatHeaders: () => Header[] -``` - -Returns a flat array of right pinned headers for the table, including parent headers. - -### `getLeftLeafHeaders` - -```tsx -getLeftLeafHeaders: () => Header[] -``` - -Returns a flat array of leaf-node left pinned headers for the table. - -### `getCenterLeafHeaders` - -```tsx -getCenterLeafHeaders: () => Header[] -``` - -Returns a flat array of leaf-node unpinned/center headers for the table. - -### `getRightLeafHeaders` - -```tsx -getRightLeafHeaders: () => Header[] -``` - -Returns a flat array of leaf-node right pinned headers for the table. - -### `getLeftLeafColumns` - -```tsx -getLeftLeafColumns: () => Column[] -``` - -Returns all left pinned leaf columns. - -### `getRightLeafColumns` - -```tsx -getRightLeafColumns: () => Column[] -``` - -Returns all right pinned leaf columns. - -### `getCenterLeafColumns` - -```tsx -getCenterLeafColumns: () => Column[] -``` - -Returns all center pinned (unpinned) leaf columns. - -## Column API - -### `getCanPin` - -```tsx -getCanPin: () => boolean -``` - -Returns whether or not the column can be pinned. - -### `getPinnedIndex` - -```tsx -getPinnedIndex: () => number -``` - -Returns the numeric pinned index of the column within a pinned column group. - -### `getIsPinned` - -```tsx -getIsPinned: () => ColumnPinningPosition -``` - -Returns the pinned position of the column. (`'left'`, `'right'` or `false`) - -### `pin` - -```tsx -pin: (position: ColumnPinningPosition) => void -``` - -Pins a column to the `'left'` or `'right'`, or unpins the column to the center if `false` is passed. - -## Row API - -### `getLeftVisibleCells` - -```tsx -getLeftVisibleCells: () => Cell[] -``` - -Returns all left pinned leaf cells in the row. - -### `getRightVisibleCells` - -```tsx -getRightVisibleCells: () => Cell[] -``` - -Returns all right pinned leaf cells in the row. - -### `getCenterVisibleCells` - -```tsx -getCenterVisibleCells: () => Cell[] -``` - -Returns all center pinned (unpinned) leaf cells in the row. diff --git a/docs/api/features/column-sizing.md b/docs/api/features/column-sizing.md deleted file mode 100644 index 0bf7631be8..0000000000 --- a/docs/api/features/column-sizing.md +++ /dev/null @@ -1,253 +0,0 @@ ---- -title: Column Sizing APIs -id: column-sizing ---- - -## State - -Column sizing state is stored on the table using the following shape: - -```tsx -export type ColumnSizingTableState = { - columnSizing: ColumnSizing - columnSizingInfo: ColumnSizingInfoState -} - -export type ColumnSizing = Record - -export type ColumnSizingInfoState = { - startOffset: null | number - startSize: null | number - deltaOffset: null | number - deltaPercentage: null | number - isResizingColumn: false | string - columnSizingStart: [string, number][] -} -``` - -## Column Def Options - -### `enableResizing` - -```tsx -enableResizing?: boolean -``` - -Enables or disables column resizing for the column. - -### `size` - -```tsx -size?: number -``` - -The desired size for the column - -### `minSize` - -```tsx -minSize?: number -``` - -The minimum allowed size for the column - -### `maxSize` - -```tsx -maxSize?: number -``` - -The maximum allowed size for the column - -## Column API - -### `getSize` - -```tsx -getSize: () => number -``` - -Returns the current size of the column - -### `getStart` - -```tsx -getStart: (position?: ColumnPinningPosition) => number -``` - -Returns the offset measurement along the row-axis (usually the x-axis for standard tables) for the column, measuring the size of all preceding columns. - -Useful for sticky or absolute positioning of columns. (e.g. `left` or `transform`) - -### `getAfter` - -```tsx -getAfter: (position?: ColumnPinningPosition) => number -``` - -Returns the offset measurement along the row-axis (usually the x-axis for standard tables) for the column, measuring the size of all succeeding columns. - -Useful for sticky or absolute positioning of columns. (e.g. `right` or `transform`) - -### `getCanResize` - -```tsx -getCanResize: () => boolean -``` - -Returns `true` if the column can be resized. - -### `getIsResizing` - -```tsx -getIsResizing: () => boolean -``` - -Returns `true` if the column is currently being resized. - -### `resetSize` - -```tsx -resetSize: () => void -``` - -Resets the column size to its initial size. - -## Header API - -### `getSize` - -```tsx -getSize: () => number -``` - -Returns the size for the header, calculated by summing the size of all leaf-columns that belong to it. - -### `getStart` - -```tsx -getStart: (position?: ColumnPinningPosition) => number -``` - -Returns the offset measurement along the row-axis (usually the x-axis for standard tables) for the header. This is effectively a sum of the offset measurements of all preceding headers. - -### `getResizeHandler` - -```tsx -getResizeHandler: () => (event: unknown) => void -``` - -Returns an event handler function that can be used to resize the header. It can be used as an: - -- `onMouseDown` handler -- `onTouchStart` handler - -The dragging and release events are automatically handled for you. - -## Table Options - -### `enableColumnResizing` - -```tsx -enableColumnResizing?: boolean -``` - -Enables/disables column resizing for \*all columns\*\*. - -### `columnResizeMode` - -```tsx -columnResizeMode?: 'onChange' | 'onEnd' -``` - -Determines when the columnSizing state is updated. `onChange` updates the state when the user is dragging the resize handle. `onEnd` updates the state when the user releases the resize handle. - -### `columnResizeDirection` - -```tsx -columnResizeDirection?: 'ltr' | 'rtl' -``` - -Enables or disables right-to-left support for resizing the column. defaults to 'ltr'. - -### `onColumnSizingChange` - -```tsx -onColumnSizingChange?: OnChangeFn -``` - -This optional function will be called when the columnSizing state changes. If you provide this function, you will be responsible for maintaining its state yourself. You can pass this state back to the table via the `state.columnSizing` table option. - -### `onColumnSizingInfoChange` - -```tsx -onColumnSizingInfoChange?: OnChangeFn -``` - -This optional function will be called when the columnSizingInfo state changes. If you provide this function, you will be responsible for maintaining its state yourself. You can pass this state back to the table via the `state.columnSizingInfo` table option. - -## Table API - -### `setColumnSizing` - -```tsx -setColumnSizing: (updater: Updater) => void -``` - -Sets the column sizing state using an updater function or a value. This will trigger the underlying `onColumnSizingChange` function if one is passed to the table options, otherwise the state will be managed automatically by the table. - -### `setColumnSizingInfo` - -```tsx -setColumnSizingInfo: (updater: Updater) => void -``` - -Sets the column sizing info state using an updater function or a value. This will trigger the underlying `onColumnSizingInfoChange` function if one is passed to the table options, otherwise the state will be managed automatically by the table. - -### `resetColumnSizing` - -```tsx -resetColumnSizing: (defaultState?: boolean) => void -``` - -Resets column sizing to its initial state. If `defaultState` is `true`, the default state for the table will be used instead of the initialValue provided to the table. - -### `resetHeaderSizeInfo` - -```tsx -resetHeaderSizeInfo: (defaultState?: boolean) => void -``` - -Resets column sizing info to its initial state. If `defaultState` is `true`, the default state for the table will be used instead of the initialValue provided to the table. - -### `getTotalSize` - -```tsx -getTotalSize: () => number -``` - -Returns the total size of the table by calculating the sum of the sizes of all leaf-columns. - -### `getLeftTotalSize` - -```tsx -getLeftTotalSize: () => number -``` - -If pinning, returns the total size of the left portion of the table by calculating the sum of the sizes of all left leaf-columns. - -### `getCenterTotalSize` - -```tsx -getCenterTotalSize: () => number -``` - -If pinning, returns the total size of the center portion of the table by calculating the sum of the sizes of all unpinned/center leaf-columns. - -### `getRightTotalSize` - -```tsx -getRightTotalSize: () => number -``` - -If pinning, returns the total size of the right portion of the table by calculating the sum of the sizes of all right leaf-columns. diff --git a/docs/api/features/column-visibility.md b/docs/api/features/column-visibility.md deleted file mode 100644 index b0c8686a7a..0000000000 --- a/docs/api/features/column-visibility.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: Column Visibility APIs -id: column-visibility ---- - -## State - -Column visibility state is stored on the table using the following shape: - -```tsx -export type ColumnVisibilityState = Record - -export type VisibilityTableState = { - columnVisibility: ColumnVisibilityState -} -``` - -## Column Def Options - -### `enableHiding` - -```tsx -enableHiding?: boolean -``` - -Enables/disables hiding the column - -## Column API - -### `getCanHide` - -```tsx -getCanHide: () => boolean -``` - -Returns whether the column can be hidden - -### `getIsVisible` - -```tsx -getIsVisible: () => boolean -``` - -Returns whether the column is visible - -### `toggleVisibility` - -```tsx -toggleVisibility: (value?: boolean) => void -``` - -Toggles the column visibility - -### `getToggleVisibilityHandler` - -```tsx -getToggleVisibilityHandler: () => (event: unknown) => void -``` - -Returns a function that can be used to toggle the column visibility. This function can be used to bind to an event handler to a checkbox. - -## Table Options - -### `onColumnVisibilityChange` - -```tsx -onColumnVisibilityChange?: OnChangeFn -``` - -If provided, this function will be called with an `updaterFn` when `state.columnVisibility` 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. - -### `enableHiding` - -```tsx -enableHiding?: boolean -``` - -Enables/disables hiding of columns. - -## Table API - -### `getVisibleFlatColumns` - -```tsx -getVisibleFlatColumns: () => Column[] -``` - -Returns a flat array of columns that are visible, including parent columns. - -### `getVisibleLeafColumns` - -```tsx -getVisibleLeafColumns: () => Column[] -``` - -Returns a flat array of leaf-node columns that are visible. - -### `getLeftVisibleLeafColumns` - -```tsx -getLeftVisibleLeafColumns: () => Column[] -``` - -If column pinning, returns a flat array of leaf-node columns that are visible in the left portion of the table. - -### `getRightVisibleLeafColumns` - -```tsx -getRightVisibleLeafColumns: () => Column[] -``` - -If column pinning, returns a flat array of leaf-node columns that are visible in the right portion of the table. - -### `getCenterVisibleLeafColumns` - -```tsx -getCenterVisibleLeafColumns: () => Column[] -``` - -If column pinning, returns a flat array of leaf-node columns that are visible in the unpinned/center portion of the table. - -### `setColumnVisibility` - -```tsx -setColumnVisibility: (updater: Updater) => void -``` - -Updates the column visibility state via an updater function or value - -### `resetColumnVisibility` - -```tsx -resetColumnVisibility: (defaultState?: boolean) => void -``` - -Resets the column visibility state to the initial state. If `defaultState` is provided, the state will be reset to `{}` - -### `toggleAllColumnsVisible` - -```tsx -toggleAllColumnsVisible: (value?: boolean) => void -``` - -Toggles the visibility of all columns - -### `getIsAllColumnsVisible` - -```tsx -getIsAllColumnsVisible: () => boolean -``` - -Returns whether all columns are visible - -### `getIsSomeColumnsVisible` - -```tsx -getIsSomeColumnsVisible: () => boolean -``` - -Returns whether some columns are visible - -### `getToggleAllColumnsVisibilityHandler` - -```tsx -getToggleAllColumnsVisibilityHandler: () => ((event: unknown) => void) -``` - -Returns a handler for toggling the visibility of all columns, meant to be bound to a `input[type=checkbox]` element. - -## Row API - -### `getVisibleCells` - -```tsx -getVisibleCells: () => Cell[] -``` - -Returns an array of cells that account for column visibility for the row. \ No newline at end of file diff --git a/docs/api/features/expanding.md b/docs/api/features/expanding.md deleted file mode 100644 index d838513064..0000000000 --- a/docs/api/features/expanding.md +++ /dev/null @@ -1,208 +0,0 @@ ---- -title: Expanding APIs -id: expanding ---- - -## State - -Expanding state is stored on the table using the following shape: - -```tsx -export type ExpandedState = true | Record - -export type ExpandedTableState = { - expanded: ExpandedState -} -``` - -## Row API - -### `toggleExpanded` - -```tsx -toggleExpanded: (expanded?: boolean) => void -``` - -Toggles the expanded state (or sets it if `expanded` is provided) for the row. - -### `getIsExpanded` - -```tsx -getIsExpanded: () => boolean -``` - -Returns whether the row is expanded. - -### `getIsAllParentsExpanded` - -```tsx -getIsAllParentsExpanded: () => boolean -``` - -Returns whether all parent rows of the row are expanded. - -### `getCanExpand` - -```tsx -getCanExpand: () => boolean -``` - -Returns whether the row can be expanded. - -### `getToggleExpandedHandler` - -```tsx -getToggleExpandedHandler: () => () => void -``` - -Returns a function that can be used to toggle the expanded state of the row. This function can be used to bind to an event handler to a button. - -## Table Options - -### `manualExpanding` - -```tsx -manualExpanding?: boolean -``` - -Enables manual row expansion. If this is set to `true`, `getExpandedRowModel` will not be used to expand rows and you would be expected to perform the expansion in your own data model. This is useful if you are doing server-side expansion. - -### `onExpandedChange` - -```tsx -onExpandedChange?: OnChangeFn -``` - -This function is called when the `expanded` table state changes. If a function is provided, you will be responsible for managing this state on your own. To pass the managed state back to the table, use the `tableOptions.state.expanded` option. - -### `autoResetExpanded` - -```tsx -autoResetExpanded?: boolean -``` - -Enable this setting to automatically reset the expanded state of the table when expanding state changes. - -### `enableExpanding` - -```tsx -enableExpanding?: boolean -``` - -Enable/disable expanding for all rows. - -### `getExpandedRowModel` - -```tsx -getExpandedRowModel?: (table: Table) => () => RowModel -``` - -This function is responsible for returning the expanded row model. If this function is not provided, the table will not expand rows. You can use the default exported `getExpandedRowModel` function to get the expanded row model or implement your own. - -### `getIsRowExpanded` - -```tsx -getIsRowExpanded?: (row: Row) => boolean -``` - -If provided, allows you to override the default behavior of determining whether a row is currently expanded. - -### `getRowCanExpand` - -```tsx -getRowCanExpand?: (row: Row) => boolean -``` - -If provided, allows you to override the default behavior of determining whether a row can be expanded. - -### `paginateExpandedRows` - -```tsx -paginateExpandedRows?: boolean -``` - -If `true` expanded rows will be paginated along with the rest of the table (which means expanded rows may span multiple pages). - -If `false` expanded rows will not be considered for pagination (which means expanded rows will always render on their parents page. This also means more rows will be rendered than the set page size) - -## Table API - -### `setExpanded` - -```tsx -setExpanded: (updater: Updater) => void -``` - -Updates the expanded state of the table via an update function or value - -### `toggleAllRowsExpanded` - -```tsx -toggleAllRowsExpanded: (expanded?: boolean) => void -``` - -Toggles the expanded state for all rows. Optionally, provide a value to set the expanded state to. - -### `resetExpanded` - -```tsx -resetExpanded: (defaultState?: boolean) => void -``` - -Reset the expanded state of the table to the initial state. If `defaultState` is provided, the expanded state will be reset to `{}` - -### `getCanSomeRowsExpand` - -```tsx -getCanSomeRowsExpand: () => boolean -``` - -Returns whether there are any rows that can be expanded. - -### `getToggleAllRowsExpandedHandler` - -```tsx -getToggleAllRowsExpandedHandler: () => (event: unknown) => void -``` - -Returns a handler that can be used to toggle the expanded state of all rows. This handler is meant to be used with an `input[type=checkbox]` element. - -### `getIsSomeRowsExpanded` - -```tsx -getIsSomeRowsExpanded: () => boolean -``` - -Returns whether there are any rows that are currently expanded. - -### `getIsAllRowsExpanded` - -```tsx -getIsAllRowsExpanded: () => boolean -``` - -Returns whether all rows are currently expanded. - -### `getExpandedDepth` - -```tsx -getExpandedDepth: () => number -``` - -Returns the maximum depth of the expanded rows. - -### `getExpandedRowModel` - -```tsx -getExpandedRowModel: () => RowModel -``` - -Returns the row model after expansion has been applied. - -### `getPreExpandedRowModel` - -```tsx -getPreExpandedRowModel: () => RowModel -``` - -Returns the row model before expansion has been applied. diff --git a/docs/api/features/filters.md b/docs/api/features/filters.md deleted file mode 100644 index c7c05fcd73..0000000000 --- a/docs/api/features/filters.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Filter APIs -id: filters ---- - - - -The Filtering API docs are now split into multiple API doc pages: - -- [Column Faceting](../column-faceting) -- [Global Faceting](../global-faceting) -- [Column Filtering](../column-filtering) -- [Global Filtering](../global-filtering) \ No newline at end of file diff --git a/docs/api/features/global-faceting.md b/docs/api/features/global-faceting.md deleted file mode 100644 index 489571e1c4..0000000000 --- a/docs/api/features/global-faceting.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Global Faceting APIs -id: global-faceting ---- - -## Table API - -### `getGlobalFacetedRowModel` - -```tsx -getGlobalFacetedRowModel: () => RowModel -``` - -Returns the faceted row model for the global filter. - -### `getGlobalFacetedUniqueValues` - -```tsx -getGlobalFacetedUniqueValues: () => Map -``` - -Returns the faceted unique values for the global filter. - -### `getGlobalFacetedMinMaxValues` - -```tsx -getGlobalFacetedMinMaxValues: () => [number, number] -``` - -Returns the faceted min and max values for the global filter. diff --git a/docs/api/features/global-filtering.md b/docs/api/features/global-filtering.md deleted file mode 100644 index fe8d23b297..0000000000 --- a/docs/api/features/global-filtering.md +++ /dev/null @@ -1,290 +0,0 @@ ---- -title: Global Filtering APIs -id: global-filtering ---- - -## Can-Filter - -The ability for a column to be **globally** filtered is determined by the following: - -- The column was defined a valid `accessorKey`/`accessorFn`. -- If provided, `options.getColumnCanGlobalFilter` returns `true` for the given column. If it is not provided, the column is assumed to be globally filterable if the value in the first row is a `string` or `number` type. -- `column.enableColumnFilter` is not set to `false` -- `options.enableColumnFilters` is not set to `false` -- `options.enableFilters` is not set to `false` - -## State - -Filter state is stored on the table using the following shape: - -```tsx -export interface GlobalFilterTableState { - globalFilter: any -} -``` - -## Filter Functions - -You can use the same filter functions that are available for column filtering for global filtering. See the [Column Filtering APIs](../column-filtering) to learn more about filter functions. - -#### Using Filter Functions - -Filter functions can be used/referenced/defined by passing the following to `options.globalFilterFn`: - -- A `string` that references a built-in filter function -- A function directly provided to the `options.globalFilterFn` option - -The final list of filter functions available for the `tableOptions.globalFilterFn` options use the following type: - -```tsx -export type FilterFnOption = - | 'auto' - | BuiltInFilterFn - | FilterFn -``` - -#### Filter Meta - -Filtering data can often expose additional information about the data that can be used to aid other future operations on the same data. A good example of this concept is a ranking-system like that of [`match-sorter`](https://github.com/kentcdodds/match-sorter) that simultaneously ranks, filters and sorts data. While utilities like `match-sorter` make a lot of sense for single-dimensional filter+sort tasks, the decoupled filtering/sorting architecture of building a table makes them very difficult and slow to use. - -To make a ranking/filtering/sorting system work with tables, `filterFn`s can optionally mark results with a **filter meta** value that can be used later to sort/group/etc the data to your liking. This is done by calling the `addMeta` function supplied to your custom `filterFn`. - -Below is an example using our own `match-sorter-utils` package (a utility fork of `match-sorter`) to rank, filter, and sort the data - -```tsx -import { sortFns } from '@tanstack/[adapter]-table' -import { rankItem, compareItems } from '@tanstack/match-sorter-utils' - -const fuzzyFilter = (row, columnId, value, addMeta) => { - // Rank the item - const itemRank = rankItem(row.getValue(columnId), value) - - // Store the ranking info - addMeta(itemRank) - - // Return if the item should be filtered in/out - return itemRank.passed -} - -const fuzzySort = (rowA, rowB, columnId) => { - let dir = 0 - - // Only sort by rank if the column has ranking information - if (rowA.columnFiltersMeta[columnId]) { - dir = compareItems( - rowA.columnFiltersMeta[columnId]!, - rowB.columnFiltersMeta[columnId]! - ) - } - - // Provide an alphanumeric fallback for when the item ranks are equal - return dir === 0 ? sortFns.alphanumeric(rowA, rowB, columnId) : dir -} -``` - -## Column Def Options - -### `enableGlobalFilter` - -```tsx -enableGlobalFilter?: boolean -``` - -Enables/disables the **global** filter for this column. - -## Column API - -### `getCanGlobalFilter` - -```tsx -getCanGlobalFilter: () => boolean -``` - -Returns whether or not the column can be **globally** filtered. Set to `false` to disable a column from being scanned during global filtering. - -## Row API - -### `columnFiltersMeta` - -```tsx -columnFiltersMeta: Record -``` - -The column filters meta map for the row. This object tracks any filter meta for a row as optionally provided during the filtering process. - -## Table Options - -### `filterFns` - -```tsx -filterFns?: Record -``` - -This option allows you to define custom filter functions that can be referenced in a column's `filterFn` option by their key. -Example: - -```tsx -declare module '@tanstack/table-core' { - interface FilterFns { - myCustomFilter: FilterFn - } -} - -const column = columnHelper.data('key', { - filterFn: 'myCustomFilter', -}) - -const table = useTable({ - columns: [column], - filterFns: { - myCustomFilter: (rows, columnIds, filterValue) => { - // return the filtered rows - }, - }, -}) -``` - -### `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). - -### `maxLeafRowFilterDepth` - -```tsx -maxLeafRowFilterDepth?: number -``` - -By default, filtering is done for all rows (max depth of 100), no matter if they are root level parent rows or the child leaf rows of a parent row. Setting this option to `0` will cause filtering to only be applied to the root level parent rows, with all sub-rows remaining unfiltered. Similarly, setting this option to `1` will cause filtering to only be applied to child leaf rows 1 level deep, and so on. - -This is useful for situations where you want a row's entire child hierarchy to be visible regardless of the applied filter. - -### `enableFilters` - -```tsx -enableFilters?: boolean -``` - -Enables/disables all filters for the table. - -### `manualFiltering` - -```tsx -manualFiltering?: boolean -``` - -Disables the `getFilteredRowModel` from being used to filter data. This may be useful if your table needs to dynamically support both client-side and server-side filtering. - -### `getFilteredRowModel` - -```tsx -getFilteredRowModel?: ( - table: Table -) => () => RowModel -``` - -If provided, this function is called **once** per table 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 `{ getFilteredRowModel }` export. - -Example: - -```tsx -import { getFilteredRowModel } from '@tanstack/[adapter]-table' - - getFilteredRowModel: createFilteredRowModel(filterFns), -}) -``` - -### `globalFilterFn` - -```tsx -globalFilterFn?: FilterFn | keyof FilterFns | keyof BuiltInFilterFns -``` - -The filter function to use for global filtering. - -Options: - -- A `string` referencing a [built-in filter function](#filter-functions)) -- A `string` that references a custom filter functions provided via the `tableOptions.filterFns` 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. - -### `enableGlobalFilter` - -```tsx -enableGlobalFilter?: boolean -``` - -Enables/disables the global filter for the table. - -### `getColumnCanGlobalFilter` - -```tsx -getColumnCanGlobalFilter?: (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. -This is useful if the column can contain data that is not `string` or `number` (i.e. `undefined`). - -## Table API - -### `getPreFilteredRowModel` - -```tsx -getPreFilteredRowModel: () => RowModel -``` - -Returns the row model for the table before any **column** filtering has been applied. - -### `getFilteredRowModel` - -```tsx -getFilteredRowModel: () => 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: (defaultState?: boolean) => void -``` - -Resets the **globalFilter** state to `initialState.globalFilter`, or `true` can be passed to force a default blank state reset to `undefined`. - -### `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. diff --git a/docs/api/features/grouping.md b/docs/api/features/grouping.md deleted file mode 100644 index f2c9776c60..0000000000 --- a/docs/api/features/grouping.md +++ /dev/null @@ -1,353 +0,0 @@ ---- -title: Grouping APIs -id: grouping ---- - -## State - -Grouping state is stored on the table using the following shape: - -```tsx -export type GroupingState = string[] - -export type GroupingTableState = { - grouping: GroupingState -} -``` - -## Aggregation Functions - -The following aggregation functions are built-in to the table core: - -- `sum` - - Sums the values of a group of rows -- `min` - - Finds the minimum value of a group of rows -- `max` - - Finds the maximum value of a group of rows -- `extent` - - Finds the minimum and maximum values of a group of rows -- `mean` - - Finds the mean/average value of a group of rows -- `median` - - Finds the median value of a group of rows -- `unique` - - Finds the unique values of a group of rows -- `uniqueCount` - - Finds the number of unique values of a group of rows -- `count` - - Calculates the number of rows in a group - -Every grouping function receives: - -- A function to retrieve the leaf values of the groups rows -- A function to retrieve the immediate-child values of the groups rows - -and should return a value (usually primitive) to build the aggregated row model. - -This is the type signature for every aggregation function: - -```tsx -export type AggregationFn = ( - getLeafRows: () => Row[], - getChildRows: () => Row[] -) => any -``` - -#### Using Aggregation Functions - -Aggregation functions can be used/referenced/defined by passing the following to `columnDefinition.aggregationFn`: - -- A `string` that references a built-in aggregation function -- A `string` that references a custom aggregation functions provided via the `tableOptions.aggregationFns` option -- A function directly provided to the `columnDefinition.aggregationFn` option - -The final list of aggregation functions available for the `columnDef.aggregationFn` use the following type: - -```tsx -export type AggregationFnOption = - | 'auto' - | keyof AggregationFns - | BuiltInAggregationFn - | AggregationFn -``` - -## Column Def Options - -### `aggregationFn` - -```tsx -aggregationFn?: AggregationFn | keyof AggregationFns | keyof BuiltInAggregationFns -``` - -The aggregation function to use with this column. - -Options: - -- A `string` referencing a [built-in aggregation function](#aggregation-functions)) -- A [custom aggregation function](#aggregation-functions) - -### `aggregatedCell` - -```tsx -aggregatedCell?: Renderable< - { - table: Table - row: Row - column: Column - cell: Cell - getValue: () => any - renderValue: () => any - } -> -``` - -The cell to display each row for the column if the cell is an aggregate. If a function is passed, it will be passed a props object with the context of the cell and should return the property type for your adapter (the exact type depends on the adapter being used). - -### `enableGrouping` - -```tsx -enableGrouping?: boolean -``` - -Enables/disables grouping for this column. - -### `getGroupingValue` - -```tsx -getGroupingValue?: (row: TData) => any -``` - -Specify a value to be used for grouping rows on this column. If this option is not specified, the value derived from `accessorKey` / `accessorFn` will be used instead. - -## Column API - -### `aggregationFn` - -```tsx -aggregationFn?: AggregationFnOption -``` - -The resolved aggregation function for the column. - -### `getCanGroup` - -```tsx -getCanGroup: () => boolean -``` - -Returns whether or not the column can be grouped. - -### `getIsGrouped` - -```tsx -getIsGrouped: () => boolean -``` - -Returns whether or not the column is currently grouped. - -### `getGroupedIndex` - -```tsx -getGroupedIndex: () => number -``` - -Returns the index of the column in the grouping state. - -### `toggleGrouping` - -```tsx -toggleGrouping: () => void -``` - -Toggles the grouping state of the column. - -### `getToggleGroupingHandler` - -```tsx -getToggleGroupingHandler: () => () => void -``` - -Returns a function that toggles the grouping state of the column. This is useful for passing to the `onClick` prop of a button. - -### `getAutoAggregationFn` - -```tsx -getAutoAggregationFn: () => AggregationFn | undefined -``` - -Returns the automatically inferred aggregation function for the column. - -### `getAggregationFn` - -```tsx -getAggregationFn: () => AggregationFn | undefined -``` - -Returns the aggregation function for the column. - -## Row API - -### `groupingColumnId` - -```tsx -groupingColumnId?: string -``` - -If this row is grouped, this is the id of the column that this row is grouped by. - -### `groupingValue` - -```tsx -groupingValue?: any -``` - -If this row is grouped, this is the unique/shared value for the `groupingColumnId` for all of the rows in this group. - -### `getIsGrouped` - -```tsx -getIsGrouped: () => boolean -``` - -Returns whether or not the row is currently grouped. - -### `getGroupingValue` - -```tsx -getGroupingValue: (columnId: string) => unknown -``` - -Returns the grouping value for any row and column (including leaf rows). - -## Table Options - -### `aggregationFns` - -```tsx -aggregationFns?: Record -``` - -This option allows you to define custom aggregation functions that can be referenced in a column's `aggregationFn` option by their key. -Example: - -```tsx -declare module '@tanstack/table-core' { - interface AggregationFns { - myCustomAggregation: AggregationFn - } -} - -const column = columnHelper.data('key', { - aggregationFn: 'myCustomAggregation', -}) - -const table = useTable({ - columns: [column], - aggregationFns: { - myCustomAggregation: (columnId, leafRows, childRows) => { - // return the aggregated value - }, - }, -}) -``` - -### `manualGrouping` - -```tsx -manualGrouping?: boolean -``` - -Enables manual grouping. If this option is set to `true`, the table will not automatically group rows using `getGroupedRowModel()` and instead will expect you to manually group the rows before passing them to the table. This is useful if you are doing server-side grouping and aggregation. - -### `onGroupingChange` - -```tsx -onGroupingChange?: OnChangeFn -``` - -If this function is provided, it will be called when the grouping state changes and you will be expected to manage the state yourself. You can pass the managed state back to the table via the `tableOptions.state.grouping` option. - -### `enableGrouping` - -```tsx -enableGrouping?: boolean -``` - -Enables/disables grouping for all columns. - -### `getGroupedRowModel` - -```tsx -getGroupedRowModel?: (table: Table) => () => RowModel -``` - -Returns the row model after grouping has taken place, but no further. - -### `groupedColumnMode` - -```tsx -groupedColumnMode?: false | 'reorder' | 'remove' // default: `reorder` -``` - -Grouping columns are automatically reordered by default to the start of the columns list. If you would rather remove them or leave them as-is, set the appropriate mode here. - -## Table API - -### `setGrouping` - -```tsx -setGrouping: (updater: Updater) => void -``` - -Sets or updates the `state.grouping` state. - -### `resetGrouping` - -```tsx -resetGrouping: (defaultState?: boolean) => void -``` - -Resets the **grouping** state to `initialState.grouping`, or `true` can be passed to force a default blank state reset to `[]`. - -### `getPreGroupedRowModel` - -```tsx -getPreGroupedRowModel: () => RowModel -``` - -Returns the row model for the table before any grouping has been applied. - -### `getGroupedRowModel` - -```tsx -getGroupedRowModel: () => RowModel -``` - -Returns the row model for the table after grouping has been applied. - -## Cell API - -### `getIsAggregated` - -```tsx -getIsAggregated: () => boolean -``` - -Returns whether or not the cell is currently aggregated. - -### `getIsGrouped` - -```tsx -getIsGrouped: () => boolean -``` - -Returns whether or not the cell is currently grouped. - -### `getIsPlaceholder` - -```tsx -getIsPlaceholder: () => boolean -``` - -Returns whether or not the cell is currently a placeholder. \ No newline at end of file diff --git a/docs/api/features/pagination.md b/docs/api/features/pagination.md deleted file mode 100644 index 0befc42a21..0000000000 --- a/docs/api/features/pagination.md +++ /dev/null @@ -1,207 +0,0 @@ ---- -title: Pagination APIs -id: pagination ---- - -## State - -Pagination state is stored on the table using the following shape: - -```tsx -export type PaginationState = { - pageIndex: number - pageSize: number -} - -export type PaginationTableState = { - pagination: PaginationState -} - -export type PaginationInitialTableState = { - pagination?: Partial -} -``` - -## Table Options - -### `manualPagination` - -```tsx -manualPagination?: boolean -``` - -Enables manual pagination. If this option is set to `true`, the table will not automatically paginate rows using `getPaginatedRowModel()` and instead will expect you to manually paginate the rows before passing them to the table. This is useful if you are doing server-side pagination and aggregation. - -### `pageCount` - -```tsx -pageCount?: number -``` - -When manually controlling pagination, you can supply a total `pageCount` value to the table if you know it. If you do not know how many pages there are, you can set this to `-1`. Alternatively, you can provide a `rowCount` value and the table will calculate the `pageCount` internally. - -### `rowCount` - -```tsx -rowCount?: number -``` - -When manually controlling pagination, you can supply a total `rowCount` value to the table if you know it. `pageCount` will be calculated internally from `rowCount` and `pageSize`. - -### `autoResetPageIndex` - -```tsx -autoResetPageIndex?: boolean -``` - -If set to `true`, pagination will be reset to the first page when page-altering state changes eg. `data` is updated, filters change, grouping changes, etc. - -> 🧠 Note: This option defaults to `false` if `manualPagination` is set to `true` - -### `onPaginationChange` - -```tsx -onPaginationChange?: OnChangeFn -``` - -If this function is provided, it will be called when the pagination state changes and you will be expected to manage the state yourself. You can pass the managed state back to the table via the `tableOptions.state.pagination` option. - -### `getPaginatedRowModel` - -```tsx -getPaginatedRowModel?: (table: Table) => () => RowModel -``` - -Returns the row model after pagination has taken place, but no further. - -Pagination columns are automatically reordered by default to the start of the columns list. If you would rather remove them or leave them as-is, set the appropriate mode here. - -## Table API - -### `setPagination` - -```tsx -setPagination: (updater: Updater) => void -``` - -Sets or updates the `state.pagination` state. - -### `resetPagination` - -```tsx -resetPagination: (defaultState?: boolean) => void -``` - -Resets the **pagination** state to `initialState.pagination`, or `true` can be passed to force a default blank state reset to `[]`. - -### `setPageIndex` - -```tsx -setPageIndex: (updater: Updater) => void -``` - -Updates the page index using the provided function or value. - -### `resetPageIndex` - -```tsx -resetPageIndex: (defaultState?: boolean) => void -``` - -Resets the page index to its initial state. If `defaultState` is `true`, the page index will be reset to `0` regardless of initial state. - -### `setPageSize` - -```tsx -setPageSize: (updater: Updater) => void -``` - -Updates the page size using the provided function or value. - -### `resetPageSize` - -```tsx -resetPageSize: (defaultState?: boolean) => void -``` - -Resets the page size to its initial state. If `defaultState` is `true`, the page size will be reset to `10` regardless of initial state. - -### `getPageOptions` - -```tsx -getPageOptions: () => number[] -``` - -Returns an array of page options (zero-index-based) for the current page size. - -### `getCanPreviousPage` - -```tsx -getCanPreviousPage: () => boolean -``` - -Returns whether the table can go to the previous page. - -### `getCanNextPage` - -```tsx -getCanNextPage: () => boolean -``` - -Returns whether the table can go to the next page. - -### `previousPage` - -```tsx -previousPage: () => void -``` - -Decrements the page index by one, if possible. - -### `nextPage` - -```tsx -nextPage: () => void -``` - -Increments the page index by one, if possible. - -### `firstPage` - -```tsx -firstPage: () => void -``` - -Sets the page index to `0`. - -### `lastPage` - -```tsx -lastPage: () => void -``` - -Sets the page index to the last available page. - -### `getPageCount` - -```tsx -getPageCount: () => number -``` - -Returns the page count. If manually paginating or controlling the pagination state, this will come directly from the `options.pageCount` table option, otherwise it will be calculated from the table data using the total row count and current page size. - -### `getPrePaginatedRowModel` - -```tsx -getPrePaginatedRowModel: () => RowModel -``` - -Returns the row model for the table before any pagination has been applied. - -### `getPaginatedRowModel` - -```tsx -getPaginatedRowModel: () => RowModel -``` - -Returns the row model for the table after pagination has been applied. diff --git a/docs/api/features/pinning.md b/docs/api/features/pinning.md deleted file mode 100644 index 92222ac7fe..0000000000 --- a/docs/api/features/pinning.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Pinning APIs -id: pinning ---- - - - -The pinning apis are now split into multiple api pages: - -- [Column Pinning](../column-pinning) -- [Row Pinning](../row-pinning) \ No newline at end of file diff --git a/docs/api/features/row-pinning.md b/docs/api/features/row-pinning.md deleted file mode 100644 index 8f06c07db1..0000000000 --- a/docs/api/features/row-pinning.md +++ /dev/null @@ -1,138 +0,0 @@ ---- -title: Row Pinning APIs -id: row-pinning ---- - -## Can-Pin - -The ability for a row to be **pinned** is determined by the following: - -- `options.enableRowPinning` resolves to `true` -- `options.enablePinning` is not set to `false` - -## State - -Pinning state is stored on the table using the following shape: - -```tsx -export type RowPinningPosition = false | 'top' | 'bottom' - -export type RowPinningState = { - top?: string[] - bottom?: string[] -} - -export type RowPinningRowState = { - rowPinning: RowPinningState -} -``` - -## Table Options - -### `enableRowPinning` - -```tsx -enableRowPinning?: boolean | ((row: Row) => boolean) -``` - -Enables/disables row pinning for all rows in the table. - -### `keepPinnedRows` - -```tsx -keepPinnedRows?: boolean -``` - -When `false`, pinned rows will not be visible if they are filtered or paginated out of the table. When `true`, pinned rows will always be visible regardless of filtering or pagination. Defaults to `true`. - -### `onRowPinningChange` - -```tsx -onRowPinningChange?: OnChangeFn -``` - -If provided, this function will be called with an `updaterFn` when `state.rowPinning` changes. This overrides the default internal state management, so you will also need to supply `state.rowPinning` from your own managed state. - -## Table API - -### `setRowPinning` - -```tsx -setRowPinning: (updater: Updater) => void -``` - -Sets or updates the `state.rowPinning` state. - -### `resetRowPinning` - -```tsx -resetRowPinning: (defaultState?: boolean) => void -``` - -Resets the **rowPinning** state to `initialState.rowPinning`, or `true` can be passed to force a default blank state reset to `{}`. - -### `getIsSomeRowsPinned` - -```tsx -getIsSomeRowsPinned: (position?: RowPinningPosition) => boolean -``` - -Returns whether or not any rows are pinned. Optionally specify to only check for pinned rows in either the `top` or `bottom` position. - -### `getTopRows` - -```tsx -getTopRows: () => Row[] -``` - -Returns all top pinned rows. - -### `getBottomRows` - -```tsx -getBottomRows: () => Row[] -``` - -Returns all bottom pinned rows. - -### `getCenterRows` - -```tsx -getCenterRows: () => Row[] -``` - -Returns all rows that are not pinned to the top or bottom. - -## Row API - -### `pin` - -```tsx -pin: (position: RowPinningPosition) => void -``` - -Pins a row to the `'top'` or `'bottom'`, or unpins the row to the center if `false` is passed. - -### `getCanPin` - -```tsx -getCanPin: () => boolean -``` - -Returns whether or not the row can be pinned. - -### `getIsPinned` - -```tsx -getIsPinned: () => RowPinningPosition -``` - -Returns the pinned position of the row. (`'top'`, `'bottom'` or `false`) - -### `getPinnedIndex` - -```tsx -getPinnedIndex: () => number -``` - -Returns the numeric pinned index of the row within a pinned row group. \ No newline at end of file diff --git a/docs/api/features/row-selection.md b/docs/api/features/row-selection.md deleted file mode 100644 index 5b488dccce..0000000000 --- a/docs/api/features/row-selection.md +++ /dev/null @@ -1,230 +0,0 @@ ---- -title: Row Selection APIs -id: row-selection ---- - -## State - -Row selection state is stored on the table using the following shape: - -```tsx -export type RowSelectionState = Record - -export type RowSelectionTableState = { - rowSelection: RowSelectionState -} -``` - -By default, the row selection state uses the index of each row as the row identifiers. Row selection state can instead be tracked with a custom unique row id by passing in a custom [getRowId](../../../api/core/table.md#getrowid) function to the the table. - -## Table Options - -### `enableRowSelection` - -```tsx -enableRowSelection?: boolean | ((row: Row) => boolean) -``` - -- Enables/disables row selection for all rows in the table OR -- A function that given a row, returns whether to enable/disable row selection for that row - -### `enableMultiRowSelection` - -```tsx -enableMultiRowSelection?: boolean | ((row: Row) => boolean) -``` - -- Enables/disables multiple row selection for all rows in the table OR -- A function that given a row, returns whether to enable/disable multiple row selection for that row's children/grandchildren - -### `enableSubRowSelection` - -```tsx -enableSubRowSelection?: boolean | ((row: Row) => boolean) -``` - -Enables/disables automatic sub-row selection when a parent row is selected, or a function that enables/disables automatic sub-row selection for each row. - -(Use in combination with expanding or grouping features) - -### `onRowSelectionChange` - -```tsx -onRowSelectionChange?: OnChangeFn -``` - -If provided, this function will be called with an `updaterFn` when `state.rowSelection` 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. - -## Table API - -### `getToggleAllRowsSelectedHandler` - -```tsx -getToggleAllRowsSelectedHandler: () => (event: unknown) => void -``` - -Returns a handler that can be used to toggle all rows in the table. - -### `getToggleAllPageRowsSelectedHandler` - -```tsx -getToggleAllPageRowsSelectedHandler: () => (event: unknown) => void -``` - -Returns a handler that can be used to toggle all rows on the current page. - -### `setRowSelection` - -```tsx -setRowSelection: (updater: Updater) => void -``` - -Sets or updates the `state.rowSelection` state. - -### `resetRowSelection` - -```tsx -resetRowSelection: (defaultState?: boolean) => void -``` - -Resets the **rowSelection** state to the `initialState.rowSelection`, or `true` can be passed to force a default blank state reset to `{}`. - -### `getIsAllRowsSelected` - -```tsx -getIsAllRowsSelected: () => boolean -``` - -Returns whether or not all rows in the table are selected. - -### `getIsAllPageRowsSelected` - -```tsx -getIsAllPageRowsSelected: () => boolean -``` - -Returns whether or not all rows on the current page are selected. - -### `getIsSomeRowsSelected` - -```tsx -getIsSomeRowsSelected: () => boolean -``` - -Returns whether or not any rows in the table are selected. - -NOTE: Returns `false` if all rows are selected. - -### `getIsSomePageRowsSelected` - -```tsx -getIsSomePageRowsSelected: () => boolean -``` - -Returns whether or not any rows on the current page are selected. - -### `toggleAllRowsSelected` - -```tsx -toggleAllRowsSelected: (value: boolean) => void -``` - -Selects/deselects all rows in the table. - -### `toggleAllPageRowsSelected` - -```tsx -toggleAllPageRowsSelected: (value: boolean) => void -``` - -Selects/deselects all rows on the current page. - -### `getPreSelectedRowModel` - -```tsx -getPreSelectedRowModel: () => RowModel -``` - -### `getSelectedRowModel` - -```tsx -getSelectedRowModel: () => RowModel -``` - -### `getFilteredSelectedRowModel` - -```tsx -getFilteredSelectedRowModel: () => RowModel -``` - -### `getGroupedSelectedRowModel` - -```tsx -getGroupedSelectedRowModel: () => RowModel -``` - -## Row API - -### `getIsSelected` - -```tsx -getIsSelected: () => boolean -``` - -Returns whether or not the row is selected. - -### `getIsSomeSelected` - -```tsx -getIsSomeSelected: () => boolean -``` - -Returns whether or not some of the row's sub rows are selected. - -### `getIsAllSubRowsSelected` - -```tsx -getIsAllSubRowsSelected: () => boolean -``` - -Returns whether or not all of the row's sub rows are selected. - -### `getCanSelect` - -```tsx -getCanSelect: () => boolean -``` - -Returns whether or not the row can be selected. - -### `getCanMultiSelect` - -```tsx -getCanMultiSelect: () => boolean -``` - -Returns whether or not the row can multi-select. - -### `getCanSelectSubRows` - -```tsx -getCanSelectSubRows: () => boolean -``` - -Returns whether or not the row can select sub rows automatically when the parent row is selected. - -### `toggleSelected` - -```tsx -toggleSelected: (value?: boolean) => void -``` - -Selects/deselects the row. - -### `getToggleSelectedHandler` - -```tsx -getToggleSelectedHandler: () => (event: unknown) => void -``` - -Returns a handler that can be used to toggle the row. diff --git a/docs/api/features/sorting.md b/docs/api/features/sorting.md deleted file mode 100644 index 54c4bbad14..0000000000 --- a/docs/api/features/sorting.md +++ /dev/null @@ -1,385 +0,0 @@ ---- -title: Sorting APIs -id: sorting ---- - -## State - -Sorting state is stored on the table using the following shape: - -```tsx -export type SortDirection = 'asc' | 'desc' - -export type ColumnSort = { - id: string - desc: boolean -} - -export type SortingState = ColumnSort[] - -export type SortingTableState = { - sorting: SortingState -} -``` - -## Sorting Functions - -The following sorting functions are built-in to the table core: - -- `alphanumeric` - - Sorts by mixed alphanumeric values without case-sensitivity. Slower, but more accurate if your strings contain numbers that need to be naturally sorted. -- `alphanumericCaseSensitive` - - Sorts by mixed alphanumeric values with case-sensitivity. Slower, but more accurate if your strings contain numbers that need to be naturally sorted. -- `text` - - Sorts by text/string values without case-sensitivity. Faster, but less accurate if your strings contain numbers that need to be naturally sorted. -- `textCaseSensitive` - - Sorts by text/string values with case-sensitivity. Faster, but less accurate if your strings contain numbers that need to be naturally sorted. -- `datetime` - - Sorts by time, use this if your values are `Date` objects. -- `basic` - - Sorts using a basic/standard `a > b ? 1 : a < b ? -1 : 0` comparison. This is the fastest sorting function, but may not be the most accurate. - -Every sorting function receives 2 rows and a column ID and are expected to compare the two rows using the column ID to return `-1`, `0`, or `1` in ascending order. Here's a cheat sheet: - -| Return | Ascending Order | -| ------ | --------------- | -| `-1` | `a < b` | -| `0` | `a === b` | -| `1` | `a > b` | - -This is the type signature for every sorting function: - -```tsx -export type SortFn = { - (rowA: Row, rowB: Row, columnId: string): number -} -``` - -#### Using Sorting Functions - -Sorting functions can be used/referenced/defined by passing the following to `columnDefinition.sortFn`: - -- A `string` that references a built-in sorting function -- A `string` that references a custom sorting functions provided via the `tableOptions.sortFns` option -- A function directly provided to the `columnDefinition.sortFn` option - -The final list of sorting functions available for the `columnDef.sortFn` use the following type: - -```tsx -export type SortFnOption = - | 'auto' - | SortFns - | BuiltInSortFns - | SortFn -``` - -## Column Def Options - -### `sortFn` - -```tsx -sortFn?: SortFn | keyof SortFns | keyof BuiltInSortFns -``` - -The sorting function to use with this column. - -Options: - -- A `string` referencing a [built-in sorting function](#sorting-functions)) -- A [custom sorting function](#sorting-functions) - -### `sortDescFirst` - -```tsx -sortDescFirst?: boolean -``` - -Set to `true` for sorting toggles on this column to start in the descending direction. - -### `enableSorting` - -```tsx -enableSorting?: boolean -``` - -Enables/Disables sorting for this column. - -### `enableMultiSort` - -```tsx -enableMultiSort?: boolean -``` - -Enables/Disables multi-sorting for this column. - -### `invertSorting` - -```tsx -invertSorting?: boolean -``` - -Inverts the order of the sorting for this column. This is useful for values that have an inverted best/worst scale where lower numbers are better, eg. a ranking (1st, 2nd, 3rd) or golf-like scoring - -### `sortUndefined` - -```tsx -sortUndefined?: 'first' | 'last' | false | -1 | 1 // defaults to 1 -``` - -- `'first'` - - Undefined values will be pushed to the beginning of the list -- `'last'` - - Undefined values will be pushed to the end of the list -- `false` - - Undefined values will be considered tied and need to be sorted by the next column filter or original index (whichever applies) -- `-1` - - Undefined values will be sorted with higher priority (ascending) (if ascending, undefined will appear on the beginning of the list) -- `1` - - Undefined values will be sorted with lower priority (descending) (if ascending, undefined will appear on the end of the list) - -> NOTE: `'first'` and `'last'` options are new in v8.16.0 - -## Column API - -### `getAutoSortFn` - -```tsx -getAutoSortFn: () => SortFn -``` - -Returns a sorting function automatically inferred based on the columns values. - -### `getAutoSortDir` - -```tsx -getAutoSortDir: () => SortDirection -``` - -Returns a sort direction automatically inferred based on the columns values. - -### `getSortFn` - -```tsx -getSortFn: () => SortFn -``` - -Returns the resolved sorting function to be used for this column - -### `getNextSortingOrder` - -```tsx -getNextSortingOrder: () => SortDirection | false -``` - -Returns the next sorting order. - -### `getCanSort` - -```tsx -getCanSort: () => boolean -``` - -Returns whether this column can be sorted. - -### `getCanMultiSort` - -```tsx -getCanMultiSort: () => boolean -``` - -Returns whether this column can be multi-sorted. - -### `getSortIndex` - -```tsx -getSortIndex: () => number -``` - -Returns the index position of this column's sorting within the sorting state - -### `getIsSorted` - -```tsx -getIsSorted: () => false | SortDirection -``` - -Returns whether this column is sorted. - -### `getFirstSortDir` - -```tsx -getFirstSortDir: () => SortDirection -``` - -Returns the first direction that should be used when sorting this column. - -### `clearSorting` - -```tsx -clearSorting: () => void -``` - -Removes this column from the table's sorting state - -### `toggleSorting` - -```tsx -toggleSorting: (desc?: boolean, isMulti?: boolean) => void -``` - -Toggles this columns sorting state. If `desc` is provided, it will force the sort direction to that value. If `isMulti` is provided, it will additivity multi-sort the column (or toggle it if it is already sorted). - -### `getToggleSortingHandler` - -```tsx -getToggleSortingHandler: () => undefined | ((event: unknown) => void) -``` - -Returns a function that can be used to toggle this column's sorting state. This is useful for attaching a click handler to the column header. - -## Table Options - -### `sortFns` - -```tsx -sortFns?: Record -``` - -This option allows you to define custom sorting functions that can be referenced in a column's `sortFn` option by their key. -Example: - -```tsx -declare module '@tanstack/table-core' { - interface SortFns { - myCustomSorting: SortFn - } -} - -const column = columnHelper.data('key', { - sortFn: 'myCustomSorting', -}) - -const table = useTable({ - columns: [column], - sortFns: { - myCustomSorting: (rowA: any, rowB: any, columnId: any): number => - rowA.getValue(columnId).value < rowB.getValue(columnId).value ? 1 : -1, - }, -}) -``` - -### `manualSorting` - -```tsx -manualSorting?: boolean -``` - -Enables manual sorting for the table. If this is `true`, you will be expected to sort your data before it is passed to the table. This is useful if you are doing server-side sorting. - -### `onSortingChange` - -```tsx -onSortingChange?: OnChangeFn -``` - -If provided, this function will be called with an `updaterFn` when `state.sorting` 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. - -### `enableSorting` - -```tsx -enableSorting?: boolean -``` - -Enables/Disables sorting for the table. - -### `enableSortingRemoval` - -```tsx -enableSortingRemoval?: boolean -``` - -Enables/Disables the ability to remove sorting for the table. -- If `true` then changing sort order will circle like: 'none' -> 'desc' -> 'asc' -> 'none' -> ... -- If `false` then changing sort order will circle like: 'none' -> 'desc' -> 'asc' -> 'desc' -> 'asc' -> ... - -### `enableMultiRemove` - -```tsx -enableMultiRemove?: boolean -``` - -Enables/disables the ability to remove multi-sorts - -### `enableMultiSort` - -```tsx -enableMultiSort?: boolean -``` - -Enables/Disables multi-sorting for the table. - -### `sortDescFirst` - -```tsx -sortDescFirst?: boolean -``` - -If `true`, all sorts will default to descending as their first toggle state. - -### `getSortedRowModel` - -```tsx -getSortedRowModel?: (table: Table) => () => RowModel -``` - -This function is used to retrieve the sorted row model. If using server-side sorting, this function is not required. To use client-side sorting, pass the exported `getSortedRowModel()` from your adapter to your table or implement your own. - -### `maxMultiSortColCount` - -```tsx -maxMultiSortColCount?: number -``` - -Set a maximum number of columns that can be multi-sorted. - -### `isMultiSortEvent` - -```tsx -isMultiSortEvent?: (e: unknown) => boolean -``` - -Pass a custom function that will be used to determine if a multi-sort event should be triggered. It is passed the event from the sort toggle handler and should return `true` if the event should trigger a multi-sort. - -## Table API - -### `setSorting` - -```tsx -setSorting: (updater: Updater) => void -``` - -Sets or updates the `state.sorting` state. - -### `resetSorting` - -```tsx -resetSorting: (defaultState?: boolean) => void -``` - -Resets the **sorting** state to `initialState.sorting`, or `true` can be passed to force a default blank state reset to `[]`. - -### `getPreSortedRowModel` - -```tsx -getPreSortedRowModel: () => RowModel -``` - -Returns the row model for the table before any sorting has been applied. - -### `getSortedRowModel` - -```tsx -getSortedRowModel: () => RowModel -``` - -Returns the row model for the table after sorting has been applied. diff --git a/docs/framework/angular/guide/table-state.md b/docs/framework/angular/guide/table-state.md index 770807c6a8..100e5fd601 100644 --- a/docs/framework/angular/guide/table-state.md +++ b/docs/framework/angular/guide/table-state.md @@ -8,7 +8,7 @@ TanStack Table has a simple underlying internal state management system to store ### Accessing Table State -You do not need to set up anything special in order for the table state to work. If you pass nothing into either `state`, `initialState`, or any of the `on[State]Change` table options, the table will manage its own state internally. You can access any part of this internal state by using the `table.getState()` table instance API. +You do not need to set up anything special in order for the table state to work. If you pass nothing into either `state`, `initialState`, or any of the `on[State]Change` table options, the table will manage its own state internally. You can access any part of this internal state by using the `table.store.state` table instance API. ```ts table = injectTable(() => ({ @@ -18,8 +18,8 @@ table = injectTable(() => ({ })) someHandler() { - console.log(this.table.getState()) //access the entire internal state - console.log(this.table.getState().rowSelection) //access just the row selection state + console.log(this.table.store.state) //access the entire internal state + console.log(this.table.store.state.rowSelection) //access just the row selection state } ``` diff --git a/docs/framework/lit/guide/table-state.md b/docs/framework/lit/guide/table-state.md index ddaf3032a5..9bcbebaf8d 100644 --- a/docs/framework/lit/guide/table-state.md +++ b/docs/framework/lit/guide/table-state.md @@ -8,7 +8,7 @@ TanStack Table has a simple underlying internal state management system to store ### Accessing Table State -You do not need to set up anything special in order for the table state to work. If you pass nothing into either `state`, `initialState`, or any of the `on[State]Change` table options, the table will manage its own state internally. You can access any part of this internal state by using the `table.getState()` table instance API. +You do not need to set up anything special in order for the table state to work. If you pass nothing into either `state`, `initialState`, or any of the `on[State]Change` table options, the table will manage its own state internally. You can access any part of this internal state by using the `table.store.state` table instance API. ```ts private tableController = new TableController(this); @@ -20,8 +20,8 @@ render() { ... }) - console.log(table.getState()) //access the entire internal state - console.log(table.getState().rowSelection) //access just the row selection state + console.log(table.store.state) //access the entire internal state + console.log(table.store.state.rowSelection) //access just the row selection state // ... } ``` @@ -120,12 +120,12 @@ render() { getCoreRowModel: createCoreRowModel(), getSortedRowModel: createSortedRowModel(sortFns) }) - const state = { ...table.initialState, ...this._tableState }; + const state = { ...table.initialState, ...this.tableState }; table.setOptions(prev => ({ ...prev, state, onStateChange: updater => { - this._tableState = + this.tableState = updater instanceof Function ? updater(state) : updater //any state changes will be pushed up to our own state management }, })) diff --git a/docs/framework/react/guide/table-state.md b/docs/framework/react/guide/table-state.md index 2a9c3cd3ac..405e01ec51 100644 --- a/docs/framework/react/guide/table-state.md +++ b/docs/framework/react/guide/table-state.md @@ -15,7 +15,7 @@ TanStack Table has a simple underlying internal state management system to store ### Accessing Table State -You do not need to set up anything special in order for the table state to work. If you pass nothing into either `state`, `initialState`, or any of the `on[State]Change` table options, the table will manage its own state internally. You can access any part of this internal state by using the `table.getState()` table instance API. +You do not need to set up anything special in order for the table state to work. If you pass nothing into either `state`, `initialState`, or any of the `on[State]Change` table options, the table will manage its own state internally. You can access any part of this internal state by using the `table.store.state` table instance API. ```jsx const table = useTable({ @@ -24,8 +24,8 @@ const table = useTable({ //... }) -console.log(table.getState()) //access the entire internal state -console.log(table.getState().rowSelection) //access just the row selection state +console.log(table.store.state) //access the entire internal state +console.log(table.store.state.rowSelection) //access just the row selection state ``` ### Custom Initial State diff --git a/docs/framework/solid/guide/table-state.md b/docs/framework/solid/guide/table-state.md index fa4abf09e4..83a77d7f2f 100644 --- a/docs/framework/solid/guide/table-state.md +++ b/docs/framework/solid/guide/table-state.md @@ -8,7 +8,7 @@ TanStack Table has a simple underlying internal state management system to store ### Accessing Table State -You do not need to set up anything special in order for the table state to work. If you pass nothing into either `state`, `initialState`, or any of the `on[State]Change` table options, the table will manage its own state internally. You can access any part of this internal state by using the `table.getState()` table instance API. +You do not need to set up anything special in order for the table state to work. If you pass nothing into either `state`, `initialState`, or any of the `on[State]Change` table options, the table will manage its own state internally. You can access any part of this internal state by using the `table.store.state` table instance API. ```jsx const table = createTable({ @@ -19,8 +19,8 @@ const table = createTable({ //... }) -console.log(table.getState()) //access the entire internal state -console.log(table.getState().rowSelection) //access just the row selection state +console.log(table.store.state) //access the entire internal state +console.log(table.store.state.rowSelection) //access just the row selection state ``` ### Custom Initial State diff --git a/docs/framework/svelte/guide/table-state.md b/docs/framework/svelte/guide/table-state.md index e9b96f1e8c..a45cc3f675 100644 --- a/docs/framework/svelte/guide/table-state.md +++ b/docs/framework/svelte/guide/table-state.md @@ -8,7 +8,7 @@ TanStack Table has a simple underlying internal state management system to store ### Accessing Table State -You do not need to set up anything special in order for the table state to work. If you pass nothing into either `state`, `initialState`, or any of the `on[State]Change` table options, the table will manage its own state internally. You can access any part of this internal state by using the `table.getState()` table instance API. +You do not need to set up anything special in order for the table state to work. If you pass nothing into either `state`, `initialState`, or any of the `on[State]Change` table options, the table will manage its own state internally. You can access any part of this internal state by using the `table.store.state` table instance API. ```ts const table = createTable({ @@ -19,8 +19,8 @@ const table = createTable({ //... }) -console.log(table.getState()) //access the entire internal state -console.log(table.getState().rowSelection) //access just the row selection state +console.log(table.store.state) //access the entire internal state +console.log(table.store.state.rowSelection) //access just the row selection state ``` ### Custom Initial State diff --git a/docs/framework/vue/guide/table-state.md b/docs/framework/vue/guide/table-state.md index 09fb44f729..e58218e70e 100644 --- a/docs/framework/vue/guide/table-state.md +++ b/docs/framework/vue/guide/table-state.md @@ -8,7 +8,7 @@ TanStack Table has a simple underlying internal state management system to store ### Accessing Table State -You do not need to set up anything special in order for the table state to work. If you pass nothing into either `state`, `initialState`, or any of the `on[State]Change` table options, the table will manage its own state internally. You can access any part of this internal state by using the `table.getState()` table instance API. +You do not need to set up anything special in order for the table state to work. If you pass nothing into either `state`, `initialState`, or any of the `on[State]Change` table options, the table will manage its own state internally. You can access any part of this internal state by using the `table.store.state` table instance API. ```ts const table = useTable({ @@ -17,8 +17,8 @@ const table = useTable({ //... }) -console.log(table.getState()) //access the entire internal state -console.log(table.getState().rowSelection) //access just the row selection state +console.log(table.store.state) //access the entire internal state +console.log(table.store.state.rowSelection) //access just the row selection state ``` ### Using Reactive Data diff --git a/docs/guide/column-filtering.md b/docs/guide/column-filtering.md index 9d5190cbda..bce1395afb 100644 --- a/docs/guide/column-filtering.md +++ b/docs/guide/column-filtering.md @@ -94,7 +94,7 @@ Since the column filter state is an array of objects, you can have multiple colu #### Accessing Column Filter State -You can access the column filter state from the table instance just like any other table state using the `table.getState()` API. +You can access the column filter state from the table instance just like any other table state using the `table.store.state` API. ```jsx const table = useTable({ @@ -103,7 +103,7 @@ const table = useTable({ //... }) -console.log(table.getState().columnFilters) // access the column filters state from the table instance +console.log(table.store.state.columnFilters) // access the column filters state from the table instance ``` However, if you need to access the column filter state before the table is initialized, you can "control" the column filter state like down below. diff --git a/docs/guide/column-sizing.md b/docs/guide/column-sizing.md index ddd50a7779..46e304e908 100644 --- a/docs/guide/column-sizing.md +++ b/docs/guide/column-sizing.md @@ -156,7 +156,7 @@ TanStack Table keeps track of an state object called `columnSizingInfo` that you diff --git a/docs/guide/custom-features.md b/docs/guide/custom-features.md index c7879005ae..06ff0490d3 100644 --- a/docs/guide/custom-features.md +++ b/docs/guide/custom-features.md @@ -257,7 +257,7 @@ const table = useTable({ onDensityChange: setDensity, //using the new onDensityChange option, TS is still happy :) }) //... -const { density } = table.getState() +const { density } = table.store.state return( ([]) diff --git a/docs/guide/pagination.md b/docs/guide/pagination.md index bcc8b076a8..e5f932d94d 100644 --- a/docs/guide/pagination.md +++ b/docs/guide/pagination.md @@ -203,7 +203,7 @@ There are several pagination table instance APIs that are useful for hooking up {'>>'} - 
${JSON.stringify(this._sorting, null, 2)}
+ 
${JSON.stringify(table.state.sorting, null, 2)}