@mini_7/material-react-table-mcp 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (170) hide show
  1. package/README.md +68 -0
  2. package/data/MIGRATION.md +136 -0
  3. package/data/api.json +5379 -0
  4. package/data/examples/advanced.tsx +309 -0
  5. package/data/examples/aggregation-and-grouping.tsx +153 -0
  6. package/data/examples/aggregation-multi.tsx +105 -0
  7. package/data/examples/alternate-column-filtering.tsx +49 -0
  8. package/data/examples/alternate-detail-panel.tsx +81 -0
  9. package/data/examples/alternate-pagination.tsx +23 -0
  10. package/data/examples/basic.tsx +109 -0
  11. package/data/examples/chart-detail-panel.tsx +89 -0
  12. package/data/examples/column-actions-space.tsx +44 -0
  13. package/data/examples/column-alignment.tsx +70 -0
  14. package/data/examples/custom-column-actions.tsx +109 -0
  15. package/data/examples/custom-column-filtering-ui.tsx +89 -0
  16. package/data/examples/custom-headless.tsx +125 -0
  17. package/data/examples/custom-top-toolbar.tsx +88 -0
  18. package/data/examples/customize-display-columns.tsx +85 -0
  19. package/data/examples/customize-filter-components.tsx +101 -0
  20. package/data/examples/customize-filter-modes.tsx +73 -0
  21. package/data/examples/customize-filter-variants.tsx +116 -0
  22. package/data/examples/customize-global-filter-component.tsx +52 -0
  23. package/data/examples/customize-remove-column-grouping.tsx +94 -0
  24. package/data/examples/customize-row-selection.tsx +54 -0
  25. package/data/examples/customize-table-styles.tsx +100 -0
  26. package/data/examples/disable-column-actions.tsx +37 -0
  27. package/data/examples/disable-column-hiding.tsx +90 -0
  28. package/data/examples/disable-density-toggle.tsx +49 -0
  29. package/data/examples/dynamic-columns.tsx +189 -0
  30. package/data/examples/editing-crud-cell.tsx +377 -0
  31. package/data/examples/editing-crud-modal.tsx +370 -0
  32. package/data/examples/editing-crud-row.tsx +333 -0
  33. package/data/examples/editing-crud-table.tsx +369 -0
  34. package/data/examples/editing-crud-tree.tsx +416 -0
  35. package/data/examples/enable-cell-actions.tsx +76 -0
  36. package/data/examples/enable-click-to-copy.tsx +39 -0
  37. package/data/examples/enable-column-grouping.tsx +120 -0
  38. package/data/examples/enable-column-ordering.tsx +48 -0
  39. package/data/examples/enable-column-pinning.tsx +69 -0
  40. package/data/examples/enable-column-resizing.tsx +56 -0
  41. package/data/examples/enable-column-virtualization.tsx +27 -0
  42. package/data/examples/enable-detail-panel-conditionally.tsx +78 -0
  43. package/data/examples/enable-detail-panel-virtualized.tsx +80 -0
  44. package/data/examples/enable-expanding-tree.tsx +110 -0
  45. package/data/examples/enable-filter-facet-values.tsx +65 -0
  46. package/data/examples/enable-row-dragging.tsx +137 -0
  47. package/data/examples/enable-row-numbers-original.tsx +48 -0
  48. package/data/examples/enable-row-numbers-static.tsx +48 -0
  49. package/data/examples/enable-row-ordering.tsx +57 -0
  50. package/data/examples/enable-row-pinning-select.tsx +76 -0
  51. package/data/examples/enable-row-pinning-static.tsx +50 -0
  52. package/data/examples/enable-row-pinning-sticky.tsx +69 -0
  53. package/data/examples/enable-row-selection.tsx +96 -0
  54. package/data/examples/enable-row-virtualization.tsx +101 -0
  55. package/data/examples/enable-sticky-header.tsx +59 -0
  56. package/data/examples/expanding-tree-expanded.tsx +121 -0
  57. package/data/examples/expanding-tree-flat-parse.tsx +125 -0
  58. package/data/examples/expanding-tree-root-expanded.tsx +151 -0
  59. package/data/examples/export-to-csv.tsx +114 -0
  60. package/data/examples/export-to-pdf.tsx +104 -0
  61. package/data/examples/external-toolbar.tsx +108 -0
  62. package/data/examples/font-awesome-icons.tsx +106 -0
  63. package/data/examples/infinite-scrolling.tsx +208 -0
  64. package/data/examples/lazy-detail-panel.tsx +262 -0
  65. package/data/examples/lazy-sub-rows.tsx +190 -0
  66. package/data/examples/linear-progress.tsx +66 -0
  67. package/data/examples/loading.tsx +50 -0
  68. package/data/examples/localization-i18n-ar.tsx +65 -0
  69. package/data/examples/localization-i18n-az.tsx +60 -0
  70. package/data/examples/localization-i18n-bg.tsx +60 -0
  71. package/data/examples/localization-i18n-cs.tsx +60 -0
  72. package/data/examples/localization-i18n-da.tsx +60 -0
  73. package/data/examples/localization-i18n-de.tsx +60 -0
  74. package/data/examples/localization-i18n-el.tsx +60 -0
  75. package/data/examples/localization-i18n-en.tsx +60 -0
  76. package/data/examples/localization-i18n-es.tsx +60 -0
  77. package/data/examples/localization-i18n-et.tsx +60 -0
  78. package/data/examples/localization-i18n-fa.tsx +66 -0
  79. package/data/examples/localization-i18n-fi.tsx +60 -0
  80. package/data/examples/localization-i18n-fr.tsx +60 -0
  81. package/data/examples/localization-i18n-he.tsx +66 -0
  82. package/data/examples/localization-i18n-hr.tsx +60 -0
  83. package/data/examples/localization-i18n-hu.tsx +60 -0
  84. package/data/examples/localization-i18n-hy.tsx +65 -0
  85. package/data/examples/localization-i18n-id.tsx +60 -0
  86. package/data/examples/localization-i18n-it.tsx +60 -0
  87. package/data/examples/localization-i18n-ja.tsx +60 -0
  88. package/data/examples/localization-i18n-ko.tsx +60 -0
  89. package/data/examples/localization-i18n-nl.tsx +60 -0
  90. package/data/examples/localization-i18n-no.tsx +60 -0
  91. package/data/examples/localization-i18n-np.tsx +60 -0
  92. package/data/examples/localization-i18n-pl.tsx +60 -0
  93. package/data/examples/localization-i18n-pt-BR.tsx +60 -0
  94. package/data/examples/localization-i18n-pt.tsx +60 -0
  95. package/data/examples/localization-i18n-ro.tsx +60 -0
  96. package/data/examples/localization-i18n-ru.tsx +60 -0
  97. package/data/examples/localization-i18n-sk.tsx +60 -0
  98. package/data/examples/localization-i18n-sr-Cyrl-RS.tsx +60 -0
  99. package/data/examples/localization-i18n-sr-Latn-RS.tsx +60 -0
  100. package/data/examples/localization-i18n-sv.tsx +60 -0
  101. package/data/examples/localization-i18n-tr.tsx +60 -0
  102. package/data/examples/localization-i18n-uk.tsx +60 -0
  103. package/data/examples/localization-i18n-vi.tsx +60 -0
  104. package/data/examples/localization-i18n-zh-hans.tsx +60 -0
  105. package/data/examples/localization-i18n-zh-hant.tsx +60 -0
  106. package/data/examples/manual-selection.tsx +105 -0
  107. package/data/examples/minimal.tsx +78 -0
  108. package/data/examples/mui-theme.tsx +136 -0
  109. package/data/examples/multi-sorting.tsx +58 -0
  110. package/data/examples/persistent-state.tsx +184 -0
  111. package/data/examples/react-query.tsx +182 -0
  112. package/data/examples/remote.tsx +150 -0
  113. package/data/examples/row-actions-buttons.tsx +89 -0
  114. package/data/examples/row-actions-menu-items.tsx +64 -0
  115. package/data/examples/single-row-selection.tsx +98 -0
  116. package/data/examples/virtualized.tsx +138 -0
  117. package/data/guides/accessibility.md +119 -0
  118. package/data/guides/aggregation.md +210 -0
  119. package/data/guides/async-loading.md +132 -0
  120. package/data/guides/best-practices.md +363 -0
  121. package/data/guides/cell-actions.md +139 -0
  122. package/data/guides/click-to-copy.md +67 -0
  123. package/data/guides/column-actions.md +69 -0
  124. package/data/guides/column-filtering.md +366 -0
  125. package/data/guides/column-grouping.md +192 -0
  126. package/data/guides/column-hiding.md +133 -0
  127. package/data/guides/column-ordering-dnd.md +99 -0
  128. package/data/guides/column-pinning.md +72 -0
  129. package/data/guides/column-resizing.md +157 -0
  130. package/data/guides/column-size.md +162 -0
  131. package/data/guides/customize-components.md +395 -0
  132. package/data/guides/customize-icons.md +35 -0
  133. package/data/guides/data-columns.md +292 -0
  134. package/data/guides/density-toggle.md +46 -0
  135. package/data/guides/detail-panel.md +195 -0
  136. package/data/guides/display-columns.md +135 -0
  137. package/data/guides/editing.md +367 -0
  138. package/data/guides/expanding-sub-rows.md +194 -0
  139. package/data/guides/full-screen-toggle.md +63 -0
  140. package/data/guides/global-filtering.md +237 -0
  141. package/data/guides/localization.md +57 -0
  142. package/data/guides/memoization.md +157 -0
  143. package/data/guides/pagination.md +171 -0
  144. package/data/guides/row-actions.md +116 -0
  145. package/data/guides/row-numbers.md +24 -0
  146. package/data/guides/row-ordering-dnd.md +51 -0
  147. package/data/guides/row-pinning.md +96 -0
  148. package/data/guides/row-selection.md +237 -0
  149. package/data/guides/sorting.md +190 -0
  150. package/data/guides/state-management.md +165 -0
  151. package/data/guides/sticky-header.md +41 -0
  152. package/data/guides/table-event-listeners.md +103 -0
  153. package/data/guides/toolbar-customization.md +251 -0
  154. package/data/guides/virtualization.md +183 -0
  155. package/data/index.json +1930 -0
  156. package/data/reference/mrt-components.md +183 -0
  157. package/data/reference/mrt-hooks.md +125 -0
  158. package/data/skills/composable-components/SKILL.md +189 -0
  159. package/data/skills/customization/SKILL.md +190 -0
  160. package/data/skills/drag-and-drop-ordering/SKILL.md +227 -0
  161. package/data/skills/editing/SKILL.md +243 -0
  162. package/data/skills/filtering/SKILL.md +213 -0
  163. package/data/skills/getting-started/SKILL.md +213 -0
  164. package/data/skills/localization/SKILL.md +182 -0
  165. package/data/skills/migrate-v3-to-v4/SKILL.md +161 -0
  166. package/data/skills/state-and-server-data/SKILL.md +200 -0
  167. package/data/skills/virtualization/SKILL.md +203 -0
  168. package/dist/data.js +137 -0
  169. package/dist/index.js +232 -0
  170. package/package.json +50 -0
