diff --git a/apps/material-react-table-docs/pages/migrating-to-v2.mdx b/apps/material-react-table-docs/pages/migrating-to-v2.mdx index 8179036cb..e2ff8c7e2 100644 --- a/apps/material-react-table-docs/pages/migrating-to-v2.mdx +++ b/apps/material-react-table-docs/pages/migrating-to-v2.mdx @@ -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. - - - -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: -- 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'; @@ -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 `` 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 `` component. See [below](#usematerialreacttable) for more details. #### Renamed Props/Options @@ -98,9 +88,9 @@ export const App = () => { ### useMaterialReactTable -Passing all table options as props to `` 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 `` 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'; @@ -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 { @@ -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'; @@ -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" -``` - -
- Is anything missing from this v2 migration guide? Make a PR or join the [Discord](https://discord.gg/5wqyRx6fnm) to discuss.