From e808abfd08f20f952662cd99bbfe5cba84f530af Mon Sep 17 00:00:00 2001 From: Kevin Van Cott Date: Sat, 17 Feb 2024 18:06:36 -0600 Subject: [PATCH] docs: add column visibility docs (#5362) --- docs/api/core/cell.md | 2 +- docs/api/core/column-def.md | 2 +- docs/api/core/column.md | 2 +- docs/api/core/header-group.md | 2 +- docs/api/core/header.md | 2 +- docs/api/core/row.md | 2 +- docs/api/core/table.md | 2 +- docs/api/features/column-ordering.md | 2 +- docs/api/features/column-sizing.md | 2 +- docs/api/features/column-visibility.md | 2 +- docs/api/features/expanding.md | 2 +- docs/api/features/filters.md | 2 +- docs/api/features/grouping.md | 2 +- docs/api/features/pagination.md | 2 +- docs/api/features/pinning.md | 2 +- docs/api/features/row-selection.md | 2 +- docs/api/features/sorting.md | 2 +- docs/guide/cells.md | 2 +- docs/guide/column-defs.md | 2 +- docs/guide/column-filtering.md | 2 +- docs/guide/column-ordering.md | 2 +- docs/guide/column-pinning.md | 2 +- docs/guide/column-sizing.md | 2 +- docs/guide/column-visibility.md | 119 +++++++++++++++++- docs/guide/expanding.md | 2 +- docs/guide/faceted-values.md | 2 +- docs/guide/features.md | 2 +- docs/guide/filters.md | 2 +- docs/guide/fuzzy-filtering.md | 2 +- docs/guide/global-filtering.md | 2 +- docs/guide/grouping.md | 2 +- docs/guide/headers.md | 2 +- docs/guide/migrating.md | 2 +- docs/guide/pagination.md | 2 +- docs/guide/pinning.md | 2 +- docs/guide/row-models.md | 2 +- docs/guide/row-pinning.md | 2 +- docs/guide/row-selection.md | 2 +- docs/guide/rows.md | 2 +- docs/guide/sorting.md | 2 +- docs/guide/tables.md | 2 +- docs/guide/virtualization.md | 2 +- packages/table-core/src/features/Pinning.ts | 2 +- .../table-core/src/features/Visibility.ts | 5 + 44 files changed, 164 insertions(+), 44 deletions(-) diff --git a/docs/api/core/cell.md b/docs/api/core/cell.md index 8aa83eaabc..2eb84ab992 100644 --- a/docs/api/core/cell.md +++ b/docs/api/core/cell.md @@ -1,5 +1,5 @@ --- -title: Cell +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). diff --git a/docs/api/core/column-def.md b/docs/api/core/column-def.md index 17b2ee2aae..c6ef013aa7 100644 --- a/docs/api/core/column-def.md +++ b/docs/api/core/column-def.md @@ -1,5 +1,5 @@ --- -title: ColumnDef +title: ColumnDef APIs --- Column definitions are plain objects with the following options: diff --git a/docs/api/core/column.md b/docs/api/core/column.md index 4239ba1b54..42f56a004f 100644 --- a/docs/api/core/column.md +++ b/docs/api/core/column.md @@ -1,5 +1,5 @@ --- -title: Column +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). diff --git a/docs/api/core/header-group.md b/docs/api/core/header-group.md index 8b38a4f220..f7a3af2192 100644 --- a/docs/api/core/header-group.md +++ b/docs/api/core/header-group.md @@ -1,5 +1,5 @@ --- -title: HeaderGroup +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). diff --git a/docs/api/core/header.md b/docs/api/core/header.md index 3d3e2070a5..d672c557ec 100644 --- a/docs/api/core/header.md +++ b/docs/api/core/header.md @@ -1,5 +1,5 @@ --- -title: Header +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). diff --git a/docs/api/core/row.md b/docs/api/core/row.md index 836d458607..d6f0567392 100644 --- a/docs/api/core/row.md +++ b/docs/api/core/row.md @@ -1,5 +1,5 @@ --- -title: Row +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). diff --git a/docs/api/core/table.md b/docs/api/core/table.md index 9c7a74a277..902465e665 100644 --- a/docs/api/core/table.md +++ b/docs/api/core/table.md @@ -1,5 +1,5 @@ --- -title: Table +title: Table APIs --- ## `useReactTable` / `createSolidTable` / `useVueTable` / `createSvelteTable` diff --git a/docs/api/features/column-ordering.md b/docs/api/features/column-ordering.md index 48d4f8b77e..37bfb95337 100644 --- a/docs/api/features/column-ordering.md +++ b/docs/api/features/column-ordering.md @@ -1,5 +1,5 @@ --- -title: Column Ordering +title: Column Ordering APIs id: column-ordering --- diff --git a/docs/api/features/column-sizing.md b/docs/api/features/column-sizing.md index 4c44e21597..0bf7631be8 100644 --- a/docs/api/features/column-sizing.md +++ b/docs/api/features/column-sizing.md @@ -1,5 +1,5 @@ --- -title: Column Sizing +title: Column Sizing APIs id: column-sizing --- diff --git a/docs/api/features/column-visibility.md b/docs/api/features/column-visibility.md index ad9a9cc709..e1280e7c03 100644 --- a/docs/api/features/column-visibility.md +++ b/docs/api/features/column-visibility.md @@ -1,5 +1,5 @@ --- -title: Column Visibility +title: Column Visibility APIs id: column-visibility --- diff --git a/docs/api/features/expanding.md b/docs/api/features/expanding.md index 26d1ba6542..af7ab0db43 100644 --- a/docs/api/features/expanding.md +++ b/docs/api/features/expanding.md @@ -1,5 +1,5 @@ --- -title: Expanding +title: Expanding APIs id: expanding --- diff --git a/docs/api/features/filters.md b/docs/api/features/filters.md index 864fa89db6..4d0c5fe3f3 100644 --- a/docs/api/features/filters.md +++ b/docs/api/features/filters.md @@ -1,5 +1,5 @@ --- -title: Filters +title: Filter APIs id: filters --- diff --git a/docs/api/features/grouping.md b/docs/api/features/grouping.md index dfed1777bd..b9c21631fc 100644 --- a/docs/api/features/grouping.md +++ b/docs/api/features/grouping.md @@ -1,5 +1,5 @@ --- -title: Grouping +title: Grouping APIs id: grouping --- diff --git a/docs/api/features/pagination.md b/docs/api/features/pagination.md index f32dc0dcaa..8403e604de 100644 --- a/docs/api/features/pagination.md +++ b/docs/api/features/pagination.md @@ -1,5 +1,5 @@ --- -title: Pagination +title: Pagination APIs id: pagination --- diff --git a/docs/api/features/pinning.md b/docs/api/features/pinning.md index a4d8db8121..f9822d170d 100644 --- a/docs/api/features/pinning.md +++ b/docs/api/features/pinning.md @@ -1,5 +1,5 @@ --- -title: Pinning +title: Pinning APIs id: pinning --- diff --git a/docs/api/features/row-selection.md b/docs/api/features/row-selection.md index d8874b7048..4b39aa1ea0 100644 --- a/docs/api/features/row-selection.md +++ b/docs/api/features/row-selection.md @@ -1,5 +1,5 @@ --- -title: Row Selection +title: Row Selection APIs id: row-selection --- diff --git a/docs/api/features/sorting.md b/docs/api/features/sorting.md index 9fd28c9951..1e755889ad 100644 --- a/docs/api/features/sorting.md +++ b/docs/api/features/sorting.md @@ -1,5 +1,5 @@ --- -title: Sorting +title: Sorting APIs id: sorting --- diff --git a/docs/guide/cells.md b/docs/guide/cells.md index 6eb2f64ce7..689ba5f5a0 100644 --- a/docs/guide/cells.md +++ b/docs/guide/cells.md @@ -1,5 +1,5 @@ --- -title: Cells +title: Cells Guide --- ## API diff --git a/docs/guide/column-defs.md b/docs/guide/column-defs.md index 738bb98bd6..f4918fac01 100644 --- a/docs/guide/column-defs.md +++ b/docs/guide/column-defs.md @@ -1,5 +1,5 @@ --- -title: Columns +title: Columns Guide --- ## API diff --git a/docs/guide/column-filtering.md b/docs/guide/column-filtering.md index 6b6072a542..957f6269f8 100644 --- a/docs/guide/column-filtering.md +++ b/docs/guide/column-filtering.md @@ -1,5 +1,5 @@ --- -title: Column Filtering +title: Column Filtering Guide --- ## Examples diff --git a/docs/guide/column-ordering.md b/docs/guide/column-ordering.md index 4fe63d45fd..2c60edd13e 100644 --- a/docs/guide/column-ordering.md +++ b/docs/guide/column-ordering.md @@ -1,5 +1,5 @@ --- -title: Column Ordering +title: Column Ordering Guide --- ## Examples diff --git a/docs/guide/column-pinning.md b/docs/guide/column-pinning.md index dcb6118d0f..d011d3f49c 100644 --- a/docs/guide/column-pinning.md +++ b/docs/guide/column-pinning.md @@ -1,5 +1,5 @@ --- -title: Column Pinning +title: Column Pinning Guide --- ## Examples diff --git a/docs/guide/column-sizing.md b/docs/guide/column-sizing.md index 8b810e55d7..4c35ffbab8 100644 --- a/docs/guide/column-sizing.md +++ b/docs/guide/column-sizing.md @@ -1,5 +1,5 @@ --- -title: Column Sizing +title: Column Sizing Guide --- ## Examples diff --git a/docs/guide/column-visibility.md b/docs/guide/column-visibility.md index c7126063bc..d65d42fff3 100644 --- a/docs/guide/column-visibility.md +++ b/docs/guide/column-visibility.md @@ -1,5 +1,5 @@ --- -title: Column Visibility +title: Column Visibility Guide --- ## Examples @@ -8,9 +8,124 @@ Want to skip to the implementation? Check out these examples: - [column-visibility](../framework/react/examples/column-visibility) - [column-ordering](../framework/react/examples/column-ordering) +- [sticky-column-pinning](../framework/react/examples/column-pinning-sticky) + +### Other Examples + +- [SolidJS column-visibility](../framework/solid/examples/column-visibility) +- [Svelte column-visibility](../framework/svelte/examples/column-visibility) ## API [Column Visibility API](../api/features/column-visibility) -## Column Visibility Guide \ No newline at end of file +## Column Visibility Guide + +The column visibility feature allows table columns to be hidden or shown dynamically. In previous versions of react-table, this feature was a static property on a column, but in v8, there is a dedicated `columnVisibility` state and APIs for managing column visibility dynamically. + +### Column Visibility State + +The `columnVisibility` state is a map of column IDs to boolean values. A column will be hidden if its ID is present in the map and the value is `false`. If the column ID is not present in the map, or the value is `true`, the column will be shown. + +```jsx +const [columnVisibility, setColumnVisibility] = useState({ + columnId1: true, + columnId2: false, //hide this column by default + columnId3: true, +}); + +const table = useReactTable({ + //... + state: { + columnVisibility, + //... + }, + onColumnVisibilityChange: setColumnVisibility, +}); +``` + +Alternatively, if you don't need to manage the column visibility state outside of the table, you can still set the initial default column visibility state using the `initialState` option. + +> **Note**: If `columnVisibility` is provided to both `initialState` and `state`, the `state` initialization will take precedence and `initialState` will be ignored. Do not provide `columnVisibility` to both `initialState` and `state`, only one or the other. + +```jsx +const table = useReactTable({ + //... + initialState: { + columnVisibility: { + columnId1: true, + columnId2: false, //hide this column by default + columnId3: true, + }, + //... + }, +}); +``` + +### Disable Hiding Columns + +By default, all columns can be hidden or shown. If you want to prevent certain columns from being hidden, you set the `enableHiding` column option to `false` for those columns. + +```jsx +const columns = [ + { + header: 'ID', + accessorKey: 'id', + enableHiding: false, // disable hiding for this column + }, + { + header: 'Name', + accessor: 'name', // can be hidden + }, +]; +``` + +### Column Visibility Toggle APIs + +There are several column API methods that are useful for rendering column visibility toggles in the UI. + +- `column.getCanHide` - Useful for disabling the visibility toggle for a column that has `enableHiding` set to `false`. +- `column.getIsVisible` - Useful for setting the initial state of the visibility toggle. +- `column.toggleVisibility` - Useful for toggling the visibility of a column. +- `column.getToggleVisibilityHandler` - Shortcut for hooking up the `column.toggleVisibility` method to a UI event handler. + +```jsx +{table.getAllColumns().map((column) => ( + +))} +``` + +### Column Visibility Aware Table APIs + +When you render your header, body, and footer cells, there are a lot of API options available. You may see APIs like `table.getAllLeafColumns` and `row.getAllCells`, but if you use these APIs, they will not take column visibility into account. Instead, you need to use the "visible" variants of these APIs, such as `table.getVisibleLeafColumns` and `row.getVisibleCells`. + +```jsx + + + + {table.getVisibleLeafColumns().map((column) => ( // takes column visibility into account + // + ))} + + + + {table.getRowModel().rows.map((row) => ( + + {row.getVisibleCells().map((cell) => ( // takes column visibility into account + // + ))} + + ))} + +
+``` + +If you are using the Header Group APIs, they will already take column visibility into account. diff --git a/docs/guide/expanding.md b/docs/guide/expanding.md index 09ec3a554b..5c278a870a 100644 --- a/docs/guide/expanding.md +++ b/docs/guide/expanding.md @@ -1,5 +1,5 @@ --- -title: Expanding +title: Expanding Guide --- ## Examples diff --git a/docs/guide/faceted-values.md b/docs/guide/faceted-values.md index 89158bf966..67bb8a630b 100644 --- a/docs/guide/faceted-values.md +++ b/docs/guide/faceted-values.md @@ -1,5 +1,5 @@ --- -title: Faceted Values +title: Faceted Values Guide --- ## Examples diff --git a/docs/guide/features.md b/docs/guide/features.md index a7b4e7f0ab..89ab465d1c 100644 --- a/docs/guide/features.md +++ b/docs/guide/features.md @@ -1,5 +1,5 @@ --- -title: Features +title: Features Guide --- TanStack Table comes with many features, each with their own associated options and API: diff --git a/docs/guide/filters.md b/docs/guide/filters.md index e2f3c1468b..bb2daf0290 100644 --- a/docs/guide/filters.md +++ b/docs/guide/filters.md @@ -1,5 +1,5 @@ --- -title: Filters +title: Filters Guide --- diff --git a/docs/guide/fuzzy-filtering.md b/docs/guide/fuzzy-filtering.md index b1bb38fe65..869518734f 100644 --- a/docs/guide/fuzzy-filtering.md +++ b/docs/guide/fuzzy-filtering.md @@ -1,5 +1,5 @@ --- -title: Fuzzy Filtering +title: Fuzzy Filtering Guide --- ## Examples diff --git a/docs/guide/global-filtering.md b/docs/guide/global-filtering.md index efff065990..02b8c0ef41 100644 --- a/docs/guide/global-filtering.md +++ b/docs/guide/global-filtering.md @@ -1,5 +1,5 @@ --- -title: Global Filtering +title: Global Filtering Guide --- ## Examples diff --git a/docs/guide/grouping.md b/docs/guide/grouping.md index 9f4c02631f..56fe25a7d2 100644 --- a/docs/guide/grouping.md +++ b/docs/guide/grouping.md @@ -1,5 +1,5 @@ --- -title: Grouping +title: Grouping Guide --- ## Examples diff --git a/docs/guide/headers.md b/docs/guide/headers.md index 43425c7dc9..d59e5fcd32 100644 --- a/docs/guide/headers.md +++ b/docs/guide/headers.md @@ -1,5 +1,5 @@ --- -title: Headers +title: Headers Guide --- ## API diff --git a/docs/guide/migrating.md b/docs/guide/migrating.md index f7895ace47..43b8429010 100644 --- a/docs/guide/migrating.md +++ b/docs/guide/migrating.md @@ -1,5 +1,5 @@ --- -title: Migrating to V8 +title: Migrating to V8 Guide --- ## Migrating to V8 diff --git a/docs/guide/pagination.md b/docs/guide/pagination.md index 4054ba1cb3..7b6c41595e 100644 --- a/docs/guide/pagination.md +++ b/docs/guide/pagination.md @@ -1,5 +1,5 @@ --- -title: Pagination +title: Pagination Guide --- ## Examples diff --git a/docs/guide/pinning.md b/docs/guide/pinning.md index e43b8fba15..aa8c116291 100644 --- a/docs/guide/pinning.md +++ b/docs/guide/pinning.md @@ -1,5 +1,5 @@ --- -title: Pinning +title: Pinning Guide --- diff --git a/docs/guide/row-models.md b/docs/guide/row-models.md index 92b6a3a71e..f51ddbb06e 100644 --- a/docs/guide/row-models.md +++ b/docs/guide/row-models.md @@ -1,5 +1,5 @@ --- -title: Row Models +title: Row Models Guide --- ## Row Models Guide diff --git a/docs/guide/row-pinning.md b/docs/guide/row-pinning.md index 14803a4c1f..442a81e3e5 100644 --- a/docs/guide/row-pinning.md +++ b/docs/guide/row-pinning.md @@ -1,5 +1,5 @@ --- -title: Row Pinning +title: Row Pinning Guide --- ## Examples diff --git a/docs/guide/row-selection.md b/docs/guide/row-selection.md index 1be5b5ebf1..0ffd62eca7 100644 --- a/docs/guide/row-selection.md +++ b/docs/guide/row-selection.md @@ -1,5 +1,5 @@ --- -title: Row Selection +title: Row Selection Guide --- ## Examples diff --git a/docs/guide/rows.md b/docs/guide/rows.md index b34ac42669..f25edd4dc3 100644 --- a/docs/guide/rows.md +++ b/docs/guide/rows.md @@ -1,5 +1,5 @@ --- -title: Rows +title: Rows Guide --- ## API diff --git a/docs/guide/sorting.md b/docs/guide/sorting.md index 6905e34593..769847931e 100644 --- a/docs/guide/sorting.md +++ b/docs/guide/sorting.md @@ -1,5 +1,5 @@ --- -title: Sorting +title: Sorting Guide --- ## Examples diff --git a/docs/guide/tables.md b/docs/guide/tables.md index 5090a4c27b..d4361f04a7 100644 --- a/docs/guide/tables.md +++ b/docs/guide/tables.md @@ -1,5 +1,5 @@ --- -title: Tables +title: Tables Guide --- ## API diff --git a/docs/guide/virtualization.md b/docs/guide/virtualization.md index 6abedd5383..2432c901df 100644 --- a/docs/guide/virtualization.md +++ b/docs/guide/virtualization.md @@ -1,5 +1,5 @@ --- -title: Virtualization +title: Virtualization Guide --- ## Examples diff --git a/packages/table-core/src/features/Pinning.ts b/packages/table-core/src/features/Pinning.ts index f942f1e3df..7f9c971de7 100644 --- a/packages/table-core/src/features/Pinning.ts +++ b/packages/table-core/src/features/Pinning.ts @@ -429,7 +429,7 @@ export const Pinning: TableFeature = { getMemoOptions(table.options, 'debugRows', 'getCenterVisibleCells') ) row.getLeftVisibleCells = memo( - () => [row._getAllVisibleCells(), table.getState().columnPinning.left, ,], + () => [row._getAllVisibleCells(), table.getState().columnPinning.left], (allCells, left) => { const cells = (left ?? []) .map(columnId => allCells.find(cell => cell.column.id === columnId)!) diff --git a/packages/table-core/src/features/Visibility.ts b/packages/table-core/src/features/Visibility.ts index c54069a8b4..55c020990f 100644 --- a/packages/table-core/src/features/Visibility.ts +++ b/packages/table-core/src/features/Visibility.ts @@ -18,6 +18,11 @@ export interface VisibilityTableState { } export interface VisibilityOptions { + /** + * Whether to enable column hiding. Defaults to `true`. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-visibility#enablehiding) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-visibility) + */ enableHiding?: boolean /** * 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.