npm - material-react-table-narender - Versions diffs - 1.0.0 - Mend

material-react-table-narender 1.0.0

Files changed (1769) hide show

package/apps/material-react-table-docs/pages/docs/guides/state-management.mdx ADDED Viewed

@@ -0,0 +1,174 @@
+import Head from 'next/head';
+import TableOptionsTable from '../../../components/prop-tables/TableOptionsTable';
+import PersistentStateExample from '../../../examples/persistent-state';
+<Head>
+  <title>State Management Guide - Material React Table V3 Docs</title>
+  <meta
+    name="description"
+    content="How to access and manage internal state in Material React Table"
+  />
+</Head>
+## State Management Guide
+> Note: `tableInstanceRef` has been removed in MRT v2 since the `useMaterialReactTable` hook now returns the table instance directly. See the [Migration Guide](/migrating-to-v2) for more information.
+Material React Table does not try to hide any of its internal state from you. You can initialize state with custom initial values, manage individual states yourself as you discover the need to have access to them, or read any of the state from the table instance itself.
+This is all optional, of course. If you do not need access to any of the internal state, you do not need to do anything and it will just automatically be managed internally.
+See the [State Options API Docs](/docs/api/state-options) for more information on which states are available for you to manage.
+### Relevant Table Options
+<TableOptionsTable onlyOptions={new Set(['initialState', 'state'])} />
+### Populate Initial State
+If all you care about is setting parts of the initial or default state when the table mounts, then you may be able to specify that state in the `initialState` table option and not have to worry about managing the state yourself.
+For example, let's say you do not need access to the `showColumnFilters` state, but you want to set the default value to `true` when the table mounts. You can do that with the `initialState` table option:
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  initialState: {
+    density: 'xs', //set default density to compact
+    expanded: true, //expand all rows by default
+    pagination: { pageIndex: 0, pageSize: 15 }, //set different default page size
+    showColumnFilters: true, //show filters by default
+    sorting: [{ id: 'name', desc: false }], //sort by name ascending by default
+  },
+});
+return <MaterialReactTable table={table} />;
+```
+> Note: If you use both `initialState` and `state`, the state initializer in `state` table option will take precedence and overwrite the same state values in `initialState`. So just use either `initialState` or `state`, not both for the same states.
+### Manage Individual States as Needed
+It is pretty common to need to manage certain state yourself, so that you can react to changes in that state, or have easy access to it when sending it to an API.
+You can pass in any state that you are managing yourself to the `state` table option, and it will be used instead of the internal state. Each state property option also has a corresponding `on[StateName]Change` callback that you can use set/update your managed state as it changes internally in the table.
+For example, let's say you need to store the pagination, sorting, and row selection states in a place where you can easily access it in order to use it in parameters for an API call.
+```jsx
+const [pagination, setPagination] = useState({
+  pageIndex: 0,
+  pageSize: 15, //set different default page size by initializing the state here
+});
+const [rowSelection, setRowSelection] = useState({});
+const [sorting, setSorting] = useState([{ id: 'name', desc: false }]);
+//see example at bottom of page for alternatives to useEffect here
+useEffect(() => {
+  //do something when the pagination state changes
+}, [pagination]);
+const table = useMaterialReactTable({
+  columns,
+  data,
+  getRowId: (originalRow) => row.username,
+  onPaginationChange: setPagination,
+  onRowSelectionChange: setRowSelection,
+  onSortingChange: setSorting,
+  state: { pagination, rowSelection, sorting }, //must pass states back down if using their on[StateName]Change callbacks
+});
+return <MaterialReactTable table={table} />;
+```
+### Add Side Effects in Set State Callbacks
+In React 18 and beyond, it is becoming more discouraged to use `useEffect` to react to state changes, because in React Strict Mode (and maybe future versions of React), the useEffect hook may run twice per render. Instead, more event driven functions are recommended to be used. Here is an example for how that looks here. The callback signature for the `on[StateName]Change` works just like a React setState callback from the `useState` hook. This means that you have to check if the updater is a function or not, and then call the setState function with the updater callback if it is a function.
+```tsx
+const [pagination, setPagination] = useState({
+  pageIndex: 0,
+  pageSize: 15,
+});
+const handlePaginationChange = (updater: MRT_Updater<PaginationState>) => {
+  //call the setState as normal, but need to check if using an updater callback with a previous state
+  setPagination((prevPagination) =>
+    //if updater is a function, call it with the previous state, otherwise just use the updater value
+    updater instanceof Function ? updater(prevPagination) : updater,
+  );
+  //put more code for your side effects here, guaranteed to only run once, even in React Strict Mode
+};
+const table = useMaterialReactTable({
+  columns,
+  data,
+  onPaginationChange: handlePaginationChange,
+  state: { pagination },
+});
+return <MaterialReactTable table={table} />;
+```
+### Read From the Table Instance
+> Note: Previously, in early MRT v1, you could use the `tableInstanceRef` table option to get access to the table instance. This is no longer necessary as the `useMaterialReactTable` hook now just returns the table instance directly.
+The `useMaterialReactTable` hook returns the table instance. The `<MaterialReactTable />` needs the table instance for all of its internal logic, but you can also use it for your own purposes.
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  //...
+});
+const someEventHandler = (event) => {
+  console.info(table.getRowModel().rows); //example - get access to all page rows in the table
+  console.info(table.getSelectedRowModel()); //example - get access to all selected rows in the table
+  console.info(table.getState().sorting); //example - get access to the current sorting state without having to manage it yourself
+};
+return (
+  <div>
+    <ExternalButton onClick={someEventHandler}>
+      Export or Something
+    </ExternalButton>
+    <MaterialReactTable table={table} />
+  </div>
+);
+```
+The table instance is the same object that you will also see as a provided parameter in many of the other callback functions throughout Material React Table, such as all the `render...` props or the `Cell` or `Header` render overrides in the column definition options.
+```jsx
+const columns = useMemo(
+  () => [
+    {
+      Header: 'Name',
+      accessor: 'name',
+      Cell: ({ cell, table }) => <span>{cell.getValue()}</span>,
+      //The `table` parameter from the Cell option params and the `table` are the same object
+    },
+  ],
+  [],
+);
+const table = useMaterialReactTable({
+  columns,
+  data,
+  renderTopToolbarCustomActions: ({ table }) => {
+    //The `table` parameter here and the table returned from the hook are the same object
+    return <Button>Button</Button>;
+  },
+});
+return <MaterialReactTable table={table} />;
+```
+### Persistent State
+Persistent state is not a built-in feature of Material React Table, but it is an easy feature to implement yourself using the above patterns with the `state` table option and the `on[StateName]Change` callbacks. Here is an example of how you might implement persistent state using `sessionStorage`:
+<PersistentStateExample />

