docs: add column visibility docs (#5362)

TanStack · Feb 18, 2024 · e808abf · e808abf
1 parent c42e95a
commit e808abf
Show file tree

Hide file tree

Showing 44 changed files with 164 additions and 44 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -1,5 +1,5 @@
 ---
-title: Sorting
+title: Sorting APIs
 id: sorting
 ---
 

diff --git 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
@@ -1,5 +1,5 @@
 ---
-title: Columns
+title: Columns Guide
 ---
 
 ## API

diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
+## 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) => (
+ <label key={column.id}>
+ <input
+ checked={column.getIsVisible()}
+ disabled={!column.getCanHide()}
+ onChange={column.getToggleVisibilityHandler()}
+ type="checkbox"
+ />
+ {column.columnDef.header}
+ </label>
+))}
+```
+
+### 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>
+ <thead>
+ <tr>
+ {table.getVisibleLeafColumns().map((column) => ( // takes column visibility into account
+ //
+ ))}
+ </tr>
+ </thead>
+ <tbody>
+ {table.getRowModel().rows.map((row) => (
+ <tr key={row.id}>
+ {row.getVisibleCells().map((cell) => ( // takes column visibility into account
+ //
+ ))}
+ </tr>
+ ))}
+ </tbody>
+</table>
+```
+
+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
@@ -1,5 +1,5 @@
 ---
-title: Expanding
+title: Expanding Guide
 ---
 
 ## Examples

diff --git 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
@@ -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
@@ -1,5 +1,5 @@
 ---
-title: Filters
+title: Filters Guide
 ---
 
 <!-- Deprecated -->

diff --git 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
@@ -1,5 +1,5 @@
 ---
-title: Global Filtering
+title: Global Filtering Guide
 ---
 
 ## Examples

diff --git 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
@@ -1,5 +1,5 @@
 ---
-title: Headers
+title: Headers Guide
 ---
 
 ## API

diff --git 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
@@ -1,5 +1,5 @@
 ---
-title: Pagination
+title: Pagination Guide
 ---
 
 ## Examples

diff --git a/docs/guide/pinning.md b/docs/guide/pinning.md
@@ -1,5 +1,5 @@
 ---
-title: Pinning
+title: Pinning Guide
 ---
 
 <!-- Deprecated -->

diff --git 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
@@ -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
@@ -1,5 +1,5 @@
 ---
-title: Row Selection
+title: Row Selection Guide
 ---
 
 ## Examples

diff --git a/docs/guide/rows.md b/docs/guide/rows.md
@@ -1,5 +1,5 @@
 ---
-title: Rows
+title: Rows Guide
 ---
 
 ## API