Async Loading UI Guide - Material React Table V3 Docs

Async Loading UI Feature Guide

While you are fetching your data, you may want to show some loading indicators. Material React Table has some nice loading UI features built in that look better than a simple spinner.

This guide is mostly focused on the loading UI features. Make sure to also check out the Remote Data and React Query examples for server-side logic examples.

Relevant Table Options

#	Type	More Info Links
1	CircularProgressProps \| ({ table }) => CircularProgressProps	Material UI CircularProgress Props

2	LinearProgressProps \| ({ isTopToolbar, table }) => LinearProgressProps	Material UI LinearProgress Props

3	SkeletonProps \| ({ cell, column, row, table }) => SkeletonProps	Material UI Skeleton Props

Relevant State Options

#	Type	Default Value
1	boolean	false

2	boolean	false

3	boolean	false

4	boolean	false

5	boolean	false

isLoading UI

There are three different loading UI features that are built into Material React Table:

Loading Overlay - shows spinner overlay over the table container.
Cell Skeletons - show pretty and shimmering skeletons for each cell.
Linear Progress Bars - shows progress bars above and/or below the table.

You can use any combination of these loading UIs by managing the showLoadingOverlay, showSkeletons, and showProgressBars states.

There are also two other loading states that are shortcuts for combining some of the above states:

isLoading - shows loading overlay and cell skeletons.
isSaving - shows the progress bars and adds spinners to the save buttons in editing features.

Here is some of the recommended loading UI that you might use with React Query:

const {
  data = [],
  isLoading: isLoadingTodos,
  isRefetching: isRefetchingTodos,
} = useQuery({
  /**/
});

const { mutate, isPending: isSavingTodos } = useMutation({
  /**/
});

const table = useMaterialReactTable({
  columns,
  data,
  state: {
    isLoading: isLoadingTodos, //cell skeletons and loading overlay
    showProgressBars: isRefetchingTodos, //progress bars while refetching
    isSaving: isSavingTodos, //progress bars and save button spinners
  },
});

return <MaterialReactTable table={table} />;

Note: The Loading Overlay UI makes the table container non-interactive while it is showing. This is usually desired while no data is yet in the table. Consider avoiding using the Loading Overlay UI during "refetching" operations like filtering, sorting, or pagination.

Customize Loading UI

You can customize the loading UI by passing props to the muiSkeletonProps, muiLinearProgressProps, and muiCircularProgressProps props.

const table = useMaterialReactTable({
  columns,
  data,
  muiSkeletonProps: {
    animation: 'wave',
  },
  muiLinearProgressProps: {
    color: 'secondary',
  },
  muiCircularProgressProps: {
    color: 'secondary',
  },
});

return <MaterialReactTable table={table} />;

Demo

Open Stackblitz Open Code Sandbox Open on GitHub

Primary

Secondary

Drop to group by

First Name	Last Name	Email	City

Rows per page

1-10 of 10

This example is written for MRT V3.

If your app is still using MRT V1, either Upgrade to MRT V3 or use the V1 Docs instead. (useMaterialReactTable only exists in V2 and V3)

Source Code

1import { useMemo } from 'react';
2import { MaterialReactTable, type MRT_ColumnDef } from 'material-react-table';
3import { type Person } from './makeData';
4
5const data: Array<Person> = [];
6
7const Example = () => {
8  const columns = useMemo<MRT_ColumnDef<Person>[]>(
9    //column definitions...
10    () => [
11      {
12        accessorKey: 'firstName',
13        header: 'First Name',
14      },
15      {
16        accessorKey: 'lastName',
17        header: 'Last Name',
18      },
19      {
20        accessorKey: 'email',
21        header: 'Email',
22      },
23      {
24        accessorKey: 'city',
25        header: 'City',
26      },
27    ],
28    [],
29    
30  );
31
32  return (
33    <MaterialReactTable
34      columns={columns}
35      data={data}
36      state={{ isLoading: true }}
37      muiCircularProgressProps={{
38        color: 'secondary',
39        thickness: 5,
40        size: 55,
41      }}
42      muiSkeletonProps={{
43        animation: 'pulse',
44        height: 28,
45      }}
46    />
47  );
48};
49
50export default Example;
51

Custom Loading Spinner component

New in v2.11.0

If you need to use a custom loading spinner component other than the built-in MUI one, you can now pass in custom component in the muiCircularProgressProps Component prop.

import { MyCustomSpinner } from './MyCustomSpinner';