package/apps/material-react-table-docs/pages/docs/guides/sticky-header.mdx ADDED Viewed

@@ -0,0 +1,52 @@
+import Head from 'next/head';
+import TableOptionsTable from '../../../components/prop-tables/TableOptionsTable';
+import EnableExample from '../../../examples/enable-sticky-header';
+<Head>
+  <title>Sticky Header/Footer Guide - Material React Table V3 Docs</title>
+  <meta
+    name="description"
+    content="How to use and customize the sticky header feature in Material React Table"
+  />
+</Head>
+## Sticky Header and Footer Feature Guide
+The sticky header and footer feature allows you to keep the header and footer of the table visible while scrolling through the table. This is useful when you have a large table and want to keep the header and footer visible at all times.
+### Relevant Table Options
+<TableOptionsTable
+  onlyOptions={new Set(['enableStickyHeader', 'enableStickyFooter'])}
+/>
+### Enable Sticky Header
+Enabling the sticky header is as simple as setting the `enableStickyHeader` table option to `true`. This will make the header of the table stick to the top and remain visible while scrolling through the table.
+When the sticky header is enabled, you will probably also want to give the table a maxHeight so that the table can scroll vertically and keep the header visible. You can do this by styling the table container with the `muiTableContainerProps` table option.
+> If no maxHeight is specified, the table container will default to a `100vh` maxHeight when `enableStickyHeader` is enabled.
+```tsx
+<MaterialReactTable
+  columns={columns}
+  data={data}
+  enableStickyHeader
+  muiTableContainerProps={{ sx: { maxHeight: '500px' } }}
+/>
+```
+### Enable Sticky Footer
+Similarly, enabling the sticky footer is as simple as setting the `enableStickyFooter` table option to `true`. This will make the footer of the table stick to the bottom of the table and always be visible, even before the table is scrolled to the bottom.
+```tsx
+<MaterialReactTable columns={columns} data={data} enableStickyFooter />
+```
+### Enable Sticky Header and Footer Demo
+<EnableExample />
+View Extra Storybook **[Examples](https://www.material-react-table.dev/?path=/story/styling-sticky-header-examples)**

package/apps/material-react-table-docs/pages/docs/guides/table-event-listeners.mdx ADDED Viewed

@@ -0,0 +1,113 @@
+import Head from 'next/head';
+<Head>
+  <title>{'Table Event Listeners Guide - Material React Table V3 Docs'}</title>
+  <meta
+    name="description"
+    content="How to add event listeners such as onClicks and onChange events to components in Material React Table"
+  />
+</Head>
+## Table Event Listeners Guide
+You can pretty much add ANY event listener to ANY component in Material React Table.
+You can do this by passing props to any of the `mui...Props` props. This guide gives a few examples of the most common use cases, but there are limitless possibilities.
+### Add Event Listeners to any of the Material UI Components
+In the [customize components docs](/docs/guides/customize-components#material-ui-prop-types), we explained how to pass any prop you need to pass to any exposed Material UI component that is in the table. The list of props that you can pass to Material UI components includes any event listener.
+Here are a few common examples of some useful event listeners you might want to add to the table, although the possibilities are countless.
+#### Add an onClick to a Table Row
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  muiTableBodyRowProps: ({ row }) => ({
+    onClick: (event) => {
+      console.info(event, row.id);
+    },
+    sx: {
+      cursor: 'pointer', //you might want to change the cursor too when adding an onClick
+    },
+  }),
+});
+```
+#### Add an onDoubleClick to a Table Cell
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  muiTableBodyCellProps: ({ cell }) => ({
+    onDoubleClick: (event) => {
+      console.info(event, cell.id);
+    },
+  }),
+});
+```
+#### Add an onBlur to an Edit TextField
+```jsx
+//add to every edit text field
+const table = useMaterialReactTable({
+  columns,
+  data,
+  muiEditTextFieldProps: ({ cell }) => ({
+    onBlur: (event) => {
+      console.info(event, cell.id);
+    },
+  }),
+});
+```
+```jsx
+//or add to just edit text fields in a specific column
+const columns = [
+  {
+    accessorKey: 'name',
+    header: 'Name',
+    muiEditTextFieldProps: ({ cell }) => ({
+      onBlur: (event) => {
+        console.info(event);
+      },
+    }),
+  },
+];
+```
+#### Add an onChange to an Edit TextField
+> Warning: Be careful when using onChange, as it can trigger re-renders with every keystroke, which can lead to performance issues
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  muiEditTextFieldProps: ({ cell }) => ({
+    onChange: (event) => {
+      console.info(event, cell.id);
+    },
+  }),
+});
+```
+```jsx
+//or add to just edit text fields in a specific column
+const columns = [
+  {
+    accessorKey: 'name',
+    header: 'Name',
+    muiEditTextFieldProps: ({ cell }) => ({
+      onChange: (event) => {
+        console.info(event);
+      },
+    }),
+  },
+];
+```

package/apps/material-react-table-docs/pages/docs/guides/toolbar-customization.mdx ADDED Viewed

@@ -0,0 +1,269 @@
+import Head from 'next/head';
+import TableOptionsTable from '../../../components/prop-tables/TableOptionsTable';
+import StateOptionsTable from '../../../components/prop-tables/StateOptionsTable';
+import DisableExample from '../../../examples/minimal';
+import CustomTopToolbarExample from '../../../examples/custom-top-toolbar';
+import ExternalExample from '../../../examples/external-toolbar';
+<Head>
+  <title>{'Toolbar Customization Guide - Material React Table V3 Docs'}</title>
+  <meta
+    name="description"
+    content="How to customize the Toolbars, add buttons to toolbars, or customize progress bars and alert banners in Material React Table"
+  />
+</Head>
+## Toolbar Customization Guide
+This guide shows you how to [hide](#hide-or-disable-toolbars), [customize](#customize-toolbar-buttons), or [override](#override-with-custom-toolbar-components) the top and bottom toolbars in Material React Table.
+> Note: This guide has become much more simple since the introduction of the `useMaterialReactTable` hook in v2. <br />
+> No more `tableInstanceRef` or `useReducer` rerender hacks required!
+### Relevant Table Options
+<TableOptionsTable
+  onlyOptions={
+    new Set([
+      'enableBottomToolbar',
+      'enableToolbarInternalActions',
+      'enableTopToolbar',
+      'muiBottomToolbarProps',
+      'muiLinearProgressProps',
+      'muiToolbarAlertBannerChipProps',
+      'muiToolbarAlertBannerProps',
+      'muiTopToolbarProps',
+      'positionGlobalFilter',
+      'positionPagination',
+      'positionToolbarAlertBanner',
+      'positionToolbarDropZone',
+      'renderBottomToolbar',
+      'renderBottomToolbarCustomActions',
+      'renderToolbarAlertBannerContent',
+      'renderToolbarInternalActions',
+      'renderTopToolbar',
+      'renderTopToolbarCustomActions',
+    ])
+  }
+/>
+### Relevant State
+<StateOptionsTable
+  onlyOptions={new Set(['showAlertBanner', 'showProgressBars'])}
+/>
+### Hide or Disable Toolbars
+There are `enableTopToolbar` and `enableBottomToolbar` table options that you can use to show or hide the toolbars.
+```jsx
+const table = useMaterialReactTable({
+  data,
+  columns,
+  enableTopToolbar: false,
+  enableBottomToolbar: false,
+});
+return <MaterialReactTable table={table} />;
+```
+Alternatively, you could just use a different MRT component that does not have the toolbars built-in. For example, use the `<MRT_TableContainer />` or `<MRT_Table />` components instead of the `<MaterialReactTable />` component.
+```jsx
+const table = useMaterialReactTable({
+  data,
+  columns,
+});
+//This MRT sub-component does not contain the code for the toolbars. MRT_TablePaper and MaterialReactTable do.
+return <MRT_TableContainer table={table} />;
+```
+#### No Toolbars Example
+<DisableExample />
+### Customize Toolbar buttons
+Everything in the toolbars are customizable. You can add your own buttons or change the order of the built-in buttons.
+#### Customize Built-In Internal Toolbar Button Area
+The `renderToolbarInternalActions` table option allows you to redefine the built-in buttons that usually reside in the top right of the top toolbar. You can reorder the icon buttons or even insert your own custom buttons. All of the built-in buttons are available to be imported from 'material-react-table'.
+```jsx
+import {
+  MaterialReactTable,
+  MRT_ShowHideColumnsButton,
+  MRT_ToggleFullScreenButton,
+} from 'material-react-table';
+const table = useMaterialReactTable({
+  data,
+  columns,
+  renderToolbarInternalActions: ({ table }) => (
+    <>
+      {/* add your own custom print button or something */}
+      <IconButton onClick={() => showPrintPreview(true)}>
+        <PrintIcon />
+      </IconButton>
+      {/* built-in buttons (must pass in table prop for them to work!) */}
+      <MRT_ShowHideColumnsButton table={table} />
+      <MRT_ToggleFullScreenButton table={table} />
+    </>
+  ),
+});
+return <MaterialReactTable table={table} />;
+```
+#### Add Custom Toolbar Buttons/Components
+The `renderTopToolbarCustomActions` and `renderBottomToolbarCustomActions` table options allow you to add your own custom buttons or components to the top and bottom toolbar areas. These props are functions that return a ReactNode. You can add your own buttons or whatever components you want.
+In all of these `render...` table options, you get access to the `table` instance that you can use to perform actions or extract data from the table.
+```jsx
+const table = useMaterialReactTable({
+  data,
+  columns,
+  enableRowSelection: true,
+  //Simply adding a table title to the top-left of the top toolbar
+  renderTopToolbarCustomActions: () => (
+    <Typography variant="h3">Customer's Table</Typography>
+  ),
+  //Adding a custom button to the bottom toolbar
+  renderBottomToolbarCustomActions: ({ table }) => (
+    <Button
+      variant="contained"
+      color="lightblue"
+      //extract all selected rows from the table instance and do something with them
+      onClick={() => handleDownloadRows(table.getSelectedRowModel().rows)}
+    >
+      Download Selected Rows
+    </Button>
+  ),
+});
+return <MaterialReactTable table={table} />;
+```
+#### Custom Toolbar Actions Example
+<CustomTopToolbarExample />
+### Position Toolbar Areas
+The `positionToolbarAlertBanner`, `positionGlobalFilter`, `positionPagination`, and `positionToolbarDropZone` table options allow you to swap the default position of certain areas of the toolbars. Experiment moving them around until you find a layout that works for you.
+```jsx
+const table = useMaterialReactTable({
+  data,
+  columns
+  //if rendering top toolbar buttons, sometimes you want alerts to be at the bottom
+  positionToolbarAlertBanner: 'bottom',
+  positionGlobalFilter: 'left', //move the search box to the left of the top toolbar
+  positionPagination: 'top',
+  renderTopToolbarCustomActions: () => <Box>...</Box>,
+});
+return <MaterialReactTable table={table} />;
+```
+### Customize Toolbar Props and Styles
+The `muiTopToolbarProps`, `muiBottomToolbarProps`, `muiToolbarAlertBannerProps`, and `muiToolbarAlertBannerChipProps` table options allow you to customize the props and styles of the underlying Material components that make up the toolbar components. Remember that you can pass CSS overrides to their `sx` or `style` props. Some have found this useful for forcing `position: absolute` on alerts, etc.
+### Customize Linear Progress Bars
+The progress bars that display in both the top and bottom toolbars become visible when either the `isLoading` or `showProgressBars` state options are set to `true`. You can customize the progress bars by passing in props to the `muiLinearProgressProps` table option. By default, the progress bars have a full animated progress bar, but you can set the `value` table option to a number between 0 and 100 to show real progress values if your table is doing some complicated long running tasks that you want to show progress for. Visit the [Material UI Progress docs](https://mui.com/material-ui/react-progress/) to learn more.
+```jsx
+const table = useMaterialReactTable({
+  data,
+  columns,
+  muiLinearProgressProps: ({ isTopToolbar }) => ({
+    color: 'warning',
+    sx: { display: isTopToolbar ? 'block' : 'none' }, //only show top toolbar progress bar
+    value: fetchProgress, //show precise real progress value if you so desire
+  }),
+  state: {
+    isLoading,
+    showProgressBars,
+  },
+});
+return <MaterialReactTable table={table} />;
+```
+### Customize Toolbar Alert Banner
+The toolbar alert banner is an internal component used to display alerts to the user. By default, it will automatically show messages around the number of selected rows or grouping state.
+However, you can repurpose this alert banner to show your own custom messages too. You can force the alert banner to show by setting the `showAlertBanner` state option to `true`. You can then customize the messages and other stylings using the `muiToolbarAlertBannerProps` to create your custom message. You probably saw this in the [Remote Data](/docs/examples/remote) or [React Query](/docs/examples/react-query) examples.
+```jsx
+const table = useMaterialReactTable({
+  data,
+  columns,
+  //show a custom error message if there was an error fetching data in the top toolbar
+  muiToolbarAlertBannerProps: isError
+    ? {
+        color: 'error',
+        children: 'Network Error. Could not fetch data.',
+      }
+    : undefined,
+  state: {
+    showAlertBanner: isError,
+    showProgressBars: isFetching,
+  },
+});
+return <MaterialReactTable table={table} />;
+```
+### Override with Custom Toolbar Components
+If you want to completely override the default toolbar components, you can do so by passing in your own custom components to the `renderTopToolbar` and `renderBottomToolbar` props.
+The drawback to this approach is that you will not get all the automatic features of the default toolbar components, such as the automatic alert banner, progress bars, etc. You will have to implement all of that yourself if you still want those features. Though you can also just import those MRT components and use them in your custom toolbar.
+```jsx
+import {
+  MRT_GlobalFilterTextInput, //import MRT sub components!
+  MRT_TablePagination,
+  MaterialReactTable,
+  useMaterialReactTable,
+} from 'material-react-table';
+const table = useMaterialReactTable({
+  data,
+  columns,
+  renderTopToolbar: ({ table }) => (
+    <Box
+      sx={{
+        display: 'flex',
+        justifyContent: 'space-between',
+        alignItems: 'center',
+      }}
+    >
+      <MRT_GlobalFilterTextInput table={table} />
+      <MRT_TablePagination table={table} />
+    </Box>
+  ),
+  renderBottomToolbar: ({ table }) => (
+    <Box>
+      <Button>Download</Button>
+    </Box>
+  ),
+});
+return <MaterialReactTable table={table} />;
+```
+### Build Your Own Toolbar
+Instead of overriding the toolbar components up above, you may want 100% control over the layout and styling of your table controls and where they are on the page. You can do this by just using a MRT sub component such as `<MRT_TableContainer />` for the table component, which does not have the internal toolbar components built-in. Optionally, build your own custom toolbar components using the other MRT sub components.
+<ExternalExample />