Material React Table

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.

The table can perform processing on the data of a data column, such as sorting, filtering, grouping, etc.

The other type of column that you can make is a display column, which you can learn more about in the next section.

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 renders are for. Accessors should only return primitive data so that the table can sort, filter, search, and group properly.

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.

By default, the accessorKey will double as the id for the column, but if you need the id of the column to be different than the accessorKey, you can use the id property in addition.

const columns = useMemo<MRT_ColumnDef<Customer>[]>( //TS helps with the autocomplete while writing columns
  () => [
    {
      accessorKey: 'username', //normal recommended usage of an accessorKey
      header: 'Username',
    },
    {
      accessorKey: 'name.firstName', //example of dot notation used to access nested data
      header: 'First Name',
    },
    {
      accessorKey: 'name.lastName', //example of dot notation used to access nested data
      header: 'Last Name',
    },
    {
      accessorKey: 'customerAge',
      id: 'age' //id overridden, usually not necessary to do this, but can be helpful
      header: 'Age',
    },
  ],
  [],
);

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.

const columns = useMemo<MRT_ColumnDef<Customer>[]>(
  () => [
    {
      //simple accessorFn that works the same way as an `accessorKey`
      accessorFn: (row) => row.username,
      id: 'username',
      header: 'Username',
    },
    {
      //accessorFn function that combines multiple data together
      accessorFn: (row) => `${row.firstName} ${row.lastName}`,
      id: 'name',
      header: 'Name',
    },
    {
      //accessorFn used to access nested data, though you could just use dot notation in an accessorKey
      accessorFn: (row) => row.personalInfo.age,
      id: 'age',
      header: 'Age',
    },
  ],
  [],
);

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.

const columnHelper = createMRTColumnHelper<Customer>(); //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
  }),
];

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.

The header (lowercase) property is still required and still must only be a string because it is used within multiple components in the table and has string manipulation methods performed on it.

const columns = useMemo(
  () => [
    {
      accessorKey: 'name',
      header: 'Name',
      Header: ({ column }) => (
        <i style={{ color: 'red' }}>{column.columnDef.header}</i> //re-use the header we already defined
      ), //arrow function
    },
    {
      accessorKey: 'age',
      header: 'Age',
      Header: <i style={{ color: 'red' }}>Age</i>, //plain jsx with no function
    },
  ],
  [],
);

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.

const columns = useMemo(
  () => [
    {
      accessorFn: (row) => `${row.firstName} ${row.lastName}`,
      header: 'Name',
      //Add a link in a cell render
      Cell: ({ renderedCellValue, row }) => (
        <Link to={`/profile/${row.original.username}`}>
          {renderedCellValue}
        </Link>
      ),
    },
    {
      accessorKey: 'salary',
      header: 'Salary',
      //Format a number in a cell render
      Cell: ({ cell }) => (
        <span>${cell.getValue<number>().toLocaleString()}</span>
      ),
    },
    {
      accessorKey: 'profileImage',
      header: 'Profile Image',
      //Render images in a cell render
      Cell: ({ cell }) => <img src={cell.getValue<string>()} />,
    },
  ],
  [],
);

If you want to pass in custom JSX to render the footer, you can pass in a Footer option. If no custom markup is needed, you can just use the footer string property.

The footer cells can be a good place to put totals or other summary information.

const columns = useMemo(
  () => [
    {
      accessorKey: 'name',
      header: 'Name',
      footer: 'Name', //simple string header
    },
    {
      accessorKey: 'age',
      header: 'Age',
      //Custom footer markup for a aggregation calculation
      Footer: () => (
        <Stack>
          Max Age:
          <Box color="warning.main">{Math.round(maxAge)}</Box>
        </Stack>
      ),
    },
  ],
  [],
);

See the Customize Components Guide for more ways to style and customize header and cell components.

This topic is covered in detail in the Column Size Guide, but here is a brief overview.

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.

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',
    header: 'Username',
    minSize: 100, //min size enforced during resizing
    maxSize: 200, //max size enforced during resizing
    size: 180, //medium column
  },
  {
    accessorKey: 'email',
    header: 'Email',
    size: 300, //large column
  },
];

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 for more details on the layoutModes, and how and why they are enabled and how they affect column widths.

By default, all columns are left-aligned. You can change the alignment of a column by setting the align option to either "center", "right", or "justify" in the muiTableHeadCellProps and muiTableBodyCellProps props/column options.

const columns = [
  {
    accessorKey: 'id',
    header: 'ID',
    //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, body, and footer cells each individually
    muiTableHeadCellProps: {
      align: 'center',
    },
    muiTableBodyCellProps: {
      align: 'center',
    },
    muiTableFooterCellProps: {
      align: 'center',
    },
  },
];

1import { useMemo } from 'react';
2import {
3  MaterialReactTable,
4  useMaterialReactTable,
5  type MRT_ColumnDef,
6} from 'material-react-table';
7import { data, type Person } from './makeData';
8
9const Example = () => {
10  const columns = useMemo<MRT_ColumnDef<Person>[]>(
11    () => [
12      {
13        accessorKey: 'firstName',
14        header: 'First Name',
15        size: 100,
16        muiTableHeadCellProps: {
17          align: 'center',
18        },
19        muiTableBodyCellProps: {
20          align: 'center',
21        },
22      },
23      {
24        accessorKey: 'lastName',
25        header: 'Last Name',
26        size: 100,
27        muiTableHeadCellProps: {
28          align: 'center',
29        },
30        muiTableBodyCellProps: {
31          align: 'center',
32        },
33      },
34      {
35        accessorKey: 'age',
36        header: 'Age',
37        muiTableHeadCellProps: {
38          align: 'right',
39        },
40        muiTableBodyCellProps: {
41          align: 'right',
42        },
43      },
44      {
45        accessorKey: 'salary',
46        header: 'Salary',
47        muiTableHeadCellProps: {
48          align: 'right',
49        },
50        muiTableBodyCellProps: {
51          align: 'right',
52        },
53        Cell: ({ cell }) =>
54          cell
55            .getValue<number>()
56            .toLocaleString('en-US', { style: 'currency', currency: 'USD' }),
57      },
58    ],
59    [],
60  );
61
62  const table = useMaterialReactTable({
63    columns,
64    data,
65  });
66
67  return <MaterialReactTable table={table} />;
68};
69
70export default Example;
71

In the same way that you can pass props to the main <MaterialReactTable /> 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.

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.