From 102ffd2707a671ecb5fc9ce79f2feddc6cabbce5 Mon Sep 17 00:00:00 2001 From: Kevin Van Cott Date: Wed, 8 May 2024 12:33:27 -0500 Subject: [PATCH] docs: header and column docs (#5531) * docs: header and column docs * undo example log --- docs/guide/cells.md | 2 +- docs/guide/column-defs.md | 2 + docs/guide/columns.md | 65 ++++++++++++++++++++++++++++++++- docs/guide/headers.md | 77 ++++++++++++++++++++++++++++++++++++++- docs/guide/tables.md | 2 + 5 files changed, 145 insertions(+), 3 deletions(-) diff --git a/docs/guide/cells.md b/docs/guide/cells.md index 66f8198a1c..489411122e 100644 --- a/docs/guide/cells.md +++ b/docs/guide/cells.md @@ -8,7 +8,7 @@ title: Cells Guide ## Cells Guide -This quick guide will discuss the different ways you can retrieve and interact with cell objects in TanStack Table. +This quick guide will discuss the different ways you can retrieve and interact with `cell` objects in TanStack Table. ### Where to Get Cells From diff --git a/docs/guide/column-defs.md b/docs/guide/column-defs.md index 54a54ed6f7..10d1456acd 100644 --- a/docs/guide/column-defs.md +++ b/docs/guide/column-defs.md @@ -8,6 +8,8 @@ title: Columns Guide ## Column Definitions Guide +> Note: This guide is about setting up column definitions for your table and NOT about the actual [`column`](../columns) objects that are generated within the table instance. + Column defs are the single most important part of building a table. They are responsible for: - Building the underlying data model that will be used for everything including sorting, filtering, grouping, etc. diff --git a/docs/guide/columns.md b/docs/guide/columns.md index 387f32b7c7..ca8769b7d4 100644 --- a/docs/guide/columns.md +++ b/docs/guide/columns.md @@ -6,4 +6,67 @@ title: Columns Guide [Header API](../../api/core/column) -## Columns Guide \ No newline at end of file +## Columns Guide + +> Note: This guide is about the actual `column` objects that are generated within the table instance and NOT about setting up the [column definitions](../column-defs) for your table. + +This quick guide will discuss the different ways you can retrieve and interact with `column` objects in TanStack Table. + +### Where to Get Columns From + +You can find the `column` objects in many places. They are often attached + +#### Header and Cell Objects + +Before you reach for one of the `table` instance APIs, consider if you actually need to retrieve either [`headers`](../headers) or [`cells`](../cells) instead of `columns`. If you are rending out the markup for your table, you will most likely want to reach for the APIs that return headers or cells instead of columns. The column objects themselves are not really meant to render out the headers or cells, but the `header` and `cell` objects will contain references to these `column` objects from which they can derive the necessary information to render their UI. + +```js +const column = cell.column; // get column from cell +const column = header.column; // get column from header +``` + +#### Column Table Instance APIs + +There are dozens of `table` instance APIs you can use to retrieve columns from the table instance. Which APIs you will use will depend entirely on which features you are using in your table and your use-case. + +##### Get Column + +If you need to just get a single column by its ID, you can use the `table.getColumn` API. + +```js +const column = table.getColumn('firstName'); +``` + +##### Get Columns + +The simplest column API is `table.getAllColumns`, which will return a list of all columns in the table. There are dozens of other column APIs that are affected by other features and the state of the table that come alongside this API though. `table.getAllFlatColumns`, `table.getAllLeafColumns`, `getCenterLeafColumns`, `table.getLeftVisibleLeafColumns` are just some examples of other column APIs that you might use in tandem with the column visibility or column pinning features. + +### Column Objects + +Column objects are not actually meant to be used to render out the table UI directly, so they are not associated 1-to-1 with any `` or `` elements in your table, but they contain a lot of useful properties and methods that you can use to interact with the table state. + +#### Column IDs + +Every column must have a unique `id` defined in their associated [Column Definition](../column-defs). Usually, you define this `id` yourself, or it is derived from the `accessorKey` or `header` properties in the column definition. + +#### ColumnDef + +A reference to the original `columnDef` object that was used to created the column is always available on the column object. + +#### Nested Grouped Columns Properties + +There are a few properties on `column` objects that are only useful if the column is part of a nested or grouped column structure. These properties include: + +- `columns`: An array of child columns that belong to a group column. +- `depth`: The header group "row index" that the column group belongs to. +- `parent`: The parent column of the column. If the column is a top-level column, this will be `undefined`. + +### More Column APIs + +There are dozens of Column APIs that you can use to interact with the table state and extract cell values from the table based on the state of the table. See each features column API documentation for more information. + +### Column Rendering + +Don't necessarily use `column` objects to render `headers` or `cells` directly. Instead, use the [`header](../headers) and [`cell`](../cells) objects, as discussed above. + +But if you are just rendering a list of columns somewhere else in your UI for something like a column visibility menu or something similar, you can just map over a columns array and render out the UI as you normally would. \ No newline at end of file diff --git a/docs/guide/headers.md b/docs/guide/headers.md index 56efa67ead..97623c908c 100644 --- a/docs/guide/headers.md +++ b/docs/guide/headers.md @@ -6,4 +6,79 @@ title: Headers Guide [Header API](../../api/core/header) -## Headers Guide \ No newline at end of file +## Headers Guide + +This quick guide will discuss the different ways you can retrieve and interact with `header` objects in TanStack Table. + +Headers are the equivalent of cells, but meant for the `` section of the table instead of the `` section. + +### Where to Get Headers From + +Headers come from [Header Groups](../header-groups), which are the equivalent of rows, but meant for the `` section of the table instead of the `` section. + +#### HeaderGroup Headers + +If you are in a header group, the headers are stored as an array in the `headerGroup.headers` property. Usually you will just map over this array to render your headers. + +```jsx + + {table.getHeaderGroups().map(headerGroup => { + return ( + + {headerGroup.headers.map(header => ( // map over the headerGroup headers array + + {/* */} + + ))} + + ) + })} + +``` + +#### Header Table Instance APIs + +There are multiple `table` instance APIs that you can use to retrieve a list of headers depending on the features that you are using. The most common API you might use is `table.getFlatHeaders`, which will return a flat list of all headers in the table, but there are at least a dozen other headers that are useful in tandem with the column visibility and column pinning features. APIs like `table.getLeftLeafHeaders` or `table.getRightFlatHeaders` could be useful depending on your use case. + +### Header Objects + +Header objects are similar to [Cell](../cells) objects, but meant for the `` section of the table instead of the `` section. Every header object can be associated with a `` or similar cell element in your UI. There are a few properties and methods on `header` objects that you can use to interact with the table state and extract cell values from the table based on the state of the table. + +#### Header IDs + +Every header object has an `id` property that makes it unique within the table instance. Usually you only need this `id` as a unique identifier for React keys or if you are following the [performant column resizing example](../../framework/react/examples/column-resizing-performant). + +For simple headers with no advanced nested or grouped headers logic, the `header.id` will be the same as it's parent `column.id`. However, if the header is part group column or a placeholder cell, it will have a more complicated id that is constructed from the header family, depth/header row index, column id, and header group id. + +#### Nested Grouped Headers Properties + +There are a few properties on `header` objects that are only useful if the header is part of a nested or grouped header structure. These properties include: + +- `colspan`: The number of columns that the header should span. This is useful for rendering the `colSpan` attribute on the `` element. +- `rowSpan`: The number of rows that the header should span. This is useful for rendering the `rowSpan` attribute on the `` element. (Currently not implemented in default TanStack Table) +- `depth`: The header group "row index" that the header group belongs to. +- `isPlaceholder`: A boolean flag that is true if the header is a placeholder header. Placeholder headers are used to fill in the gaps when a column is hidden or when a column is part of a group column. +- `placeholderId`: The unique identifier for the placeholder header. +- `subHeaders`: The array of sub/child headers that belong to this header. Will be empty if the header is a leaf header. + +> Note: `header.index` refers to its index within the header group (row of headers), i.e. its position from left to right. It is not the same as `header.depth`, which refers to the header group "row index". + +#### Header Parent Objects + +Every header stores a reference to its parent [column](../columns) object and its parent [header group](../header-groups) object. + +### More Header APIs + +Headers have a few more useful APIs attached to them that are useful for interacting with the table state. Most of them relate to the Column sizing and resizing features. See the [Column Resizing Guide](../column-resizing) for more information. + +### Header Rendering + +Since the `header` column option you defined can be either a string, jsx, or a function returning either of those, the best way to render the headers is to use the `flexRender` utility from your adapter, which will handle all of those cases for you. + +```jsx +{headerGroup.headers.map(header => ( + + {/* Handles all possible header column def scenarios for `header` */} + {flexRender(header.column.columnDef.header, header.getContext())} + +))} \ No newline at end of file diff --git a/docs/guide/tables.md b/docs/guide/tables.md index 9b1c5705c2..b74c09f69d 100644 --- a/docs/guide/tables.md +++ b/docs/guide/tables.md @@ -10,6 +10,8 @@ title: Table Instance Guide TanStack Table is a headless UI library. When we talk about the `table` or "table instance", we're not talking about a literal `` element. Instead, we're referring to the core table object that contains the table state and APIs. The `table` instance is created by calling your adapter's `createTable` function (e.g. `useReactTable`, `createSolidTable`, `createSvelteTable`, `useQwikTable`, `useVueTable`). +The `table` instance that is returned from the `createTable` function (from the framework adapter) is the main object that you will interact with to read and mutate the table state. It is the one place where everything happens in TanStack Table. + ### Creating a Table Instance To create a table instance, 2 `options` are required: `columns` and `data`. There are dozens of other table options to configure features and behavior, but these 2 are required.