Material React Table

Material React Table does not try to hide any of its internal state from you. You can store your own reference to the entire table instance wherever you need to, initialize state with custom initial values, or manage individual states yourself as you discover the need to have access to them.

This is all optional, of course. If you don't need access to some of the state, you do not need to do anything and it will just automatically be managed internally. See the State Options API Docs for more information on which states are available for you to manage.

Partial<MRT_TableState<TData>>

Partial<MRT_TableState<TData>>

MutableRefObject<MRT_TableInstance<TData> | null>

Before jumping in and managing a bunch of state yourself, you should first see if you actually need to.

You can store a reference to the underlying table instance by using the tableInstanceRef prop. This is a mutable ref object that will be populated with the table instance once the table has been initialized internally. This reference can be very useful, especially if you need it for components that are rendered outside of <MaterialReactTable />.

//must initialize with null to make TS happy
const tableInstanceRef = useRef<MRT_TableInstance<YourDataType>>(null);

const someEventHandler = (event) => {
  console.info(tableInstanceRef.current?.getRowModel().rows); //example - get access to all page rows in the table
  console.info(tableInstanceRef.current?.getSelectedRowModel()); //example - get access to all selected rows in the table
  console.info(tableInstanceRef.current?.getState().sorting); //example - get access to the current sorting state
};

return (
  <div>
    <ExternalButton onClick={someEventHandler}>
      Export or Something
    </ExternalButton>
    <MaterialReactTable
      columns={columns}
      data={data}
      tableInstanceRef={tableInstanceRef}
    />
  </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.

const tableInstanceRef = useRef(null);

const columns = useMemo(
  () => [
    {
      Header: 'Name',
      accessor: 'name',
      Cell: ({ cell, table }) => <span>{cell.getValue()}</span>,
      //The `table` parameter from the Cell option params and the `tableInstanceRef.current` are the same object
    },
  ],
  [],
);

return (
  <MaterialReactTable
    columns={columns}
    data={data}
    tableInstanceRef={tableInstanceRef}
    renderTopToolbarCustomActions={({ table }) => {
      //The `table` parameter and the `tableInstanceRef.current` are the same object
      return <Button>Button</Button>;
    }}
  />
);

If all you care 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 prop and not have to worry about managing the state yourself.

For example, let's say you don't 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 prop:

<MaterialReactTable
  columns={columns}
  data={data}
  initialState={{
    showColumnFilters: true, //show filters by default
    sorting: [{ id: 'name', desc: false }], //sort by name ascending by default
  }}
/>

Note: If you use both initialState and state, the state initializer in state prop will take precedence and overwrite the same state values in initialState. So just use either initialState or state, not both for the same state.

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 prop, 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 state in a place where you can easily access it in order to use it in parameters for an API call.

const [pagination, setPagination] = useState({
  pageIndex: 0,
  pageSize: 15, //set different default page size by initializing the state here
});

//see example at bottom of page for alternatives to useEffect here
useEffect(() => {
  //do something when the pagination state changes
}, [pagination]);

return (
  <MaterialReactTable
    columns={columns}
    data={data}
    state={{ pagination }}
    onPaginationChange={setPagination}
  />
);

Here is another full example for how you might manage the rowSelection state yourself:

1import React, { FC, useEffect, useMemo, useState } from 'react';
2import MaterialReactTable, { MRT_ColumnDef } from 'material-react-table';
3import { RowSelectionState } from '@tanstack/react-table';
4
5const data = [
6  {
7    userId: '3f25309c-8fa1-470f-811e-cdb082ab9017', //we'll use this as a unique row id
8    firstName: 'Dylan',
9    lastName: 'Murray',
10    age: 22,
11    address: '261 Erdman Ford',
12    city: 'East Daphne',
13    state: 'Kentucky',
14  }, //data definitions...
15  {
16    userId: 'be731030-df83-419c-b3d6-9ef04e7f4a9f',
17    firstName: 'Raquel',
18    lastName: 'Kohler',
19    age: 18,
20    address: '769 Dominic Grove',
21    city: 'Columbus',
22    state: 'Ohio',
23  },
24  
25];
26
27const Example: FC = () => {
28  const columns = useMemo(
29    //column definitions...
30    () =>
31      [
32        {
33          accessorKey: 'firstName',
34          header: 'First Name',
35        },
36        {
37          accessorKey: 'lastName',
38          header: 'Last Name',
39        },
40        {
41          accessorKey: 'age',
42          header: 'Age',
43        },
44        {
45          accessorKey: 'address',
46          header: 'Address',
47        },
48        {
49          accessorKey: 'city',
50          header: 'City',
51        },
52        {
53          accessorKey: 'state',
54          header: 'State',
55        },
56      ] as MRT_ColumnDef<typeof data[0]>[],
57    [], 
58  );
59
60  //optionally, you can manage the row selection state yourself
61  const [rowSelection, setRowSelection] = useState<RowSelectionState>({});
62
63  useEffect(() => {
64    //do something when the row selection changes...
65    console.info({ rowSelection });
66  }, [rowSelection]);
67
68  return (
69    <MaterialReactTable
70      columns={columns}
71      data={data}
72      enableRowSelection
73      getRowId={(row) => row.userId} //give each row a more useful id
74      onRowSelectionChange={setRowSelection} //connect internal row selection state to your own
75      state={{ rowSelection }} //pass our managed row selection state to the table to use
76    />
77  );
78};
79
80export default Example;
81

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 functions is a bit strange, so pay attention to the example below.

const [pagination, setPagination] = useState({
  pageIndex: 0,
  pageSize: 15,
});

const handlePaginationChange = (updater: Updater<PaginationState>) => {//Updater is a type from @tanstack/react-table
  //TanStack Table requires this strange syntax since updater can be a function to update the state or the new state itself
  setPagination((prevPagination) => updater instanceOf Function ? updater(prevPagination) : updater);

  //put more code for your side effects here, guaranteed to only run once, even in React Strict Mode
}

return (
  <MaterialReactTable
    columns={columns}
    data={data}
    state={{ pagination }}
    onPaginationChange={handlePaginationChange}
  />
);