Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update migrating-to-v2.mdx #763

Closed
wants to merge 1 commit into from
Closed

Update migrating-to-v2.mdx #763

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 18 additions & 54 deletions apps/material-react-table-docs/pages/migrating-to-v2.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,40 +13,30 @@ import { InstallCommand } from '../components/mdx/InstallCommand';

## 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.

### New Feature Highlights

1. The 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
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

See the full [changelog](/changelog#version-2.0.0---10-27-2023) for more details.

### Upgrade Dependencies

To upgrade (and upgrade all other MUI dependencies), just run the install commands again.

<InstallCommand />

Your `package.json` should have `"material-react-table": "^2.x.x"` as a dependency.

### 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:
- `@mui/x-date-pickers v >=6.15.0` is now a required peer dependency. Install it with:

<InstallCommand packagesString="@mui/x-date-pickers" />

- 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. See [here](https://mui.com/x/react-date-pickers/adapters-locale/) for more details.
- 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';
Expand All @@ -71,7 +61,7 @@ export const App = () => {
+ import { MaterialReactTable, useMaterialReactTable } from 'material-react-table'
```

- There is no longer a `tableInstanceRef` prop. It has been replaced by the `useMaterialReactTable` hook, which is way easier to use. It will also be recommended that all table options should be passed to the new `useMaterialReactTable` hook instead as props to the `<MaterialReactTable />` component. See [below](#usematerialreacttable) for more details.
- 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 `<MaterialReactTable />` component. See [below](#usematerialreacttable) for more details.

#### Renamed Props/Options

Expand All @@ -98,9 +88,9 @@ export const App = () => {

### useMaterialReactTable

Passing all table options as props to `<MaterialReactTable />` will still work, but there is a new and better way to define table options with the `useMaterialReactTable` hook.
Passing all table options as props to `<MaterialReactTable />` still works, but there is now 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):
For example, below is a classic example for how to use Material React Table in V1 (still works in V2):

```jsx
import { MaterialReactTable } from 'material-react-table';
Expand All @@ -120,7 +110,7 @@ export const MyTableComponent = () => {
};
```

But now, you can define all table options in the `useMaterialReactTable`.
However, you can now define all table options in the `useMaterialReactTable`.

```jsx
import {
Expand All @@ -147,9 +137,9 @@ export const MyTableComponent = () => {

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. No more 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.
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. Allows for you to not need 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.
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';
Expand All @@ -171,30 +161,4 @@ export const MyTableComponent = () => {
};
```

### 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 will keep columns in a fixed width, and columns will not grow to fill any remaining horizontal space. This is probably 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 just 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"
```

<br />

Is anything missing from this v2 migration guide? Make a PR or join the [Discord](https://discord.gg/5wqyRx6fnm) to discuss.
Loading