|
| 1 | +--- |
| 2 | +title: Data Guide |
| 3 | +--- |
| 4 | + |
| 5 | +## Data (and TypeScript) Guide |
| 6 | + |
| 7 | +Tables start with your data. Your column definitions and rows will depend on the shape of your data. TanStack Table has some TypeScript features that will help you create the rest of your table code with a great type-safe experience. If you set up your data and types correctly, TanStack Table will be able to infer the shape of your data and enforce that your column definitions are made correctly. |
| 8 | + |
| 9 | +### TypeScript |
| 10 | + |
| 11 | +TypeScript is NOT required to use the TanStack Table packages... ***BUT*** TanStack Table is written and organized in such a way that makes the awesome TypeScript experience that you get feel like it is one of the main selling points of the library. If you are not using TypeScript, you will be missing out on a lot of great autocompletion and type-checking features that will both speed up your development time and reduce the number of bugs in your code. |
| 12 | + |
| 13 | +#### TypeScript Generics |
| 14 | + |
| 15 | +Having a basic understanding of what TypeScript Generics are and how they work will help you understand this guide better, but it should be easy enough to pick up as you go. The official [TypeScript Generics Docs](https://www.typescriptlang.org/docs/handbook/2/generics.html) may be helpful for those not yet familiar with TypeScript. |
| 16 | + |
| 17 | +### Defining Data Types |
| 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 Generic is usually referred to as `TData` throughout the rest of the TanStack Table types and APIs. |
| 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 | +type User = { |
| 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. This is because the `data` type is literally defined as the `TData` generic type. Whatever you pass to the `data` table option will become the `TData` type for the rest of the table instance. Just make sure your column definitions use the same `TData` type as the `data` type when you define them later. |
| 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[]>([]) //vue |
| 67 | +//etc... |
| 68 | +``` |
| 69 | + |
| 70 | +#### Deep Keyed Data |
| 71 | + |
| 72 | +If your data is not a nice flat array of objects, that's okay! Once you get around to defining your columns, there are strategies for accessing deeply nested data in your accessors. |
| 73 | + |
| 74 | +If your `data` looks something like this: |
| 75 | + |
| 76 | +```json |
| 77 | +[ |
| 78 | + { |
| 79 | + "name": { |
| 80 | + "first": "Tanner", |
| 81 | + "last": "Linsley" |
| 82 | + }, |
| 83 | + "info": { |
| 84 | + "age": 33, |
| 85 | + "visits": 100, |
| 86 | + } |
| 87 | + }, |
| 88 | + { |
| 89 | + "name": { |
| 90 | + "first": "Kevin", |
| 91 | + "last": "Vandy" |
| 92 | + }, |
| 93 | + "info": { |
| 94 | + "age": 27, |
| 95 | + "visits": 200, |
| 96 | + } |
| 97 | + } |
| 98 | +] |
| 99 | +``` |
| 100 | + |
| 101 | +You can define a type like this: |
| 102 | + |
| 103 | +```ts |
| 104 | +type User = { |
| 105 | + name: { |
| 106 | + first: string |
| 107 | + last: string |
| 108 | + } |
| 109 | + info: { |
| 110 | + age: number |
| 111 | + visits: number |
| 112 | + } |
| 113 | +} |
| 114 | +``` |
| 115 | +
|
| 116 | +And you will be able to access the data in your column definitions with either dot notation in an accessorKey or simply by using an accessorFn. |
| 117 | +
|
| 118 | +```ts |
| 119 | +const columns = [ |
| 120 | + { |
| 121 | + header: 'First Name', |
| 122 | + accessorKey: 'name.first', |
| 123 | + }, |
| 124 | + { |
| 125 | + header: 'Last Name', |
| 126 | + accessorKey: 'name.last', |
| 127 | + }, |
| 128 | + { |
| 129 | + header: 'Age', |
| 130 | + accessorFn: info => info.age, |
| 131 | + }, |
| 132 | + //... |
| 133 | +] |
| 134 | +``` |
| 135 | + |
| 136 | +This is discussed in more detail in the [Column Def Guide](../column-defs). |
| 137 | + |
| 138 | +> NOTE: The "keys" in your json data can usually be anything, but any periods in the keys will be interpreted as a deep key and will cause errors. |
| 139 | +
|
| 140 | +#### Nested Sub-Row Data |
| 141 | + |
| 142 | +If you are using expanding features, it can be common to have nested sub-rows in your data. This results in a recursive type that is a bit different. |
| 143 | + |
| 144 | +So if your data looks like this: |
| 145 | + |
| 146 | +```json |
| 147 | +[ |
| 148 | + { |
| 149 | + "firstName": "Tanner", |
| 150 | + "lastName": "Linsley", |
| 151 | + "subRows": [ |
| 152 | + { |
| 153 | + "firstName": "Kevin", |
| 154 | + "lastName": "Vandy", |
| 155 | + }, |
| 156 | + { |
| 157 | + "firstName": "John", |
| 158 | + "lastName": "Doe", |
| 159 | + "subRows": [ |
| 160 | + //... |
| 161 | + ] |
| 162 | + } |
| 163 | + ] |
| 164 | + }, |
| 165 | + { |
| 166 | + "firstName": "Jane", |
| 167 | + "lastName": "Doe", |
| 168 | + } |
| 169 | +] |
| 170 | +``` |
| 171 | + |
| 172 | +You can define a type like this: |
| 173 | + |
| 174 | +```ts |
| 175 | +type User = { |
| 176 | + firstName: string |
| 177 | + lastName: string |
| 178 | + subRows?: User[] //does not have to be called "subRows", can be called anything |
| 179 | +} |
| 180 | +``` |
| 181 | +
|
| 182 | +Where `subRows` is an optional array of `User` objects. This is discussed in more detail in the [Expanding Guide](../expanding). |
| 183 | +
|
| 184 | +### Give Data a "Stable" Reference |
| 185 | +
|
| 186 | +The `data` array that you pass to the table instance ***MUST*** have a "stable" reference in order to prevent bugs that cause infinite re-renders (especially in React). |
| 187 | +
|
| 188 | +This will depend on which framework adapter you are using, but in React, you should often use `React.useState`, `React.useMemo`, or similar to ensure that both the `data` and `columns` table options have stable references. |
| 189 | +
|
| 190 | +```tsx |
| 191 | +const fallbackData = [] |
| 192 | + |
| 193 | +export default function MyComponent() { |
| 194 | + //✅ GOOD: This will not cause an infinite loop of re-renders because `columns` is a stable reference |
| 195 | + const columns = useMemo(() => [ |
| 196 | + // ... |
| 197 | + ], []); |
| 198 | + |
| 199 | + //✅ GOOD: This will not cause an infinite loop of re-renders because `data` is a stable reference |
| 200 | + const [data, setData] = useState(() => [ |
| 201 | + // ... |
| 202 | + ]); |
| 203 | + |
| 204 | + // Columns and data are defined in a stable reference, will not cause infinite loop! |
| 205 | + const table = useReactTable({ |
| 206 | + columns, |
| 207 | + data ?? fallbackData, //also good to use a fallback array that is defined outside of the component (stable reference) |
| 208 | + }); |
| 209 | + |
| 210 | + return <table>...</table>; |
| 211 | +} |
| 212 | +``` |
| 213 | + |
| 214 | +`React.useState` and `React.useMemo` are not the only ways to give your data a stable reference. You can also define your data outside of the component or use a 3rd party state management library like Redux, Zustand, or TanStack Query. |
| 215 | + |
| 216 | +The main thing to avoid is defining the `data` array inside the same scope as the `useReactTable` call. That will cause the `data` array to be redefined on every render, which will cause an infinite loop of re-renders. |
| 217 | + |
| 218 | +```tsx |
| 219 | +export default function MyComponent() { |
| 220 | + //😵 BAD: This will cause an infinite loop of re-renders because `columns` is redefined as a new array on every render! |
| 221 | + const columns = [ |
| 222 | + // ... |
| 223 | + ]; |
| 224 | + |
| 225 | + //😵 BAD: This will cause an infinite loop of re-renders because `data` is redefined as a new array on every render! |
| 226 | + const data = [ |
| 227 | + // ... |
| 228 | + ]; |
| 229 | + |
| 230 | + //❌ Columns and data are defined in the same scope as `useReactTable` without a stable reference, will cause infinite loop! |
| 231 | + const table = useReactTable({ |
| 232 | + columns, |
| 233 | + data ?? [], //❌ Also bad because the fallback array is re-created on every render |
| 234 | + }); |
| 235 | + |
| 236 | + return <table>...</table>; |
| 237 | +} |
| 238 | +``` |
| 239 | + |
| 240 | +### How TanStack Table Transforms Data |
| 241 | + |
| 242 | +Later, in other parts of these docs, you will see how TanStack Table processes the `data` that you pass to the table and generates the row and cell objects that are used to create the table. The `data` the you pass to the table is never mutated by TanStack Table, but the actual values in the rows and cells may be transformed by the accessors in your column definitions, or by other features performed by [row models](../row-models) like grouping or aggregation. |
| 243 | + |
| 244 | +### How Much Data Can TanStack Table Handle? |
| 245 | + |
| 246 | +Believe it or not, TanStack Table was actually built to scale up to handle potentially hundreds of thousands of rows of data in the client. This is obviously not always possible, depending on the size of each column's data and the number of columns. However, the sorting, filtering, pagination, and grouping features are all built with performance in mind for large datasets. |
| 247 | + |
| 248 | +The default mindset of a developer building a data grid is to implement server-side pagination, sorting, and filtering for large datasets. This is still usually a good idea, but a lot of developers underestimate how much data can actually be handled in the client with modern browsers and the right optimizations. If your table will never have more than a few thousand rows, you can probably take advantage of the client-side features in TanStack Table instead of implementing them yourself on the server. Before committing to letting TanStack Table's client-side features handle your large dataset, you should test it with your actual data to see if it performs well enough for your needs, of course. |
| 249 | + |
| 250 | +This is discussed in more detail in the [Pagination Guide](../pagination#should-you-use-client-side-pagination). |
0 commit comments