MRT logoMaterial React Table

On This Page

    Usage

    Here is a brief overview of how to use Material React Table. These are very simple examples and will not cover all features of the library, but should be a great starting point.

    Setup

    To start using MaterialReactTable, you first need to install material-react-table and the necessary Material UI v5 dependencies.

    There are additional steps and customizations you can do for Material UI, if you have not set it up in your application already. Check out the Material UI docs for more information.

    If you need to change the colors of the table components, advanced Material UI Theming is covered in the Customize Components guide.

    Import MaterialReactTable and useMaterialReactTable

    Once you have everything installed, you can import from material-react-table like this:

    import { MaterialReactTable, useMaterialReactTable } from 'material-react-table';

    MaterialReactTable is the main component that you will use to render your table.

    useMaterialReactTable is the React hook that you will use to define all the columns, data, and other options for your table.

    Creating Data/Rows

    Your data must be an array of objects that have properties matching the accessors in your column definitions. The objects themselves can theoretically be in any shape, but it will be easier to set up your columns if your data is already in a flat object format like the example below, but it is not required.

    Simple Data Example

    //recommended flat structure for data, but not required (nested data is fine, but takes more setup in column definitions)
    //must be memoized or stable (useState, useMemo, defined outside of the component, etc.)
    const data = [
    {
    name: 'John', // key "name" matches `accessorKey` in ColumnDef down below
    age: 30, // key "age" matches `accessorKey` in ColumnDef down below
    },
    {
    name: 'Sara',
    age: 25,
    },
    ];

    Your data does NOT have to be created statically like this, of course. More than likely, your data is being fetched from a backend API. Check out the Remote Data example to see how you can use a remote data source.

    Creating Columns

    There are several different ways to define columns, depending on your needs. Let's create some basic "data" columns. That is, columns that connect to our data. Since we defined our data in a flat object format, we can simply use the accessorKey property to access the data.

    Simple Column Definition Example

    //simple column definitions pointing to flat data
    const columns = useMemo(
    () => [
    {
    header: 'Name',
    accessorKey: 'name', //simple recommended way to define a column
    //more column options can be added here to enable/disable features, customize look and feel, etc.
    },
    {
    header: 'Age',
    accessorFn: (dataRow) => parseInt(dataRow.age), //alternate way to access data if processing logic is needed
    },
    ],
    [],
    );

    Full Simple Example

    Put it all together, and you have a basic table! You can also play around and enable some features, either per column in the column definitions, or as props passed to <MaterialReactTable />.

    import { useMemo } from 'react';
    import {
    MaterialReactTable,
    useMaterialReactTable,
    type MRT_ColumnDef, //if using TypeScript (optional, but recommended)
    } from 'material-react-table';
    //If using TypeScript, define the shape of your data (optional, but recommended)
    interface Person {
    name: string;
    age: number;
    }
    //mock data - strongly typed if you are using TypeScript (optional, but recommended)
    const data: Person[] = [
    {
    name: 'John',
    age: 30,
    },
    {
    name: 'Sara',
    age: 25,
    },
    ];
    export default function App() {
    //column definitions - strongly typed if you are using TypeScript (optional, but recommended)
    const columns = useMemo<MRT_ColumnDef<Person>[]>(
    () => [
    {
    accessorKey: 'name', //simple recommended way to define a column
    header: 'Name',
    muiTableHeadCellProps: { style: { color: 'green' } }, //custom props
    },
    {
    accessorFn: (originalRow) => originalRow.age, //alternate way
    id: 'age', //id required if you use accessorFn instead of accessorKey
    header: 'Age',
    Header: <i style={{ color: 'red' }}>Age</i>, //optional custom markup
    },
    ],
    [],
    );
    //pass table options to useMaterialReactTable
    const table = useMaterialReactTable({
    columns,
    data, //must be memoized or stable (useState, useMemo, defined outside of this component, etc.)
    enableRowSelection: true, //enable some features
    enableColumnOrdering: true,
    enableGlobalFilter: false, //turn off a feature
    });
    //note: you can also pass table options as props directly to <MaterialReactTable /> instead of using useMaterialReactTable
    //but that is not recommended and will likely be deprecated in the future
    return <MaterialReactTable table={table} />;
    }

    Note: It is very important that the columns and data definitions are memoized or stable. Otherwise, the entire table will be re-rendered during every react re-render in your application, which can lead to performance issues. To make a variable stable, store it in useState, wrap it in useMemo, or define it outside of a component so it does not get recreated on every render.

    Live Code Sandbox Example

    Next Steps

    There are numerous ways you can customize the behavior and look and feel of your Material React Table. View some of the examples to see how you can customize your table, and visit the props page to see all the props that you can use to turn features on and off and customize the look and feel of your table.

    Also, be sure to check out all the Fundamental Guides and any of the Advanced Feature Guides you may be interested in to learn more about the different features you can toggle on and off, or customize.