You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
> [Looking for version 7 of `react-table`? Click here!](https://github.com/tanstack/table/tree/v7)
26
33
27
34
## Enjoy this library?
28
35
29
-
Try some other [TanStack](https://tanstack.com) like [React Query](https://github.com/TanStack/query), [React Form](https://github.com/tannerlinsley/react-form), [React Charts](https://github.com/TanStack/react-charts)
36
+
Try other [TanStack](https://tanstack.com) libraries:
- Introspect the types! Even without the docs finished, the library ships with 100% typescript to help you explore its capabilities.
169
128
-[Read the contribution guidelines](https://github.com/tanstack/table/tree/main/CONTRIBUTING.md)
170
129
- Write some docs! Start with the [API docs](https://github.com/TanStack/react-table/tree/main/docs/api) and try adding some information about one or more of the features. The types do a decent job of showing what's supported and the capabilities of the library.
171
-
- Try your hand at migrating an example to v8! The todo list for the examples is above!
172
130
-**Using a plugin?** Try rewriting your plugin (v8 doesn't have a plugin system any more) as a functional wrapper that uses TanStack Table internally. The new API is much more powerful and easier to compose. If you find something you can't figure out, let us know and we'll add it to the API.
173
131
174
132
### [Become a Sponsor](https://github.com/sponsors/tannerlinsley/)
There are 3 table features that can reorder columns, which happen in the following order:
19
+
20
+
1.**Column Pinning** - If pinning, columns are split into left, center (unpinned), and right pinned columns.
21
+
2. Manual [Column Ordering](../guide/column-ordering) - A manually specified column order is applied.
22
+
3.[Grouping](../guide/grouping) - If grouping is enabled, a grouping state is active, and `tableOptions.columnGroupingMode` is set to `'reorder' | 'remove'`, then the grouped columns are reordered to the start of the column flow.
The column sizing feature allows you to optionally specify the width of each column including min and max widths. It also allows you and your users the ability to dynamically change the width of all columns at will, eg. by dragging the column headers.
There are 3 table features that can reorder columns, which happen in the following order:
19
-
20
-
1.**Column Pinning** - If pinning, columns are split into left, center (unpinned), and right pinned columns.
21
-
2. Manual [Column Ordering](../guide/column-ordering) - A manually specified column order is applied.
22
-
3.[Grouping](../guide/grouping) - If grouping is enabled, a grouping state is active, and `tableOptions.columnGroupingMode` is set to `'reorder' | 'remove'`, then the grouped columns are reordered to the start of the column flow.
23
-
24
-
There are 2 table features that can reorder rows, which happen in the following order:
25
-
26
-
1.**Row Pinning** - If pinning, rows are split into top, center (unpinned), and bottom pinned rows.
The row selection feature keeps track of which rows are selected and allows you to toggle the selection of rows in a myriad of ways. Let's take a look at some common use cases.
Copy file name to clipboardExpand all lines: docs/guide/tables.md
+122
Original file line number
Diff line number
Diff line change
@@ -5,3 +5,125 @@ title: Tables
5
5
## API
6
6
7
7
[Table API](../api/core/table)
8
+
9
+
## Table Instance Guide
10
+
11
+
TanStack Table is a headless UI library. When we talk about the `table` or "table instance", we're not talking about a literal `<table>` 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`, `useVueTable`).
12
+
13
+
### Creating a Table Instance
14
+
15
+
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.
16
+
17
+
#### Defining Data
18
+
19
+
`data` is an array of objects that will be turned into the rows of your table. Each object in the array represents a row of data (under normal circumstances). If you are using TypeScript, we usually define a type for the shape of our data. This type is used as a generic type for all of the other table, column, row, and cell instances. This type is usually referred to as `TData`.
20
+
21
+
For example, if we have a table that displays a list of users in an array like this:
22
+
23
+
```json
24
+
[
25
+
{
26
+
"firstName": "Tanner",
27
+
"lastName": "Linsley",
28
+
"age": 33,
29
+
"visits": 100,
30
+
"progress": 50,
31
+
"status": "Married"
32
+
},
33
+
{
34
+
"firstName": "Kevin",
35
+
"lastName": "Vandy",
36
+
"age": 27,
37
+
"visits": 200,
38
+
"progress": 100,
39
+
"status": "Single"
40
+
}
41
+
]
42
+
```
43
+
44
+
Then we can define a User (TData) type like this:
45
+
46
+
```ts
47
+
//TData
48
+
typeUser= {
49
+
firstName:string
50
+
lastName:string
51
+
age:number
52
+
visits:number
53
+
progress:number
54
+
status:string
55
+
}
56
+
```
57
+
58
+
We can then define our `data` array with this type, and then TanStack Table will be able to intelligently infer lots of types for us later on in our columns, rows, cells, etc.
59
+
60
+
```ts
61
+
//note: data needs a "stable" reference in order to prevent infinite re-renders
62
+
const data:User[] = []
63
+
//or
64
+
const [data, setData] =React.useState<User[]>([])
65
+
//or
66
+
const data =ref<User[]>([])
67
+
//etc...
68
+
```
69
+
70
+
> Note: `data` needs a "stable" reference (especially in React) in order to prevent infinite re-renders. This is why we recommend using `React.useState` or `React.useMemo`, or defining your data outside of the same react component that creates the table instance, or using a library like TanStack Query to manage your data state.
71
+
72
+
#### Defining Columns
73
+
74
+
Column definitions are covered in detail in the next section in the [Column Def Guide](./column-defs). We'll note here, however, that when you define the type of your columns, you should use the same `TData` type that you used for you data.
75
+
76
+
```ts
77
+
const columns:ColumnDef<User>[] = [] //Pass User type as the generic TData type
78
+
//or
79
+
const columnHelper =createColumnHelper<User>() //Pass User type as the generic TData type
80
+
```
81
+
82
+
The column definitions are where we will tell TanStack Table how each column should access and/or transform row data with either an `accessorKey` or `accessorFn`. See the [Column Def Guide](./column-defs#creating-accessor-columns) for more info.
83
+
84
+
#### Creating the Table Instance
85
+
86
+
With our `columns` and `data` defined, we can now create our basic table instance.
87
+
88
+
```ts
89
+
//vanilla js
90
+
const table =createTable({ columns, data })
91
+
92
+
//react
93
+
const table =useReactTable({ columns, data })
94
+
95
+
//solid
96
+
const table =createSolidTable({ columns, data })
97
+
98
+
//svelte
99
+
const table =createSvelteTable({ columns, data })
100
+
101
+
//vue
102
+
const table =useVueTable({ columns, data })
103
+
```
104
+
105
+
So what's in the `table` instance? Let's take a look at what interactions we can have with the table instance.
106
+
107
+
### Table State
108
+
109
+
The table instance contains all of the table state, which can be accessed via the `table.getState()` API. Each table feature registers various states in the table state. For example, the row selection feature registers `rowSelection` state, the pagination feature registers `pagination` state, etc.
110
+
111
+
Each feature will also have corresponding state setter APIs and state resetter APIs on the table instance. For example, the row selection feature will have a `setRowSelection` API and a `resetRowSelection`.
112
+
113
+
```ts
114
+
table.getState().rowSelection//read the row selection state
115
+
table.setRowSelection((old) => ({...old})) //set the row selection state
116
+
table.resetRowSelection() //reset the row selection state
117
+
```
118
+
119
+
### Table APIs
120
+
121
+
There are dozens of table APIs created by each feature to help you either read or mutate the table state in different ways.
122
+
123
+
API reference docs for the core table instance and all other feature APIs can be found throughout the API docs.
124
+
125
+
For example, you can find the core table instance API docs here: [Table API](../api/core/table#table-api)
126
+
127
+
### Table Row Models
128
+
129
+
There special set of table instance APIs for reading rows out of the table instance called row models. TanStack Table has advanced features where the rows that are generated may be very different than the the array of `data` that you originally passed in. To learn more about the different row models that you can pass in as a table option, see the [Row Models Guide](./row-models).
The TanStack Table packages do not come with any virtualization APIs or features built-in, but TanStack Table can easily work with other virtualization libraries like [react-window](https://www.npmjs.com/package/react-window) or TanStack's own [TanStack Virtual](https://tanstack.com/virtual/v3). This guide will show some strategies for using TanStack Table with TanStack Virtual.
0 commit comments