docs: add column visibility docs

TanStack · Feb 18, 2024 · 2b36a7d · 2b36a7d
1 parent c42e95a
commit 2b36a7d
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