+
+The `` is a `` element that surrounds the cell value or custom `Cell` render.
+
+##### \
+
+Renders the value of a cell. This is a popular component to use as an alternative to TanStack Table's `flexRender` method. It renders everything inside of the `| `, but not the ` | ` itself.
+
+##### \
+
+A button for grabbing a row for dragging.
+
+##### \
+
+A button or buttons for pinning a row.
+
+#### TableFooter Components
+
+[View TableFooter Components Source Code on GitHub](https://github.com/KevinVandy/material-react-table/tree/v2/packages/material-react-table/src/components/footer)
+
+##### \
+
+The `` component contains the `` element, and all of the table footer rows.
+
+##### \
+
+The `` is a `` element that contains all of the table footer cells in a row.
+
+##### \
+
+The `` is a `` element that surrounds the cell value or custom `Footer` render.
+
+#### Input Components
+
+[View Input Components Source Code on GitHub](https://github.com/KevinVandy/material-react-table/tree/v2/packages/material-react-table/src/components/inputs)
+
+##### \
+
+The textfield component for editing a cell value that can either show in a modal or table cell.
+
+##### \
+
+The search textfield component for global filtering.
+
+##### \
+
+The textfield component for filtering a column. A somewhat comprehensive component that can be a textfield, select, multi-select, or date picker.
+
+##### \
+
+The checkbox component for filtering a column by boolean values.
+
+##### \
+
+The range slider component for filtering a column by a range of numbers.
+
+##### \
+
+A Container component that will render two MRT_FilterTextField components for filtering in a range (min and max).
+
+##### \
+
+A checkbox component for selecting a row or selecting all rows from the table header.
diff --git a/apps/material-react-table-docs/pages/docs/api/mrt-hooks.mdx b/apps/material-react-table-docs/pages/docs/api/mrt-hooks.mdx
new file mode 100644
index 000000000..79b572ab0
--- /dev/null
+++ b/apps/material-react-table-docs/pages/docs/api/mrt-hooks.mdx
@@ -0,0 +1,153 @@
+import Head from 'next/head';
+import OptionsSwitcher from '../../../example-groups/OptionsSwitcher';
+
+
+ {'MRT Hooks - Material React Table V2 Docs'}
+
+
+
+
+
+## MRT Hooks
+
+
+
+
+
+MRT has been adopting more and more of a hooks based approach for its internal logic. Its API is becoming more standardized so that you can use the same hooks that the MRT components use internally to build your own custom headless table if you want to.
+
+### useMaterialReactTable
+
+[Source Code](https://github.com/KevinVandy/material-react-table/blob/v2/packages/material-react-table/src/hooks/useMaterialReactTable.ts)
+
+> This is probably the only MRT hook you will need to use, unless you are writing a custom headless table.
+
+This is the main hook from Material React Table. It creates a TanStack Table instance with all of the features that MRT provides and that you enable, and uses the proper default table options.
+
+```tsx
+import { useMaterialReactTable } from 'material-react-table';
+
+const table = useMaterialReactTable({
+ ...options,
+});
+```
+
+This hook is the combination of 2 other internal MRT hooks: [`useMRT_TableOptions`](#usemrt_tableoptions), and [`useMRT_TableInstance`](#usemrt_tableinstance).
+
+### useMRT_TableOptions
+
+[Source Code](https://github.com/KevinVandy/material-react-table/blob/v2/packages/material-react-table/src/hooks/useMRT_TableOptions.ts)
+
+This hook simply takes in your custom table options and merges them with the default table options. It also does some extra logic to make sure that some default table options are set correctly based on other enabled features. For example, if you enable row virtualization features, the sticky header will also be enabled by default, and the layoutMode will adjust accordingly.
+
+```tsx
+import { useMRT_TableOptions } from 'material-react-table';
+
+const transformedTableOptions = useMRT_TableOptions({
+ ...options,
+});
+```
+
+### useMRT_TableInstance
+
+[Source Code](https://github.com/KevinVandy/material-react-table/blob/v2/packages/material-react-table/src/hooks/useMRT_TableInstance.ts)
+
+This is where most of the magic happens. This hook is responsible for creating the TanStack Table instance, and adding all of the MRT features to it. It needs table options to be passed in to it correctly, with good defaults, and it will return the table instance.
+
+```tsx
+import { useMRT_TableInstance } from 'material-react-table';
+
+const table = useMRT_TableInstance({
+ ...transformedTableOptions, //usually from useMRT_TableOptions
+});
+```
+
+This hook also uses the [`useMRT_Effects`](#usemrt_effects)
+
+### useMRT_Effects
+
+[Source Code](https://github.com/KevinVandy/material-react-table/blob/v2/packages/material-react-table/src/hooks/useMRT_Effects.ts)
+
+This hook is responsible for adding some extra useEffect hooks to the table instance. These hooks are needed by some MRT features on a table wide level.
+
+### useMRT_Rows
+
+> New in v2.2.0
+
+[Source Code](https://github.com/KevinVandy/material-react-table/blob/v2/packages/material-react-table/src/hooks/useMRT_Rows.ts)
+
+This hook is mostly a wrapper around `table.getRowModel`, but with a bit more custom logic for fuzzy ranking, row pinning, and more. It consumes a `table` instance and returns the rows that should be rendered in the main table body. This can be a useful hook if you are writing a custom headless table, but still want all of the extra MRT enhanced behavior for fuzzy ranking, row pinning, etc. Alternatively, you can just use `table.getRowModel()` for a more vanilla TanStack Table experience.
+
+```tsx
+import { useMaterialReactTable, useMRT_Rows } from 'material-react-table';
+
+const table = useMaterialReactTable({
+ ...options,
+});
+
+const rows = useMRT_Rows(table);
+
+return rows.map((row) => {
+ //render row
+});
+```
+
+### useMRT_ColumnVirtualizer
+
+> New in v2.2.0
+
+[Source Code](https://github.com/KevinVandy/material-react-table/blob/v2/packages/material-react-table/src/hooks/useMRT_ColumnVirtualizer.ts)
+
+This hook is a wrapper around the `useVirtualizer` hook from TanStack Virtual. It consumes a `table` instance and returns a Column Virtualizer instance that is optimized for MRT table columns, with considerations for other MRT features like column pinning, column resizing, column hiding, and more.
+
+```tsx
+import {
+ useMaterialReactTable,
+ useMRT_ColumnVirtualizer,
+} from 'material-react-table';
+
+const table = useMaterialReactTable({
+ ...options,
+});
+
+const columnVirtualizer = useMRT_ColumnVirtualizer(table);
+```
+
+You would only need to use this hook if you are writing a custom headless table and want the same default column virtualization behavior that MRT provides. If you are using the MRT components, this hook is already used internally by the `MRT_Table` component.
+
+### useMRT_RowVirtualizer
+
+> New in v2.2.0
+
+[Source Code](https://github.com/KevinVandy/material-react-table/blob/v2/packages/material-react-table/src/hooks/useMRT_RowVirtualizer.ts)
+
+This hook is a wrapper around the `useVirtualizer` hook from TanStack Virtual. It consumes a `table` instance and returns a Row Virtualizer instance that is optimized for MRT table rows, with considerations for other MRT features like row pinning, row dragging, and more.
+
+```tsx
+import {
+ useMaterialReactTable,
+ useMRT_RowVirtualizer,
+} from 'material-react-table';
+
+const table = useMaterialReactTable({
+ ...options,
+});
+
+const rowVirtualizer = useMRT_RowVirtualizer(table);
+```
+
+You would only need to use this hook if you are writing a custom headless table and want the same default row virtualization behavior that MRT provides. If you are using the MRT components, this hook is already used internally by the `MRT_Table` component.
diff --git a/apps/material-react-table-docs/pages/docs/api/row-instance-apis.mdx b/apps/material-react-table-docs/pages/docs/api/row-instance-apis.mdx
index 57210021e..3b7f57cbb 100644
--- a/apps/material-react-table-docs/pages/docs/api/row-instance-apis.mdx
+++ b/apps/material-react-table-docs/pages/docs/api/row-instance-apis.mdx
@@ -1,9 +1,10 @@
import Head from 'next/head';
import RowInstanceAPIsTable from '../../../components/prop-tables/RowInstanceAPIsTable';
import SourceCode from '../../../components/prop-tables/RowInstanceAPIsSource';
+import OptionsSwitcher from '../../../example-groups/OptionsSwitcher';
- Row Instance APIs - Material React Table V2 Docs
+ {'Row Instance APIs - Material React Table V2 Docs'}
+
+> NOTE: These are NOT [props](/docs/api/props) or [column options](/docs/api/column-options) for Material React Table. These are just static methods on a row instance that you can use.
+
Every row in the table has an associated row instance that can be accessed in many of the callback props that you can use to access a row's information and methods.
You can access and use a `row` object in quite a few places, but here are some of the most common:
@@ -44,25 +68,23 @@ const columns = [
},
];
-return (
- ({
- disabled: row.original.isAccountActive === false,
- })}
- renderDetailPanel={({ row }) => (
-
- First Name: {row.original.firstName}
- Last Name: {row.original.lastName}
-
- )}
- />
-);
+const table = useMaterialReactTable({
+ columns,
+ data,
+ //or a row instance in callback props like this
+ muiSelectCheckboxProps: ({ row }) => ({
+ disabled: row.original.isAccountActive === false,
+ }),
+ renderDetailPanel: ({ row }) => (
+
+ First Name: {row.original.firstName}
+ Last Name: {row.original.lastName}
+
+ ),
+});
```
-> NOTE: These are NOT [props](/docs/api/props) or [column options](/docs/api/column-options) for Material React Table. These are just static methods on a row instance that you can use.
+
diff --git a/apps/material-react-table-docs/pages/docs/api/state-options.mdx b/apps/material-react-table-docs/pages/docs/api/state-options.mdx
index 87a9b1365..70a8d08ec 100644
--- a/apps/material-react-table-docs/pages/docs/api/state-options.mdx
+++ b/apps/material-react-table-docs/pages/docs/api/state-options.mdx
@@ -1,9 +1,10 @@
import Head from 'next/head';
import StateOptionsTable from '../../../components/prop-tables/StateOptionsTable';
import SourceCode from '../../../components/prop-tables/StateOptionsSource';
+import OptionsSwitcher from '../../../example-groups/OptionsSwitcher';
- State Options - Material React Table V2 Docs
+ {'State Options - Material React Table V2 Docs'}
+
> Many of the state options you can pass here are the same as the ones you can pass to the [useReactTable](https://tanstack.com/table/v8/docs/api/core/table) useTableInstance hook.
Here is a list of all the state options you can pass to `initialState` or `state`.
-```tsx
-
+```jsx
+const table = useMaterialReactTable({
+ columns,
+ data,
+ //note: each individual state must be mutually exclusive to `initial state` or `state`
+ initialState: {
+ // all the state options you can pass here
+ },
+ state: {
+ // or here
+ },
+});
```
diff --git a/apps/material-react-table-docs/pages/docs/api/table-instance-apis.mdx b/apps/material-react-table-docs/pages/docs/api/table-instance-apis.mdx
index 5b2d155a5..02cd9a8e9 100644
--- a/apps/material-react-table-docs/pages/docs/api/table-instance-apis.mdx
+++ b/apps/material-react-table-docs/pages/docs/api/table-instance-apis.mdx
@@ -1,9 +1,10 @@
import Head from 'next/head';
import TableInstanceAPIsTable from '../../../components/prop-tables/TableInstanceAPIsTable';
import SourceCode from '../../../components/prop-tables/TableInstanceAPIsSource';
+import OptionsSwitcher from '../../../example-groups/OptionsSwitcher';
- Table Instance APIs - Material React Table V2 Docs
+ {'Table Instance APIs - Material React Table V2 Docs'}
-You can access this table instance yourself by either setting up a `tableInstanceRef` or by consuming a `table` param from many of the callback functions in many of the props.
+> NOTE: These are NOT the [table options](/docs/api/table-options) for Material React Table. These are just static methods on a table instance that you can use.
+
+These are the methods available on the `table` instance that is returned from the `useMaterialReactTable` hook. You can use these methods to interact with the table instance.
```jsx
const columns = useMemo(() => [
@@ -46,8 +68,6 @@ const someEventHandler = () => {
return ;
```
-> NOTE: These are NOT the [table options](/docs/api/table-options) for Material React Table. These are just static methods on a table instance that you can use.
-
diff --git a/apps/material-react-table-docs/pages/docs/api/table-options.mdx b/apps/material-react-table-docs/pages/docs/api/table-options.mdx
index 62ea82cdd..f35e6d66c 100644
--- a/apps/material-react-table-docs/pages/docs/api/table-options.mdx
+++ b/apps/material-react-table-docs/pages/docs/api/table-options.mdx
@@ -1,9 +1,10 @@
import Head from 'next/head';
import TableOptionsTable from '../../../components/prop-tables/TableOptionsTable';
import SourceCode from '../../../components/prop-tables/TableOptionsSource';
+import OptionsSwitcher from '../../../example-groups/OptionsSwitcher';
- Table Options - Material React Table V2 Docs
+ {'Table Options - Material React Table V2 Docs'}
+
> Many of the options you can pass to `useMaterialReactTable` are the same as the ones you can pass to the TanStack Table [useReactTable](https://tanstack.com/table/v8/docs/api/core/table) hook.
Here is a list of all the table options that you can pass to the `useMaterialReactTable` hook.
```jsx
const table = useMaterialReactTable({
- // all the options that you can pass here
+ // all the options that you can pass here (recommended)
});
-//Note: you can also pass table options directly to the MaterialReactTable component instead of the useMaterialReactTable hook
-//But this will not be encouraged as it will be deprecated in the future
-return ;
+//or all of the props that could be passed to `` IF not using `useMaterialReactTable` hook
+return (
+
+);
+
+return ; //recommended
```
diff --git a/apps/material-react-table-docs/pages/docs/examples/aggregation-and-grouping.mdx b/apps/material-react-table-docs/pages/docs/examples/aggregation-and-grouping.mdx
index f15ba55cc..c5d0913ca 100644
--- a/apps/material-react-table-docs/pages/docs/examples/aggregation-and-grouping.mdx
+++ b/apps/material-react-table-docs/pages/docs/examples/aggregation-and-grouping.mdx
@@ -17,7 +17,7 @@ import Examples from '../../../example-groups/ExpandingExamples';
/>
-## Aggregation and Grouping Example
+## Aggregation Example
Grouping and Aggregation features are usually hard to implement, but MRT (thanks to [TanStack Table](https://tanstack.com/table/v8/docs/api/features/grouping)) makes it easy. Once enabled, simply click the vertical ellipses (⋮) icon for the column you want to group by and select **Group by (column name)**.
@@ -25,6 +25,8 @@ You can group by a single column or multiple columns at a time. Then, you can ru
The Grouping and Aggregation features work hand in hand with the Expanding and Sorting features. Try grouping by various columns in the example below and sorting by the aggregated columns, such as "age" or "salary".
+See the [Column Grouping](/docs/features/column-grouping) and [Aggregation](/docs/features/aggregation) docs for more information.
+
View Extra Storybook **[Examples](https://www.material-react-table.dev/?path=/story/features-aggregation-examples)**
diff --git a/apps/material-react-table-docs/pages/docs/examples/chart-detail-panel.mdx b/apps/material-react-table-docs/pages/docs/examples/chart-detail-panel.mdx
new file mode 100644
index 000000000..6666425dc
--- /dev/null
+++ b/apps/material-react-table-docs/pages/docs/examples/chart-detail-panel.mdx
@@ -0,0 +1,28 @@
+import Head from 'next/head';
+import Examples from '../../../example-groups/ExpandingExamples';
+
+
+ {'Chart Detail Panel Example - Material React Table V2 Docs'}
+
+
+
+
+
+## Chart Detail Panel Example
+
+The detail panel features can be used for a variety of purposes. In this example, we are integrating the new [MUI X Charts](https://mui.com/x/react-charts/getting-started/) library to display an expandable line chart for each row.
+
+You could, of course, use any charting library that you prefer, but using MUI X Charts will give you a consistent look and feel with Material React Table and any other Material UI components you may be using.
+
+
+
+View Extra Storybook **[Examples](https://www.material-react-table.dev/?path=/story/features-aggregation-examples)**
diff --git a/apps/material-react-table-docs/pages/docs/examples/column-grouping.mdx b/apps/material-react-table-docs/pages/docs/examples/column-grouping.mdx
new file mode 100644
index 000000000..dd79684a0
--- /dev/null
+++ b/apps/material-react-table-docs/pages/docs/examples/column-grouping.mdx
@@ -0,0 +1,23 @@
+import Head from 'next/head';
+import Examples from '../../../example-groups/ExpandingExamples';
+
+
+ {'Column Grouping Example - Material React Table V2 Docs'}
+
+
+
+
+
+## Column Grouping Example
+
+Material React Table has a few different UI options and behaviors for displaying grouped columns. See the [Column Grouping Guide](/docs/guides/column-grouping) to learn more.
+
+
+
+View Extra Storybook **[Examples](https://www.material-react-table.dev/?path=/story/features-column-grouping-examples)**
diff --git a/apps/material-react-table-docs/pages/docs/examples/column-ordering.mdx b/apps/material-react-table-docs/pages/docs/examples/column-ordering.mdx
new file mode 100644
index 000000000..b576fe8a2
--- /dev/null
+++ b/apps/material-react-table-docs/pages/docs/examples/column-ordering.mdx
@@ -0,0 +1,26 @@
+import Head from 'next/head';
+import Examples from '../../../example-groups/DraggingExamples';
+
+
+ {'Column DnD Ordering Example - Material React Table V2 Docs'}
+
+
+
+
+
+## Column DnD Ordering Example
+
+Material React Table has built-in support for column drag and drop re-ordering. Learn more about column ordering in the [Column Ordering Feature Guide](/docs/guides/column-ordering-dnd).
+
+
+
+View Extra Storybook **[Examples](https://www.material-react-table.dev/?path=/story/prop-playground--default)**
diff --git a/apps/material-react-table-docs/pages/docs/examples/column-pinning.mdx b/apps/material-react-table-docs/pages/docs/examples/column-pinning.mdx
index 4980d3d93..2155e5588 100644
--- a/apps/material-react-table-docs/pages/docs/examples/column-pinning.mdx
+++ b/apps/material-react-table-docs/pages/docs/examples/column-pinning.mdx
@@ -16,7 +16,7 @@ import Examples from '../../../example-groups/StickyPinningExamples';
## Column Pinning Example
-Material React Table easily has an easy to enable column pinning feature. Columns can be pinned to the left or right of the table, and the will be frozen in place while the rest of the table scrolls horizontally. See the [Column Pinning Feature Guide](/docs/guides/column-pinning) for more information.
+Material React Table has an easy-to-enable column pinning feature. Columns can be pinned to the left or right of the table, and the column will be frozen in place while the rest of the table scrolls horizontally. See the [Column Pinning Feature Guide](/docs/guides/column-pinning) for more information.
diff --git a/apps/material-react-table-docs/pages/docs/examples/column-virtualization.mdx b/apps/material-react-table-docs/pages/docs/examples/column-virtualization.mdx
index 4aee2f2f2..6591cec26 100644
--- a/apps/material-react-table-docs/pages/docs/examples/column-virtualization.mdx
+++ b/apps/material-react-table-docs/pages/docs/examples/column-virtualization.mdx
@@ -19,7 +19,7 @@ import Examples from '../../../example-groups/VirtualizedExamples';
## Column Virtualization Example
-Material React Table has a built-in column virtualization feature (via [`@tanstack/react-virual`](https://tanstack.com/virtual/v3)) that allows you to render a large number of columns without major performance issues that you would normally see with a large number of DOM elements.
+Material React Table has a built-in column virtualization feature (via [`@tanstack/react-virtual`](https://tanstack.com/virtual/v3)) that allows you to render a large number of columns without major performance issues that you would normally see with a large number of DOM elements.
Try out the performance of the table below with **500 columns**! Filtering, Search, and Sorting also maintain usable performance.
diff --git a/apps/material-react-table-docs/pages/docs/examples/custom-filter-ui.mdx b/apps/material-react-table-docs/pages/docs/examples/custom-filter-ui.mdx
new file mode 100644
index 000000000..bb38e966c
--- /dev/null
+++ b/apps/material-react-table-docs/pages/docs/examples/custom-filter-ui.mdx
@@ -0,0 +1,26 @@
+import Head from 'next/head';
+import Examples from '../../../example-groups/FilteringExamples';
+
+
+ {'Custom Filter UI Example - Material React Table V2 Docs'}
+
+
+
+
+
+## Custom Filter UI Example
+
+Material React Table supports rendering your own custom filter UI. This can be useful if you want to render your filters in a custom top toolbar, sidebar, or drawer. Learn more in the full [Column Filtering Feature Guide](/docs/guides/column-filtering).
+
+
+
+View Extra Storybook **[Examples](https://www.material-react-table.dev/?path=/story/prop-playground--default)**
diff --git a/apps/material-react-table-docs/pages/docs/examples/customized-grouping.mdx b/apps/material-react-table-docs/pages/docs/examples/customized-grouping.mdx
new file mode 100644
index 000000000..f995d05fe
--- /dev/null
+++ b/apps/material-react-table-docs/pages/docs/examples/customized-grouping.mdx
@@ -0,0 +1,23 @@
+import Head from 'next/head';
+import Examples from '../../../example-groups/ExpandingExamples';
+
+
+ {'Customized Grouping Example - Material React Table V2 Docs'}
+
+
+
+
+
+## Customized Grouping Example
+
+Here is an advanced example showing off various ways in which the expand column can be customized with column grouping features. See the [Column Grouping Guide](/docs/guides/column-grouping) to learn more.
+
+
+
+View Extra Storybook **[Examples](https://www.material-react-table.dev/?path=/story/features-column-grouping-examples)**
diff --git a/apps/material-react-table-docs/pages/docs/examples/detail-panel.mdx b/apps/material-react-table-docs/pages/docs/examples/detail-panel.mdx
index f0fe78d83..3ce8ba65d 100644
--- a/apps/material-react-table-docs/pages/docs/examples/detail-panel.mdx
+++ b/apps/material-react-table-docs/pages/docs/examples/detail-panel.mdx
@@ -5,21 +5,21 @@ import Examples from '../../../example-groups/ExpandingExamples';
{'Detail Panel Example - Material React Table V2 Docs'}
## Detail Panel Example
-Material React Table has multiple types of "expanding" row features. In its simplest form, you can use the `detailPanel` prop to render a component when a row is clicked. This is useful for showing additional information about a row, such as a list of nested data. Learn more in the [Detail Panel Feature Guide](/docs/guides/detail-panel).
+Material React Table has multiple types of "expanding" row features. In its simplest form, you can use the `renderDetailPanel` option to render a component when a row is clicked. This is useful for showing additional information about a row, such as a list of nested data. Learn more in the [Detail Panel Feature Guide](/docs/guides/detail-panel).
diff --git a/apps/material-react-table-docs/pages/docs/examples/dynamic-columns.mdx b/apps/material-react-table-docs/pages/docs/examples/dynamic-columns.mdx
new file mode 100644
index 000000000..ea80b18be
--- /dev/null
+++ b/apps/material-react-table-docs/pages/docs/examples/dynamic-columns.mdx
@@ -0,0 +1,26 @@
+import Head from 'next/head';
+import Examples from '../../../example-groups/RemoteFetchingExamples';
+
+
+ {'Dynamic Columns Example - Material React Table V2 Docs'}
+
+
+
+
+
+## Dynamic Columns (Remote) Example
+
+This example shows how to generate column definitions dynamically from remote data after first render using TanStack Query. You may need to manage the `columnOrder` state manually if doing this.
+
+
+
+View Extra Storybook **[Examples](https://www.material-react-table.dev/?path=/story/prop-playground--default)**
diff --git a/apps/material-react-table-docs/pages/docs/examples/editing-crud-tree.mdx b/apps/material-react-table-docs/pages/docs/examples/editing-crud-tree.mdx
new file mode 100644
index 000000000..683888e62
--- /dev/null
+++ b/apps/material-react-table-docs/pages/docs/examples/editing-crud-tree.mdx
@@ -0,0 +1,30 @@
+import Head from 'next/head';
+import Examples from '../../../example-groups/EditingCRUDExamples';
+
+
+ {'Editing CRUD Tree Example - Material React Table V2 Docs'}
+
+
+
+
+
+## Editing (CRUD) Tree Example
+
+Editing nested row data can be challenging. In this example, rows can be expanded to show sub rows, and editing and creating new rows can be done at any level.
+
+Adding a new blank row in the exact row index position is now possible with the new `positionCreatingRow` table option.
+
+This example also shows some complex client-side optimistic updates, where the table data is updated immediately after a valid user action.
+
+
+
+View Extra Storybook **[Examples](https://www.material-react-table.dev/?path=/story/features-creating-examples--create-row-index-index-expanding)**
diff --git a/apps/material-react-table-docs/pages/docs/examples/editing-crud.mdx b/apps/material-react-table-docs/pages/docs/examples/editing-crud.mdx
index f480cd659..7c8fe1ece 100644
--- a/apps/material-react-table-docs/pages/docs/examples/editing-crud.mdx
+++ b/apps/material-react-table-docs/pages/docs/examples/editing-crud.mdx
@@ -2,7 +2,7 @@ import Head from 'next/head';
import Examples from '../../../example-groups/EditingCRUDExamples';
- Editing CRUD Example - Material React Table V2 Docs
+ {'Editing CRUD Example - Material React Table V2 Docs'}
+
+ {'Expanding Parsed Tree Example - Material React Table V2 Docs'}
+
+
+
+
+
+
+## Expanding Parsed Tree Example
+
+Material React Table supports showing rows in a expanding tree structure and parsing them from a flat data structure with the `getSubRows` option. Learn more about how to customize this in the [expanding sub-rows feature guide](/docs/guides/expanding-sub-rows).
+
+
+
+View Extra Storybook **[Examples](https://www.material-react-table.dev/?path=/story/features-aggregation-examples)**
diff --git a/apps/material-react-table-docs/pages/docs/examples/expanding-tree.mdx b/apps/material-react-table-docs/pages/docs/examples/expanding-tree.mdx
index 2ea2a5484..aa86f98cc 100644
--- a/apps/material-react-table-docs/pages/docs/examples/expanding-tree.mdx
+++ b/apps/material-react-table-docs/pages/docs/examples/expanding-tree.mdx
@@ -19,7 +19,9 @@ import Examples from '../../../example-groups/ExpandingExamples';
## Expanding Tree Example
-Material React Table supports showing rows in a expanding tree structure. Learn more about how to customize this in the [expanding sub-rows feature guide](/docs/features/expanding-sub-rows).
+Material React Table supports showing rows in a expanding tree structure. This example is the ***simplest*** implementation of this feature where each row of data potentially has a special `subRows` property that contains an array of sub rows. You don't have to follow this exact structure, but this is how MRT will expect to find your sub rows by default.
+
+Learn more about how to customize this in the [expanding sub-rows feature guide](/docs/guides/expanding-sub-rows).
diff --git a/apps/material-react-table-docs/pages/docs/examples/export-csv.mdx b/apps/material-react-table-docs/pages/docs/examples/export-csv.mdx
index f36062de9..b2f436add 100644
--- a/apps/material-react-table-docs/pages/docs/examples/export-csv.mdx
+++ b/apps/material-react-table-docs/pages/docs/examples/export-csv.mdx
@@ -2,7 +2,7 @@ import Head from 'next/head';
import Examples from '../../../example-groups/DataExportExamples';
- Data Export Example - Material React Table V2 Docs
+ {'CSV Export Example - Material React Table V2 Docs'}
-## Data Export Example
+## CSV Export Example
Material React Table does not have a data exporting feature built in. However, you can easily integrate your own exporting feature, if desired.
diff --git a/apps/material-react-table-docs/pages/docs/examples/filter-switching.mdx b/apps/material-react-table-docs/pages/docs/examples/filter-switching.mdx
index e5f141697..16b0bf523 100644
--- a/apps/material-react-table-docs/pages/docs/examples/filter-switching.mdx
+++ b/apps/material-react-table-docs/pages/docs/examples/filter-switching.mdx
@@ -17,7 +17,7 @@ import Examples from '../../../example-groups/FilteringExamples';
/>
-## Faceted Switching Example
+## Filter Switching Example
Material React Table supports letting users switch between multiple filter modes. Learn more in the full [Column Filtering Feature Guide](/docs/guides/column-filtering).
diff --git a/apps/material-react-table-docs/pages/docs/examples/filter-variants.mdx b/apps/material-react-table-docs/pages/docs/examples/filter-variants.mdx
index c54e750ea..3e49341e0 100644
--- a/apps/material-react-table-docs/pages/docs/examples/filter-variants.mdx
+++ b/apps/material-react-table-docs/pages/docs/examples/filter-variants.mdx
@@ -19,7 +19,7 @@ import Examples from '../../../example-groups/FilteringExamples';
## Filter Variants Example
-Material React Table has not only has filtering built-in, but it has a lot of different filter variants that take care of a lot of the heavy lifting for you. Text filters, date filters, range filters, range slider filters, and more are all built-in and ready to use. There is a ton more you can do to customize the behavior of filtering, so be sure to check out the full [Column Filtering Feature Guide](/docs/guides/column-filtering) for more information.
+Material React Table not only has filtering built in, but it also has a lot of different filter variants that take care of a lot of the heavy lifting for you. Text filters, date filters, range filters, range slider filters, and more are all built in and ready to use. There is much more you can do to customize the behavior of filtering, so be sure to check out the full [Column Filtering Feature Guide](/docs/guides/column-filtering) for more information.
diff --git a/apps/material-react-table-docs/pages/docs/examples/lazy-detail-panel.mdx b/apps/material-react-table-docs/pages/docs/examples/lazy-detail-panel.mdx
new file mode 100644
index 000000000..07662db9b
--- /dev/null
+++ b/apps/material-react-table-docs/pages/docs/examples/lazy-detail-panel.mdx
@@ -0,0 +1,28 @@
+import Head from 'next/head';
+import Examples from '../../../example-groups/RemoteFetchingExamples';
+
+
+ {'Lazy Detail Panel Example - Material React Table V2 Docs'}
+
+
+
+
+
+## Lazy Detail Panel Example
+
+Fetching the additional data for the detail panels only after the user clicks to expand the row can be a good way to improve performance, and it is pretty easy to implement in Material React Table.
+
+It's even easier if you are using [React Query.](https://tanstack.com/query/latest) In this example, react query is used to fetch the data for the detail panel, but only after the user clicks to expand the row. The data is also cached for a certain period of time so that when the detail panel is closed and reopened, the data is already available and won't need to be re-fetched.
+
+
+
+View Extra Storybook **[Examples](https://www.material-react-table.dev/?path=/story/features-aggregation-examples)**
diff --git a/apps/material-react-table-docs/pages/docs/examples/lazy-sub-rows.mdx b/apps/material-react-table-docs/pages/docs/examples/lazy-sub-rows.mdx
new file mode 100644
index 000000000..8697ef9e4
--- /dev/null
+++ b/apps/material-react-table-docs/pages/docs/examples/lazy-sub-rows.mdx
@@ -0,0 +1,30 @@
+import Head from 'next/head';
+import Examples from '../../../example-groups/RemoteFetchingExamples';
+
+
+ {'Lazy Sub-Rows Example - Material React Table V2 Docs'}
+
+
+
+
+
+## Lazy Sub-Rows Example
+
+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.
+
+There are quite a few ways in which you could implement fetching sub-rows lazily. This example is just one way to do it.
+
+This example combines concepts from the [React Query Example](/docs/examples/react-query) and the [Expanding Parsed Tree Example](/docs/examples/expanding-tree-flat-parse).
+
+
+
+View Extra Storybook **[Examples](https://www.material-react-table.dev/?path=/story/features-aggregation-examples)**
diff --git a/apps/material-react-table-docs/pages/docs/examples/minimal.mdx b/apps/material-react-table-docs/pages/docs/examples/minimal.mdx
index 7c19ca3af..110be49ba 100644
--- a/apps/material-react-table-docs/pages/docs/examples/minimal.mdx
+++ b/apps/material-react-table-docs/pages/docs/examples/minimal.mdx
@@ -21,7 +21,7 @@ import Examples from '../../../example-groups/BasicExamples';
Material React Table gives you a lot out of the box, but it's also easy to turn off any features that you do not need.
-Every feature has an `enable...` prop that let's you turn it on or off.
+Every feature has an `enable...` table option that let's you turn it on or off.
For example, you can turn off sorting or hide the top or bottom toolbars if you want.
diff --git a/apps/material-react-table-docs/pages/docs/examples/popover-filters.mdx b/apps/material-react-table-docs/pages/docs/examples/popover-filters.mdx
index 5c1afe0b5..c4b9b44a8 100644
--- a/apps/material-react-table-docs/pages/docs/examples/popover-filters.mdx
+++ b/apps/material-react-table-docs/pages/docs/examples/popover-filters.mdx
@@ -19,7 +19,7 @@ import Examples from '../../../example-groups/FilteringExamples';
## Popover Filters Example
-Material React Table supports displaying column filters in other ways than in the default sub-header location. This example shows how to only show column filters when the user clicks on the filter icon in the header, and then display the filters in a popover. Learn more in the full [Column Filtering Feature Guide](/docs/guides/column-filtering).
+Material React Table supports displaying column filters in other ways than in the default sub-header location. This example shows how to only display column filters when the user clicks on the filter icon in the header and then display the filters in a popover. Learn more in the full [Column Filtering Feature Guide](/docs/guides/column-filtering).
diff --git a/apps/material-react-table-docs/pages/docs/examples/row-dragging.mdx b/apps/material-react-table-docs/pages/docs/examples/row-dragging.mdx
new file mode 100644
index 000000000..89734ba2e
--- /dev/null
+++ b/apps/material-react-table-docs/pages/docs/examples/row-dragging.mdx
@@ -0,0 +1,26 @@
+import Head from 'next/head';
+import Examples from '../../../example-groups/DraggingExamples';
+
+
+ {'Row Dragging Example - Material React Table V2 Docs'}
+
+
+
+
+
+## Row Dragging Example
+
+Material React Table has built-in support row drag and drop features that can be used in a variety of ways. Learn more about column ordering in the [Row Ordering/DnD Feature Guide](/docs/guides/row-ordering-dnd).
+
+
+
+View Extra Storybook **[Examples](https://www.material-react-table.dev/?path=/story/prop-playground--default)**
diff --git a/apps/material-react-table-docs/pages/docs/examples/row-ordering.mdx b/apps/material-react-table-docs/pages/docs/examples/row-ordering.mdx
new file mode 100644
index 000000000..db55ffc14
--- /dev/null
+++ b/apps/material-react-table-docs/pages/docs/examples/row-ordering.mdx
@@ -0,0 +1,26 @@
+import Head from 'next/head';
+import Examples from '../../../example-groups/DraggingExamples';
+
+
+ {'Row DnD Ordering Example - Material React Table V2 Docs'}
+
+
+
+
+
+## Row DnD Ordering Example
+
+Material React Table has built-in support for row drag and drop re-ordering. Learn more about column ordering in the [Row Ordering Feature Guide](/docs/guides/row-ordering-dnd).
+
+
+
+View Extra Storybook **[Examples](https://www.material-react-table.dev/?path=/story/prop-playground--default)**
diff --git a/apps/material-react-table-docs/pages/docs/examples/row-virtualization.mdx b/apps/material-react-table-docs/pages/docs/examples/row-virtualization.mdx
index 839ba770b..a1a4f767d 100644
--- a/apps/material-react-table-docs/pages/docs/examples/row-virtualization.mdx
+++ b/apps/material-react-table-docs/pages/docs/examples/row-virtualization.mdx
@@ -19,7 +19,7 @@ import Examples from '../../../example-groups/VirtualizedExamples';
## Row Virtualization Example
-Material React Table has a built-in row virtualization feature (via [`@tanstack/react-virual`](https://tanstack.com/virtual/v3)) that allows you to render a large number of rows without major performance issues that you would normally see with a large number of DOM elements.
+Material React Table has a built-in row virtualization feature (via [`@tanstack/react-virtual`](https://tanstack.com/virtual/v3)) that allows you to render a large number of rows without major performance issues that you would normally see with a large number of DOM elements.
Try out the performance of the table below with **10,000 rows**! Filtering, Search, and Sorting also maintain usable performance.
diff --git a/apps/material-react-table-docs/pages/docs/examples/sticky-header.mdx b/apps/material-react-table-docs/pages/docs/examples/sticky-header.mdx
index 73f478733..3b6cfb14c 100644
--- a/apps/material-react-table-docs/pages/docs/examples/sticky-header.mdx
+++ b/apps/material-react-table-docs/pages/docs/examples/sticky-header.mdx
@@ -16,7 +16,7 @@ import Examples from '../../../example-groups/StickyPinningExamples';
## Sticky Header Example
-Material React Table easily allows you to make the header and footer sticky while scrolling. See the [Sticky Header Feature Guide](/docs/guides/sticky-header) for more information.
+Material React Table allows you to easily make the header and footer sticky while scrolling. See the [Sticky Header Feature Guide](/docs/guides/sticky-header) for more information.
diff --git a/apps/material-react-table-docs/pages/docs/examples/sticky-row-selection.mdx b/apps/material-react-table-docs/pages/docs/examples/sticky-row-selection.mdx
new file mode 100644
index 000000000..17170090c
--- /dev/null
+++ b/apps/material-react-table-docs/pages/docs/examples/sticky-row-selection.mdx
@@ -0,0 +1,26 @@
+import Head from 'next/head';
+import Examples from '../../../example-groups/StickyPinningExamples';
+
+
+ {'Sticky Row Selection Example - Material React Table V2 Docs'}
+
+
+
+
+
+## Sticky Row Selection Example
+
+Material React Table has the ability to pin rows as they are selected and keep them in view while scrolling. In this example, when rows are selected, they will initially appear to stay in place, but when the user scrolls up or down, the selected rows will stick to the top or bottom of the table. Learn more about row pinning in the [Row Pinning Feature Guide](/docs/guides/row-pinning).
+
+
+
+View Extra Storybook **[Examples](https://www.material-react-table.dev/?path=/story/prop-playground--default)**
diff --git a/apps/material-react-table-docs/pages/docs/examples/virtualized.mdx b/apps/material-react-table-docs/pages/docs/examples/virtualized.mdx
index 9e5043d42..5e2725e08 100644
--- a/apps/material-react-table-docs/pages/docs/examples/virtualized.mdx
+++ b/apps/material-react-table-docs/pages/docs/examples/virtualized.mdx
@@ -19,7 +19,7 @@ import Examples from '../../../example-groups/VirtualizedExamples';
## Virtualized Example
-Material React Table has a built-in virtualization features (via [`@tanstack/react-virual`](https://tanstack.com/virtual/v3)) that allows you to render a large number of rows or columns without major performance issues that you would normally see with a large number of DOM elements.
+Material React Table has a built-in virtualization features (via [`@tanstack/react-virtual`](https://tanstack.com/virtual/v3)) that allows you to render a large number of rows or columns without major performance issues that you would normally see with a large number of DOM elements.
Try out the performance of the table below with **10,000 rows** and over a dozen columns! Filtering, Search, and Sorting also maintain usable performance.
diff --git a/apps/material-react-table-docs/pages/docs/getting-started/index.mdx b/apps/material-react-table-docs/pages/docs/getting-started/index.mdx
index 22d51a543..aa6e1af0e 100644
--- a/apps/material-react-table-docs/pages/docs/getting-started/index.mdx
+++ b/apps/material-react-table-docs/pages/docs/getting-started/index.mdx
@@ -3,7 +3,7 @@ import TableOfContentsList from '../../../components/navigation/TableOfContentsL
import { routes } from '../../../components/navigation/routes';
- Getting Started - Material React Table V2 Docs
+ {'Getting Started - Material React Table V2 Docs'}
- Installation - Material React Table V2 Docs
+ {'Installation - Material React Table V2 Docs'}
## Installation
+> These are install instructions for an older version of Material React Table (v2). If you are looking for install instructions for the latest version, [click here](https://material-react-table.com/docs/getting-started/install).
+
+### Compatibility
+
+First, before installing Material React Table, let's make sure you have the correct versions of React, Material UI, and Material UI X Date Pickers installed. You may want to go to the [latest version of MRT](https://material-react-table.com/docs/getting-started/install) if you ended up on an older version of the docs by mistake.
+
+
+
> `material-react-table` requires **Material UI V5** packages as dependencies in your project.
>
> If you are already using Material UI, you probably already have most of these peer dependencies installed.
@@ -20,11 +29,11 @@ import { FAQs } from '../../../components/mdx/FAQs';
> 3. `@mui/icons-material` (v5)
> 4. `@emotion/react` (v11)
> 5. `@emotion/styled` (v11)
-> 6. `react` and `react-dom` (v18) - (MRT v2 will eventually use React 18 concurrent mode)
+> 6. `react` and `react-dom` (v17+)
### Quick Install
-
+
### Install With Required Peer Dependencies (Recommended)
@@ -42,6 +51,7 @@ If you get an error like this:
"Error: Element type is invalid: expected a string (for built-in components)
or a class/function (for composite components) but got: undefined.
```
+
You likely forgot to export your component from the file it's defined in,
or you might have mixed up default and named imports.
@@ -84,7 +94,7 @@ Then try upgrading either `webpack` or `react-scripts` to the latest versions.
name: "Should I install '@tanstack/react-table' in my package.json for Material React Table?",
acceptedAnswer: {
'@type': 'Answer',
- text: "No, you do not need to install TanStack Table in your project manually, as the latest TanStack Table version automatically gets installed under the hood by MRT itself as an internal dependency. You can imports and functions from '@tanstack/react-table' too. ",
+ text: "No, you do not need to install TanStack Table in your project manually, as the latest TanStack Table version automatically gets installed under the hood by MRT itself as an internal dependency. You can import and functions from '@tanstack/react-table' too. ",
},
},
{
diff --git a/apps/material-react-table-docs/pages/docs/getting-started/migrating-to-v2.mdx b/apps/material-react-table-docs/pages/docs/getting-started/migrating-to-v2.mdx
new file mode 100644
index 000000000..bdf8befe2
--- /dev/null
+++ b/apps/material-react-table-docs/pages/docs/getting-started/migrating-to-v2.mdx
@@ -0,0 +1,221 @@
+import Head from 'next/head';
+import { InstallCommand } from '../../../components/mdx/InstallCommand';
+import { Typography, Link as MuiLink, Alert, AlertTitle } from '@mui/material';
+
+
+
+ {'Migrating to Material React Table V2 - Material React Table V2 Docs'}
+
+
+
+
+
+
+ Material React Table V3 was released September 5th, 2024
+
+ Upgrade to MRT V3 and Material UI V6 Today!
+
+ View the V3 Migration Guide here.
+
+
+
+## Migrating to Material React Table V2 from V1
+
+This should be an easy to moderate upgrade for most developers. The only breaking changes have to do with the removed `tableInstanceRef`, some renamed props/options, and new column sizing behaviors.
+
+> Note: As of v2.12.0, the React and ReactDom peer dependencies have been moved back down to React v17 in order to help more people upgrade to MRT v2 without having to upgrade to React v18.
+
+### New Feature Highlights
+
+1. New optional but recommended `useMaterialReactTable` hook that allows you to create the `table` instance in your own scope
+2. Greatly improved editing and new creating features
+3. New row pinning Features
+4. New column filtering `'popover'` display mode to give a more "Excel-like" filtering experience
+5. New autocomplete, date, and date range filter variants
+6. New pagination UI options
+7. New alert banner UI options and overrides available
+8. New loading overlay UI
+9. Improved table head cell default styles
+10. Improved column sizing and layout modes for column resizing features
+11. All internal MRT components are now exported for custom headless use cases
+12. New optional `createMRTColumnHelper` utility function for better `TValue`/`cell.getValue()` type inference
+13. Many more features are compatible with virtualization
+
+See the full [changelog](/changelog#version-2.0.0---10-27-2023) for more details.
+
+### Upgrade Dependencies
+
+Run this command to set the `material-react-table` dependency to the latest version in your `package.json`. This will not perform the full install yet.
+
+```bash
+npx npm-check-updates -u material-react-table
+```
+
+Your `package.json` should have `"material-react-table": "^2.x.x"` as a dependency.
+
+Then run the install command again. Either `npm i`, `pnpm i`, or `yarn`, etc. Or run the full command below to make sure all MUI dependencies are also upgraded or installed.
+
+
+
+### Breaking Changes
+
+- `@mui/x-date-pickers v >=6.15.0` is now a required peer dependency. If not already installed from the previous step, install it with:
+
+
+
+- If you use the date picker features, you will also need to import the `LocalizationProvider` from `@mui/x-date-pickers` and wrap your app in it. Click [here](https://mui.com/x/react-date-pickers/adapters-locale/) for more details.
+
+```jsx
+import { LocalizationProvider } from '@mui/x-date-pickers';
+import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
+
+export const App = () => {
+ return (
+
+ {/* Add this if using date filter features */}
+
+
+
+
+ );
+};
+```
+
+- `MaterialReactTable` is now a named export instead of a default export. Use curly braces to import it.
+
+```diff
+- import MaterialReactTable from 'material-react-table'
++ import { MaterialReactTable, useMaterialReactTable } from 'material-react-table'
+```
+
+- The `tableInstanceRef` prop has been replaced by the `useMaterialReactTable` hook, which is much easier to use. It is also recommended that all table options be passed to the new `useMaterialReactTable` hook instead as props to the `` component. See [below](#usematerialreacttable) for more details.
+
+#### Renamed Props/Options
+
+- `editingMode` -> `editDisplayMode`
+- `rowNumberMode` -> `rowNumberDisplayMode`
+- `enablePinning` -> `enableColumnPinning` and `enableRowPinning`
+- `virtualizerInstanceRef` split into `columnVirtualizerRef` and `rowVirtualizerRef`
+- `virtualizerProps` split into `columnVirtualizerOptions` and `rowVirtualizerOptions`
+- `columnVirtualizerProps` -> `columnVirtualizerOptions`
+- `rowVirtualizerProps` -> `rowVirtualizerOptions`
+- `muiTablePaginationProps` -> `muiPaginationProps`
+- `muiTableBodyCellCopyButtonProps` -> `muiCopyButtonProps`
+- `muiTableBodyCellEditTextFieldProps` -> `muiEditTextFieldProps`
+- `muiTableBodyCellSkeletonProps` -> `muiSkeletonProps`
+- `muiTableBodyRowDragHandleProps` -> `muiRowDragHandleProps`
+- `muiTableDetailPanelProps` -> `muiDetailPanelProps`
+- `muiTableHeadCellColumnActionsButtonProps` -> `muiColumnActionsButtonProps`
+- `muiTableHeadCellDragHandleProps` -> `muiColumnDragHandleProps`
+- `muiTableHeadCellFilterCheckboxProps` -> `muiFilterCheckboxProps`
+- `muiTableHeadCellFilterTextFieldProps` -> `muiFilterTextFieldProps`
+- `muiTableHeadCellFilterSliderProps` -> `muiFilterSliderProps`
+- `MRT_FilterFnsState` -> `MRT_ColumnFilterFns`
+- `MaterialReactTableProps` -> `MRT_TableOptions`
+- `MRT_FullScreenToggleButton` => `MRT_ToggleFullScreenButton`
+
+### useMaterialReactTable
+
+Passing all table options as props to `` still works, but there now is an improved way to define table options with the `useMaterialReactTable` hook.
+
+For example, here is a classic example for how to use Material React Table in V1 (still works in v2):
+
+```jsx
+import { MaterialReactTable } from 'material-react-table';
+
+export const MyTableComponent = () => {
+ // const tableInstanceRef = useRef(); //deprecated
+
+ return (
+ //Defining table options as props to still works (as long as you don't also pass in a table prop)
+
+ );
+};
+```
+
+But you can now define all table options in the `useMaterialReactTable`.
+
+```jsx
+import {
+ MaterialReactTable,
+ useMaterialReactTable,
+} from 'material-react-table';
+
+export const MyTableComponent = () => {
+ const table = useMaterialReactTable({
+ columns,
+ data,
+ enableRowSelection: true, //table options as options to this hook
+ });
+
+ return (
+
+ );
+};
+```
+
+### Why is useMaterialReactTable Better?
+
+There are a few reasons why having full access to the `table` instance is better than having MRT create it under the hood for you.
+
+1. There is no longer a need for a confusing `tableInstanceRef` prop that doesn't properly cause re-renders when the table instance changes. Now, any component that consumes the `table` instance will properly re-render when the table instance changes.
+
+2. It allows you to not have to use all of Material React Table's components. For example, if you only want to use the `Table` component with no TableContainer or Toolbars, you can simply import a different component from Material React Table.
+
+```jsx
+import { MRT_Table, useMaterialReactTable } from 'material-react-table';
+
+export const MyTableComponent = () => {
+ const table = useMaterialReactTable({
+ columns,
+ data,
+ enableRowSelection: true,
+ });
+
+ const selectedRows = table.getSelectedRowModel().rows;
+ console.log(selectedRows);
+
+ return (
+ //this internal sub-component does not include the Paper, TableContainer, or Toolbars (lighter weight)
+
+ );
+};
+```
+
+### Column Sizing and Layout Modes
+
+There are some new column sizing behaviors to be aware of in v2.
+
+In addition to the `"semantic"` and `"grid"` layoutModes, there is now a new `"grid-no-grow"` layoutMode that is automatically enabled by default when `enableColumnResizing` is `true`.
+
+This new layoutMode keeps columns in a fixed width, and columns will not grow to fill any remaining horizontal space. This is likely a very welcome change for most, but you can revert the behavior back to the old behavior by setting the layoutMode table option to `"grid"` or `"semantic"` manually.
+
+If you were previously trying to accomplish the same `"grid-no-grow"` by setting the flex-grow CSS to 0 in V1, it is recommended that you now remove that CSS in favor of simply using the new `"grid-no-grow"` layoutMode, which will also add an invisible `"mrt-row-spacer"` display column that makes the row borders look better.
+
+```diff
+- muiTableHeadCellProps={{
+- sx: {
+- flex: '0 0 auto',
+- },
+- }}
+- muiTableBodyCellProps={{
+- sx: {
+- flex: '0 0 auto',
+- },
+- }}
++ layoutMode="grid-no-grow"
+```
+
+
+
+Is anything missing from this v2 migration guide? Make a PR or join the [Discord](https://discord.gg/5wqyRx6fnm) to discuss.
diff --git a/apps/material-react-table-docs/pages/docs/getting-started/usage.mdx b/apps/material-react-table-docs/pages/docs/getting-started/usage.mdx
index d3f736346..a02eeaf77 100644
--- a/apps/material-react-table-docs/pages/docs/getting-started/usage.mdx
+++ b/apps/material-react-table-docs/pages/docs/getting-started/usage.mdx
@@ -2,7 +2,7 @@ import Head from 'next/head';
import SimpleCodeSandbox from '../../../examples/SimpleCodeSandbox';
- Usage - Material React Table V2 Docs
+ {'Usage - Material React Table V2 Docs'}
**Common Gotcha**: When defining `data` that will be passed to a `useMaterialReactTable` hook, make sure that the `data` is _memoized_ or _stable_ (i.e. `useState`, `useMemo`, defined outside of your table component, etc.). Otherwise you may get infinite renders.
+
#### Simple Data Example
```jsx
@@ -54,11 +59,11 @@ const data = [
];
```
-Your data does NOT have to be created statically like this, of course. More than likely, your data is being fetched from a backend API. Check out the [Remote Data example](/docs/examples/remote) to see how you can use a remote data source.
+Your data does NOT have to be created statically like this, of course. More than likely, your data is being fetched from a backend API. Check out the [Remote Data examples](/docs/examples/react-query) to see how you can fetch data and pass it to your tables.
### Creating Columns
-There are several different ways to define columns, depending on your needs. Let's create some basic "data" columns. That is, columns that connect to our data. Since we defined our data in a flat object format, we can simply use the `accessorKey` property to access the data.
+There are several different ways to define columns, depending on your needs. Let's create some basic `"data"` columns. That is, columns that connect to our data. Most of the time, we can simply use the `accessorKey` property to access the data if the data is in a simple format. Alternatively, if some data in a column needs some logic or processing, you can use the `accessorFn` property to define a function that returns the data for each cell.
#### Simple Column Definition Example
@@ -70,6 +75,13 @@ const columns = useMemo(
header: 'Name',
accessorKey: 'name', //simple recommended way to define a column
//more column options can be added here to enable/disable features, customize look and feel, etc.
+ //optional custom cell render
+ Cell: ({ row }) => (
+
+ 
+ {row.name}
+
+ ),
},
{
header: 'Age',
@@ -80,9 +92,11 @@ const columns = useMemo(
);
```
+> Note: Do NOT have your accessors resolve JSX or markup. That's what custom `Cell` renders are for. Accessors should only return primitive data so that the table can sort, filter, search, and group properly.
+
### Full Simple Example
-Put it all together, and you have a basic table! You can also play around and enable some features, either per column in the column definitions, or as props passed to ``.
+Put it all together, and you have a basic table! You can also play around and enable some features, either per column in the column definitions, or as table options passed to `useMaterialReactTable`.
```tsx
import { useMemo } from 'react';
@@ -118,12 +132,14 @@ export default function App() {
accessorKey: 'name', //simple recommended way to define a column
header: 'Name',
muiTableHeadCellProps: { style: { color: 'green' } }, //custom props
+ enableHiding: false, //disable a feature for this column
},
{
- accessorFn: (originalRow) => originalRow.age, //alternate way
+ accessorFn: (originalRow) => parseInt(originalRow.age), //alternate way
id: 'age', //id required if you use accessorFn instead of accessorKey
header: 'Age',
Header: Age, //optional custom markup
+ Cell: ({ cell }) => {cell.getValue().toLocaleString()}, //optional custom cell render
},
],
[],
@@ -134,17 +150,17 @@ export default function App() {
columns,
data, //must be memoized or stable (useState, useMemo, defined outside of this component, etc.)
enableRowSelection: true, //enable some features
- enableColumnOrdering: true,
+ enableColumnOrdering: true, //enable a feature for all columns
enableGlobalFilter: false, //turn off a feature
});
//note: you can also pass table options as props directly to instead of using useMaterialReactTable
- //but that is not recommended and will likely be deprecated in the future
+ //but the useMaterialReactTable hook will be the most recommended way to define table options
return ;
}
```
-> **Note:** It is very important that the columns and data definitions are _memoized_ or _stable_. Otherwise, the entire table will be re-rendered during every react re-render in your application, which can lead to performance issues. To make a variable stable, store it in `useState`, wrap it in `useMemo`, or define it outside of a component so it does not get recreated on every render.
+> **Note:** Again, it is very important that the columns and data definitions are _memoized_ or _stable_. Otherwise, the entire table will be re-rendered during every react re-render in your application, which can lead to performance issues. To make a variable stable, store it in `useState`, wrap it in `useMemo`, define it outside of a component, or in your state management tool of choice so it does not get recreated on every render and cause an infinite re-render loop.
### Live Code Sandbox Example
diff --git a/apps/material-react-table-docs/pages/docs/guides/aggregation-and-grouping.mdx b/apps/material-react-table-docs/pages/docs/guides/aggregation.mdx
similarity index 70%
rename from apps/material-react-table-docs/pages/docs/guides/aggregation-and-grouping.mdx
rename to apps/material-react-table-docs/pages/docs/guides/aggregation.mdx
index c8ee28b95..65ef9651c 100644
--- a/apps/material-react-table-docs/pages/docs/guides/aggregation-and-grouping.mdx
+++ b/apps/material-react-table-docs/pages/docs/guides/aggregation.mdx
@@ -6,20 +6,20 @@ import AggregationExample from '../../../examples/aggregation-and-grouping';
import AggregationMultiExample from '../../../examples/aggregation-multi';
-
- {'Aggregation and Grouping Feature Guide - Material React Table V2 Docs'}
-
+ {'Aggregation Guide - Material React Table V2 Docs'}
-## Aggregation and Grouping Feature Guide
+## Aggregation Feature Guide
-Material React Table has built-in grouping and aggregation features. There are options for both automatic client-side grouping and aggregation, as well as manual server-side grouping and aggregation. This guide will walk you through the different options and how to use and customize them.
+Material React Table has built-in aggregation features. There are options for both automatic client-side grouping and aggregation, as well as manual server-side grouping and aggregation. This guide will walk you through the different options and how to use and customize them.
-### Relevant Props
+> See the [Column Grouping Guide](/docs/guides/column-grouping) as a prerequisite to this guide. The Aggregation and Grouping Guide was recently split into two separate guides.
+
+### Relevant Table Options
@@ -50,74 +56,6 @@ Material React Table has built-in grouping and aggregation features. There are o
-### Enable Grouping
-
-To enable grouping, set the `enableGrouping` prop to `true`. This will both add a drag handle button so that columns can be dragged to the dropzone to be grouped and will add an entry column actions menu to group or ungroup a column.
-
-```jsx
-
-```
-
-#### Disable Grouping Per Column
-
-```jsx
-const columns = [
- {
- accessorKey: 'name',
- header: 'Name',
- enableGrouping: false, // disable grouping for this column
- },
- {
- accessorKey: 'age',
- header: 'Age',
- },
-];
-
-return ;
-```
-
-#### Hide Drag Buttons for Grouping
-
-If you do not want the drag buttons that come with the grouping feature, you can independently disable them without disabling the grouping feature entirely by setting the `enableColumnDragging` prop to `false`.
-
-```jsx
-
-```
-
-### Group Columns by Default
-
-If you want columns to be grouped by default, you can set the `grouping` state in either the `initialState` or `state` prop.
-
-```jsx
-
-```
-
-### Expand Grouped Rows by Default
-
-In addition to grouping columns by default, you may also want those grouped rows to be expanded and visible by default, too. You can do this by setting the `expanded` state to `true` in either the `initialState` or `state` prop.
-
-```jsx
-
-```
-
### Aggregation on Grouped Rows
One of the cool features of Material React Table is that it can automatically aggregate the data in grouped rows. To enable this, you must specify both an `aggregationFn` and an `AggregatedCell` render option on a column definition.
@@ -156,14 +94,14 @@ const columns = [
},
];
-return (
-
-);
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableGrouping: true,
+ initialState: { grouping: ['team'], expanded: true },
+});
+
+return ;
```
#### Custom Aggregation Functions
@@ -191,17 +129,20 @@ const averageScore = useMemo(() => {
return totalPoints / totalPlayers;
}, [data]);
-const columns = [
- {
- accessorKey: 'name',
- header: 'Name',
- },
- {
- accessorKey: 'score',
- header: 'Score',
- Footer: () => Average Score: {averageScore} , //do not do calculations in render, do them in useMemo hook and pass them in here
- },
-];
+const columns = useMemo(
+ () => [
+ {
+ accessorKey: 'name',
+ header: 'Name',
+ },
+ {
+ accessorKey: 'score',
+ header: 'Score',
+ Footer: () => Average Score: {averageScore} , //do not do calculations in render, do them in useMemo hook and pass them in here
+ },
+ ],
+ [averageScore],
+);
```
> Please remember to perform heavy aggregation calculations in a useMemo hook to avoid unnecessary re-renders!
@@ -243,8 +184,6 @@ const columns = [
#### PlaceholderCell Column Option
-> New in v1.7.4
-
"Placeholder Cells" are cells that are usually meant to be empty in grouped rows and columns. They are simply rendered with a value of `null` by default, but you can override the default render for these cells with the `PlaceholderCell` render option on a column definition.
```jsx
@@ -265,8 +204,6 @@ const columns = [
### Multiple Aggregations Per column
-> New in v1.3!
-
You may want to calculate more than one aggregation per column. This is now easier if you are upgraded to at least v1.3.0. You can now specify an array of `aggregationFn`s, and then reference the aggregation results from an array in the `AggregatedCell` render option.
```jsx
diff --git a/apps/material-react-table-docs/pages/docs/guides/async-loading.mdx b/apps/material-react-table-docs/pages/docs/guides/async-loading.mdx
index 47c485242..2750f9f7c 100644
--- a/apps/material-react-table-docs/pages/docs/guides/async-loading.mdx
+++ b/apps/material-react-table-docs/pages/docs/guides/async-loading.mdx
@@ -6,23 +6,29 @@ import LinearProgressExample from '../../../examples/linear-progress';
import ReactQueryExample from '../../../examples/react-query';
- {'Async Loading Feature Guide - Material React Table V2 Docs'}
+ {'Async Loading UI Guide - Material React Table V2 Docs'}
-## Async Loading Feature Guide
+## Async Loading UI Feature Guide
While you are fetching your data, you may want to show some loading indicators. Material React Table has some nice loading UI features built in that look better than a simple spinner.
> This guide is mostly focused on the loading UI features. Make sure to also check out the [Remote Data](/docs/examples/remote) and [React Query](/docs/examples/react-query) examples for server-side logic examples.
-### Relevant Props
+### Relevant Table Options
### Relevant State Options
@@ -41,33 +47,104 @@ While you are fetching your data, you may want to show some loading indicators.
### isLoading UI
-Rather than coding your own spinner or loading indicator, you can simply set the `isLoading` state to `true`, and Material React Table will show progress bars and cell skeletons for you.
+There are three different loading UI features that are built into Material React Table:
+
+1. Loading Overlay - shows spinner overlay over the table container. (New in V2)
+2. Cell Skeletons - show pretty and shimmering skeletons for each cell.
+3. Linear Progress Bars - shows progress bars above and/or below the table.
+
+You can use any combination of these loading UIs by managing the `showLoadingOverlay`, `showSkeletons`, and `showProgressBars` states.
+
+There are also two other loading states that are shortcuts for combining some of the above states:
+
+- `isLoading` - shows loading overlay and cell skeletons.
+- `isSaving` - shows the progress bars and adds spinners to the save buttons in editing features.
+
+Here is some of the recommended loading UI that you might use with React Query:
```jsx
-
+const {
+ data = [],
+ isLoading: isLoadingTodos,
+ isRefetching: isRefetchingTodos,
+} = useQuery({
+ /**/
+});
+
+const { mutate, isPending: isSavingTodos } = useMutation({
+ /**/
+});
+
+const table = useMaterialReactTable({
+ columns,
+ data,
+ state: {
+ isLoading: isLoadingTodos, //cell skeletons and loading overlay
+ showProgressBars: isRefetchingTodos, //progress bars while refetching
+ isSaving: isSavingTodos, //progress bars and save button spinners
+ },
+});
+
+return ;
+```
+
+> Note: The Loading Overlay UI makes the table container non-interactive while it is showing. This is usually desired while no data is yet in the table. Consider avoiding using the Loading Overlay UI during "refetching" operations like filtering, sorting, or pagination.
+
+### Customize Loading UI
+
+You can customize the loading UI by passing props to the `muiSkeletonProps`, `muiLinearProgressProps`, and `muiCircularProgressProps` props.
+
+```jsx
+const table = useMaterialReactTable({
+ columns,
+ data,
+ muiSkeletonProps: {
+ animation: 'wave',
+ },
+ muiLinearProgressProps: {
+ color: 'secondary',
+ },
+ muiCircularProgressProps: {
+ color: 'secondary',
+ },
+});
+
+return ;
```
-#### Only Show Progress Bars or Skeletons
+#### Custom Loading Spinner component
-If you do not want both progress bars and cell skeletons to show, you can use the `showProgressBars` and `showSkeletons` states, instead.
+> New in v2.11.0
+
+If you need to use a custom loading spinner component other than the built-in MUI one, you can now pass in custom component in the `muiCircularProgressProps` `Component` prop.
```jsx
-
+import { MyCustomSpinner } from './MyCustomSpinner';
+
+const table = useMaterialReactTable({
+ columns,
+ data,
+ muiCircularProgressProps: {
+ Component: ,
+ },
+});
```
-### Customize Linear Progress Bars
+### Only Show Progress Bars or Skeletons
+
+If you do not want both progress bars and cell skeletons to show, you can use the `showProgressBars` and `showSkeletons` states, instead.
-You can customize the linear progress bars by passing props to the `muiLinearProgressProps` prop.
+```jsx
+const table = useMaterialReactTable({
+ columns,
+ data,
+ state: {
+ showProgressBars: true, //or showSkeletons
+ },
+});
+```
diff --git a/apps/material-react-table-docs/pages/docs/guides/best-practices.mdx b/apps/material-react-table-docs/pages/docs/guides/best-practices.mdx
new file mode 100644
index 000000000..b0ca5daf3
--- /dev/null
+++ b/apps/material-react-table-docs/pages/docs/guides/best-practices.mdx
@@ -0,0 +1,373 @@
+import Head from 'next/head';
+
+
+ {'Best Practices (TypeScript) - Material React Table V2 Docs'}
+
+
+
+## MRT Best Practices
+
+Here are some best practices to follow when using Material React Table. We'll cover Type-Safety (even if you are not using TypeScript) and how to best create re-usable MRT components.
+
+### Stay Up-To-Date
+
+Run this command in your terminal every few weeks to make sure you are using the latest version of Material React Table and MUI
+
+```bash
+npx npm-check-updates -u material-react-table @mui/material @mui/x-date-pickers @mui/icons-material @emotion/react @emotion/styled
+```
+
+### Type-Safety
+
+TanStack Table itself is written in TypeScript, and Material React Table builds on top of its great type definitions for a best-in-class TypeScript experience.
+
+If, however, you cannot use TypeScript in your project for some reason, checkout down below for [how to use JSDoc instead of TypeScript](#use-jsdoc-instead-of-typescript) to get the same type hints.
+
+#### Is TypeScript Required?
+
+No, TypeScript is not required to use Material React Table. You can just use JavaScript and everything will work just fine, but you will be missing out on a lot of great type hints and type safety that can help you build your app faster and with less bugs.
+
+There are a couple of ways to still get type hints without TypeScript with the [`createMRTColumnHelper`](#createmrtcolumnhelper-utility) utility function or by using [JSDoc](#use-jsdoc-instead-of-typescript), so you can still get some of the benefits of type safety without TypeScript.
+
+#### Defining TData Type
+
+Material React Table makes use of generics to make working with your specific row data structures easier. You will see that most of the `MRT_*` types that you can use accept a `TData` generic.
+
+Let's say that the data in your table is an array of users that looks like this:
+
+```tsx
+const data: User[] = [
+ { id: 1, name: 'John', age: 23 },
+ { id: 2, name: 'Alice', age: 17 },
+ { id: 3, name: 'Bob', age: 32 },
+];
+```
+
+Then your `TData` type can be defined as:
+
+```tsx
+export type User = {
+ id: number;
+ name: string;
+ age: number;
+};
+```
+
+You will often pass this `TData` type as a generic to the `MRT_*` types that you use so that you can get type hints for your specific data structure.
+
+#### Define Your Columns With Type-Safety
+
+Material React Table provides a couple of ways to define your columns with type safety. You can either simply use the `MRT_ColumnDef` type or use the new `createMRTColumnHelper` utility function.
+
+#### MRT_ColumnDef Type
+
+The most straightforward way to define your columns with type-safety is to just type your columns as `Array>`.
+
+```tsx
+import {
+ MaterialReactTable,
+ useMaterialReactTable,
+ type MRT_ColumnDef, // <--- import MRT_ColumnDef
+} from 'material-react-table';
+import { type User } from './types'; // <--- import your TData type from wherever you defined it
+
+// define your columns, pass User as a generic to MRT_ColumnDef
+const columns: Array> = [
+ {
+ accessorKey: 'id', //you should get type hints for all of your keys if you defined your TData type correctly
+ header: 'ID',
+ enableSorting: false, //you should get type hints for all possible column options that you can define here
+ },
+ {
+ accessorKey: 'name',
+ header: 'Name',
+ },
+ {
+ accessorFn: (originalRow) => Number(originalRow.age), //you should also get type hints for your accessorFn
+ header: 'Age',
+ Cell: ({ cell }) => {cell.getValue()}, //cell.getValue() will be typed as `unknown` by default, but you can pass a generic to get the correct type
+ //see the createMRTColumnHelper example below for a better way to get type safety with cell.getValue()
+ },
+];
+```
+
+#### createMRTColumnHelper Utility
+
+> New in V2 (After many requests)
+
+Alternatively you can use the `createMRTColumnHelper` utility function to define your columns. This works the same way as the TanStack `createColumnHelper`.
+
+Additional `TValue` type-safety is provided by using this utility. That means that when you call `cell.getValue()` in either a custom `Cell` render, or in any of the `mui*Props`, you will get the correct type for the data in that column instead of `unknown`.
+
+```tsx
+import {
+ MaterialReactTable,
+ useMaterialReactTable,
+ createMRTColumnHelper, // <--- import createMRTColumnHelper
+} from 'material-react-table';
+import { type User } from './types'; // <--- import your TData type from wherever you defined it (if using TS)
+
+const columnHelper = createMRTColumnHelper(); // <--- pass your TData type as a generic to createMRTColumnHelper (if using TS)
+
+//columns will be inferred as Array>
+const columns = [
+ //accessorKey as first argument, rest of column options as second argument
+ columnHelper.accessor('name', {
+ header: 'Last Name',
+ }),
+ //accessorFn as first argument, rest of column options as second argument
+ columnHelper.accessor((row) => Number(row.age), {
+ id; 'age', //id required for accessorFn
+ header: 'Age',
+ filterVariant: 'range-slider', //you should get type hints for all possible column options that you can define here
+ Cell: ({ cell }) => {cell.getValue()}, //cell.getValue() will be typed as number instead of unknown
+ }),
+ //display column (no accessor needed)
+ columnHelper.display({
+ header: 'Contact',
+ Cell: ({ row }) => (
+
+ ),
+ }),
+];
+```
+
+#### Use JSDoc instead of TypeScript
+
+If you are in a situation where you are not able to install TypeScript in your project, you can technically do the same thing as up above in JavaScript using JSDoc.
+
+```jsx
+import {
+ MaterialReactTable,
+ useMaterialReactTable,
+} from 'material-react-table';
+
+//define TData type with JSDoc
+/**
+ * @typedef {Object} User
+ * @property {number} id
+ * @property {string} name
+ * @property {number} age
+ */
+
+//import MRT_ColumnDef type with JSDoc
+/**
+ * @type {import('material-react-table').MRT_ColumnDef[]}
+ */
+const columns = [
+ {
+ accessorKey: 'id', //you should get type hints for all of your keys if you defined your TData type correctly
+ header: 'ID',
+ enableSorting: false, //you should get type hints for all possible column options that you can define here
+ },
+ {
+ accessorKey: 'name',
+ header: 'Name',
+ },
+ {
+ accessorFn: (originalRow) => Number(originalRow.age), //you should also get type hints for your accessorFn
+ header: 'Age',
+ },
+];
+```
+
+### Re-Usable MRT Components
+
+If you are going to have multiple tables in your app, chances are that you will want to make a re-usable component built on top of Material React Table. This is a good idea and good practice, but here are a few suggestions to maintain type safety with some TypeScript generics.
+
+#### Re-usable Components or Options?
+
+In my opinion, instead of creating a re-usable component, it is instead actually best to define your default options and share them between all of your tables.
+
+##### Re-usable Default Options
+
+In this example, we are simply creating a factory function that creates all of the default options that you want all of your tables to start with.
+
+```ts
+import { type MRT_RowData, type MRT_TableOptions } from 'material-react-table';
+
+//define re-useable default table options for all tables in your app
+export const getDefaultMRTOptions = (): Partial<
+ MRT_TableOptions
+> => ({
+ //list all of your default table options here
+ enableGlobalFilter: false,
+ enableRowPinning: true,
+ initialState: { showColumnFilters: true },
+ manualFiltering: true,
+ manualPagination: true,
+ manualSorting: true,
+ muiTableHeadCellProps: {
+ sx: { fontSize: '1.1rem' },
+ },
+ paginationDisplayMode: 'pages',
+ //etc...
+ defaultColumn: {
+ //you can even list default column options here
+ },
+});
+```
+
+Then you can use these options in every new table that you create:
+
+```tsx
+import {
+ MaterialReactTable,
+ useMaterialReactTable,
+ type MRT_ColumnDef,
+} from 'material-react-table';
+import { getDefaultMRTOptions } from './utils'; //your default options
+
+interface User {
+ id: number;
+ name: string;
+ age: number;
+}
+
+const defaultMRTOptions = getDefaultMRTOptions(); //get your default options
+
+export const OneOfYourTableComponents = () => {
+ const columns: MRT_ColumnDef[] = [
+ //...
+ ];
+
+ const { data } = useQuery({
+ //...
+ });
+
+ const table = useMaterialReactTable({
+ ...defaultMRTOptions, //spread your default options
+ columns,
+ data,
+ enableGlobalFilter: true, //override default options
+ initialState: {
+ ...defaultMRTOptions.initialState, //spread default initial state
+ showColumnFilters: false, //override default initial state for just this table
+ },
+ //...
+ });
+
+ //you will have access to the entire table instance where you need it
+ console.log(table.getState());
+
+ return ;
+};
+```
+
+Doing it this way, you maintain 100% control of your table instance and any state that you are managing in each table component.
+
+I believe this is by far the best way to work with Material React Table in your application code, and how I personally use it in my own apps.
+
+##### Re-usable MRT Component
+
+If you still want to just create a re-usable MRT component instead, you can do that too, of course. Here is a type-safe way to do that:
+
+```tsx
+import {
+ MaterialReactTable,
+ useMaterialReactTable,
+ type MRT_ColumnDef,
+ type MRT_RowData, //default shape of TData (Record)
+ type MRT_TableOptions,
+} from 'material-react-table';
+
+interface Props extends MRT_TableOptions {
+ columns: MRT_ColumnDef[];
+ data: TData[];
+}
+
+export const CustomMRTTable = ({
+ columns,
+ data,
+ ...rest
+}: Props) => {
+ const table = useMaterialReactTable({
+ columns,
+ data,
+ //your custom table options...
+ ...rest, //accept props to override default table options
+ });
+
+ return ;
+};
+```
+
+By using the `TData` generic correctly, you can maintain type-safety in your re-usable component that will adapt to different types of data you will have throughout your application.
+
+Though, be aware that the weakness of this approach is that it will be more annoying to get access to the `table` instance or read table state where you need it.
+
+When re-using your MRT table component, it will just look something like this:
+
+```tsx
+import { CustomMRTTable } from './CustomMRTTable';
+
+const columns: MRT_ColumnDef[] = [
+ //...
+];
+
+export const YourComponent = () => {
+ //no easy access to the table instance or table state here unless you manage all of the state in this component
+ const [pagination, setPagination] = useState({
+ pageIndex: 0,
+ pageSize: 10,
+ });
+ const [sorting, setSorting] = useState([]);
+ //etc...
+
+ const { data } = useQuery({
+ //...
+ });
+
+ return (
+
+ );
+};
+```
+
+### Debugging Material React Table
+
+Material React Table _(though really TanStack Table)_ can be a lot easier to debug than other data grid libraries. This is because you are often in charge of the state that you care about, and the entire table instance is available to you in your own scope if you are using the `useMaterialReactTable` hook. There are also some advanced TanStack Table Dev Tools that you can optionally install.
+
+#### Console Logging from the Table Instance
+
+When in doubt, console log it! There are a lot of things you can easily console log. Here are some examples:
+
+##### Console Log All Internal Table State
+
+```jsx
+const table = useMaterialReactTable({
+ columns,
+ data,
+ //** */
+});
+
+console.log(table.getState());
+```
+
+##### Console Log Current Rendering Rows
+
+```jsx
+const table = useMaterialReactTable({
+ columns,
+ data,
+ //** */
+});
+
+console.log(table.getRowModel().rows);
+```
diff --git a/apps/material-react-table-docs/pages/docs/guides/cell-actions.mdx b/apps/material-react-table-docs/pages/docs/guides/cell-actions.mdx
new file mode 100644
index 000000000..ec5aa947d
--- /dev/null
+++ b/apps/material-react-table-docs/pages/docs/guides/cell-actions.mdx
@@ -0,0 +1,161 @@
+import Head from 'next/head';
+import TableOptionsTable from '../../../components/prop-tables/TableOptionsTable';
+import ColumnOptionsTable from '../../../components/prop-tables/ColumnOptionsTable';
+import EnableExample from '../../../examples/enable-cell-actions';
+
+
+ {'Cell Actions Guide - Material React Table V2 Docs'}
+
+
+
+## Cell Actions Feature Guide
+
+> New in v2.10.0
+
+Material React Table provides you an easy shell to render a context menu for when a table cell/row is right clicked or otherwise activated. This is useful for providing additional actions that can be performed on a cell or row.
+
+### Relevant Table Options
+
+
+
+### Relevant Column Options
+
+
+
+### Enable Cell Actions
+
+To enable cell actions, you need to set the `enableCellActions` option to `true` for the cells that you want to have access to the context menu. This can be done at the table level or at the column level, and accepts a boolean or a function that returns a boolean.
+
+```jsx
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableCellActions: true,
+ //or
+ enableCellActions: (cell) => (cell.row.original.someCondition ? true : false),
+});
+```
+
+### Render Cell Action Menu Items
+
+The cell actions context menu will only appear if there are items to display. You can provide the `renderCellActionMenuItems` table option or column option to render the appropriate items in the context menu for each cell.
+
+MRT also provides a `MRT_ActionMenuItem` component that you can use to render the menu items. This just a wrapper for the MUI MenuItem component that also provides consistent CSS for styling the icons, spacing, and optional sub-menu items. Use it if you want to have a consistent look and feel with all of the other built-in MRT Menus.
+
+```jsx
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableCellActions: true,
+ renderCellActionMenuItems: ({ closeMenu, cell, row, table }) => [
+ //array required
+ }
+ key={1}
+ label="Item 1"
+ onClick={() => {
+ //your logic here
+ closeMenu(); //close the menu after the action is performed
+ }}
+ table={table}
+ />,
+ }
+ key={2}
+ label="Item 2"
+ onClick={async () => {
+ //await your logic here
+ closeMenu(); //close the menu after the async action is performed
+ }}
+ table={table}
+ />,
+ ],
+});
+```
+
+### Include Automatic Cell Actions
+
+A few cell actions are included by default when certain other features are enabled.
+
+- A "Copy" action will be included when the `enableClickToCopy` option is set to `"context-menu"` (instead of `true`) for the table or column.
+
+- An "Edit" action will be included when the `enableEditing` option is set to `true` and the `editDisplayMode` option is set to `"cell"`. This will not disable the default double-click to edit behavior, but will provide an additional way to edit the cell.
+
+More built-in cell actions may be added in the future.
+
+```jsx
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableCellActions: true,
+ enableClickToCopy: 'context-menu',
+ enableEditing: true,
+ editDisplayMode: 'cell',
+});
+```
+
+If you want to render these actions alongside your custom actions, you will just need to include the `internalMenuItems` parameter in your `renderCellActionMenuItems` function.
+
+```jsx
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableCellActions: true,
+ enableClickToCopy: 'context-menu',
+ enableEditing: true,
+ editDisplayMode: 'cell',
+ renderCellActionMenuItems: ({
+ closeMenu,
+ cell,
+ row,
+ table,
+ internalMenuItems,
+ }) => [
+ ...internalMenuItems, //render the copy and edit actions wherever you want in the list
+ , //optionally place a Menu Divider to separate groups of actions
+ }
+ key={1}
+ label="Item 1"
+ onClick={() => {
+ //your logic here
+ closeMenu(); //close the menu after the action is performed
+ }}
+ table={table}
+ />,
+ }
+ key={2}
+ label="Item 2"
+ onClick={async () => {
+ //await your logic here
+ closeMenu(); //close the menu after the async action is performed
+ }}
+ table={table}
+ />,
+ ],
+});
+```
+
+
+
+View Extra Storybook **[Examples](https://www.material-react-table.dev/?path=/story/features-cell-action-examples)**
diff --git a/apps/material-react-table-docs/pages/docs/guides/click-to-copy.mdx b/apps/material-react-table-docs/pages/docs/guides/click-to-copy.mdx
index 6658033e0..d9ebf8170 100644
--- a/apps/material-react-table-docs/pages/docs/guides/click-to-copy.mdx
+++ b/apps/material-react-table-docs/pages/docs/guides/click-to-copy.mdx
@@ -4,7 +4,7 @@ import ColumnOptionsTable from '../../../components/prop-tables/ColumnOptionsTab
import Example from '../../../examples/enable-click-to-copy';
- Click to Copy Feature Guide - Material React Table V2 Docs
+ Click to Copy Guide - Material React Table V2 Docs
- Column Actions Feature Guide - Material React Table V2 Docs
+ {'Column Actions Guide - Material React Table V2 Docs'}
+```jsx
+const table = useMaterialReactTable({
+ data,
+ columns,
+ enableColumnActions: false,
+});
+
+return ;
```
-Alternatively, if you only want to hide the column actions button in specific columns, you can set the `enableColumnActions` property for the desired column definition to `false` instead.
+Alternatively, if you only want to hide the column actions button in specific columns, you can set the `enableColumnActions` option for the desired column definition to `false` instead.
In this demo, we disable the column actions button for the 'ID' column.
@@ -57,28 +63,28 @@ In this demo, we disable the column actions button for the 'ID' column.
### Custom Column Actions Menu
-If you do not like the default column actions menu items that Material React Table generates, you can provide your own custom menu items with the `renderColumnActionsMenuItems` prop or column option. You can choose whether or not to include the internal menu items by using the `internalColumnMenuItems` parameter.
+If you do not like the default column actions menu items that Material React Table generates, you can provide your own custom menu items with the `renderColumnActionsMenuItems` table or column option. You can choose whether or not to include the internal menu items by using the `internalColumnMenuItems` parameter.
-```tsx
- {
+```jsx
+const table = useMaterialReactTable({
+ data,
+ columns,
+ renderColumnActionsMenuItems: ({ internalColumnMenuItems }) => {
return [
...internalColumnMenuItems, //optionally include the internal menu items above or below your custom menu items
,
,
];
- }}
-/>
+ },
+});
+
+return ;
```
### Justify Column Actions Button
-> Changed to left alignment in `v1.2.0`
-
By default, the column actions button is left aligned directly after the column header text and any sort or filter labels that may be present. If you want to change this, you can use a CSS selector in `muiTableHeadCellProps` to change the `justify-content` property of the column header container.
diff --git a/apps/material-react-table-docs/pages/docs/guides/column-filtering.mdx b/apps/material-react-table-docs/pages/docs/guides/column-filtering.mdx
index 20e0906c4..4b2fa913d 100644
--- a/apps/material-react-table-docs/pages/docs/guides/column-filtering.mdx
+++ b/apps/material-react-table-docs/pages/docs/guides/column-filtering.mdx
@@ -8,12 +8,9 @@ import CustomizeFilterVariantsExample from '../../../examples/customize-filter-v
import CustomizeFilterModesExample from '../../../examples/customize-filter-modes';
import CustomizeFilterComponentsExample from '../../../examples/customize-filter-components';
import EnableColumnFacetValuesExample from '../../../examples/enable-filter-facet-values';
-import RemoteExample from '../../../examples/remote';
-
- {'Column Filtering Feature Guide - Material React Table V2 Docs'}
-
+ {'Column Filtering Guide - Material React Table V2 Docs'}
`'autocomplete'`, `'date'`, and `'date-range'` variants are new in v2
+> `'autocomplete'`, `'date'`, and `'date-range'`, variants are new in v2.0.0
+>
+> `datetime`, `datetime-range`, `time`, and `time-range` variants are new in v2.4.0
#### Faceted Values for Filter Variants
-Faceted values are a list of unique values for a column that gets generated under the hood from table data when the `enableFacetedValues` prop is set to `true`. These values can be used to populate the select dropdowns for the `'select'` and `'multi-select'` filter variants, or the min and max values for the `'range-slider'` variant. This means that you no longer need to manually specify the `filterSelectOptions` prop for these variants manually, especially if you are using client-side filtering.
+Faceted values are a list of unique values for a column that gets generated under the hood from table data when the `enableFacetedValues` table option is set to `true`. These values can be used to populate the select dropdowns for the `'select'` and `'multi-select'` filter variants, or the min and max values for the `'range-slider'` variant. This means that you no longer need to manually specify the `filterSelectOptions` table option for these variants manually, especially if you are using client-side filtering.
@@ -121,23 +128,23 @@ Faceted values are a list of unique values for a column that gets generated unde
If you are using server-side pagination and filtering, you can still customize the faceted values output with the `getFacetedUniqueValues` and `getFacetedMinMaxValues` props.
-```tsx
- {
+ getFacetedMinMaxValues: (table) => {
//fetch min and max values from server
return [minValue, maxValue];
- }}
+ },
//if using server-side filtering
- getFacetedUniqueValues={(table) => {
+ getFacetedUniqueValues: (table) => {
const uniqueValueMap = new Map();
//fetch unique values from server, ideally including the count of each unique value
return uniqueValueMap;
- }}
-/>
+ },
+})
```
### Column Filter Display Modes
@@ -174,7 +181,7 @@ By default, Material React Table uses a `fuzzy` filtering algorithm based on the
##### Pre-built MRT Filter Functions
-> Pre-built filter functions from Material React Table include `between`, `betweenInclusive`, `contains`, `empty`, `endsWith`, `equals`, `fuzzy`, `greaterThan`, `greaterThanOrEqualTo`, `lessThan`, `lessThanOrEqualTo`, `notEmpty`, `notEquals`, and `startsWith`. View these algorithms [here](https://github.com/KevinVandy/material-react-table/blob/v2/packages/material-react-table/src/filterFns.ts)
+> Pre-built filter functions from Material React Table include `between`, `betweenInclusive`, `contains`, `empty`, `endsWith`, `equals`, `fuzzy`, `greaterThan`, `greaterThanOrEqualTo`, `lessThan`, `lessThanOrEqualTo`, `notEmpty`, `notEquals`, and `startsWith`. View these algorithms [here](https://github.com/KevinVandy/material-react-table/blob/v2/packages/material-react-table/src/fns/filterFns.ts)
##### Pre-built TanStack Table Filter Functions
@@ -216,7 +223,7 @@ This function will be used to filter 1 row at a time and should return a `boolea
#### Add Custom Filter Functions
-You can add custom filter functions to the `filterFns` prop. These will be available to all columns to use. The `filterFn` prop on a column will override any filter function with the same name in the `filterFns` prop.
+You can add custom filter functions to the `filterFns` table option. These will be available to all columns to use. The `filterFn` table option on a column will override any filter function with the same name in the `filterFns` table option.
```jsx
const columns = [
@@ -227,32 +234,34 @@ const columns = [
},
];
-return (
- {
- return row.customField === value;
- },
- }}
- />
-);
+const table = useMaterialReactTable({
+ columns,
+ data,
+ filterFns: {
+ customFilterFn: (row, id, filterValue) => {
+ return row.customField === value;
+ },
+ },
+});
```
### Filter Modes
#### Enable Column Filter Modes (Filter Switching)
-If you want to let the user switch between multiple different filter modes from a drop-down menu on the Filter Textfield, you can enable that with the `enableColumnFilterModes` prop or column option. This will enable the filter icon in the filter text field to open a drop-down menu with the available filter modes when clicked.
+If you want to let the user switch between multiple different filter modes from a drop-down menu on the Filter Textfield, you can enable that with the `enableColumnFilterModes` table option or column option. This will enable the filter icon in the filter text field to open a drop-down menu with the available filter modes when clicked.
```tsx
-
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableColumnFilterModes: true,
+});
```
#### Customize Filter Modes
-You can narrow down the available filter mode options by setting the `columnFilterModeOptions` prop or a column specific `columnFilterModeOptions` option.
+You can narrow down the available filter mode options by setting the `columnFilterModeOptions` table option or a column specific `columnFilterModeOptions` option.
```tsx
const columns = [
@@ -271,7 +280,7 @@ const columns = [
#### Render Custom Filter Mode Menu
-You can also render custom menu items in the filter mode drop-down menu by setting the `renderColumnFilterModeMenuItems` prop or column option. This option is a function that takes in the column and returns an array of `MenuItem` components. This is useful if you want to add custom filter modes that are not included in Material React Table, or if you just want to render the menu in your own custom way
+You can also render custom menu items in the filter mode drop-down menu by setting the `renderColumnFilterModeMenuItems` table option or column option. This option is a function that takes in the column and returns an array of `MenuItem` components. This is useful if you want to add custom filter modes that are not included in Material React Table, or if you just want to render the menu in your own custom way
```jsx
const columns = [
@@ -295,14 +304,14 @@ const columns = [
},
];
-return (
-
-);
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableColumnFilterModes: true,
+ // renderColumnFilterModeMenuItems could go here if you want to apply to all columns
+});
+
+return ;
```
@@ -315,9 +324,9 @@ Check out the [Expanded Leaf Row Filtering Behavior docs](/docs/guides/expanding
### Manual Server-Side Column Filtering
-A very common use case when you have a lot of data is to filter the data on the server, instead of client-side. In this case, you will want to set the `manualFiltering` prop to `true` and manage the `columnFilters` state yourself like so (can work in conjunction with [manual global filtering](https://www.material-react-table.com/docs/guides/global-filtering#manual-server-side-global-filtering)).
+A very common use case when you have a lot of data is to filter the data on the server, instead of client-side. In this case, you will want to set the `manualFiltering` table option to `true` and manage the `columnFilters` state yourself like so (can work in conjunction with [manual global filtering](https://www.material-react-table.com/docs/guides/global-filtering#manual-server-side-global-filtering)).
-```tsx
+```jsx
// You can manage and have control over the columnFilters state yourself
const [columnFilters, setColumnFilters] = useState([]);
const [data, setData] = useState([]); //data will get updated after re-fetching
@@ -330,28 +339,26 @@ useEffect(() => {
};
}, [columnFilters]);
-return (
-
-);
+const table = useMaterialReactTable({
+ columns,
+ data, // this will already be filtered on the server
+ manualFiltering: true, //turn off client-side filtering
+ onColumnFiltersChange: setColumnFilters, //hoist internal columnFilters state to your state
+ state: { columnFilters }, //pass in your own managed columnFilters state
+});
+
+return ;
```
> Specifying `manualFiltering` turns off all client-side filtering and assumes that the `data` you pass to `` is already filtered.
-Here is the full Remote Data example featuring server-side **filtering**, pagination, and sorting.
-
-
+See either the [React Query](/docs/examples/react-query) or [useEffect fetching](/docs/examples/remote) examples to see fully server-side **filtering**, pagination, and sorting in action.
### Customize Material UI Filter components
-You can customize the Material UI filter components by setting the `muiFilterTextFieldProps` prop or column option.
+You can customize the Material UI filter components by setting the `muiFilterTextFieldProps` table option or column option.
-You can also turn a filter textfield into a select dropdown by setting the `filterSelectOptions` prop or column option.
+You can also turn a filter textfield into a select dropdown by setting the `filterSelectOptions` table option or column option.
@@ -363,7 +370,7 @@ If you need custom filter components that are much more complex than text-boxes
Filter Match Highlighting is a new featured enabled by default that will highlight text in the table body cells that matches the current filter query with a shade of the `theme.palette.warning.main` color.
-Filter Match Highlighting will only work on columns with the default `text` filter variant. Also, if you are using a custom `Cell` render override for a column, you will need to use the `renderedCellValue` prop instead of `cell.getValue()` in order to preserve the filter match highlighting.
+Filter Match Highlighting will only work on columns with the default `text` filter variant. Also, if you are using a custom `Cell` render override for a column, you will need to use the `renderedCellValue` table option instead of `cell.getValue()` in order to preserve the filter match highlighting.
```jsx
const columns = [
@@ -377,14 +384,14 @@ const columns = [
#### Disable Filter Match Highlighting
-This feature can be disabled by setting the `enableFilterMatchHighlighting` prop to `false`.
+This feature can be disabled by setting the `enableFilterMatchHighlighting` table option to `false`.
```jsx
-
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableFilterMatchHighlighting: false,
+});
```
View Extra Storybook **[Examples](https://www.material-react-table.dev/?path=/story/features-filtering-examples)**
diff --git a/apps/material-react-table-docs/pages/docs/guides/column-grouping.mdx b/apps/material-react-table-docs/pages/docs/guides/column-grouping.mdx
new file mode 100644
index 000000000..8d5353ef4
--- /dev/null
+++ b/apps/material-react-table-docs/pages/docs/guides/column-grouping.mdx
@@ -0,0 +1,213 @@
+import Head from 'next/head';
+import TableOptionsTable from '../../../components/prop-tables/TableOptionsTable';
+import ColumnOptionsTable from '../../../components/prop-tables/ColumnOptionsTable';
+import StateOptionsTable from '../../../components/prop-tables/StateOptionsTable';
+import ColumnGroupingExample from '../../../examples/enable-column-grouping';
+import CustomizeRemoveColumnGroupingExample from '../../../examples/customize-remove-column-grouping';
+
+
+ {'Column Grouping Guide - Material React Table V2 Docs'}
+
+
+
+## Column Grouping Feature Guide
+
+Material React Table has built-in column grouping features. There are options for both automatic client-side grouping as well as manual server-side grouping. This guide will walk you through the different options and how to use and customize them.
+
+### Relevant Table Options
+
+
+
+### Relevant Column Options
+
+
+
+### Relevant State
+
+
+
+### Enable Grouping
+
+To enable grouping, set the `enableGrouping` table option to `true`. This will both add a drag handle button so that columns can be dragged to the dropzone to be grouped and will add an entry column actions menu to group or ungroup a column.
+
+```jsx
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableGrouping: true,
+});
+```
+
+### Grouped Column Mode
+
+> New in v2.5.0, The `"remove"` columnGroupMode now has an official UI implementation
+
+The `groupedColumnMode` table option controls how grouped columns are displayed once a column has been grouped. There are three options:
+
+1. `"reorder"` (default) - Grouped columns will be displayed as the first columns in the table, followed by the 'mrt-row-expand' display column, followed by the remaining columns in their original order.
+2. `"remove"` - Grouped columns will be removed from the table and only their aggregate values will be displayed alongside the expand button in the 'mrt-row-expand' display column, followed by the remaining columns in their original order.
+3. `false` - Grouping columns will have no effect on the column order. The 'mrt-row-expand' display column will be displayed as the first column in the table, followed by the remaining columns in their original order.
+
+```jsx
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableGrouping: true,
+ groupedColumnMode: 'remove', //instead of default "reorder"
+});
+```
+
+
+
+#### Disable Grouping Per Column
+
+```jsx
+const columns = [
+ {
+ accessorKey: 'name',
+ header: 'Name',
+ enableGrouping: false, // disable grouping for this column
+ },
+ {
+ accessorKey: 'age',
+ header: 'Age',
+ },
+];
+
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableGrouping: true,
+});
+
+return ;
+```
+
+#### Hide Drag Buttons for Grouping
+
+If you do not want the drag buttons that come with the grouping feature, you can independently disable them without disabling the grouping feature entirely by setting the `enableColumnDragging` table option to `false`.
+
+```jsx
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableGrouping: true,
+ enableColumnDragging: false, //do not show drag handle buttons, but still show grouping options in column actions menu
+});
+
+return ;
+```
+
+### Group Columns by Default
+
+If you want columns to be grouped by default, you can set the `grouping` state in either the `initialState` or `state` table option.
+
+```jsx
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableGrouping: true,
+ initialState: { grouping: ['location', 'department'] }, //group by location and department by default
+});
+
+return ;
+```
+
+### Expand Grouped Rows by Default
+
+In addition to grouping columns by default, you may also want those grouped rows to be expanded and visible by default, too. You can do this by setting the `expanded` state to `true` in either the `initialState` or `state` table option.
+
+```jsx
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableGrouping: true,
+ initialState: {
+ grouping: ['location', 'department'], //group by location and department by default and expand grouped rows
+ expanded: true, //show grouped rows by default
+ },
+});
+
+return ;
+```
+
+### Customize Expand Column
+
+You can customize the expand column by using the `displayColumnDefOptions` table option.
+
+```jsx
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableGrouping: true,
+ displayColumnDefOptions: {
+ 'mrt-row-expand': {
+ size: 120, //make the expand column wider
+ },
+ },
+});
+```
+
+Going further, you can completely overhaul how the expand column renders using custom `Cell` and `Header` renders here for advanced use cases.
+
+```jsx
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableGrouping: true,
+ displayColumnDefOptions: {
+ 'mrt-row-expand': {
+ Cell: ({ row, table }) => {
+ return (
+ <>
+
+ {/*custom content*/}
+
+ );
+ },
+ Header: ({ table }) => {
+ return (
+ <>
+
+ {/*custom content*/}
+
+ );
+ },
+ },
+ },
+});
+```
+
+
+
+### Manual Grouping
+
+Manual Grouping means that the `data` that you pass to the table is already grouped and aggregated, and you do not want Material React Table to do any of the grouping or aggregation for you. This is useful if you are using a backend API to do the grouping and aggregation for you, and you just want to display the results. However, you will need to put your data in the specific format that the `expanding` features understand.
+
+> Learn more about [Expanding Sub Rows](/docs/guides/expanding-sub-rows) and [Aggregation](/docs/guides/aggregation) Features in their own dedicated guides.
diff --git a/apps/material-react-table-docs/pages/docs/guides/column-hiding.mdx b/apps/material-react-table-docs/pages/docs/guides/column-hiding.mdx
index a875a219f..a3af15b81 100644
--- a/apps/material-react-table-docs/pages/docs/guides/column-hiding.mdx
+++ b/apps/material-react-table-docs/pages/docs/guides/column-hiding.mdx
@@ -5,7 +5,7 @@ import StateOptionsTable from '../../../components/prop-tables/StateOptionsTable
import Example from '../../../examples/disable-column-hiding';
- Column Hiding Feature Guide - Material React Table V2 Docs
+ {'Column Hiding Guide - Material React Table V2 Docs'}
+
### Relevant State
@@ -34,44 +36,108 @@ The column hiding feature is enabled by default and allows the user to hide data
You can easily hide columns by default by setting the `columnVisibility` `state` or `initialState` to hide the desired columns by id.
-```tsx
-
+```jsx
+const table = useMaterialReactTable({
+ columns,
+ data,
+ initialState: { columnVisibility: { firstName: false } }, //hide firstName column by default
+});
+
+return ;
+```
+
+### Dynamically Hide Columns
+
+If you need to control how the columns are hidden dynamically, you can use `state` instead of `initialState` along with the `onColumnVisibilityChange` table option. Or alternatively you can use the `setColumnVisibility` table instance api.
+
+```jsx
+const [columnVisibility, setColumnVisibility] = useState({
+ firstName: false,
+});
+
+useEffect(() => {
+ setColumnVisibility({ firstName: true }); //programmatically show firstName column
+}, [someDependency]);
+
+const table = useMaterialReactTable({
+ columns,
+ data,
+ state: { columnVisibility }, //manage columnVisibility state
+ onColumnVisibilityChange: setColumnVisibility,
+});
+
+//NOTE: Instead of managing the columnVisibility state yourself, we could call a table instance api
+table.setColumnVisibility({ firstName: true }); //programmatically show firstName column
```
### Disable Column Hiding
-If you do not want this feature to be enabled at all, you can disable it by setting the `enableHiding` prop to `false`.
+If you do not want this feature to be enabled at all, you can disable it by setting the `enableHiding` table option to `false`.
-```tsx
-
+```jsx
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableHiding: false,
+});
```
Alternatively, you can disable hiding specific columns by setting the `enableHiding` column option to `false` per column.
-If you want to hide certain columns by default, you can specify an column visibility in the `initialState.columnVisibility` prop. This can also be useful for making the column hiding state persistent.
+If you want to hide certain columns by default, you can specify column visibility in the `initialState.columnVisibility` table option.
### Enable Column Hiding on Display Columns
-By default, column hiding is only enabled on data columns. Display columns, such as `mrt-row-numbers`, `mrt-row-select`, etc., do not have column hiding enabled, and their toggle will be disabled. You can turn that back on by setting the `enableHiding` option to `true` in the `displayColumnsOptions` prop.
+By default, column hiding is only enabled on data columns. Display columns, such as `mrt-row-numbers`, `mrt-row-select`, etc., do not have column hiding enabled, and their toggle will be disabled. You can turn that back on by setting the `enableHiding` option to `true` in the `displayColumnsOptions` table option.
-```tsx
-
+ },
+});
```
-See the [Display Columns Feature Guide](/docs/guides/display-columns#display-column-definition-options-prop) for a more in depth explanation of the `displayColumnsOptions` prop.
+See the [Display Columns Feature Guide](/docs/guides/display-columns#display-column-definition-options-prop) for a more in depth explanation of the `displayColumnsOptions` table option.
+
+### Hide Column From Show Hide Menu
+
+> New in v2.3.0
+
+By default, all columns are visible in the column show hide menu that is opened from the columns button in the toolbar internal actions button. You can hide a column from this menu by setting the `visibleInShowHideMenu` column option to `false`.
+
+```jsx
+const columns = [
+ {
+ accessorKey: 'uuid',
+ header: 'UUID',
+ visibleInShowHideMenu: false, //hide this column from the show hide menu, but still show the column in the table
+ },
+];
+
+const table = useMaterialReactTable({
+ columns,
+ data,
+ displayColumnDefOptions: {
+ 'mrt-row-actions': {
+ visibleInShowHideMenu: false, //hide the built-in row actions column from the show hide menu
+ },
+ },
+});
+```
+
+### Custom Columns Menu
+
+The `MRT_ShowHideColumnsMenu` component is one of the few MRT components that is pretty opinionated and not easily customizable. Instead of trying to customize the menu with overrides, it might be easier for you to just build your own new button and menu from scratch using the Table and Column Instance APIs.
+
+Adding your own Toolbar Buttons is covered in the [Toolbar Guide](/docs/guides/toolbar-customization#customize-built-in-internal-toolbar-button-area)
+
+If all you want to do is customize the buttons above the columns menu, you can import and use the `MRT_ShowHideColumnsMenuItems` component from material react table, which is a component that renders the columns in the list with the toggle switches, but then render your own buttons in the top or bottom of the menu itself.
View Extra Storybook **[Examples](https://www.material-react-table.dev/?path=/story/features-column-hiding-examples)**
diff --git a/apps/material-react-table-docs/pages/docs/guides/column-ordering-dnd.mdx b/apps/material-react-table-docs/pages/docs/guides/column-ordering-dnd.mdx
index b2d5fb308..44eaca780 100644
--- a/apps/material-react-table-docs/pages/docs/guides/column-ordering-dnd.mdx
+++ b/apps/material-react-table-docs/pages/docs/guides/column-ordering-dnd.mdx
@@ -5,7 +5,7 @@ import StateOptionsTable from '../../../components/prop-tables/StateOptionsTable
import DNDExample from '../../../examples/enable-column-ordering';
- Column Ordering/DnD Feature Guide - Material React Table V2 Docs
+ {'Column Ordering/DnD Guide - Material React Table V2 Docs'}
+ },
+});
+
+return ;
```
+> **Note:** If the number of `columns` and the length of the `columnOrder` state do not match, MRT will automatically re-generate the `columnOrder` state internally as of v2.10.0.
+
### Manage Column Order State
-If you need to manage the `columnOrder` state yourself, you can do so in the `state` prop and `onColumnOrderChange` callback, but you will also need to initialize the `columnOrder` state yourself.
+If you need easier access to the `columnOrder` state, you can store the column order in your own state management, and then pass it back into the MRT `state` table option and sync back up internal mutations with the `onColumnOrderChange` callback.
+
+You should also should initialize the `columnOrder` state yourself for the best results. Though, as of v2.10.0, if you do not initialize the `columnOrder` state, as Material React Table will generate a default column order for you based on the order of the columns passed in the `columns` option, so you only need to properly initialize the column order state if there is a problem with the default order.
```jsx
const columns = [
@@ -77,23 +87,25 @@ const columns = [
//easy shortcut to initialize the columnOrder state as array of column ids
const [columnOrder, setColumnOrder] = useState(
- columns.map((c) => c.accessorKey), //array of column ids
+ ['mrt-row-select', ...columns.map((c) => c.accessorKey)], //array of column ids (Initializing is optional as of v2.10.0)
);
-return (
-
-);
+const table = useMaterialReactTable({
+ data,
+ columns,
+ enableRowSelection: true,
+ state: {
+ columnOrder,
+ },
+ onColumnOrderChange: setColumnOrder,
+});
+
+return ;
```
### Enable Column Ordering with Drag and Drop
-Material React Table has a built-in drag and drop feature to reorder columns. This feature is enabled by passing the `enableColumnOrdering` prop.
+Material React Table has a built-in drag and drop feature to reorder columns. This feature is enabled by passing the `enableColumnOrdering` table option.
The ability for a column to have a drag and drop handle can be specified by setting the `enableColumnOrdering` option on the column.
diff --git a/apps/material-react-table-docs/pages/docs/guides/column-pinning.mdx b/apps/material-react-table-docs/pages/docs/guides/column-pinning.mdx
index e963bfbba..4ffc97aaa 100644
--- a/apps/material-react-table-docs/pages/docs/guides/column-pinning.mdx
+++ b/apps/material-react-table-docs/pages/docs/guides/column-pinning.mdx
@@ -5,7 +5,7 @@ import StateOptionsTable from '../../../components/prop-tables/StateOptionsTable
import Example from '../../../examples/enable-column-pinning';
- Column Pinning Feature Guide - Material React Table V2 Docs
+ {'Column Pinning Guide - Material React Table V2 Docs'}
+
### Relevant State
@@ -32,23 +32,46 @@ Column pinning is a cool feature that lets users pin (freeze) columns to the lef
### Enable Column Pinning
-Column pinning can simply be enabled by setting the `enableColumnPinning` prop to `true`.
+Column pinning can simply be enabled by setting the `enableColumnPinning` table option to `true`.
-```tsx
-
+```jsx
+const table = useMaterialReactTable({
+ data,
+ columns,
+ enableColumnPinning: true,
+});
+
+return ;
```
### Pin (Freeze) Columns By Default
Columns can start out pinned in your table by setting the `columnPinning` states in `initialState` or `state`.
-```tsx
-
+```jsx
+const table = useMaterialReactTable({
+ data,
+ columns,
+ enableColumnPinning: true,
+ initialState: { columnPinning: { left: ['email'] } }, //pin email column to left by default
+});
+
+return ;
+```
+
+### Apply Absolute Column Widths
+
+You might consider using the `layoutMode: 'grid-no-grow'` table option to give all columns an exact width if you don't want the columns collapsing a little while scrolling. Some people like this subtle behavior, but others do not.
+
+```jsx
+const table = useMaterialReactTable({
+ data,
+ columns,
+ enableColumnPinning: true,
+ layoutMode: 'grid-no-grow',
+});
+
+return ;
```
#### Column Pinning Example
diff --git a/apps/material-react-table-docs/pages/docs/guides/column-resizing.mdx b/apps/material-react-table-docs/pages/docs/guides/column-resizing.mdx
index 0f70f06ff..b58bae63b 100644
--- a/apps/material-react-table-docs/pages/docs/guides/column-resizing.mdx
+++ b/apps/material-react-table-docs/pages/docs/guides/column-resizing.mdx
@@ -3,11 +3,10 @@ import TableOptionsTable from '../../../components/prop-tables/TableOptionsTable
import ColumnOptionsTable from '../../../components/prop-tables/ColumnOptionsTable';
import StateOptionsTable from '../../../components/prop-tables/StateOptionsTable';
import Example from '../../../examples/enable-column-resizing';
+import RTLExample from '../../../examples/localization-i18n-fa';
-
- {'Column Resizing Feature Guide - Material React Table V2 Docs'}
-
+ {'Column Resizing Guide - Material React Table V2 Docs'}
The Column Size features was recently split into its own [Guide](/docs/guides/column-size). View that guide as a prerequisite to this one.
+
+### Relevant Table Options
### Relevant State
@@ -45,104 +51,123 @@ Material React Table lets you easily change the default widths (sizes) of column
onlyOptions={new Set(['columnSizing', 'columnSizingInfo'])}
/>
-### Layout Modes
-
-Material React Table has 3 layout modes that affect how columns styles are applied internally. Depending on which features you enable, the `layoutMode` table option will automatically change to the appropriate value, though you can override it with your own value if you want.
-
-1. `"semantic"` (default with default features) - uses default css styles that come with ``, ``, `| `, etc. elements.
-2. `"grid"` (default when virtualization is enabled) - uses CSS Grid and Flexbox styles instead of default styles.
-3. `"grid-no-grow"` (default when column resizing is enabled) - uses CSS Grid and Flexbox styles, but also sets `flex-grow: 0` on all columns.
+### Initial Column Sizes
-### Change Default Column Widths
+Column sizes will behave differently depending on which `layoutMode` you have set.
-#### Column Size
+See the [Column Size Guide](/docs/guides/column-size) for more information on layout modes and how to set initial column sizes properly for you use case.
-This was also covered in the [Data Columns Guide](/docs/guides/data-columns), but we'll cover it again here.
+### Enable Column Resizing Feature
-You can change the width of any column by setting its `size` option on the column definition. `minSize` and `maxSize` are also available to enforce limits during resizing.
+`enableColumnResizing` is the boolean table option that enables the column resizing feature.
```jsx
-const columns = [
- {
- accessorKey: 'id',
- header: 'ID',
- size: 50, //small column
- },
- {
- accessorKey: 'username',
- header: 'Username',
- minSize: 100, //min size enforced during resizing
- maxSize: 400, //max size enforced during resizing
- size: 180, //medium column
- },
- {
- accessorKey: 'email',
- header: 'Email',
- size: 300, //large column
- },
-];
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableColumnResizing: true,
+});
+
+return ;
```
-#### Default Column
+You can disable specific columns from being resizable by setting the `enableResizing` column option to false in their respective column definition.
+
+### Column Resize Mode
-By default, columns will have the following size properties defined:
+The default `columnResizeMode` is `onChange` (in MRT versions v1.7+), which means that the column resizing will occur immediately as the user drags the column resize handle. If you are running into performance issues because of many other enabled features, you might want to set the `columnResizeMode` to `onEnd` instead. This will make the column resizing only occur after the user has finished dragging the column resize handle and released their mouse.
```jsx
-defaultColumn = { minSize: 40, maxSize: 1000, size: 180 }; //units are in px
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableColumnResizing: true,
+ columnResizeMode: 'onEnd', //instead of the default "onChange" mode
+});
```
-You can modify the default column widths by setting the `defaultColumn` prop on the table.
+
+
+### Column Growing
+
+> MRT V2 has a new "opposite" behavior in regards to column sizes when column resizing is enabled compared to MRT V2
+
+When column resizing is enabled, by default, a layoutMode of `"grid-no-grow"` will be applied internally. This means that columns will have an absolute size and they will NOT grow to fill in the remaining space of the table. You can let columns grow to fill in the remaining space by changing the `layoutMode` back to `"grid"` or `"semantic"`.
```jsx
-
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableColumnResizing: true,
+ layoutMode: 'grid', //instead of the default "grid-no-grow" when column resizing is enabled
+});
```
-### Enable Column Resizing Feature
-
-`enableColumnResizing` is the boolean prop that enables the column resizing feature.
+Alternatively, if you only want certain columns to grow to fill the remaining space, you can set the `grow` column option to `true` in their respective column definitions.
```jsx
-
+const columns = [
+ //...
+ {
+ accessorKey: 'address',
+ header: 'Address',
+ size: 250,
+ grow: true, //allow this column to grow to fill the remaining space
+ },
+];
```
-You can disable specific columns from being resizable by setting the `enableResizing` column option to false in their respective column definition.
+This is discussed in more detail in the [Column Size Guide](/docs/guides/column-size#column-grow).
-#### Column Resize Mode
+### Column Resize Direction
-The default `columnResizeMode` is `onChange` (in MRT versions v1.7+), which means that the column resizing will occur immediately as the user drags the column resize handle. If you are running into performance issues because of many other enabled features, you might want to set the `columnResizeMode` to `onEnd` instead. This will make the column resizing only occur after the user has finished dragging the column resize handle and released their mouse.
+> New in V2.1
+
+If you are displaying your table in a RTL (right-to-left) language, you can set the `columnResizeDirection` table option to `"rtl"` to make the column resize handle appear on the left side of the column instead of the right side. This may behave differently depending on which Emotion or MUI theme settings you have enabled.
+
+If you have already set the proper `theme.direction` setting in your MUI theme, then this option will already have been set automatically for you, but you can still override it using the `columnResizeDirection` table option.
```jsx
-
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableColumnResizing: true,
+ columnResizeDirection: 'rtl', //instead of the default "ltr" direction
+});
+
+return (
+
+ {' '}
+ {/* app-wide style? */}
+
+
+);
```
-
+
-#### Enable Column Growing
+### Enable Resizing on Built-in Display Columns
-> MRT V2 has a new "opposite" behavior in regards to column sizes when column resizing is enabled compared to MRT V2
+As discussed further in the [Display Columns Guide](/docs/guides/display-columns), you can customize the options of the built-in columns that get generated under the hood by MRT by enabling certain features.
-When column resizing is enabled, by default, a layoutMode of `"grid-no-grow"` will be applied internally. This means that columns will have an absolute size and they will not grow to fill in the remaining space of the table.
+Here, we can enable column resizing on the built-in row numbers column by setting the `enableResizing` column option to true in the `displayColumnDefOptions` table option.
```jsx
-
+const table = useMaterialReactTable({
+ columns,
+ data,
+ displayColumnDefOptions: {
+ 'mrt-row-numbers': {
+ enableResizing: true, //allow the row numbers column to be resized
+ size: 40,
+ grow: false, //new in v2.8 - do not fill remaining space using this column
+ },
+ },
+ enableRowNumbers: true,
+ layoutMode: 'grid', // `grow` only works in the grid* layout modes
+});
+
+return ;
```
View Extra Storybook **[Examples](https://www.material-react-table.dev/?path=/story/features-column-resizing-examples)**
diff --git a/apps/material-react-table-docs/pages/docs/guides/column-size.mdx b/apps/material-react-table-docs/pages/docs/guides/column-size.mdx
new file mode 100644
index 000000000..581b31e65
--- /dev/null
+++ b/apps/material-react-table-docs/pages/docs/guides/column-size.mdx
@@ -0,0 +1,174 @@
+import Head from 'next/head';
+import TableOptionsTable from '../../../components/prop-tables/TableOptionsTable';
+import ColumnOptionsTable from '../../../components/prop-tables/ColumnOptionsTable';
+import StateOptionsTable from '../../../components/prop-tables/StateOptionsTable';
+
+
+ {'Column Size Guide - Material React Table V2 Docs'}
+
+
+
+## Column Size Feature Guide
+
+Material React Table lets you easily change the default widths (sizes) of columns.
+
+### Relevant Table Options
+
+
+
+### Relevant Column Options
+
+
+
+### Relevant State
+
+
+
+### Layout Modes
+
+Material React Table has 3 layout modes that affect how columns styles are applied internally. Depending on which features you enable, the `layoutMode` table option will automatically change to the appropriate value, though you can override it with your own value if you want.
+
+1. `"semantic"` (default with default features) - uses default css styles that come with ``, ``, ``, etc. elements.
+2. `"grid"` (default when virtualization is enabled) - uses CSS Grid and Flexbox styles instead of default styles.
+3. `"grid-no-grow"` (default when column resizing is enabled) - uses CSS Grid and Flexbox styles, but also sets `flex-grow: 0` on all columns and adds an empty "spacer" column to the end of the table to fill the potential remaining space.
+
+If you want your columns to have an absolute width, you can use the `"grid-no-grow"` layout mode and set the `size` option on each column.
+
+### Column Size
+
+You can change the width of any column by setting its `size` option on the column definition. There are `minSize` and `maxSize` column options available to enforce limits during resizing events.
+
+The `size`, `minSize`, and `maxSize` do not take in any CSS width unit. They are only numbers that represent the width of the column in pixels.
+
+```jsx
+const columns = [
+ {
+ accessorKey: 'id',
+ header: 'ID',
+ grow: false, //don't allow this column to grow to fill in remaining space - new in v2.8
+ size: 50, //small column
+ },
+ {
+ accessorKey: 'username',
+ header: 'Username',
+ minSize: 100, //min size enforced during resizing
+ maxSize: 400, //max size enforced during resizing
+ size: 180, //medium column
+ },
+ {
+ accessorKey: 'email',
+ header: 'Email',
+ grow: true, //allow this column to grow to fill in remaining space - new in v2.8
+ size: 300, //large column
+ },
+];
+```
+
+### Column Grow
+
+> New in v2.8 - You can now set a `grow` column option if using layoutMode `"grid-no-grow"` or `"grid"`
+
+You can also set `grow` properties on the column definitions when using layoutMode `"grid-no-grow"` or `"grid"`.
+
+If the layout mode of your table is `"grid"` and you set `grow: false` on a column, that column will have a fixed size and will not grow to fill in the remaining space of the table.
+
+If the layout mode of your table is `"grid-no-grow"` and you set `grow: true` on a column, that column will grow to fill in the remaining space of the table.
+
+If the layout mode of your table is `"grid-no-grow"` and you set `grow: 1` on one column, and `grow: 2` on another column, the first column will grow to fill in 1/3 of the remaining space of the table, and the second column will grow to fill in 2/3 of the remaining space of the table.
+
+If the layout mode of your table is `"semantic"`, the `grow` column option will have no effect, but columns will size themselves to fit their own content better than the other layout modes.
+
+### But I Want My Columns to Have a Percentage Width
+
+Material React Table is not designed to use percentage column widths well by default. This is because having horizontal scrollbars on tables is both a very common use case, and usually the best way to ensure that the actual content of the cells in each column is visible and not cutoff or wrapped excessively.
+
+If you disagree with that, that's fair, and you're not out of luck. Material React Table exposes all mui props, so if you really want to, you can add whatever CSS you want to achieve your own custom column widths behavior. This is not recommended by the maintainer, but some developers have found it useful to set all column sizes and minSizes to a very small number like `1`, `1.5`, `2`, ect., and then use either `layoutMode: "semantic"` or `layoutMode: "grid"`. This makes the columns act more like they are using percentage widths, up until a certain point. If you really need to never have a horizontal scrollbar, you can edit the `muiTableContainerProps.sx` styles to set `overflowX: "hidden"`. Be very careful with this though, as this could cause your table to be unusable on smaller screens.
+
+If the above still does not get you to where you need to be, `muiTableHeadCellProps.sx`, `muiTableBodyCellProps.sx`, and `muiTableFooterCellProps.sx` and more are all exposed and available to you to override with whatever custom CSS that you need. Just be aware that non of the built-in TanStack Table size APIs will be accurate anymore.
+
+#### Side Note: Just Make Your Scrollbars Prettier
+
+Making your scrollbars look better (especially on Windows and Linux) can go a long way to not letting a horizontal scrollbar ruin the look of your table.
+
+Here's what this docs site uses in its global CSS to make scrollbars to more like the default Mac OS scrollbars for everyone:
+
+```css
+::-webkit-scrollbar-track {
+ background-color: transparent;
+}
+
+::-webkit-scrollbar {
+ right: 0;
+ width: 12px;
+ height: 12px;
+}
+
+::-webkit-scrollbar-thumb {
+ background-color: #999;
+ border-radius: 8px;
+ width: 12px;
+ height: 12px;
+}
+```
+
+### Default Column
+
+By default, columns will have the following size properties defined:
+
+```jsx
+defaultColumn = { minSize: 40, maxSize: 1000, size: 180 }; //units are in px
+```
+
+You can modify the default column widths by setting the `defaultColumn` table option on the table.
+
+```jsx
+const table = useMaterialReactTable({
+ columns,
+ data,
+ defaultColumn: {
+ minSize: 20, //allow columns to get smaller than default
+ maxSize: 9001, //allow columns to get larger than default
+ size: 260, //make columns wider by default
+ },
+});
+```
+
+### Change Sizes of Built-in Display Columns
+
+As discussed further in the [Display Columns Guide](/docs/guides/display-columns), you can customize the options of the built-in columns that get generated under the hood by MRT by enabling certain features.
+
+```jsx
+const table = useMaterialReactTable({
+ columns,
+ data,
+ displayColumnDefOptions: {
+ 'mrt-row-select': {
+ size: 50, //adjust the size of the row select column
+ grow: false, //new in v2.8 (default is false for this column)
+ },
+ 'mrt-row-numbers': {
+ size: 40,
+ grow: true, //new in v2.8 (allow this column to grow to fill in remaining space)
+ },
+ },
+ enableRowNumbers: true,
+});
+
+return ;
+```
+
+View Extra Storybook **[Examples](https://www.material-react-table.dev/?path=/story/styling-custom-column-widths)**
diff --git a/apps/material-react-table-docs/pages/docs/guides/customize-components.mdx b/apps/material-react-table-docs/pages/docs/guides/customize-components.mdx
index b1d331779..f7922e686 100644
--- a/apps/material-react-table-docs/pages/docs/guides/customize-components.mdx
+++ b/apps/material-react-table-docs/pages/docs/guides/customize-components.mdx
@@ -3,10 +3,11 @@ import TableOptionsTable from '../../../components/prop-tables/TableOptionsTable
import ColumnOptionsTable from '../../../components/prop-tables/ColumnOptionsTable';
import ThemeExample from '../../../examples/mui-theme';
import CustomizeStylesExample from '../../../examples/customize-table-styles';
-import { Box } from '@mui/material';
- {'Customize (Style) Components Guide - Material React Table V2 Docs'}
+
+ {'Customize (Style) Components Guide - Material React Table V2 Docs'}
+
+ },
+});
+
+return ;
```
#### Callback Functions to Dynamically Set Prop Values
```jsx
- ({
+ muiSelectCheckboxProps: ({ row }) => ({
color: 'secondary',
disabled: row.original.isAccountLocked, //access the row data to determine if the checkbox should be disabled
- })}
-/>
+ }),
+});
+
+return ;
```
### Styling Material UI Components
-Each `mui...Prop` has multiple options for you to add styling to the component. You could simply pass `className` or `style` props to any `mui...Props` prop, but there is also the `sx` prop...which totally rocks!
-
-> Hint: You should just use the `sx` prop for all styling instead of `className` or `style` props.
+Each `mui...Prop` has multiple options for you to add styling to the component. You could simply pass `className` or `style` props to any `mui...Props` prop, but there is also the `sx` table option, which is the recommended way to style Material UI components in Material React Table.
#### The SX Prop
The recommended way to style Material UI components in Material React Table will be the [`sx` prop](https://mui.com/system/basics/#the-sx-prop) throughout this docs site, as it is both the most simple and the most powerful way to style Material UI components as of Material UI V5. They can work and be as simple as a `style` prop, but behind the scenes, they work more like emotion styled-components by using `mui/system`.
-Don't worry, `className` and `style` props will still work, but let's show off some of the more elegant syntax you can use with the `sx` prop.
+Don't worry, `className` and `style` props will still work, but let's show off some of the more elegant syntax you can use with the `sx` table option.
-1. The `sx` prop can be used just a simply as a `style` prop by default
+1. The `sx` prop can be used just as simply as a `style` prop by default (though it applies CSS classes using Emotion under the hood).
```jsx
-
+ },
+});
+
+return ;
```
2. The `sx` prop gets easy access to your _muiTheme_ without you having to call the theme from a `useTheme` hook.
```jsx
- ({
color: theme.palette.text.secondary,
}),
- }}
-/>
+ },
+});
+
+return ;
```
3. The `sx` prop gives you a much more concise way to add media queries to your styling.
```jsx
-
+ },
+});
+
+return ;
+```
+
+4. The `sx` prop still let's you use the `&` syntax to target nested elements.
+
+```jsx
+const table = useMaterialReactTable({
+ columns,
+ data,
+ muiTableHeadCellProps: {
+ sx: {
+ //use the `&` syntax to target nested elements by their class
+ '& .Mui-TableHeadCell-Content': {
+ padding: '0',
+ },
+ //use the `&` syntax to target hover state
+ '&:hover': {
+ fontWeight: 'bold',
+ },
+ },
+ },
+});
```
There are many more advantages to using the `sx` prop, but that is all we will discuss in these docs. You can learn more about it the official [Material UI Docs](https://mui.com/system/getting-started/the-sx-prop/).
+### Conditional Styling
+
+Using the `sx`, `style`, or `className` props and the parameters from the callback functions (cell, column, row, table instance APIs, etc.), you can easily add conditional styling to your Material UI components. Here's a few examples
+
+#### Style Selected Rows
+
+```jsx
+const table = useMaterialReactTable({
+ muiTableBodyRowProps: ({ row }) => ({
+ //conditionally style selected rows
+ sx: {
+ fontWeight: row.getIsSelected() ? 'bold' : 'normal',
+ },
+ }),
+});
+```
+
+#### Style Expanded Rows
+
+```jsx
+const table = useMaterialReactTable({
+ muiTableBodyRowProps: ({ row }) => ({
+ //conditionally style expanded rows
+ sx: {
+ fontWeight: row.getIsExpanded() ? 'bold' : 'normal',
+ },
+ }),
+});
+```
+
+#### Style Pinned Columns
+
+```jsx
+const table = useMaterialReactTable({
+ muiTableHeadCellProps: ({ column }) => ({
+ //conditionally style pinned columns
+ sx: {
+ backgroundColor: column.getIsPinned() ? '#f5f5f5' : 'inherit',
+ },
+ }),
+ muiTableBodyCellProps: ({ column }) => ({
+ //conditionally style pinned columns
+ sx: {
+ fontWeight: column.getIsPinned() ? 'bold' : 'normal',
+ },
+ }),
+});
+```
+
+There are hundreds of table, column, header, row, and cell instance APIs that you can use for conditional styling and other logic. See the [Table Instance APIs](/docs/api/table-instance-apis), [Column Instance APIs](/docs/api/column-instance-apis), [Row Instance APIs](/docs/api/row-instance-apis), and [Cell Instance APIs](/docs/api/cell-instance-apis) docs for more info.
+
### Material UI Theme
-Material React Table respects your Material UI Theme. If you have already set up Material UI and a global Material UI Theme, you should already be set. But if you have not, you should visit the offical [Material UI Theming Docs](https://mui.com/material-ui/customization/theming/) to learn how to set that up.
+Material React Table respects your Material UI Theme. If you have already set up Material UI and a global Material UI Theme, you should already be set. But if you have not, you should visit the official [Material UI Theming Docs](https://mui.com/material-ui/customization/theming/) to learn how to set that up.
```jsx
function App() {
@@ -204,45 +294,63 @@ import { createTheme, ThemeProvider } from '@mui/material';
//in one of your normal components
return (
-
+
);
```
-#### Important Theme Values used by Material React Table
+#### Custom Material UI Theme Example
+
+
-`` will primarily use the following values internally from your Material UI Theme by default:
+### MRT Theme Values
-- `theme.palette.background.default` - used as the background color for most table components by default
-- `theme.palette.divider` - used in dividers in menus and for the column resizing handle
-- `theme.palette.info.main` - used in the Toolbar Alert Banner and the Toolbar DropZone component
-- `theme.palette.primary.main` - used as the primary color for anything colorful in the table (input fields, checkboxes, dragging borders, etc.)
+> New in V2
-Notice that by default, the secondary color isn't used at all. Remember though that you can always override which color a component uses by passing in a `mui...Props` prop, like how we changed checkboxes to use the secondary color in the [example above](#static-prop-objects).
+Material React Table has a new `mrtTheme` table option where you can change a few of the default color values used by Material React Table.
-#### Custom Material UI Theme Example
+The default background color of the table toolbars and table are controlled by the `mrtTheme.baseBackgroundColor` value. Dragging borders, selected or pinned rows, and filter match highlighting are also configurable in the `mrtTheme` object.
-A common use case for this could be if you want to switch your primary and secondary colors, just for this table. Let's take a look at an example that does that, along with some other styling tweaks, so that we can make an ugly table.
+Here is the default `mrtTheme` object used internally if not overridden:
-
+```jsx
+const baseBackgroundColor =
+ themeOverrides?.baseBackgroundColor ??
+ (theme.palette.mode === 'dark'
+ ? lighten(theme.palette.background.default, 0.05)
+ : theme.palette.background.default);
+return {
+ baseBackgroundColor,
+ draggingBorderColor: theme.palette.primary.main,
+ matchHighlightColor:
+ theme.palette.mode === 'dark'
+ ? darken(theme.palette.warning.dark, 0.25)
+ : lighten(theme.palette.warning.light, 0.5),
+ menuBackgroundColor: lighten(baseBackgroundColor, 0.07),
+ pinnedRowBackgroundColor: alpha(theme.palette.primary.main, 0.1),
+ selectedRowBackgroundColor: alpha(theme.palette.primary.main, 0.2),
+};
+```
### Customize Table Paper Styling
-You can customize both the props and the styles of the internal `` component that wraps the table by passing in a `muiTablePaperProps` prop. This is useful if you want to change the elevation of the paper, or add a border radius, or any other styling you want to do to the paper.
+You can customize both the props and the styles of the internal `` component that wraps the table by passing in a `muiTablePaperProps` table option. This is useful if you want to change the elevation of the paper, or add a border radius, or any other styling you want to do to the paper.
```jsx
-
+ },
+});
+
+return ;
```
### Customize Table Body, Rows, Columns, and Cells
@@ -252,18 +360,20 @@ You can customize both the props and the styles of the internal `` comp
If you need to style many of the rows or columns in a consistent manner, it usually makes sense to style the `` component itself. For example if you want to stripe the rows, you can do something like this:
```jsx
- td': {
backgroundColor: '#f5f5f5',
},
},
- }}
-/>
+ },
+});
+
+return ;
```
#### Stripe Columns Example
@@ -271,23 +381,37 @@ If you need to style many of the rows or columns in a consistent manner, it usua
Similarly, if you want to stripe the columns, you can do something like this:
```jsx
-
+ },
+});
```
+
+### Customize No Rows overlay
+
+As part of the customization options, we allow you to override the No Records overlay.
+
+```jsx
+const table = useMaterialReactTable({
+ columns,
+ data,
+ renderEmptyRowsFallback: ({ table }) => (
+ Customized No Rows Overlay
+ ),
+});
+```
diff --git a/apps/material-react-table-docs/pages/docs/guides/customize-icons.mdx b/apps/material-react-table-docs/pages/docs/guides/customize-icons.mdx
index 4ae3c7ace..7210c055c 100644
--- a/apps/material-react-table-docs/pages/docs/guides/customize-icons.mdx
+++ b/apps/material-react-table-docs/pages/docs/guides/customize-icons.mdx
@@ -3,7 +3,7 @@ import TableOptionsTable from '../../../components/prop-tables/TableOptionsTable
import Example from '../../../examples/font-awesome-icons';
- Custom Icons Feature Guide - Material React Table V2 Docs
+ Custom Icons Guide - Material React Table V2 Docs
### Replace with Custom Icons
-To replace a default icon, specify the icon in the `icons` prop. You should get TS hints for the name of the icons you can replace, but you can also consult [this source file](https://github.com/KevinVandy/material-react-table/blob/v2/packages/material-react-table/src/icons.ts) for a list of all the icons you can replace.
+To replace a default icon, specify the icon in the `icons` table option. You should get TS hints for the name of the icons you can replace, but you can also consult [this source file](https://github.com/KevinVandy/material-react-table/blob/v2/packages/material-react-table/src/icons.ts) for a list of all the icons you can replace.
```jsx
-## Data (Accessor) Columns
+## Data (Accessor) Columns Guide
Data columns are used to display data and are the default columns that are created when you create a column with an `accessorKey` or `accessorFn`.
@@ -21,9 +21,11 @@ The other type of column that you can make is a display column, which you can le
Each column definition must have at least an `accessorKey` (or a combination of an `id` and `accessorFn`) and a `header` property. The `accessorKey`/`accessorFn` property is the key that will be used to join the data from the `data` keys. The `header` property is used to display the column header, but is also used in other places in the table.
+> Note: Do NOT have your accessors resolve JSX or markup. That's what custom [`Cell`](#custom-cell-render) renders are for. Accessors should only return primitive data so that the table can sort, filter, search, and group properly.
+
#### Method 1 - Using an accessorKey (Recommended)
-The simplest and most common way to define a column is to use the `accessorKey` property. The `accessorKey` property is the key that will be used to join the data from the `data` keys.
+The simplest and most common way to define a column is to use the `accessorKey` column option. The `accessorKey` column option is the key that will be used to join the data from the `data` keys.
The `accessorKey` must match one of the keys in your data, or else no data will show up in the column. The `accessorKey` also supports dot notation, so you can access nested data.
@@ -56,12 +58,12 @@ const columns = useMemo[]>( //TS helps with the autocomp
#### Method 2 - Using an accessorFn and id
-You can alternatively use the `accessorFn` property. Here are at least three ways you can use it.
+You can alternatively use the `accessorFn` column option. Here are at least three ways you can use it.
In each case, the `id` property is now required since there is no `accessorKey` for MRT to derive it from.
```tsx
-const columns = useMemo(
+const columns = useMemo[]>(
() => [
{
//simple accessorFn that works the same way as an `accessorKey`
@@ -86,6 +88,30 @@ const columns = useMemo(
);
```
+#### Method 3 - Using createMRTColumnHelper
+
+> New in V2 (After many requests)
+
+Alternatively you can use the `createMRTColumnHelper` utility function to define your columns definitions in a slightly more type-safe way. Instantiate a `columnHelper` by passing in your `TData` type as a generic argument. Then the first argument of the `columnHelper.accessor()` method can be either an `accessorKey` or an `accessorFn`. Then you can specify the rest of the column options as the second argument.
+
+```tsx
+const columnHelper = createMRTColumnHelper(); //TS now knows the shape of your data
+
+const columns = [
+ //accessorKey as first argument, rest of column options as second argument
+ columnHelper.accessor('name', {
+ //TS should provide autocomplete for valid accessorKeys
+ header: 'Last Name',
+ }),
+ //accessorFn as first argument, rest of column options as second argument
+ columnHelper.accessor((row) => Number(row.age), {
+ //TS should provide autocomplete for valid properties on your data
+ header: 'Age',
+ id: 'age', //id is required when using accessorFn
+ }),
+];
+```
+
### Custom Header Render
If you want to pass in custom JSX to render the header, you can pass in a `Header` option in addition to the `header` string property.
@@ -99,7 +125,7 @@ const columns = useMemo(
accessorKey: 'name',
header: 'Name',
Header: ({ column }) => (
- {column.columnDef.header}
+ {column.columnDef.header} //re-use the header we already defined
), //arrow function
},
{
@@ -114,14 +140,27 @@ const columns = useMemo(
### Custom Cell Render
-Similarly, the data cells in a column can have a custom JSX render with the `Cell` option.
+Similarly, the data cells in a column can have a custom JSX render with the `Cell` option. This is one of the most common features used in MRT.
+
+Using the `Cell` column option should be the only way that you use to render custom JSX in table cells. Do not put JSX in an accessorFn, or else the table will not be able to sort, filter, search, or group properly.
```tsx
const columns = useMemo(
() => [
+ {
+ accessorFn: (row) => `${row.firstName} ${row.lastName}`,
+ header: 'Name',
+ //Add a link in a cell render
+ Cell: ({ renderedCellValue, row }) => (
+
+ {renderedCellValue}
+
+ ),
+ },
{
accessorKey: 'salary',
header: 'Salary',
+ //Format a number in a cell render
Cell: ({ cell }) => (
${cell.getValue().toLocaleString()}
),
@@ -129,6 +168,7 @@ const columns = useMemo(
{
accessorKey: 'profileImage',
header: 'Profile Image',
+ //Render images in a cell render
Cell: ({ cell }) =>  ()} />,
},
],
@@ -168,37 +208,11 @@ const columns = useMemo(
> See the [Customize Components Guide](/docs/guides/customize-components) for more ways to style and customize header and cell components.
-### Enable or Disable Features Per Column
-
-In the same way that you can pass props to the main `` component to enable or disable features, you can also specify options on the column definitions to enable or disable features on a per-column basis.
-
-```tsx
-const columns = useMemo(
- () => [
- {
- accessorKey: 'salary',
- header: 'Salary',
- enableClickToCopy: true, //enable click to copy on this column
- },
- {
- accessorKey: 'profileImage',
- header: 'Profile Image',
- enableSorting: false, //disable sorting on this column
- },
- ],
- [],
-);
-```
-
-> See all the column options you can use in the [Column Options API Reference](/docs/api/column-options).
-
### Set Column Widths
-This topic is covered in detail in the [Column Resizing Guide](/docs/guides/column-resizing), but here is a brief overview.
-
-Setting a CSS (sx or style) width prop will NOT work. Material React Table (or, more accurately, TanStack Table) will keep track and set the widths of each column internally.
+This topic is covered in detail in the [Column Size Guide](/docs/guides/column-size), but here is a brief overview.
-You CAN, however, change the default width of any column by setting its `size` option on the column definition. `minSize` and `maxSize` are also available to set the minimum and maximum width of the column during resizing.
+Setting a CSS (sx or style) width prop in the `muiTableHeadCellProps`, `muiTableBodyCellProps`, etc. might not work well, and is redundant. MRT/TanStack Table has an official way to set column widths with the `size`, `minSize`, `maxSize`, and `grow` column options.
```tsx
const columns = [
@@ -206,6 +220,7 @@ const columns = [
accessorKey: 'id',
header: 'ID',
size: 50, //small column
+ grow: false, //don't allow this column to grow (if layoutMode is grid)
},
{
accessorKey: 'username',
@@ -222,27 +237,7 @@ const columns = [
];
```
-However, the column sizes might not change as much as you would expect. This is because the browser treats `` and ` | ` elements differently with in a `` element by default.
-
-You can improve this slightly by changing the table layout to `fixed` instead of the default `auto` in the `muiTableProps`.
-
-```tsx
-
-```
-
-The columns will still try to increase their width to take up the full width of the table, but the columns that do have a defined size will have their width respected more.
-
-To learn more about how table-layout `fixed` vs `auto` works, we recommend reading this [blog post](https://css-tricks.com/almanac/properties/t/table-layout/) by CSS-Tricks.
-
-#### Disable Column Growing
-
-By default, columns grow to fill the width of the table. However, you can disable this behavior by setting the `flexGrow` css for the table head and body cells to `0` when the `layoutMode` prop is also set to `"grid"`. This is covered in more detail in the [Column Resizing Guide](/docs/guides/column-resizing#disable-column-growing).
+There is a lot of different behaviors for column widths depending on what other features are enabled or how they are configured. See the [Column Size Guide](/docs/guides/column-size) for more details on the `layoutMode`s, and how and why they are enabled and how they affect column widths.
### Set Column Alignment
@@ -253,26 +248,56 @@ const columns = [
{
accessorKey: 'id',
header: 'ID',
- //right align the header and body cells
+ //right align the header, body, and footer cells each individually
muiTableHeadCellProps: {
align: 'right',
},
muiTableBodyCellProps: {
align: 'right',
},
+ muiTableFooterCellProps: {
+ align: 'right',
+ },
},
{
accessorKey: 'username',
header: 'Username',
- //center align the header and body cells
+ //center align the header, body, and footer cells each individually
muiTableHeadCellProps: {
align: 'center',
},
muiTableBodyCellProps: {
align: 'center',
},
+ muiTableFooterCellProps: {
+ align: 'center',
+ },
},
];
```
+
+### Enable or Disable Features Per Column
+
+In the same way that you can pass props to the main `` component to enable or disable features, you can also specify options on the column definitions to enable or disable features on a per-column basis.
+
+```tsx
+const columns = useMemo(
+ () => [
+ {
+ accessorKey: 'salary',
+ header: 'Salary',
+ enableClickToCopy: true, //enable click to copy on this column
+ },
+ {
+ accessorKey: 'profileImage',
+ header: 'Profile Image',
+ enableSorting: false, //disable sorting on this column
+ },
+ ],
+ [],
+);
+```
+
+> See all the column options you can use in the [Column Options API Reference](/docs/api/column-options).
diff --git a/apps/material-react-table-docs/pages/docs/guides/density-toggle.mdx b/apps/material-react-table-docs/pages/docs/guides/density-toggle.mdx
index 06b8b3d9b..97a1e0b89 100644
--- a/apps/material-react-table-docs/pages/docs/guides/density-toggle.mdx
+++ b/apps/material-react-table-docs/pages/docs/guides/density-toggle.mdx
@@ -4,7 +4,7 @@ import StateOptionsTable from '../../../components/prop-tables/StateOptionsTable
import DisableExample from '../../../examples/disable-density-toggle';
- Density Toggle Feature Guide - Material React Table V2 Docs
+ {'Density Toggle Guide - Material React Table V2 Docs'}
+const table = useMaterialReactTable({
+ data,
+ columns,
+ initialState: { density: 'compact' },
+});
+
+return ;
```
### Disable or Hide the Density Toggle
You can change the default density and disable the density toggle itself if you want.
-In this example, the density toggle is disabled and a `compact` density is set by default in the `initialState` prop.
+In this example, the density toggle is disabled and a `compact` density is set by default in the `initialState` table option.
diff --git a/apps/material-react-table-docs/pages/docs/guides/detail-panel.mdx b/apps/material-react-table-docs/pages/docs/guides/detail-panel.mdx
index 55db751cb..8e371662c 100644
--- a/apps/material-react-table-docs/pages/docs/guides/detail-panel.mdx
+++ b/apps/material-react-table-docs/pages/docs/guides/detail-panel.mdx
@@ -1,31 +1,36 @@
import Head from 'next/head';
import TableOptionsTable from '../../../components/prop-tables/TableOptionsTable';
import StateOptionsTable from '../../../components/prop-tables/StateOptionsTable';
-import Example from '../../../examples/enable-detail-panel';
import AlternateExample from '../../../examples/alternate-detail-panel';
+import ChartDetailPanelExample from '../../../examples/chart-detail-panel';
+import ExampleVirtualized from '../../../examples/enable-detail-panel-virtualized';
+import ExampleConditional from '../../../examples/enable-detail-panel-conditionally';
+import LazyDetailPanelExample from '../../../examples/lazy-detail-panel';
-
- {'Detail Panel Expanding Feature Guide - Material React Table V2 Docs'}
-
+ {'Detail Panel Expanding Guide - Material React Table V2 Docs'}
-## Detail Panel (Expanding) Feature Guide
+## Detail Panel Feature Guide
Material React Table has multiple kinds of expanding features. This guide will show you how to use the detail panel feature to expand a single row to show more information for that row.
If you are looking for how to expand multiple rows from a tree data structure, see the [Expanding Sub-Rows](/docs/guides/expanding-sub-rows) guide.
-### Relevant Props
+### Relevant Table Options
Using `row.getValue('columnId')` will not work for data that does not have its own column. Using `row.original.columnId` is recommended for detail panels since the data in the detail panel usually does not have its own column.
-
+### Disable Expand All Button
-### Expand Detail Panel By Default
+If you don't want to show the expand all button, you can set the `enableExpandAll` table option to `false`.
+
+```jsx
+const table = useMaterialReactTable({
+ data,
+ columns,
+ enableExpandAll: false,
+});
+```
+
+### Enable Detail Panel Conditionally Per Row
+
+If the return value of your `renderDetailPanel` function returns `null` or a falsy value for a row, the expand button will be disabled for that row.
+
+```jsx
+const table = useMaterialReactTable({
+ columns,
+ data,
+ renderDetailPanel: ({ row }) =>
+ row.original.someCondition ? : null,
+});
+```
+
+One thing to note about the implementation of conditional detail panels is that additional `` elements will still be created for all rows, even if they do not have detail panel content. It is implemented this way in order to avoid bugs with row virtualization, or striped row CSS.
+
+### Only Allow One Detail Panel Open At A Time
+
+If you want to only allow one detail panel to be open at a time, all you have to do is add your own `onClick` logic to the `muiExpandButtonProps` table option.
+
+```jsx
+const table = useMaterialReactTable({
+ data,
+ columns,
+ renderDetailPanel: ({ row }) => ,
+ muiExpandButtonProps: ({ row, table }) => ({
+ onClick: () => table.setExpanded({ [row.id]: !row.getIsExpanded() }), //set only this row to be expanded
+ }),
+});
+```
+
+### Rotate Expand Icon
+
+If you don't like the default rotation styles for the expand icons, you can pass in custom CSS to the `muiExpandButtonProps` and `muiExpandAllButtonProps` table options.
+
+### Replace Expand Icon
+
+You can easily use a custom expand icon either by following the [Custom Icons Guide](/docs/guides/custom-icons) or by passing in custom `children` to the `muiExpandButtonProps` and `muiExpandAllButtonProps` table options.
+
+```jsx
+const table = useMaterialReactTable({
+ data,
+ columns,
+ // icons, //or manage icons globally
+ muiExpandButtonProps: ({ row }) => ({
+ children: row.getIsExpanded() ? : ,
+ }),
+});
+```
-If you want some or all rows to be expanded by default, you can specify that in the `initialState.expanded` prop. Pass `true` to expand all rows, or specify which rowIds should be expanded.
-
-```tsx
-//expand first 2 rows by default
-` element that contains the detail panel content.
+
+If you need to customize the `` element containing the detail panel cell, you can just use the `muiTableBodyRowProps` table option that you use for customizing all rows. There is a `isDetailPanel` parameter that is available to you to target only detail panel rows.
+
+```jsx
+const table = useMaterialReactTable({
+ data,
+ columns,
+ muiDetailPanelProps: ({ row }) => ({
+ sx: {
+ //...
},
- }}
-/>
+ }),
+ muiTableBodyRowProps: ({ isDetailPanel, row }) => ({
+ sx: {
+ // isDetailPanel ? ... : ...
+ },
+ }),
+});
```
-```tsx
-//expand all rows by default
-
+
+### Expand Detail Panel By Default
+
+If you want some or all rows to be expanded by default, you can specify that in the `initialState.expanded` table option. Pass `true` to expand all rows, or specify which rowIds should be expanded.
+
+```jsx
+const table = useMaterialReactTable({
+ data,
+ columns,
+ initialState: {
expanded: true,
- }}
-/>
+ // or expand specific rows by default
+ // expanded: {
+ // 1: true,
+ // 2: true,
+ // },
+ },
+});
```
### Position Expand Column Last
-If you want to position the expand column last, you can set the `positionExpandColumn` prop to `'last'`.
+If you want to position the expand column last, you can set the `positionExpandColumn` table option to `'last'`.
+
+Alternatively though, you could use the [Column Pinning Feature](/docs/guides/column-pinning) to pin the expand column to the right side of the table.
+### Detail Panel With Charts
+
+The detail panel can be used to show a variety of content. Here's an example of a detail panel rendering charts with the [MUI X Charts](https://mui.com/x/react-charts/getting-started/) library.
+
+
+
+### Detail Panels with Virtualization
+
+> New in v2.6.0
+
+If you are using row virtualization, detail panels will now work more properly as of version 2.6.0. However, there are some caveats to be aware of. In order for row virtualization to work well, many of the animation/transitions have been disabled. This means that the detail panel will not animate open and closed. It will simply appear and disappear.
+
+You also may need to specify some more accurate row height estimations for the row virtualizer in order to achieve the best scrollbar behavior. See the [Row Virtualization Guide](/docs/guides/row-virtualization) for the full details on this topic, but here's an example of how you might do that.
+
+```jsx
+const table = useMaterialReactTable({
+ data,
+ columns,
+ enableRowVirtualization: true,
+ renderDetailPanel: ({ row }) => ,
+ rowVirtualizerOptions: ({ table }) => {
+ const { density, expanded } = table.getState();
+ return {
+ //adjust to your needs
+ estimateSize: (index) =>
+ index % 2 === 1 //even rows are normal rows, odd rows are detail panels
+ ? //Estimate open detail panels as 80px tall, closed detail panels as 0px tall
+ expanded === true
+ ? 80
+ : 0
+ : //estimate normal row heights
+ density === 'compact'
+ ? 37
+ : density === 'comfortable'
+ ? 58
+ : 73,
+ };
+ },
+});
+```
+
+
+
+### Lazy Detail Panels
+
+Fetching the additional data for the detail panels only after the user clicks to expand the row can be a good way to improve performance, and it is pretty easy to implement. It's even easier if you are using React Query.
+
+
+
View Extra Storybook **[Examples](https://www.material-react-table.dev/?path=/story/features-detail-panel-examples-)**
diff --git a/apps/material-react-table-docs/pages/docs/guides/display-columns.mdx b/apps/material-react-table-docs/pages/docs/guides/display-columns.mdx
index 6715075d2..fdc86e210 100644
--- a/apps/material-react-table-docs/pages/docs/guides/display-columns.mdx
+++ b/apps/material-react-table-docs/pages/docs/guides/display-columns.mdx
@@ -1,5 +1,6 @@
import Head from 'next/head';
import Example from '../../../examples/customize-display-columns';
+import TableOptionsTable from '../../../components/prop-tables/TableOptionsTable';
{'Display (Built-in) Columns - Material React Table V2 Docs'}
@@ -9,22 +10,28 @@ import Example from '../../../examples/customize-display-columns';
/>
-## Display (Built-in) Columns
+## Display (Built-in) Columns Guide
Display columns are used to display non-data elements in a table. They only require an `id` and `header` in the column definition. They do not need an `accessorKey` or `accessorFn`, as they are not meant to connect to your data at all.
Display columns do not have any processing features, such as sorting, filtering, grouping, etc. enabled on them by default.
+### Relevant Table Options
+
+
+
### Built-in MRT Display Columns
Material React Table has a few built-in display columns that are created automatically when certain features are enabled.
-- `mrt-row-pin` - created when `enableRowPinning` prop is `true` with certain `rowPinningDisplayMode` values
-- `mrt-row-drag` - created when `enableRowDragging` or `enableRowOrdering` prop are `true`
+- `mrt-row-pin` - created when `enableRowPinning` table option is `true` with certain `rowPinningDisplayMode` values
+- `mrt-row-drag` - created when `enableRowDragging` or `enableRowOrdering` table option are `true`
- `mrt-row-actions` - created when `enableRowActions` (or sometimes when `enableEditing`) props are `true`
- `mrt-row-expand` - created when `enableExpanding`, `enableGrouping`, or `renderDetailPanel` props are `true`
-- `mrt-row-select` - created when `enableRowSelection` prop is `true`
-- `mrt-row-numbers` - created when `enableRowNumbers` prop is `true`
+- `mrt-row-select` - created when `enableRowSelection` table option is `true`
+- `mrt-row-numbers` - created when `enableRowNumbers` table option is `true`
- `mrt-row-spacer` - created when `layoutMode` is `"grid-no-grow"` (column resizing)
Display columns are, for the most part, the same as a data column, except they do not have an accessor to access data. When a display column is created internally by Material React Table, the following options are all set to false by default:
@@ -50,43 +57,65 @@ All of these values are able to be overridden if needed, and you'll learn about
### Customize Built-in MRT Display Columns
-It is possible to change and override the default behavior of built-in display columns. Whether you want to change the default column width, add some styles, or enable some features, such as column actions or column drag and drop, you can do it with the `displayColumnDefOptions` prop.
+It is possible to change and override the default behavior of built-in display columns. Whether you want to change the default column width, add some styles, or enable some features, such as column actions or column drag and drop, you can do it with the `displayColumnDefOptions` table option.
+
+#### Default Display Column Table Option
+
+First of all, if you want to enable or disable some feature for all display columns, you can just use the `defaultDisplayColumn` table option. This will apply to all display columns, including any custom display columns you create.
+
+```jsx
+const table = useMaterialReactTable({
+ columns,
+ data,
+ defaultDisplayColumn: {
+ enableColumnOrdering: true,
+ enableColumnResizing: true,
+ minSize: 100,
+ },
+});
+```
-#### Display Column Definition Options Prop
+#### Display Column Definition Options Table Option
Let's say you need to adjust the width of the Actions column to be wide enough to fit all of your action buttons. You could do that as follows:
```jsx
- (
-
+const table = useMaterialReactTable({
+ columns,
+ data,
+ displayColumnDefOptions: { 'mrt-row-actions': { size: 300 } }, //change width of actions column to 300px
+ enableRowActions: true,
+ renderRowActions: ({ row }) => (
+
-
- )}
-/>
+
+ ),
+});
+
+return ;
```
Or maybe you want to enable a feature that is off by default for display columns, such as column ordering or pinning.
-```tsx
-
+ },
+ enableRowNumbers: true,
+});
+
+return ;
```
Here is a full example and demo for customizing display columns.
@@ -97,7 +126,7 @@ Here is a full example and demo for customizing display columns.
You do not have to use the built in Row Actions feature. You can just create your own display columns instead. It is as easy as creating a normal column, only specifying the `columnDefType` as `display`.
-```tsx
+```jsx
const columns = [
{
id: 'sendEmail',
diff --git a/apps/material-react-table-docs/pages/docs/guides/editing.mdx b/apps/material-react-table-docs/pages/docs/guides/editing.mdx
index 0a03c7e51..2825bb183 100644
--- a/apps/material-react-table-docs/pages/docs/guides/editing.mdx
+++ b/apps/material-react-table-docs/pages/docs/guides/editing.mdx
@@ -2,13 +2,10 @@ import Head from 'next/head';
import TableOptionsTable from '../../../components/prop-tables/TableOptionsTable';
import ColumnOptionsTable from '../../../components/prop-tables/ColumnOptionsTable';
import StateOptionsTable from '../../../components/prop-tables/StateOptionsTable';
-import EditingCellExample from '../../../examples/enable-editing-cell';
-import EditingModalExample from '../../../examples/enable-editing-modal';
-import EditingRowExample from '../../../examples/enable-editing-row';
-import EditingTableExample from '../../../examples/enable-editing-table';
+import EditingCrudExamples from '../../../example-groups/EditingCRUDExamples';
- Editing Feature Guide - Material React Table V2 Docs
+ {'Editing Guide - Material React Table V2 Docs'}
@@ -42,6 +47,7 @@ There are four visually distinct editing modes to choose from, whether you want
+
### Enable Editing
-To enable editing, you first need to set the `enableEditing` prop to `true`.
+To enable editing, you first need to set the `enableEditing` table option to `true`.
```jsx
-
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableEditing: true,
+});
```
-However, this is just the first step. You will need to hook up logic and event listeners, but it depends on which editing mode you want to use.
+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.
+
+### Disable Editing
+
+Editing can be turned off on a per-column basis with the `enableEditing` column option.
+
+```jsx
+const columns = [
+ {
+ accessorKey: 'age',
+ header: 'Age',
+ enableEditing: false,
+ },
+];
+```
+
+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.
+
+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.
+
+```jsx
+const columns = [
+ {
+ accessorKey: 'age',
+ header: 'Age',
+ enableEditing: false,
+ Edit: () => null, //don't render anything in the editing modal for this column
+ //or Edit: ({ cell, renderedCellValue }) => <>{renderedCellValue}, //render the normal cell value instead of a text field
+ },
+];
+```
-### Editing Modes
+### Edit Display Modes
-Material React Table has four supported editing modes: `"modal"` (default), `"row"`, `"cell"` and `"table"`. You can specify which editing mode you want to use by passing the `editDisplayMode` prop.
+There are five different editDisplayModes to choose from. The default is `"modal"`, but you can also choose `"row"`, `"cell"`, `"table"`, or `"custom"`.
-#### Modal Editing Mode
+#### Modal Edit Display Mode
-The `"modal"` editing mode opens up a dialog where the user can edit data for one row at a time. No data is saved to the table until the user clicks the save button. Clicking the cancel button clears out any changes that were made on that row.
+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.
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.
-> The `onEditingRowSave` callback function prop includes an `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.
+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.
+
+```jsx
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableEditing: true,
+ editDisplayMode: 'modal', //default
+ onEditingRowSave: ({ table, values }) => {
+ //validate data
+ //save data to api
+ table.setEditingRow(null); //exit editing mode
+ },
+ onEditingRowCancel: () => {
+ //clear any validation errors
+ },
+ muiEditRowDialogProps: {
+ //optionally customize the dialog
+ },
+ renderEditRowDialogContent: ({ internalEditComponents, row, table }) => {
+ //optionally, completely override the render of the dialog content
+ //use `internalEditComponents` to render the generated text fields, or completely render your own form and inputs
+ },
+});
+```
+
+#### Row Edit Display Mode
+
+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.
+
+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.
+
+```jsx
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableEditing: true,
+ editDisplayMode: 'row',
+ onEditingRowSave: ({ table, values }) => {
+ //validate data
+ //save data to api
+ table.setEditingRow(null); //exit editing mode
+ },
+ onEditingRowCancel: () => {
+ //clear any validation errors
+ },
+});
+```
+
+#### Cell Edit Display Mode
+
+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.
-
+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.
-#### Row Editing Mode
+```jsx
+const columns = [
+ {
+ accessor: 'age',
+ header: 'Age',
+ muiEditTextFieldProps: ({ cell, row, table }) => ({
+ onBlur: (event) => {
+ //validate data
+ //save data to api and/or rerender table
+ // table.setEditingCell(null) is called automatically onBlur internally
+ },
+ }),
+ },
+];
+
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableEditing: true,
+ editDisplayMode: 'cell',
+ //optionally, use single-click to activate editing mode instead of default double-click
+ muiTableBodyCellProps: ({ cell, column, table }) => ({
+ onClick: () => {
+ table.setEditingCell(cell); //set editing cell
+ //optionally, focus the text field
+ queueMicrotask(() => {
+ const textField = table.refs.editInputRefs.current[column.id];
+ if (textField) {
+ textField.focus();
+ textField.select?.();
+ }
+ });
+ },
+ }),
+});
+```
+
+#### Table Edit Display Mode
+
+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.
+
+#### Custom Edit Display Mode
+
+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.
+
+### Enable Creating
+
+> New in V2
+
+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.
-The `row` editing mode is an inline row editing mode. When edit mode is activated, the row shows the edit components in the data cells. No data is saved to the table until the user clicks the save button. Clicking the cancel button clears out any changes that were made on that row.
+#### Create Display Modes
-You must provide an `onEditingRowSave` callback function prop 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.
+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.
-> The `onEditingRowSave` callback function prop includes an `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.
+#### Position Creating Row
-
+> New in v2.7
-#### Cell Editing Mode
+By default, the creating row will be added to the top of the table. You can change this behavior with the `positionCreatingRow` table option.
-The `cell` editing mode is a bit simpler visually. Uses double-click cells to activate editing mode, but only for that cell.
+```jsx
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableEditing: true,
+ createDisplayMode: 'modal',
+ positionCreatingRow: 'bottom', //default is 'top'
+});
+```
-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` prop or column definition option.
+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.
-
+#### Trigger Create Mode
-#### Table Editing Mode
+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.
-The `table` editing mode is similar to the `cell` editing mode, but it simply has all of the data cells in the table become editable all at once.
+```jsx
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableEditing: true,
+ editDisplayMode: 'modal',
+ createDisplayMode: 'modal',
+ onCreatingRowSave: ({ table, values }) => {
+ //validate data
+ //save data to api
+ table.setCreatingRow(null); //exit creating mode
+ },
+ onCreatingRowCancel: () => {
+ //clear any validation errors
+ },
+ renderTopToolbarCustomActions: ({ table }) => (
+
+ ),
+});
+```
-To save data, you must hook up the `onBlur`, `onChange`, etc., events yourself. This can be done in the `muiEditTextFieldProps` prop or column definition option.
+### CRUD Examples
-
+
### Customizing Editing Components
-You can pass any Material UI TextField Props with the `muiEditTextFieldProps` prop.
+You can pass any Material UI TextField Props with the `muiEditTextFieldProps` table option.
-```tsx
+```jsx
const columns = [
{
accessor: 'age',
@@ -126,9 +307,9 @@ const columns = [
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.
-If you are implementing validation, you may also need to use the `onEditingRowCancel` prop to clear the validation error state.
+If you are implementing validation, you may also need to use the `onEditingRowCancel` table option to clear the validation error state.
-```tsx
+```jsx
const [validationErrors, setValidationErrors] = useState({});
const columns = [
@@ -169,7 +350,18 @@ const columns = [
{
accessorKey: 'email',
header: 'Email',
- Edit: ({ cell, column, table }) => ,
+ Edit: ({ cell, column, row, table }) => {
+ const onBlur = (event) => {
+ row._valuesCache[column.id] = event.target.value;
+ if (isCreating) {
+ setCreatingRow(row);
+ } else if (isEditing) {
+ setEditingRow(row);
+ }
+ };
+
+ return ;
+ },
},
];
```
@@ -178,22 +370,19 @@ const columns = [
You can customize the actions column in a few different ways in the `displayColumnDefOptions` prop's `'mrt-row-actions'` section.
-```tsx
- (
),
},
- }}
-/>
+ },
+});
```
-
-### React-Hook-Form Example
-
-TODO
diff --git a/apps/material-react-table-docs/pages/docs/guides/expanding-sub-rows.mdx b/apps/material-react-table-docs/pages/docs/guides/expanding-sub-rows.mdx
index 04f12133f..119e1f374 100644
--- a/apps/material-react-table-docs/pages/docs/guides/expanding-sub-rows.mdx
+++ b/apps/material-react-table-docs/pages/docs/guides/expanding-sub-rows.mdx
@@ -1,14 +1,15 @@
import Head from 'next/head';
import TableOptionsTable from '../../../components/prop-tables/TableOptionsTable';
-import ColumnOptionsTable from '../../../components/prop-tables/ColumnOptionsTable';
import StateOptionsTable from '../../../components/prop-tables/StateOptionsTable';
import EnableExample from '../../../examples/enable-expanding-tree';
import ExpandedExample from '../../../examples/expanding-tree-expanded';
import ExpandedRootExample from '../../../examples/expanding-tree-root-expanded';
+import ExpandingParsedTreeExample from '../../../examples/expanding-tree-flat-parse';
+import LazySubRowsExample from '../../../examples/lazy-sub-rows';
- {'Expanding Sub-Rows/Tree Data Feature Guide - Material React Table V2 Docs'}
+ {'Expanding Sub-Rows/Tree Data Guide - Material React Table V2 Docs'}
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).
-### Relevant Props
+### Relevant Table Options
originalRow.subRows} //default, can customize
- />
-);
-```
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableExpanding: true,
+ getSubRows: (originalRow) => originalRow.subRows, //default, can customize
+});
-
+return ;
+```
### Expand All Rows Button
-By default, Material React Table will show the expand all button in the expand column header. You can disable this by setting the `enableExpandAll` prop to `false`.
+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`.
```jsx
-
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableExpanding: true,
+ enableExpandAll: false, //hide expand all button in header
+});
```
+
+
+### Generate Sub Rows with getSubRows
+
+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.
+
+There are a couple key things you have to do to make this work:
+
+1. Only pass in root (top level) rows in your data prop.
+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.
+
+This can sometimes be useful in combination with [lazy loading sub rows](#lazy-load-sub-rows).
+
+> 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.
+
+
+
### Expanded Rows Pagination Behavior
-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` prop to `false`.
+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`.
```jsx
-
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableExpanding: true,
+ paginateExpandedRows: false, //expanded rows will be on the same page as their parent row
+});
```
### Expanded Leaf Row Filtering Behavior
@@ -117,32 +137,30 @@ If you are using the [filtering features](/docs/guides/column-filtering) alongsi
#### Filter From Leaf Rows
-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` prop 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).
+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).
```jsx
-
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableExpanding: true,
+ filterFromLeafRows: true, //search for child rows and preserve parent rows
+});
```
#### Max Leaf Row Filter Depth
-> New in `v1.3.11` from TanStack Table v8.6.0 and later!
-
-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` prop 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.
+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.
This is useful for situations where you want a row's entire child hierarchy to be visible, regardless of the applied filter.
```jsx
-
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableExpanding: true,
+ maxLeafRowFilterDepth: 0, //When filtering root rows, keep all child rows of the passing parent rows
+});
```
### Expand All Rows By Default
@@ -152,12 +170,12 @@ You can manage the initial state of the expanded rows with the `expanded` state
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`.
```jsx
-
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableExpanding: true,
+ initialState: { expanded: true }, //all rows expanded by default
+});
```
@@ -167,3 +185,33 @@ For example, you may want all rows to be expanded by default. To do this, you ca
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`.
+
+### Customize Expand Column
+
+You can customize the expand column by using the `displayColumnDefOptions` table option.
+
+```jsx
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableGrouping: true,
+ displayColumnDefOptions: {
+ 'mrt-row-expand': {
+ enableResizing: true, //allow resizing
+ size: 120, //make the expand column wider
+ },
+ },
+});
+```
+
+### Lazy Load Sub Rows
+
+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.
+
+There are quite a few ways in which you could implement fetching sub-rows lazily. This example is just one way to do it.
+
+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.
+
+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.
+
+
diff --git a/apps/material-react-table-docs/pages/docs/guides/full-screen-toggle.mdx b/apps/material-react-table-docs/pages/docs/guides/full-screen-toggle.mdx
index d985f055a..685fb5bf0 100644
--- a/apps/material-react-table-docs/pages/docs/guides/full-screen-toggle.mdx
+++ b/apps/material-react-table-docs/pages/docs/guides/full-screen-toggle.mdx
@@ -3,9 +3,7 @@ import TableOptionsTable from '../../../components/prop-tables/TableOptionsTable
import StateOptionsTable from '../../../components/prop-tables/StateOptionsTable';
-
- {'Full Screen Toggle Feature Guide - Material React Table V2 Docs'}
-
+ {'Full Screen Toggle Guide - Material React Table V2 Docs'}
-);
+return ;
```
### Change Z-Index of Full Screen Table
@@ -66,7 +63,7 @@ Under the hood in Material React Table V2, when the table is full screen, these
}
```
-If you need to change the `zIndex` of the full screen table, you can do so by passing in a `muiTablePaperProps` prop with a `style` object that has a `zIndex` property.
+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.
```jsx
muiTablePaperProps: ({ table }) => ({
@@ -77,4 +74,4 @@ muiTablePaperProps: ({ table }) => ({
});
```
-> Note: The `sx` prop will not work here because the `style` prop was used internally instead of the `sx` prop for higher specificity.
+> 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.
diff --git a/apps/material-react-table-docs/pages/docs/guides/global-filtering.mdx b/apps/material-react-table-docs/pages/docs/guides/global-filtering.mdx
index 3e4a0d47e..3c1c97f7f 100644
--- a/apps/material-react-table-docs/pages/docs/guides/global-filtering.mdx
+++ b/apps/material-react-table-docs/pages/docs/guides/global-filtering.mdx
@@ -8,7 +8,7 @@ import RemoteExample from '../../../examples/remote';
- {'Global Filtering/Search Feature Guide - Material React Table V2 Docs'}
+ {'Global Filtering/Search Guide - Material React Table V2 Docs'}
-```
-
-### Filter Match Highlighting
-
-> New in v1.6
-
-Filter match highlighting is a new featured enabled by default that will highlight text in the table body cells that matches the current search query with a shade of the `theme.palette.warning.main` color.
-
-If you are using a custom `Cell` render override for a column, you will need to use the `renderedCellValue` prop instead of `cell.getValue()` to preserve the filter match highlighting.
-
-```jsx
-const columns = [
- {
- accessorKey: 'name',
- header: 'Name',
- Cell: ({ renderedCellValue }) => {renderedCellValue}, // use renderedCellValue instead of cell.getValue()
- },
-];
-```
-
-#### Disable Filter Match Highlighting
-
-Filter match highlighting can be disabled by setting the `enableFilterMatchHighlighting` prop to `false`.
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableGlobalFilter: false, //disable search feature
+});
-```jsx
-
+return ;
```
### Client-Side Global Filtering
@@ -128,28 +100,28 @@ Client-side filtering (and global filtering) is enabled by default. This means t
You can use any of the built-in `filterFns` or any of the custom filter functions that you have defined in the `filterFns` prop, just like you would with the column filters.
```jsx
-
+const table = useMaterialReactTable({
+ columns,
+ data,
+ globalFilterFn: 'contains', //turn off fuzzy matching and use simple contains filter function
+});
```
Or a custom filter function:
```jsx
-
row.getValue(id).startsWith(filterValue),
- }}
- globalFilterFn="myCustomFilterFn" //set the global filter function to myCustomFilterFn
-/>
+ },
+ globalFilterFn: 'myCustomFilterFn', //set the global filter function to myCustomFilterFn
+});
```
-The default global filter function is set to `fuzzy`, which is a filtering algorithm based on the popular `match-sorter` [library from Kent C. Dodds](https://www.npmjs.com/package/match-sorter), though you can change the global filter function by setting the `globalFilterFn` prop.
+The default global filter function is set to `fuzzy`, which is a filtering algorithm based on the popular `match-sorter` [library from Kent C. Dodds](https://www.npmjs.com/package/match-sorter), though you can change the global filter function by setting the `globalFilterFn` table option.
#### Ranked Results
@@ -157,27 +129,27 @@ If you keep the default `fuzzy` filterFn option as the global filter function, y
The ranked results feature will disable itself automatically if a sort direction is applied to a column, if any sub-rows are expanded, or if any of the `manual` props are set to `true`.
-If you do not want ranked results to be enabled at all, but you still want fuzzy matching, you can set the `enableGlobalFilterRankedResults` prop to `false`.
+If you do not want ranked results to be enabled at all, but you still want fuzzy matching, you can set the `enableGlobalFilterRankedResults` table option to `false`.
```jsx
-
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableGlobalFilterRankedResults: false, //preserve the order of the data when fuzzy match searching
+});
```
#### Global Filter Modes
-Similar to the column filter modes, you can enable the user to be able to choose between multiple different filter modes for the global filter with the `enableGlobalFilterModes` prop. You can then customize which filter modes are available in the drop-down by setting the `globalFilterModeOptions` prop or by rendering your own custom menu items with the `renderGlobalFilterModeMenuItems` prop.
+Similar to the column filter modes, you can enable the user to be able to choose between multiple different filter modes for the global filter with the `enableGlobalFilterModes` table option. You can then customize which filter modes are available in the drop-down by setting the `globalFilterModeOptions` table option or by rendering your own custom menu items with the `renderGlobalFilterModeMenuItems` table option.
```jsx
-
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableGlobalFilterModes: true, //enable the user to choose between multiple search filter modes
+ globalFilterModeOptions: ['fuzzy', 'startsWith'], //only allow the user to choose between fuzzy and startsWith filter modes
+});
```
#### Show Search Field by Default
@@ -186,7 +158,7 @@ Additionally, if you want to show the search text box by default and not hide it
### Manual Server-Side Global Filtering
-A very common use case when you have a lot of data is to filter the data on the server, instead of client-side. In this case, you will want to set the `manualFiltering` prop to `true` and manage the `globalFilter` state yourself like in the example below (can work in conjuntion with [manual column filtering](https://www.material-react-table.com/docs/guides/column-filtering#manual-server-side-column-filtering)).
+A very common use case when you have a lot of data is to filter the data on the server, instead of client-side. In this case, you will want to set the `manualFiltering` table option to `true` and manage the `globalFilter` state yourself like in the example below (can work in conjunction with [manual column filtering](https://www.material-react-table.com/docs/guides/column-filtering#manual-server-side-column-filtering)).
```tsx
// You can manage and have control over the columnFilters state yourself
@@ -201,15 +173,15 @@ useEffect(() => {
};
}, [globalFilter]);
-return (
-
-);
+const table = useMaterialReactTable({
+ columns,
+ data, // this will already be filtered on the server
+ manualFiltering: true, //turn off client-side filtering
+ onGlobalFilterChange: setGlobalFilter, //hoist internal global state to your state
+ state: { globalFilter }, //pass in your own managed globalFilter state
+});
+
+return ;
```
> Specifying `manualFiltering` turns off all client-side filtering and assumes that the `data` you pass to `` is already filtered.
@@ -220,35 +192,65 @@ Here is the full Remote Data example showing off server-side **filtering**, pagi
### Customize Global Filter Position
-You can customize the position of the global filter (search box) in the top toolbar by setting the `positionGlobalFilter` prop to `left` or `right`. It is shown on the right by default.
+You can customize the position of the global filter (search box) in the top toolbar by setting the `positionGlobalFilter` table option to `left` or `right`. It is shown on the right by default.
```jsx
-
+ },
+});
```
### Customize the Search Text Field
-You can customize the search text field by passing in props to the `muiSearchTextFieldProps` prop. This is useful if you want to customize the placeholder text, add styles, or any other text field props.
+You can customize the search text field by passing in props to the `muiSearchTextFieldProps` table option. This is useful if you want to customize the placeholder text, add styles, or any other text field props.
```jsx
-
+ },
+});
+
+return ;
```
+### Filter Match Highlighting
+
+Filter match highlighting is a new featured enabled by default that will highlight text in the table body cells that matches the current search query with a shade of the `theme.palette.warning.main` color.
+
+If you are using a custom `Cell` render override for a column, you will need to use the `renderedCellValue` table option instead of `cell.getValue()` to preserve the filter match highlighting.
+
+```jsx
+const columns = [
+ {
+ accessorKey: 'name',
+ header: 'Name',
+ Cell: ({ renderedCellValue }) => {renderedCellValue}, // use renderedCellValue instead of cell.getValue()
+ },
+];
+```
+
+#### Disable Filter Match Highlighting
+
+Filter match highlighting can be disabled by setting the `enableFilterMatchHighlighting` table option to `false`.
+
+```jsx
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableFilterMatchHighlighting: false, //disable filter match highlighting
+});
+```
+
View Extra Storybook **[Examples](https://www.material-react-table.dev/?path=/story/features-search-examples)**
diff --git a/apps/material-react-table-docs/pages/docs/guides/localization.mdx b/apps/material-react-table-docs/pages/docs/guides/localization.mdx
index a5272111e..a2e719e5e 100644
--- a/apps/material-react-table-docs/pages/docs/guides/localization.mdx
+++ b/apps/material-react-table-docs/pages/docs/guides/localization.mdx
@@ -3,7 +3,7 @@ import TableOptionsTable from '../../../components/prop-tables/TableOptionsTable
import LocaleExamples from '../../../example-groups/LocaleExamples';
- Localization/i18n Guide - Material React Table V2 Docs
+ {'Localization/i18n Guide - Material React Table V2 Docs'}
@@ -22,7 +22,7 @@ Material React Table has full support for localization (i18n). Some locales are
The following locales are included and can be imported from `'material-react-table/locales/'`:
-`ar`, `bg`, `cs`, `da`, `de`, `en`, `es`, `et`, `fa`, `fi`, `fr`, `hu`, `hy`, `id`, `it`, `ja`, `ko`, `nl`, `no`, `np`, `pl`, `pt-BR`, `pt`, `ro`, `ru`, `sk`, `sr-Cryl-RS`, `sr-Latn-RS`, `sv`, `tr`, `uk`, `vi`, `zh-Hans`, `zh-Hant`
+`ar`, `az`, `bg`, `cs`, `da`, `de`, `el`, `en`, `es`, `et`, `fa`, `fi`, `fr`, `he`, `hr`, `hu`, `hy`, `id`, `it`, `ja`, `ko`, `nl`, `no`, `np`, `pl`, `pt`, `pt-BR`, `ro`, `ru`, `sk`, `sr-Cyrl-RS`, `sr-Latn-RS`, `sv`, `tr`, `uk`, `vi`, `zh-Hans`, `zh-Hant`
> If your language is not yet supported, please consider making a PR to add it to the library! See [here on GitHub](https://github.com/KevinVandy/material-react-table/tree/v2/packages/material-react-table/src/locales).
@@ -32,15 +32,18 @@ Scroll and find your language below to see an example of how to use it.
+> Note: In some frameworks like Remix, you may need to use a full import path like
`import { MRT_Localization_ES } from 'material-react-table/locales/es/index.js';` or
`import { MRT_Localization_ES } from 'material-react-table/locales/es/index.esm.js';`
+> to properly import the locale.
+
### Custom Non-Built-In Translations
-If you want to use a language that is not included in the library, you can still easily add your own custom translations to the `localization` prop.
+If you want to use a language that is not included in the library, you can still easily add your own custom translations to the `localization` table option.
```jsx
-
+ },
+});
+
+return ;
```
For a full list of all available translation keys, see [here](https://github.com/KevinVandy/material-react-table/blob/v2/packages/material-react-table/src/locales/en.ts)
diff --git a/apps/material-react-table-docs/pages/docs/guides/memoization.mdx b/apps/material-react-table-docs/pages/docs/guides/memoization.mdx
new file mode 100644
index 000000000..783155927
--- /dev/null
+++ b/apps/material-react-table-docs/pages/docs/guides/memoization.mdx
@@ -0,0 +1,164 @@
+import Head from 'next/head';
+import TableOptionsTable from '../../../components/prop-tables/TableOptionsTable';
+
+
+ {'Memoization Guide - Material React Table V2 Docs'}
+
+
+
+## Memoization (Performance) Guide
+
+Material React Table already uses some memoization techniques to improve performance for you automatically under the hood to improve performance during some events like column resizing. In this guide, we'll go over the basics of what is recommended to be memoized, what you need to keep in mind for performance, and how to tweak advanced memoization settings for your specific use case.
+
+### Relevant Table Options
+
+
+
+### What to Memoize
+
+First of all, when these docs refer to memoization, we are not necessarily talking just about the React `useMemo` hook. Using the `useMemo` hook is just one way to give an variable a stable reference in React. `useMemo`, `useState`, `useReducer`, `useQuery` (React Query), storing state in a state management library like Zustand or Redux, or even just defining a variable outside of a component are all ways to give a variable a stable reference.
+
+#### Give Data a Stable Reference
+
+The only truly required thing that must have a stable reference for both Material React Table and TanStack Table is the `data` table option. If your `data` does not have a stable reference, the table will enter an infinite loop of re-rendering upon any state change.
+
+> Failing to give `data` a stable reference can cause an infinite loop of re-renders.
+
+##### _Why does this happen? Is this a bug in MRT or TanStack Table?_
+
+No, this is not a bug in either MRT or TanStack Table. This is just fundamentally how React works. TanStack Table is designed to re-render whenever the `data` changes. You would probably be equally surprised and upset if MRT only accepted what you passed in as `data` on the first render and never updated after a refetch or state change.
+
+```jsx
+export default function MyComponent() {
+ const columns = [
+ // ...
+ ];
+
+ //😵 BAD: This will cause an infinite loop of re-renders because `data` is redefined as a new array on every render
+ const data = [
+ // ...
+ ];
+
+ const table = useMaterialReactTable({
+ columns,
+ data, //data is defined as a const in the same scope as `useMaterialReactTable`, will cause infinite loop
+ });
+
+ return ;
+}
+```
+
+##### I'm still getting an infinite loop of re-renders, but I'm using useMemo!
+
+Sometimes developers will properly memoize their `data`, but don't end up passing that memoized `data` to the table, and apply some extra transformation or filtering to the `data` before passing it to the table. This common mistake will still cause an infinite loop of re-renders.
+
+```jsx
+export default function MyComponent() {
+ const columns = [
+ // ...
+ ];
+
+ //GOOD: Storing `data` in state gives it a stable reference
+ const [data, setData] = useState([
+ // ...
+ ]);
+
+ //GOOD: This still preserves the stable reference of `data` and will not cause an infinite loop of re-renders
+ const filteredData = useMemo(
+ () => data.filter((row) => row.isActive),
+ [data],
+ );
+
+ const table = useMaterialReactTable({
+ columns,
+ //GOOD: Reading from the `data` state is stable
+ data,
+
+ //😵 BAD: This is ignoring the stable reference of `data` and re-creating a new array on every render
+ data: data.filter((row) => row.isActive),
+
+ //GOOD: This is still reading from the stable reference from a `useMemo` hook
+ data: filteredData,
+ });
+
+ return ;
+}
+```
+
+#### Memoize Columns
+
+You will generally have better performance if you properly memoize your `columns` array, or give it a stable reference like you would with `data`. Not giving `columns` a stable reference will not cause an infinite loop of re-renders like `data`, but it will still cause the table to re-render more than necessary. The columns `useMemo` dependency array does not need to be an empty array. If your column definitions are derived from other state, you should include that state in the dependency array.
+
+```jsx
+const columns = useMemo(
+ () => [
+ // ...
+ ],
+ [],
+);
+
+//OR
+
+const columns = useMemo(
+ () => [
+ // ...
+ ],
+ [dependency1, dependency2], //if column defs are derived from other state, don't forget to include that state in the dependency array
+);
+
+//OR
+
+const [columns, setColumns] = useState(() => [
+ // ...
+]);
+```
+
+#### Other Options to Memoize
+
+Usually you will not need to memoize any other options besides `columns` and `data`. However, if you have any expensive logic in any of the `render*` options, you may benefit from wrapping that logic in a React `useCallback` hook. It is not recommended to start off by wrapping all of your `render*` options in `useCallback` hooks, as this usually does not even provide a noticeable performance improvement. This usually takes some experimentation.
+
+Here's an example for how to render detail panels with a `useCallback` optimization. Getting the TypeScript types correct in the `useCallback` can be tricky, but here's how you can do it:
+
+```tsx
+const table = useMaterialReactTable({
+ columns,
+ data,
+ renderDetailPanel: useCallback<
+ Required>['renderDetailPanel'] //TS needed to get the correct type of the inner arrow function below
+ >(
+ ({ row, table }) =>
+
+ [], //add proper dependencies here if needed
+ ),
+});
+```
+
+All of the other `mui*Props` components could also be memoized with either `useMemo` or `useCallback` if you have complicated expensive logic in them for some reason in the same way as above.
+
+### Memo Mode
+
+Material React Table already memoizes columns and the entire `` component during column resizing, and column/row drag and drop events. This actually does make a significant performance improvement, and is why it is possible to have the performance that it does during these events.
+
+If you need to reach into the internals and apply some custom memoization, MRT exposes a limited way to do this. The Table Body, Table Rows, or all Table Cells can be memoized with the `memoMode` table option.
+
+```jsx
+const table = useMaterialReactTable({
+ columns,
+ data,
+ //memoize all cells. This value can be applied dynamically based on a certain scenario/condition if needed
+ memoMode: 'cells', // 'cells' | 'rows' | 'table-body'
+});
+```
+
+Usually you should not ever need to do this, and be aware that this will stop certain features from functioning correctly. For example, if you memoize all table cells, the density toggle feature will not work anymore. If you memoize the entire table body, most features including virtualization will not work anymore. You'll be left with a table that is mostly frozen after first render, but it could improve the overall performance of your web page if you don't need any of these interactive features.
+
+> Don't use `memoMode` unless you know what you're doing and have a specific use case for it.
+
+### React Forget
+
+In the future, React may finally release their magical "React Forget" compiler that will make all memoization problems in React disappear, and you won't have to worry about any of this. But until then, the above solutions are the best we have.
+
+View Extra Storybook [Examples](https://www.material-react-table.dev/?path=/story/features-memo-mode-examples)
diff --git a/apps/material-react-table-docs/pages/docs/guides/memoize-components.mdx b/apps/material-react-table-docs/pages/docs/guides/memoize-components.mdx
deleted file mode 100644
index 32130bec8..000000000
--- a/apps/material-react-table-docs/pages/docs/guides/memoize-components.mdx
+++ /dev/null
@@ -1,121 +0,0 @@
-import Head from 'next/head';
-import MemoizeCellsExample from '../../../examples/memoize-cells';
-import MemoizeRowsExample from '../../../examples/memoize-rows';
-import MemoizeTableBodyExample from '../../../examples/memoize-table-body';
-import Box from '@mui/material/Box';
-
-
- Memoize Components Guide - Material React Table V2 Docs
-
-
-
-## Memoize Components Guide
-
-As of version 1.1, Material React Table has introduced a new `memoMode` prop that will allow you to either memoize table cells, table rows, or the entire table body in order to improve render performance on large tables.
-
-However, memoizing these components will **BREAK** some features!
-
-> DON'T MEMOIZE COMPONENTS UNLESS YOU KNOW WHAT YOU'RE DOING AND UNDERSTAND WHICH FEATURES WILL BREAK.
-
-### Memoizing Table Cells
-
-Memoizing table cells can make a small but positive impact on render performance, and it is only incompatible with a few of the dynamic features of Material React Table.
-
-#### Cell Memoization Breaks the Following Features:
-
-`density toggle, column resizing`
-
-These features are incompatible with cell memoization because they depend on table cells being re-rendered.
-
-#### Features That Should Still Work with Cell Memoization:
-
-
- `column hiding, column reordering, column pinning, editing, filtering,
- pagination, searching, sorting, row expanding, row selection, row
- virtualization`
-
-
-```jsx
-
-```
-
-
-
-### Memoizing Table Rows
-
-Memoizing entire table rows can make an even more positive impact on render performance, but it is incompatible with a lot of the dynamic features of Material React Table.
-
-#### Row Memoization Breaks the Following Features:
-
-
- `density toggle, column hiding, column resizing, column reordering, column
- pinning, row expanding, row selection`
-
-
-These features are incompatible with row memoization because they require the entire row or cells to be re-rendered in order to update the UI.
-
-#### Features That Should Still Work with Row Memoization:
-
-
- `filtering, pagination, searching, sorting, row virtualization,`
-
-
-```jsx
-
-```
-
-
-
-### Memoizing Table Body
-
-If your table never needs to re-render and you do not use any of the dynamic features of Material React Table, you can memoize the entire table body to massively improve render performance.
-
-#### Table Body Memoization Breaks the Following Features:
-
-
- `density toggle, column hiding, column resizing, column reordering, column
- pinning, row expanding, row selection, filtering (internal client-side),
- pagination (internal client-side), searching (internal client-side), sorting
- (internal client-side), row virtualization`
-
-
-None of these features will work with table body memoization because the entire table body is memoized. The table is essentially "frozen" at the first render.
-
-#### Features That Should Still Work with Table Body Memoization:
-
-
- `manual server side sorting, pagination, filtering`
-
-
-```jsx
-
-```
-
-
-
-View Extra Storybook **[Examples](https://www.material-react-table.dev/?path=/story/features-memo-mode-examples)**
diff --git a/apps/material-react-table-docs/pages/docs/guides/pagination.mdx b/apps/material-react-table-docs/pages/docs/guides/pagination.mdx
index aa17c6750..8e96cfa06 100644
--- a/apps/material-react-table-docs/pages/docs/guides/pagination.mdx
+++ b/apps/material-react-table-docs/pages/docs/guides/pagination.mdx
@@ -5,7 +5,7 @@ import AlternatePaginationExample from '../../../examples/alternate-pagination';
import RemoteExample from '../../../examples/remote';
- Pagination Feature Guide - Material React Table V2 Docs
+ {'Pagination Guide - Material React Table V2 Docs'}
Note: Do not pass pagination state to both `initialState` and `state` at the same time. The `state` will overwrite the `initialState` values.
+
#### Customize Pagination Behavior
There are a few table options that you can use to customize the pagination behavior. The first one is `autoResetPageIndex`. This table option is `true` by default, and causes a table to automatically reset the table back to the first page whenever sorting, filtering, or grouping occurs. This makes sense for most use cases, but if you want to disable this behavior, you can set this table option to `false`.
@@ -74,7 +104,7 @@ const table = useMaterialReactTable({
columns,
data,
muiPaginationProps: {
- rowsPerPageOptions: ['5', '10', '20'],
+ rowsPerPageOptions: [5, 10, 20],
showFirstButton: false,
showLastButton: false,
},
diff --git a/apps/material-react-table-docs/pages/docs/guides/row-actions.mdx b/apps/material-react-table-docs/pages/docs/guides/row-actions.mdx
index 63e258199..40fc9cf71 100644
--- a/apps/material-react-table-docs/pages/docs/guides/row-actions.mdx
+++ b/apps/material-react-table-docs/pages/docs/guides/row-actions.mdx
@@ -4,7 +4,7 @@ import MenuItemsExample from '../../../examples/row-actions-menu-items';
import ButtonsExample from '../../../examples/row-actions-buttons';
- Row Actions Feature Guide - Material React Table V2 Docs
+ {'Row Actions Guide - Material React Table V2 Docs'}
[
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableRowActions: true,
+ renderRowActionMenuItems: ({ row }) => [
,
,
- ]}
-/>
+ ],
+});
+
+return ;
```
#### Add Row Action Buttons
-If you want to add row action buttons, you can use the `renderRowActions` prop.
+If you want to add row action buttons, you can use the `renderRowActions` table option.
```jsx
- (
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableRowActions: true,
+ renderRowActions: ({ row }) => (
console.info('Edit')}>
@@ -73,8 +79,10 @@ If you want to add row action buttons, you can use the `renderRowActions` prop.
- )}
-/>
+ ),
+});
+
+return ;
```
@@ -83,36 +91,43 @@ If you want to add row action buttons, you can use the `renderRowActions` prop.
#### Change Row Actions Display Column Options
-You can customize all column def options for the row actions column, including the column width, header text, and more using the `displayColumnDefOptions` prop.
+You can customize all column def options for the row actions column, including the column width, header text, and more using the `displayColumnDefOptions` table option.
```jsx
- (
+ },
+ renderRowActions: ({ table }) => (
- )}
-/>
+ ),
+});
```
#### Position Row Actions Column
-You can position the row actions column to the left or right (first or last column) of the table using the `positionActionsColumn` prop. The default is as the first column.
+You can position the row actions column to the left or right (first or last column) of the table using the `positionActionsColumn` table option. The default is as the first column.
```jsx
-
+const table = useMaterialReactTable({
+ columns,
+ data,
+ enableRowActions: true,
+ positionActionsColumn: 'last',
+ renderRowActions: ({ table }) => (
+ //...
+ ),
+})
```
+
+View Extra Storybook **[Examples](https://www.material-react-table.dev/?path=/story/features-row-actions-examples)**
diff --git a/apps/material-react-table-docs/pages/docs/guides/row-numbers.mdx b/apps/material-react-table-docs/pages/docs/guides/row-numbers.mdx
index 39c2a1dcc..9f7ca9128 100644
--- a/apps/material-react-table-docs/pages/docs/guides/row-numbers.mdx
+++ b/apps/material-react-table-docs/pages/docs/guides/row-numbers.mdx
@@ -4,7 +4,7 @@ import OriginalExample from '../../../examples/enable-row-numbers-original';
import StaticExample from '../../../examples/enable-row-numbers-static';
- Row Numbers Feature Guide - Material React Table V2 Docs
+ Row Numbers Guide - Material React Table V2 Docs
### Enable Row Numbers (Static Mode)
-In the default rowNumberMode (`static`), row numbers are just a static part of the table in their own column. They act like the row numbers in an excel spreadsheet. Sorting and filtering will not affect the row numbers.
+In the default rowNumberDisplayMode (`static`), row numbers are just a static part of the table in their own column. They act like the row numbers in an excel spreadsheet. Sorting and filtering will not affect the row numbers.
### Enable Row Numbers (Original Mode)
-Alternatively, use the `"original"` rowNumberMode to have row numbers linked to the original index of the data array. This means that when you search or filter, the same row numbers will stay with the same rows as data is sorted and filtered.
+Alternatively, use the `"original"` rowNumberDisplayMode to have row numbers linked to the original index of the data array. This means that when you search or filter, the same row numbers will stay with the same rows as data is sorted and filtered.
diff --git a/apps/material-react-table-docs/pages/docs/guides/row-ordering-dnd.mdx b/apps/material-react-table-docs/pages/docs/guides/row-ordering-dnd.mdx
index c780d5b6c..28ab3c521 100644
--- a/apps/material-react-table-docs/pages/docs/guides/row-ordering-dnd.mdx
+++ b/apps/material-react-table-docs/pages/docs/guides/row-ordering-dnd.mdx
@@ -5,7 +5,7 @@ import EnableOrderingExample from '../../../examples/enable-row-ordering';
import EnableDraggingExample from '../../../examples/enable-row-dragging';
- Row Ordering/DnD Feature Guide - Material React Table V2 Docs
+ {'Row Ordering/DnD Guide - Material React Table V2 Docs'}
This is not the [Sorting Guide](/docs/guides/sorting), which is a different feature.
-### Relevant Props
+### Relevant Table Options
{
//data re-ordering logic here
},
- }}
-/>
+ },
+});
+
+return ;
```
### Drag and Drop Rows to Other UI or Tables
-The drag-and-drop features are not limited to just internally within the same table. You can also use them to drag rows to other UI elements in your application or even to other tables. This can be done by setting the `enableRowDragging` prop to `true` and setting up an `onDragEnd` event handler on the `muiRowDragHandleProps` prop to perform whatever logic you want to happen when a row is dropped.
+The drag-and-drop features are not limited to just internally within the same table. You can also use them to drag rows to other UI elements in your application or even to other tables. This can be done by setting the `enableRowDragging` table option to `true` and setting up an `onDragEnd` event handler on the `muiRowDragHandleProps` table option to perform whatever logic you want to happen when a row is dropped.
diff --git a/apps/material-react-table-docs/pages/docs/guides/row-pinning.mdx b/apps/material-react-table-docs/pages/docs/guides/row-pinning.mdx
index 4fc0288ce..e68d666a7 100644
--- a/apps/material-react-table-docs/pages/docs/guides/row-pinning.mdx
+++ b/apps/material-react-table-docs/pages/docs/guides/row-pinning.mdx
@@ -6,7 +6,7 @@ import StaticExample from '../../../examples/enable-row-pinning-static';
import SelectExample from '../../../examples/enable-row-pinning-select';
- Row Pinning Feature Guide - Material React Table V2 Docs
+ Row Pinning Guide - Material React Table V2 Docs
{
+ const { density } = table.getState();
+ return {
+ sx: {
+ //Set a fixed height for pinned rows
+ height: row.getIsPinned()
+ ? `${
+ //Default mrt row height estimates. Adjust as needed.
+ density === 'compact' ? 37 : density === 'comfortable' ? 53 : 69
+ }px`
+ : undefined,
+ },
+ };
+ },
+ rowPinningDisplayMode: 'sticky', // default
+});
+```
+
+> Note: Sticky Row Pinning is not currently compatible with row virtualization.
+
### Static Row Pinning
Some of the other row pinning modes will show pinned rows at the top or bottom of the the table regardless of scrolling. This is a simpler implementation of the row pinning feature.
+Static row pinning does not require set row heights, as they will render in a normal `` element that itself is what is sticky.
+
| | | | | | 
+
+ 
+
+
+ 
+