const table = useMaterialReactTable({
  columns,
  data,
  muiCircularProgressProps: {
    Component: <MyCustomSpinner />,
  },
});

Only Show Progress Bars or Skeletons

If you do not want both progress bars and cell skeletons to show, you can use the showProgressBars and showSkeletons states, instead.

const table = useMaterialReactTable({
  columns,
  data,
  state: {
    showProgressBars: true, //or showSkeletons
  },
});

Demo

Open Stackblitz Open Code Sandbox Open on GitHub

Primary

Secondary

Drop to group by

First Name	Last Name	Email	City
Dylan	Murray	dmurray@yopmail.com	East Daphne
Raquel	Kohler	rkholer33@yopmail.com	Columbus
Ervin	Reinger	ereinger@mailinator.com	South Linda
Brittany	McCullough	bmccullough44@mailinator.com	Lincoln
Branson	Frami	bframi@yopmain.com	New York
Kevin	Klein	kklien@mailinator.com	Nebraska

Rows per page

1-6 of 6

This example is written for MRT V3.

If your app is still using MRT V1, either Upgrade to MRT V3 or use the V1 Docs instead. (useMaterialReactTable only exists in V2 and V3)

Source Code

1import { useEffect, useMemo, useState } from 'react';
2import { MaterialReactTable, type MRT_ColumnDef } from 'material-react-table';
3import { data, type Person } from './makeData';
4import { Button } from '@mui/material';
5
6const Example = () => {
7  const columns = useMemo<MRT_ColumnDef<Person>[]>(
8    //column definitions...
9    () => [
10      {
11        accessorKey: 'firstName',
12        header: 'First Name',
13      },
14      {
15        accessorKey: 'lastName',
16        header: 'Last Name',
17      },
18      {
19        accessorKey: 'email',
20        header: 'Email',
21      },
22      {
23        accessorKey: 'city',
24        header: 'City',
25      },
26    ],
27    [],
28    
29  );
30
31  const [progress, setProgress] = useState(0);
32
33  //simulate random progress for demo purposes
34  useEffect(() => {
35    const interval = setInterval(() => {
36      setProgress((oldProgress) => {
37        const newProgress = Math.random() * 20;
38        return Math.min(oldProgress + newProgress, 100);
39      });
40    }, 1000);
41    return () => clearInterval(interval);
42  }, []);
43
44  return (
45    <MaterialReactTable
46      columns={columns}
47      data={data}
48      muiLinearProgressProps={({ isTopToolbar }) => ({
49        color: 'secondary',
50        variant: 'determinate', //if you want to show exact progress value
51        value: progress, //value between 0 and 100
52        sx: {
53          display: isTopToolbar ? 'block' : 'none', //hide bottom progress bar
54        },
55      })}
56      renderTopToolbarCustomActions={() => (
57        <Button onClick={() => setProgress(0)} variant="contained">
58          Reset
59        </Button>
60      )}
61      state={{ showProgressBars: true }}
62    />
63  );
64};
65
66export default Example;
67

Full Loading and Server-Side Logic Example

Here is a copy of the full React Query example.

Demo

Open Stackblitz Open Code Sandbox Open on GitHub

Primary

Secondary

Drop to group by

First Name	Last Name	Address	State	Phone Number	Last Login

Rows per page

0-0 of 0

This example is written for MRT V3.

If your app is still using MRT V1, either Upgrade to MRT V3 or use the V1 Docs instead. (useMaterialReactTable only exists in V2 and V3)

Source Code

