Material React Table: The Only Tutorial You’ll Actually Finish

Updated: May 2025  |  Reading time: ~12 min  | 
Topics: React data table, Material-UI, TanStack Table v8

Why Material React Table Deserves Your Attention

If you’ve ever tried to build a serious
React data table
from scratch — complete with sorting, filtering, pagination, row selection, and column resizing —
you already know the pain. You start with a humble <table> tag, add one feature,
then another, and three weeks later you’re maintaining 800 lines of stateful spaghetti that nobody
on your team wants to touch. Sound familiar?

Material React Table
(MRT) solves this elegantly. It’s a feature-rich
React table component
built on top of
TanStack Table v8
(the spiritual successor to the legendary react-table library) and styled with
Material-UI (MUI).
The result is a headless, highly customizable engine dressed in polished MUI components — a combination
that covers 90% of enterprise data table requirements without a single line of custom pagination logic.

What makes it stand out in a crowded field of
React data grid Material-UI
solutions is its philosophy: everything is opt-in, nothing is locked behind a paywall, and the API
stays consistent whether you’re building a simple list view or a full-blown
React enterprise data table with virtualized rows, inline editing, and server-side
state management. Let’s unpack exactly how that works.

Installation and Initial Setup

Getting started with
material-react-table installation
is refreshingly straightforward. The library depends on MUI core, MUI icons, and Emotion for styling —
so if your project already runs on Material-UI, you’re halfway there. If not, the full dependency set
installs in one shot.

# Install Material React Table and its peer dependencies
npm install material-react-table \
  @mui/material \
  @mui/icons-material \
  @emotion/react \
  @emotion/styled

Once installed, the
material-react-table setup
follows a clean two-step pattern: define your columns with the useMemo hook (for performance),
bring in your data array, call useMaterialReactTable() with both, and render
<MaterialReactTable table={table} />. That’s it — you have a fully functional,
styled, and interactive table with zero additional configuration.

One detail worth noting early: MRT v2 introduced the useMaterialReactTable hook as the
primary API, replacing the older prop-drilling pattern from v1. This change makes state management
much cleaner, because the table instance returned by the hook gives you direct access
to internal state, row models, and action dispatchers — all in one object. It’s a small architectural
shift that pays dividends the moment your requirements grow beyond the basics.

A Practical Material React Table Example

Theory is cheap. Here’s a complete, working
material-react-table example
that demonstrates a realistic employee directory — the kind of component that appears in almost every
internal business application. It includes typed columns, memoized data, and the default MRT toolbar
with search, column visibility toggles, and density controls.

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

type Employee = {
  id: number;
  name: string;
  department: string;
  role: string;
  salary: number;
  startDate: string;
};

const data: Employee[] = [
  { id: 1, name: 'Alice Martin',  department: 'Engineering', role: 'Senior Dev',  salary: 120000, startDate: '2021-03-15' },
  { id: 2, name: 'Bob Chen',      department: 'Design',      role: 'UX Lead',     salary: 105000, startDate: '2020-07-01' },
  { id: 3, name: 'Carol Davis',   department: 'Engineering', role: 'DevOps',      salary: 115000, startDate: '2022-01-10' },
  { id: 4, name: 'Dan Okonkwo',   department: 'Product',     role: 'PM',          salary: 130000, startDate: '2019-11-20' },
  { id: 5, name: 'Eva Rossi',     department: 'Engineering', role: 'Frontend Dev',salary: 98000,  startDate: '2023-02-28' },
];

export default function EmployeeTable() {
  const columns = useMemo<MRT_ColumnDef<Employee>[]>(
    () => [
      { accessorKey: 'id',         header: 'ID',         size: 60  },
      { accessorKey: 'name',       header: 'Full Name',  size: 180 },
      { accessorKey: 'department', header: 'Department', size: 140 },
      { accessorKey: 'role',       header: 'Role',       size: 150 },
      {
        accessorKey: 'salary',
        header: 'Salary',
        size: 120,
        Cell: ({ cell }) =>
          new Intl.NumberFormat('en-US', {
            style: 'currency',
            currency: 'USD',
            maximumFractionDigits: 0,
          }).format(cell.getValue<number>()),
      },
      { accessorKey: 'startDate', header: 'Start Date', size: 130 },
    ],
    [],
  );

  const table = useMaterialReactTable({
    columns,
    data,
    enableColumnResizing: true,
    enableStickyHeader:   true,
    initialState: {
      density:    'compact',
      pagination: { pageSize: 10, pageIndex: 0 },
    },
  });

  return <MaterialReactTable table={table} />;
}

Notice what you get for free here: global search, per-column filters accessible from the header menu,
sortable columns, a configurable page size selector, and a responsive toolbar — all from roughly
50 lines of actual business logic. The Cell renderer on the salary column shows how
trivially easy it is to format displayed values without touching the underlying data model.
This is the kind of developer experience that makes MRT worth learning properly.