@@ -0,0 +1,367 @@
1
+ ## Editing Feature Guide
2
+
3
+ If your tables need full CRUD functionality, you can enable editing features in Material React Table.
4
+
5
+ There are five visually distinct editing modes to choose from, whether you want to let users [edit data in a modal](#modal-edit-display-mode), [inline one row at a time](#row-edit-display-mode), [one cell at a time](#cell-edit-display-mode), or just always have [editing enabled for every cell](#table-edit-display-mode), or a [completely custom editing UI](#custom-edit-display-mode).
6
+
7
+ ### Relevant Table Options
8
+
9
+ Relevant table options (get_mrt_api has full details):
10
+
11
+ - `editDisplayMode` - type `'modal' | 'cell' | 'row' | 'table' | 'custom` - default `'modal'` - You can choose between 5 different built-in editing modes. Edit a row in a modal, or a row inline, just 1 cell at a time, or always have all cells editable.
12
+ - `enableEditing` - type `boolean | (row: MRT_Row) => boolean`
13
+ - `muiEditRowDialogProps` - type `IconButtonProps | ({ table }) => IconButtonProps`
14
+ - `muiEditTextFieldProps` - type `TextFieldProps | ({ cell, column, row, table }) => TextFieldProps`
15
+ - `onCreatingRowCancel` - type `({ row, table }) => void`
16
+ - `onCreatingRowChange` - type `OnChangeFn<MRT_Row<TData> | null>`
17
+ - `onCreatingRowSave` - type `({ exitEditingMode, row, table, values}) => Promise<void> | void`
18
+ - `onEditingCellChange` - type `OnChangeFn<MRT_Cell<TData> | null>`
19
+ - `onEditingRowCancel` - type `({ row, table }) => void`
20
+ - `onEditingRowChange` - type `OnChangeFn<MRT_Row<TData> | null>`
21
+ - `onEditingRowSave` - type `({ exitEditingMode, row, table, values}) => Promise<void> | void`
22
+ - `positionCreatingRow` - type `'top' | 'bottom' | number` - default `'top'` - Where to render the new blank inserted row when in creating mode. Passing in a number will render the row before the row at that index.
23
+ - `renderCreateRowDialogContent` - type `({ internalEditComponents, row, table }) => ReactNode`
24
+ - `renderEditRowDialogContent` - type `({ internalEditComponents, row, table }) => ReactNode`
25
+
26
+ ### Relevant Column Options
27
+
28
+ Relevant column options (get_mrt_api has full details):
29
+
30
+ - `Edit` - type `({ cell, column, row, table }) => ReactNode` - Define a custom edit component for cells in a column.
31
+ - `editSelectOptions` - type `DropdownOption[] | (({ cell, column, row, table, }) => DropdownOption[])`
32
+ - `editVariant` - type `'text' | 'select'` - default `'text'`
33
+ - `enableEditing` - type `boolean | (row) => boolean`
34
+ - `muiEditTextFieldProps` - type `TextFieldProps | ({ cell, column, row, table }) => TextFieldProps`
35
+
36
+ ### Relevant State Options
37
+
38
+ Relevant state options (get_mrt_api has full details):
39
+
40
+ - `creatingRow` - type `MRT_Row` - a variable representing the currently creating row
41
+ - `editingCell` - type `MRT_Cell` - a variable representing the currently editing cell
42
+ - `editingRow` - type `MRT_Row` - a variable representing the currently editing row
43
+
44
+ ### Enable Editing
45
+
46
+ To enable editing, you first need to set the `enableEditing` table option to `true`.
47
+
48
+ ```jsx
49
+ const table = useMaterialReactTable({
50
+ columns,
51
+ data,
52
+ enableEditing: true,
53
+ });
54
+ ```
55
+
56
+ However, this is just the first step. You will need to hook up logic and event listeners, but it depends on which `editDisplayMode` you want to use.
57
+
58
+ ### Disable Editing
59
+
60
+ Editing can be turned off on a per-column basis with the `enableEditing` column option.
61
+
62
+ ```jsx
63
+ const columns = [
64
+ {
65
+ accessorKey: 'age',
66
+ header: 'Age',
67
+ enableEditing: false,
68
+ },
69
+ ];
70
+ ```
71
+
72
+ In the modal editing mode, a disabled text field will still be rendered for columns with editing disabled, but in the row, cell, and table editing modes, normal cell values will be rendered instead of text fields.
73
+
74
+ If you want to completely remove an editing textfield from the editing modal or render the normal cell value instead, you can use the `Edit` column option to override the editing UI for that column.
75
+
76
+ ```jsx
77
+ const columns = [
78
+ {
79
+ accessorKey: 'age',
80
+ header: 'Age',
81
+ enableEditing: false,
82
+ Edit: () => null, //don't render anything in the editing modal for this column
83
+ //or Edit: ({ cell, renderedCellValue }) => <>{renderedCellValue}</>, //render the normal cell value instead of a text field
84
+ },
85
+ ];
86
+ ```
87
+
88
+ ### Edit Display Modes
89
+
90
+ There are five different editDisplayModes to choose from. The default is `"modal"`, but you can also choose `"row"`, `"cell"`, `"table"`, or `"custom"`.
91
+
92
+ #### Modal Edit Display Mode
93
+
94
+ When using the default `"modal"` editDisplayMode, the user will be presented with a modal dialog where they can edit the data for one row at a time. No data is saved until the user clicks the save button. Clicking the cancel button clears out any changes that were made on that row.
95
+
96
+ An `onEditingRowSave` callback function prop must be provided where you will get access to the updated row data so that changes can be processed and saved. It is up to you how you handle the data. This function has a `exitEditingMode` parameter that must be called in order to exit editing mode upon save. The reason for this is so that you can perform validation checks before letting the modal close.
97
+
98
+ By default, Material React Table will render all of the cells in the row as text fields in a vertical stack. You can customize or override this behavior with the `muiEditRowDialogProps` table option, or the `renderEditRowDialogContent` table option.
99
+
100
+ ```jsx
101
+ const table = useMaterialReactTable({
102
+ columns,
103
+ data,
104
+ enableEditing: true,
105
+ editDisplayMode: 'modal', //default
106
+ onEditingRowSave: ({ table, values }) => {
107
+ //validate data
108
+ //save data to api
109
+ table.setEditingRow(null); //exit editing mode
110
+ },
111
+ onEditingRowCancel: () => {
112
+ //clear any validation errors
113
+ },
114
+ muiEditRowDialogProps: {
115
+ //optionally customize the dialog
116
+ },
117
+ renderEditRowDialogContent: ({ internalEditComponents, row, table }) => {
118
+ //optionally, completely override the render of the dialog content
119
+ //use `internalEditComponents` to render the generated text fields, or completely render your own form and inputs
120
+ },
121
+ });
122
+ ```
123
+
124
+ #### Row Edit Display Mode
125
+
126
+ The `"row"` editDisplayMode works just like the default `"modal"` editDisplayMode, except that the editing components will render inline in the table instead of in a modal dialog. Only one row is made editable at a time.
127
+
128
+ By default, you will probably not want to save any data until the user clicks the save button, though you could wire up `onChange` or `onBlur` events to save data as the user inputs data.
129
+
130
+ ```jsx
131
+ const table = useMaterialReactTable({
132
+ columns,
133
+ data,
134
+ enableEditing: true,
135
+ editDisplayMode: 'row',
136
+ onEditingRowSave: ({ table, values }) => {
137
+ //validate data
138
+ //save data to api
139
+ table.setEditingRow(null); //exit editing mode
140
+ },
141
+ onEditingRowCancel: () => {
142
+ //clear any validation errors
143
+ },
144
+ });
145
+ ```
146
+
147
+ #### Cell Edit Display Mode
148
+
149
+ The `"cell"` editDisplayMode is a bit simpler visually. By default, a user can double-click a cell to activate editing mode, but only for that cell.
150
+
151
+ Then there is a bit of work for you to do to wire up either the `onBlur`, `onChange`, etc., events yourself in order to save the table data. This can be done in the `muiEditTextFieldProps` table option or column definition option.
152
+
153
+ ```jsx
154
+ const columns = [
155
+ {
156
+ accessor: 'age',
157
+ header: 'Age',
158
+ muiEditTextFieldProps: ({ cell, row, table }) => ({
159
+ onBlur: (event) => {
160
+ //validate data
161
+ //save data to api and/or rerender table
162
+ // table.setEditingCell(null) is called automatically onBlur internally
163
+ },
164
+ }),
165
+ },
166
+ ];
167
+
168
+ const table = useMaterialReactTable({
169
+ columns,
170
+ data,
171
+ enableEditing: true,
172
+ editDisplayMode: 'cell',
173
+ //optionally, use single-click to activate editing mode instead of default double-click
174
+ muiTableBodyCellProps: ({ cell, column, table }) => ({
175
+ onClick: () => {
176
+ table.setEditingCell(cell); //set editing cell
177
+ //optionally, focus the text field
178
+ queueMicrotask(() => {
179
+ const textField = table.refs.editInputRefs.current?.[column.id];
180
+ if (textField) {
181
+ textField.focus();
182
+ textField.select?.();
183
+ }
184
+ });
185
+ },
186
+ }),
187
+ });
188
+ ```
189
+
190
+ #### Table Edit Display Mode
191
+
192
+ The `"table"` editDisplayMode is similar to the `"cell"` editDisplayMode, but it simply has all of the data cells in the table become editable all at once. You will most likely wire up all of the logic the same way as the `"cell"` editDisplayMode.
193
+
194
+ #### Custom Edit Display Mode
195
+
196
+ There is another option if you don't like any of the built-in editDisplayModes UI. If you want to completely handle your own editing UI, you can use the `"custom"` editDisplayMode. This will give you access to the `editingCell`, `editingRow`, and `creatingRow` state options, but MRT will not render any editing UI for you. This is common for rendering a form in a sidebar or similar.
197
+
198
+ ### Enable Creating
199
+
200
+ > New in V3
201
+
202
+ Material React Table offers new functionality to make creating news rows of data easier. It works just like the editing features, but with separate state options and callbacks. A Blank row is added to the table or modal for the user to fill out and submit.
203
+
204
+ #### Create Display Modes
205
+
206
+ There are just three different createDisplayModes to choose from. The default is `"modal"`, but you can also choose `"row"` or `"custom"`. They work exactly the same as their editDisplayMode counterparts.
207
+
208
+ #### Position Creating Row
209
+
210
+ > New in v2.7
211
+
212
+ By default, the creating row will be added to the top of the table. You can change this behavior with the `positionCreatingRow` table option.
213
+
214
+ ```jsx
215
+ const table = useMaterialReactTable({
216
+ columns,
217
+ data,
218
+ enableEditing: true,
219
+ createDisplayMode: 'modal',
220
+ positionCreatingRow: 'bottom', //default is 'top'
221
+ });
222
+ ```
223
+
224
+ In advanced use cases, such as editing nested expanding sub-rows, you could even pass in a number to the `positionCreatingRow` table option to specify the index of the row to insert the creating row before.
225
+
226
+ #### Trigger Create Mode
227
+
228
+ To trigger a new blank row to be added to the table, we just need to just populate the `creatingRow` state option with a new blank row. This can be done with the `table.setCreatingRow` table instance API. You can either pass in `true` as an argument, or pass in row object with default values.
229
+
230
+ ```jsx
231
+ const table = useMaterialReactTable({
232
+ columns,
233
+ data,
234
+ enableEditing: true,
235
+ editDisplayMode: 'modal',
236
+ createDisplayMode: 'modal',
237
+ onCreatingRowSave: ({ table, values }) => {
238
+ //validate data
239
+ //save data to api
240
+ table.setCreatingRow(null); //exit creating mode
241
+ },
242
+ onCreatingRowCancel: () => {
243
+ //clear any validation errors
244
+ },
245
+ renderTopToolbarCustomActions: ({ table }) => (
246
+ <Button
247
+ onClick={() => {
248
+ table.setCreatingRow(true); //simplest way to open the create row modal with no default values
249
+ //or you can pass in a row object to set default values with the `createRow` helper function
250
+ // table.setCreatingRow(
251
+ // createRow(table, {
252
+ // //optionally pass in default values for the new row, useful for nested data or other complex scenarios
253
+ // }),
254
+ // );
255
+ }}
256
+ >
257
+ Create New User
258
+ </Button>
259
+ ),
260
+ });
261
+ ```
262
+
263
+ ### CRUD Examples
264
+
265
+ > Live examples: `editing-crud-modal`, `editing-crud-row`, `editing-crud-cell`, `editing-crud-table`, `editing-crud-tree` (call get_mrt_example with an id).
266
+
267
+ ### Customizing Editing Components
268
+
269
+ You can pass any Material UI TextField Props with the `muiEditTextFieldProps` table option.
270
+
271
+ ```jsx
272
+ const columns = [
273
+ {
274
+ accessor: 'age',
275
+ header: 'Age',
276
+ muiEditTextFieldProps: {
277
+ required: true,
278
+ type: 'number',
279
+ variant: 'outlined',
280
+ },
281
+ },
282
+ ];
283
+ ```
284
+
285
+ #### Add Validation to Editing Components
286
+
287
+ You can add validation to the editing components by using the `muiEditTextFieldProps` events. You can write your validation logic and hook it up to the `onBlur`, `onChange`, etc., events, then set the `error` and `helperText` props accordingly.
288
+
289
+ If you are implementing validation, you may also need to use the `onEditingRowCancel` table option to clear the validation error state.
290
+
291
+ ```jsx
292
+ const [validationErrors, setValidationErrors] = useState({});
293
+
294
+ const columns = [
295
+ {
296
+ accessor: 'age',
297
+ header: 'Age',
298
+ muiEditTextFieldProps: {
299
+ error: !!validationErrors.age, //highlight mui text field red error color
300
+ helperText: validationErrors.age, //show error message in helper text.
301
+ required: true,
302
+ type: 'number',
303
+ onChange: (event) => {
304
+ const value = event.target.value;
305
+ //validation logic
306
+ if (!value) {
307
+ setValidationErrors((prev) => ({ ...prev, age: 'Age is required' }));
308
+ } else if (value < 18) {
309
+ setValidationErrors({
310
+ ...validationErrors,
311
+ age: 'Age must be 18 or older',
312
+ });
313
+ } else {
314
+ delete validationErrors.age;
315
+ setValidationErrors({ ...validationErrors });
316
+ }
317
+ },
318
+ },
319
+ },
320
+ ];
321
+ ```
322
+
323
+ ### Use Custom Editing Components
324
+
325
+ If you need to use a much more complicated Editing component than the built-in textfield, you can specify a custom editing component with the `Edit` column definition option.
326
+
327
+ ```tsx
328
+ const columns = [
329
+ {
330
+ accessorKey: 'email',
331
+ header: 'Email',
332
+ Edit: ({ cell, column, row, table }) => {
333
+ const onBlur = (event) => {
334
+ row._valuesCache[column.id] = event.target.value;
335
+ if (isCreating) {
336
+ setCreatingRow(row);
337
+ } else if (isEditing) {
338
+ setEditingRow(row);
339
+ }
340
+ };
341
+
342
+ return <CustomInput onBlur={onBlur} />;
343
+ },
344
+ },
345
+ ];
346
+ ```
347
+
348
+ ### Customize Actions/Edit Column
349
+
350
+ You can customize the actions column in a few different ways in the `displayColumnDefOptions` prop's `'mrt-row-actions'` section.
351
+
352
+ ```jsx
353
+ const table = useMaterialReactTable({
354
+ columns,
355
+ data,
356
+ displayColumnDefOptions: {
357
+ 'mrt-row-actions': {
358
+ header: 'Edit', //change "Actions" to "Edit"
359
+ size: 120,
360
+ //use a text button instead of a icon button
361
+ Cell: ({ row, table }) => (
362
+ <Button onClick={() => table.setEditingRow(row)}>Edit Customer</Button>
363
+ ),
364
+ },
365
+ },
366
+ });
367
+ ```
@@ -0,0 +1,194 @@
1
+ ## Expanding Sub-Rows (Tree Data) Feature Guide
2
+
3
+ Material React Table has support for expanding sub-rows or tree data. This feature is useful for displaying hierarchical data. The sub-rows can be expanded and collapsed by clicking on the expand/collapse icon.
4
+
5
+ > NOTE: This feature is for expanding rows of the same data type. If you want to add expansion of more data for the same row, check out the [Detail Panel Feature Guide](/docs/guides/detail-panel).
6
+
7
+ ### Relevant Table Options
8
+
9
+ Relevant table options (get_mrt_api has full details):
10
+
11
+ - `autoResetExpanded` - type `boolean` - Enable this setting to automatically reset the expanded state of the table when grouping state changes.
12
+ - `data` - type `Array<TData>` - The data for the table to display. This can be an array of anything, but you will need to set up your column definitions to "access" the data. When the data option changes reference (compared via Object.is), the table will reprocess the data. Any other data processing that relies on the core data model (such as grouping, sorting, filtering, etc) will also be reprocessed.
13
+ - `enableExpandAll` - type `boolean` - default `true`
14
+ - `enableExpanding` - type `boolean`
15
+ - `expandRowsFn` - type `(dataRow: TData) => TData[]`
16
+ - `filterFromLeafRows` - type `boolean` - default `false`
17
+ - `getIsRowExpanded` - type `(row: Row<TData>) => boolean` - If provided, allows you to override the default behavior of determining whether a row is currently expanded.
18
+ - `getRowCanExpand` - type `(row: Row<TData>) => boolean` - If provided, allows you to override the default behavior of determining whether a row can be expanded.
19
+ - `getRowId` - type `(originalRow: TData, index: number, parent?: MRT_Row<TData>) => string` - This optional function is used to derive a unique ID for any given row. If not provided the rows index is used (nested rows join together with . using their grandparents' index eg. index.index.index). If you need to identify individual rows that are originating from any server-side operations, it's suggested you use this function to return an ID that makes sense regardless of network IO/ambiguity eg. a userId, taskId, database ID field, etc.
20
+ - `getSubRows` - type `(originalRow: TData, index: number) => undefined | TData[]` - This optional function is used to access the sub rows for any given row. If you are using nested rows, you will need to use this function to return the sub rows object (or undefined) from the row.
21
+ - `groupedColumnMode` - type `false | 'reorder' | 'remove'` - default `reorder` - Grouping columns are automatically reordered by default to the start of the columns list. If you would rather remove them or leave them as-is, set the appropriate mode here.
22
+ - `manualExpanding` - type `boolean` - Enables manual row expansion. If this is set to true, getExpandedRowModel will not be used to expand rows and you would be expected to perform the expansion in your own data model. This is useful if you are doing server-side expansion.
23
+ - `maxLeafRowFilterDepth` - type `number` - default `100` - Set a maximum number leaf row depth that will be filtered. Preserve child rows of filtered rows by setting this to "0"
24
+ - `muiExpandAllButtonProps` - type `IconButtonProps | ({ table }) => IconButtonProps`
25
+ - `muiExpandButtonProps` - type `IconButtonProps | ({ row, table }) => IconButtonProps`
26
+ - `onExpandedChange` - type `OnChangeFn<ExpandedState>` - This function is called when the expanded table state changes. If a function is provided, you will be responsible for managing this state on your own. To pass the managed state back to the table, use the tableOptions.state.expanded option.
27
+ - `paginateExpandedRows` - type `boolean` - If true expanded rows will be paginated along with the rest of the table (which means expanded rows may span multiple pages). If false expanded rows will not be considered for pagination (which means expanded rows will always render on their parents page. This also means more rows will be rendered than the set page size)
28
+ - `positionExpandColumn` - type `'first' | 'last'` - default `'first'`
29
+
30
+ ### Relevant State Options
31
+
32
+ Relevant state options (get_mrt_api has full details):
33
+
34
+ - `expanded` - type `Record<string, boolean> | boolean` - default `{}`
35
+
36
+ ### Enable Expanding Sub-Rows
37
+
38
+ To enable expanding sub-rows, you must first set the `enableExpanding` table option to `true`.
39
+
40
+ However, your data must also be formatted in a way to allow for expanding rows that are in some way related to each other. By default, Material React Table will look for a special `subRows` property on each row of your data and treat any array of rows that it finds as the sub-rows for that row. You can customize or override this behavior by passing a custom `getSubRows` table option.
41
+
42
+ ```jsx
43
+ const data = [
44
+ {
45
+ id: 1,
46
+ name: 'John Doe',
47
+ subRows: [
48
+ {
49
+ id: 2,
50
+ name: 'Jane Doe',
51
+ },
52
+ //more sub rows...
53
+ ],
54
+ },
55
+ //more rows...
56
+ ];
57
+
58
+ const table = useMaterialReactTable({
59
+ columns,
60
+ data,
61
+ enableExpanding: true,
62
+ getSubRows: (originalRow) => originalRow.subRows, //default, can customize
63
+ });
64
+
65
+ return <MaterialReactTable table={table} />;
66
+ ```
67
+
68
+ ### Expand All Rows Button
69
+
70
+ By default, Material React Table will show the expand all button in the expand column header. You can disable this by setting the `enableExpandAll` table option to `false`.
71
+
72
+ ```jsx
73
+ const table = useMaterialReactTable({
74
+ columns,
75
+ data,
76
+ enableExpanding: true,
77
+ enableExpandAll: false, //hide expand all button in header
78
+ });
79
+ ```
80
+
81
+ > Live example: `enable-expanding-tree` (call get_mrt_example with that id).
82
+
83
+ ### Generate Sub Rows with getSubRows
84
+
85
+ If your data is not yet in a tree structure, but the data has relationships that can be parsed into a tree, you can use the `getSubRows` table option to let TanStack Table find the sub rows for each row.
86
+
87
+ There are a couple key things you have to do to make this work:
88
+
89
+ 1. Only pass in root (top level) rows in your data prop.
90
+ 2. Set the `getSubRows` table option to a function that scans all the rest of your data and returns the sub rows for a given row.
91
+
92
+ This can sometimes be useful in combination with [lazy loading sub rows](#lazy-load-sub-rows).
93
+
94
+ > NOTE: Be conscious of the performance implications of the `getSubRows` function. It will be called for every row in your table, so it should be performant.
95
+
96
+ > Live example: `expanding-tree-flat-parse` (call get_mrt_example with that id).
97
+
98
+ ### Expanded Rows Pagination Behavior
99
+
100
+ By default, Material React Table will treat expanded sub-rows the same as any other row when it comes to pagination. This means that some expanded rows may be on the next page. You can change this behavior by setting the `paginateExpandedRows` table option to `false`.
101
+
102
+ ```jsx
103
+ const table = useMaterialReactTable({
104
+ columns,
105
+ data,
106
+ enableExpanding: true,
107
+ paginateExpandedRows: false, //expanded rows will be on the same page as their parent row
108
+ });
109
+ ```
110
+
111
+ ### Expanded Leaf Row Filtering Behavior
112
+
113
+ If you are using the [filtering features](/docs/guides/column-filtering) alongside sub-row features, then there are a few behaviors and customizations you should be aware of.
114
+
115
+ #### Filter From Leaf Rows
116
+
117
+ By default, filtering is done from parent rows down (so if a parent row is filtered out, all of its children will be filtered out as well). Setting the `filterFromLeafRows` table option to `true` will cause filtering to be done from leaf rows up (which means parent rows will be kept so long as one of their child, or grand-child, etc. rows pass the filtering).
118
+
119
+ ```jsx
120
+ const table = useMaterialReactTable({
121
+ columns,
122
+ data,
123
+ enableExpanding: true,
124
+ filterFromLeafRows: true, //search for child rows and preserve parent rows
125
+ });
126
+ ```
127
+
128
+ #### Max Leaf Row Filter Depth
129
+
130
+ By default, filtering is done for all rows (max depth of 100), no matter if they are root level parent rows or the child leaf rows of a parent row. Setting the `maxLeafRowFilterDepth` table option to `0` will cause filtering to only be applied to the root level parent rows, with all sub-rows remaining unfiltered. Similarly, setting this option to 1 will cause filtering to only be applied to child leaf rows 1 level deep, and so on.
131
+
132
+ This is useful for situations where you want a row's entire child hierarchy to be visible, regardless of the applied filter.
133
+
134
+ ```jsx
135
+ const table = useMaterialReactTable({
136
+ columns,
137
+ data,
138
+ enableExpanding: true,
139
+ maxLeafRowFilterDepth: 0, //When filtering root rows, keep all child rows of the passing parent rows
140
+ });
141
+ ```
142
+
143
+ ### Expand All Rows By Default
144
+
145
+ You can manage the initial state of the expanded rows with the `expanded` state option in either the `initialState` or `state` props.
146
+
147
+ For example, you may want all rows to be expanded by default. To do this, you can simply set the `expanded` state option to `true`.
148
+
149
+ ```jsx
150
+ const table = useMaterialReactTable({
151
+ columns,
152
+ data,
153
+ enableExpanding: true,
154
+ initialState: { expanded: true }, //all rows expanded by default
155
+ });
156
+ ```
157
+
158
+ > Live example: `expanding-tree-expanded` (call get_mrt_example with that id).
159
+
160
+ ### Expand Root Rows Only By Default
161
+
162
+ Here is a slightly more complex initial expanded state example where all the root rows are expanded by default, but none of the sub rows themselves are expanded by default. We just need to find all of the root row ids and set their key in the `expanded` `initialState` option to `true`.
163
+
164
+ > Live example: `expanding-tree-root-expanded` (call get_mrt_example with that id).
165
+
166
+ ### Customize Expand Column
167
+
168
+ You can customize the expand column by using the `displayColumnDefOptions` table option.
169
+
170
+ ```jsx
171
+ const table = useMaterialReactTable({
172
+ columns,
173
+ data,
174
+ enableGrouping: true,
175
+ displayColumnDefOptions: {
176
+ 'mrt-row-expand': {
177
+ enableResizing: true, //allow resizing
178
+ size: 120, //make the expand column wider
179
+ },
180
+ },
181
+ });
182
+ ```
183
+
184
+ ### Lazy Load Sub Rows
185
+
186
+ If you have a ton of nested data that you want to display, but you don't want to fetch it all up front, you can set up Material React Table to only fetch the sub-rows data when the user expands the row.
187
+
188
+ There are quite a few ways in which you could implement fetching sub-rows lazily. This example is just one way to do it.
189
+
190
+ The main concept to understand from this example is that you can manage the `expanded` state option in your own scope, and fetch the data for your table based on that state.
191
+
192
+ How your data is structured from the server is up to you. It is usually easiest to have the server do the hard work and return the data in a nested tree structure, but you can also return the data in a flat structure and use the `getSubRows` table option to parse the data into a tree structure.
193
+
194
+ > Live example: `lazy-sub-rows` (call get_mrt_example with that id).
@@ -0,0 +1,63 @@
1
+ ## Full Screen Toggle Feature Guide
2
+
3
+ ### Relevant Table Options
4
+
5
+ Relevant table options (get_mrt_api has full details):
6
+
7
+ - `enableFullScreenToggle` - type `boolean` - default `true` - Enable or disable the full screen toggle feature. Disabling will also hide the full screen toggle button.
8
+ - `muiTablePaperProps` - type `PaperProps | ({ table }} => PaperProps`
9
+ - `onIsFullScreenChange` - type `OnChangeFn<boolean>`
10
+
11
+ ### Relevant State
12
+
13
+ Relevant state options (get_mrt_api has full details):
14
+
15
+ - `isFullScreen` - type `boolean` - default `false`
16
+
17
+ ### Disable Full Screen Toggle
18
+
19
+ The full screen toggle button is enabled by default. You can hide it by setting the `enableFullScreenToggle` table option to `false`.
20
+
21
+ ```jsx
22
+ const table = useMaterialReactTable({
23
+ columns,
24
+ data,
25
+ enableFullScreenToggle: false,
26
+ });
27
+
28
+ return <MaterialReactTable table={table} />;
29
+ ```
30
+
31
+ ### Change Z-Index of Full Screen Table
32
+
33
+ Under the hood in Material React Table V3, when the table is full screen, these `styles` are applied to the root mui paper component:
34
+
35
+ ```jsx
36
+ {
37
+ bottom: 0,
38
+ height: '100vh',
39
+ left: 0,
40
+ margin: 0,
41
+ maxHeight: '100vh',
42
+ maxWidth: '100vw',
43
+ padding: 0,
44
+ position: 'fixed',
45
+ right: 0,
46
+ top: 0,
47
+ width: '100vw',
48
+ zIndex: 999,
49
+ }
50
+ ```
51
+
52
+ If you need to change the `zIndex` of the full screen table, you can do so by passing in a `muiTablePaperProps` table option with a `style` object that has a `zIndex` property.
53
+
54
+ ```jsx
55
+ muiTablePaperProps: ({ table }) => ({
56
+ //not sx
57
+ style: {
58
+ zIndex: table.getState().isFullScreen ? 1000 : undefined,
59
+ },
60
+ });
61
+ ```
62
+
63
+ > Note: The `sx` table option will not work here because the `style` table option was used internally instead of the `sx` table option for higher specificity.