1import { useMemo, useState } from 'react';
2import {
3  MaterialReactTable,
4  useMaterialReactTable,
5  type MRT_ColumnDef,
6  type MRT_ColumnFiltersState,
7  type MRT_PaginationState,
8  type MRT_SortingState,
9} from 'material-react-table';
10import { IconButton, Tooltip } from '@mui/material';
11import RefreshIcon from '@mui/icons-material/Refresh';
12import {
13  QueryClient,
14  QueryClientProvider,
15  keepPreviousData,
16  useQuery,
17} from '@tanstack/react-query'; //note: this is TanStack React Query V5
18
19//Your API response shape will probably be different. Knowing a total row count is important though.
20type UserApiResponse = {
21  data: Array<User>;
22  meta: {
23    totalRowCount: number;
24  };
25};
26
27type User = {
28  firstName: string;
29  lastName: string;
30  address: string;
31  state: string;
32  phoneNumber: string;
33  lastLogin: Date;
34};
35
36const Example = () => {
37  //manage our own state for stuff we want to pass to the API
38  const [columnFilters, setColumnFilters] = useState<MRT_ColumnFiltersState>(
39    [],
40  );
41  const [globalFilter, setGlobalFilter] = useState('');
42  const [sorting, setSorting] = useState<MRT_SortingState>([]);
43  const [pagination, setPagination] = useState<MRT_PaginationState>({
44    pageIndex: 0,
45    pageSize: 10,
46  });
47
48  //consider storing this code in a custom hook (i.e useFetchUsers)
49  const {
50    data: { data = [], meta } = {}, //your data and api response will probably be different
51    isError,
52    isRefetching,
53    isLoading,
54    refetch,
55  } = useQuery<UserApiResponse>({
56    queryKey: [
57      'table-data',
58      columnFilters, //refetch when columnFilters changes
59      globalFilter, //refetch when globalFilter changes
60      pagination.pageIndex, //refetch when pagination.pageIndex changes
61      pagination.pageSize, //refetch when pagination.pageSize changes
62      sorting, //refetch when sorting changes
63    ],
64    queryFn: async () => {
65      const fetchURL = new URL('/api/data', location.origin);
66
67      //read our state and pass it to the API as query params
68      fetchURL.searchParams.set(
69        'start',
70        `${pagination.pageIndex * pagination.pageSize}`,
71      );
72      fetchURL.searchParams.set('size', `${pagination.pageSize}`);
73      fetchURL.searchParams.set('filters', JSON.stringify(columnFilters ?? []));
74      fetchURL.searchParams.set('globalFilter', globalFilter ?? '');
75      fetchURL.searchParams.set('sorting', JSON.stringify(sorting ?? []));
76
77      //use whatever fetch library you want, fetch, axios, etc
78      const response = await fetch(fetchURL.href);
79      const json = (await response.json()) as UserApiResponse;
80      return json;
81    },
82    placeholderData: keepPreviousData, //don't go to 0 rows when refetching or paginating to next page
83  });
84
85  const columns = useMemo<MRT_ColumnDef<User>[]>(
86    //column definitions...
87    () => [
88      {
89        accessorKey: 'firstName',
90        header: 'First Name',
91      },
92      {
93        accessorKey: 'lastName',
94        header: 'Last Name',
95      },
96      {
97        accessorKey: 'address',
98        header: 'Address',
99      },
100      {
101        accessorKey: 'state',
102        header: 'State',
103      },
104      {
105        accessorKey: 'phoneNumber',
106        header: 'Phone Number',
107      },
108      {
109        accessorFn: (row) => new Date(row.lastLogin),
110        id: 'lastLogin',
111        header: 'Last Login',
112        Cell: ({ cell }) => new Date(cell.getValue<Date>()).toLocaleString(),
113        filterFn: 'greaterThan',
114        filterVariant: 'date',
115        enableGlobalFilter: false,
116      },
117    ],
118    [],
119    
120  );
121
122  const table = useMaterialReactTable({
123    columns,
124    data,
125    initialState: { showColumnFilters: true },
126    manualFiltering: true, //turn off built-in client-side filtering
127    manualPagination: true, //turn off built-in client-side pagination
128    manualSorting: true, //turn off built-in client-side sorting
129    muiToolbarAlertBannerProps: isError
130      ? {
131          color: 'error',
132          children: 'Error loading data',
133        }
134      : undefined,
135    onColumnFiltersChange: setColumnFilters,
136    onGlobalFilterChange: setGlobalFilter,
137    onPaginationChange: setPagination,
138    onSortingChange: setSorting,
139    renderTopToolbarCustomActions: () => (
140      <Tooltip arrow title="Refresh Data">
141        <IconButton onClick={() => refetch()}>
142          <RefreshIcon />
143        </IconButton>
144      </Tooltip>
145    ),
146    rowCount: meta?.totalRowCount ?? 0,
147    state: {
148      columnFilters,
149      globalFilter,
150      isLoading,
151      pagination,
152      showAlertBanner: isError,
153      showProgressBars: isRefetching,
154      sorting,
155    },
156  });
157
158  return <MaterialReactTable table={table} />;
159};
160
161const queryClient = new QueryClient();
162
163const ExampleWithReactQueryProvider = () => (
164  //App.tsx or AppProviders file. Don't just wrap this component with QueryClientProvider! Wrap your whole App!
165  <QueryClientProvider client={queryClient}>
166    <Example />
167  </QueryClientProvider>
168);
169
170export default ExampleWithReactQueryProvider;
171