The enableStickyHeader option is one of those small details that separates a polished table
from a frustrating one. Once your dataset grows past a screenful, users need the header visible while
they scroll — and enabling it costs exactly one boolean prop. Similarly, initialState.density
lets you ship a compact view by default while still allowing users to switch to comfortable or spacious
density via the built-in toolbar button. UX wins with zero custom code.

Sorting, Filtering, and Pagination — The Core Trio

Material React Table sorting
is enabled by default on every column that has an accessorKey or accessorFn.
Clicking a column header toggles ascending → descending → unsorted states, and MRT handles the
visual indicator (the sort icon) automatically. Multi-column sorting is one prop away:
enableMultiSort: true. Users can then hold Shift and click multiple headers
to build compound sort orders — something that usually takes a non-trivial custom implementation
in other libraries.

Material React Table filtering
operates at two levels simultaneously. The global search bar (enabled via enableGlobalFilter,
which defaults to true) fuzzy-searches across all columns at once. Column-level filters,
accessible via the filter icon in each header menu, let users narrow by individual fields.
MRT ships with sensible filter variants out of the box — text, date range, select, multi-select,
range slider — and you can assign a specific variant per column using filterVariant.
For a department column with a fixed set of values, filterVariant: 'select' gives users
a dropdown instead of a free-text box, which is simply better UX.

Material React Table pagination
is equally hands-off. The default paginated toolbar renders page navigation, a „rows per page“ selector,
and a summary of the current range. You control defaults through initialState.pagination
and can switch to a „load more“ button pattern or full infinite scroll by setting
enablePagination: false and implementing your own scroll trigger.
For large datasets that live on a server, MRT supports
server-side pagination through manualPagination: true combined with
rowCount and an onPaginationChange callback — a pattern that maps cleanly
onto REST or GraphQL endpoints.

Advanced Features for React Enterprise Data Tables

Once you’ve internalized the basics, the real power of MRT becomes apparent in its advanced feature set.
Row selection — checkboxes, radio buttons, or programmatic selection — ships ready to use.
Enable it with enableRowSelection: true, access selected rows through
table.getSelectedRowModel().rows, and hook that into your bulk-action toolbar.
This pattern is fundamental to almost every admin interface: select rows, then apply an action
(delete, export, update status). MRT handles the checkbox rendering, indeterminate states for
„select all on page“ vs „select all rows,“ and the visual feedback — you write only the business logic.

Column grouping and aggregation let you build genuinely analytical views inside
a React interactive table.
When enableGrouping: true is set, users can drag column headers into a grouping area
to cluster rows by any field. MRT will then display aggregated values in group header rows —
sum, count, mean, min, max — calculated automatically from the visible filtered dataset.
For a sales dashboard grouped by region with a summed revenue column, this feature replaces
what would otherwise be a custom D3 table or a locked-behind-paywall DataGrid Pro feature.

Virtualization is the feature that separates a capable table from one that can handle
real enterprise datasets. MRT integrates
TanStack Virtual
for both row and column virtualization. Enabling it with enableRowVirtualization: true
means MRT only renders the rows currently visible in the viewport — so a 50,000-row dataset
performs as smoothly as a 50-row one. Column virtualization follows the same logic for wide tables
with dozens of columns. These two options together make MRT a credible choice for
React enterprise data table use cases where performance is non-negotiable.
For an in-depth walkthrough of implementing this in a real project, the tutorial at
DevCrafting
is worth bookmarking.

Server-Side State: When the Client Can’t Hold All the Data

Most tutorials stop at client-side tables, which is fine for datasets under a few thousand rows.
But real enterprise applications serve data from APIs where returning everything at once is either
too slow or simply impractical. MRT handles this through the manual* family of props:
manualSorting, manualFiltering, and manualPagination.
When any of these are set to true, MRT delegates the corresponding operation to your
code instead of processing the data client-side.

The pattern is clean: you subscribe to state changes via onSortingChange,
onColumnFiltersChange, and onPaginationChange, update your own state,
fire an API request with the new parameters, and feed the response back into data.
MRT re-renders with the new rows while keeping all UI state — expanded rows, selected columns,
density — intact. Pair this with React Query or SWR for caching and loading states, and you have
a production-ready React data grid that feels native regardless of dataset size.

A subtle but important detail: when using server-side pagination, you must pass the total row count
to rowCount so MRT can calculate the correct number of pages and render the pagination
controls accurately. Forgetting this prop produces a table that shows „1 of 1 pages“ for a dataset
with a thousand rows — one of those bugs that’s obvious in hindsight and maddening in the moment.
Similarly, when manualSorting is active, MRT won’t touch your data array — so if your
API returns pre-sorted results, they’ll render exactly as received.

Customization Without Losing Your Mind

MRT’s customization model is layered and predictable. At the component level, every rendered element
accepts a muiTableBodyRowProps, muiTableHeadCellProps,
muiTableContainerProps, or similar prop that passes directly to the underlying MUI component.
You can change row background colors based on data values, add click handlers, inject custom CSS classes,
or override styles with the MUI sx prop — all without touching the internal MRT source code.

At the column level, the Cell and Header renderers let you replace the default
output with any React node. Custom cell renderers are where MRT tables go from „functional“ to „delightful“:
render status badges, progress bars, avatar stacks, action button groups, or sparkline charts inside
individual cells. The row.original object inside the renderer gives you the full data
record, so building a context-aware action menu is trivial.

For teams that need a fully custom toolbar — your own export button, a date range picker, a „save view“
feature — MRT’s renderTopToolbarCustomActions and renderBottomToolbarCustomActions
props accept React nodes that slot into the existing toolbar layout. You keep the built-in search and
column-visibility controls while injecting your own elements. It’s a composability model that respects
your design system without demanding you rebuild the entire toolbar from scratch.

Material React Table vs MUI DataGrid: An Honest Comparison

This question comes up in every project evaluation, so let’s address it directly.
MUI DataGrid
is the official MUI data table component. Its free Community tier covers basic sorting, filtering,
and pagination. The Pro and Premium tiers ($) unlock row grouping, master-detail, Excel export,
and advanced aggregation. If your team already has an MUI X license, DataGrid Pro is a reasonable
choice — it’s well-maintained, has strong TypeScript support, and integrates seamlessly with MUI themes.

Material React Table,
on the other hand, is fully open-source under MIT. Every feature — virtualization, row grouping,
aggregation, column pinning, inline editing — is available without a license key.
Its foundation on TanStack Table v8 means the table logic is battle-tested across a huge ecosystem,
and the headless architecture gives you complete rendering control. The tradeoff is that it’s a
community project rather than a corporate-backed one, so the release cadence and long-term support
picture differs from MUI X.

• Choose MUI DataGrid if you have an active MUI X subscription, prefer first-party support, and need tight integration with MUI X Charts or Date Pickers.
• Choose Material React Table if you want full features without licensing costs, need deep customization, or are building on TanStack Table’s ecosystem (e.g., sharing logic between web and React Native).

Neither is objectively superior — the right choice depends on your team’s budget, timeline, and how
far you expect to push the table’s capabilities. But for solo developers and startups watching costs,
MRT’s zero-paywall policy is a significant practical advantage over commercial
alternatives like AG Grid Enterprise.

Inline Editing: Turning a Read Table into a Write Interface

MRT supports three editing modes out of the box: modal (a dialog opens with a form),
row (the entire row switches to edit mode inline), and cell
(individual cells become editable on click). Each mode renders MUI inputs automatically based on
the column’s data type, and you hook into the save lifecycle via onEditingRowSave
or onCellEditEnd callbacks.

The cell editing mode deserves special mention for data-heavy workflows. When a user
clicks an editable cell, it transforms into an input field without disrupting the surrounding layout.
Tab key moves focus to the next editable cell — a keyboard navigation pattern that spreadsheet users
expect instinctively. Combined with an onCellEditEnd handler that fires a PATCH request
to your API, this gives you a lightweight spreadsheet-like editing experience in a standard
React table component
without adopting a full spreadsheet library.

Validation is handled by returning an error string from the muiEditTextFieldProps.onBlur
or through custom column-level editVariant configurations. MRT propagates validation
errors to the MUI input’s error and helperText props, so your error
messages render in the correct MUI style without additional wiring. For complex validation logic,
you can integrate React Hook Form within a modal edit mode — giving you full form
validation power for records that need it.

Performance Patterns and Production Considerations

Several patterns separate a MRT table that works in development from one that performs in production.
First: always wrap your columns definition in useMemo.
Column objects are used as dependency references inside TanStack Table’s internals, so a new array
on every render triggers unnecessary recalculations. This is the single most common performance
mistake in MRT implementations, and it’s trivially avoidable.

Second: for tables with computed or aggregated columns, push computation into the
accessorFn rather than the Cell renderer. The accessorFn
runs once when MRT processes the data model; the Cell renderer runs on every render cycle.
If your computed value is expensive — parsing a date string, formatting currency, computing a derived
metric — put it in accessorFn so MRT can cache it in the row model.

Third: use enableRowVirtualization proactively, not reactively. Don’t wait for users
to report scroll lag on a 5,000-row table — enable virtualization from the start for any table
that might grow beyond a few hundred rows. The setup cost is one prop; the performance benefit
is a consistently smooth 60fps scroll regardless of dataset size. Combine this with server-side
pagination for truly large datasets, and your
React interactive table will handle enterprise-scale data as gracefully as a
purpose-built data grid.