MRT logoMaterial React Table

On This Page

    Expanding Sub-Rows (Tree Data) Feature Guide

    Material React Table has support for expanding sub-rows or tree data. This feature is useful for displaying hierarchical data. The sub-rows can be expanded and collapsed by clicking on the expand/collapse icon.

    NOTE: This feature is for expanding rows of the same data type. If you want to add expansion of more data for the same row, check out the Detail Panel Feature Guide.

    Relevant Props

    1
    Array<TData>
    Usage Docs
    2
    boolean
    TanStack Table Expanding Docs
    3
    boolean
    true
    MRT Expanding Sub Rows Docs
    4
    boolean
    MRT Expanding Sub Rows Docs
    5
    (dataRow: TData) => TData[]
    6
    boolean
    false
    TanStack Filtering Docs
    7
    () => MRT_RowModel<TData>
    8
    (row: Row<TData>) => boolean
    TanStack Table Expanding Docs
    9
    (row: Row<TData>) => boolean
    TanStack Table Expanding Docs
    10
    (originalRow: TData, index: number) => undefined | TData[]
    TanStack Table Core Table Docs
    11
    boolean
    TanStack Table Expanding Docs
    12
    number
    100
    TanStack Table Filtering Docs
    13
    IconButtonProps | ({ table }) => IconButtonProps
    Material UI IconButton Props
    14
    IconButtonProps | ({ row, table }) => IconButtonProps
    Material UI IconButton Props
    15
    OnChangeFn<ExpandedState>
    TanStack Table Expanding Docs
    16
    boolean
    TanStack Table Expanding Docs
    17
    'first' | 'last'

    Relevant State Options

    1
    Record<string, boolean> | boolean
    {}
    TanStack Table Expanding Docs

    Enable Expanding Sub-Rows

    To enable expanding sub-rows, you must first set the enableExpanding prop to true.

    However, your data must also be formatted in a way to allow for expanding rows that are in some way related to each other. By default, Material React Table will look for a special subRows property on each row of your data and treat any array of rows that it finds as the sub-rows for that row. You can customize or override this behavior by passing a custom getSubRows prop.

    const data = [
    {
    id: 1,
    name: 'John Doe',
    subRows: [
    {
    id: 2,
    name: 'Jane Doe',
    },
    ],
    },
    ];
    return (
    <MaterialReactTable
    columns={columns}
    data={data}
    enableExpanding
    getSubRows={(originalRow) => originalRow.subRows} //default, can customize
    />
    );

    Demo

    Open StackblitzOpen Code SandboxOpen on GitHub
    DylanMurray261 Erdman FordEast DaphneKentucky
    RaquelKohler769 Dominic GroveColumbusOhio

    Rows per page

    1-2 of 2

    Source Code

    1import React, { useMemo } from 'react';
    2import { MaterialReactTable, type MRT_ColumnDef } from 'material-react-table';
    3
    4export type Person = {
    5 firstName: string;
    6 lastName: string;
    7 address: string;
    8 city: string;
    9 state: string;
    10 subRows?: Person[]; //Each person can have sub rows of more people
    11};
    12
    13export const data = [
    14 {
    15 firstName: 'Dylan',
    16 lastName: 'Murray',
    17 address: '261 Erdman Ford',
    18 city: 'East Daphne',
    19 state: 'Kentucky',
    20 subRows: [
    21 {
    22 firstName: 'Ervin',
    23 lastName: 'Reinger',
    24 address: '566 Brakus Inlet',
    25 city: 'South Linda',
    26 state: 'West Virginia',
    27 subRows: [
    28 {
    29 firstName: 'Jordane',
    30 lastName: 'Homenick',
    31 address: '1234 Brakus Inlet',
    32 city: 'South Linda',
    33 state: 'West Virginia',
    34 },
    35 ],
    36 },
    37 {
    38 firstName: 'Brittany',
    39 lastName: 'McCullough',
    40 address: '722 Emie Stream',
    41 city: 'Lincoln',
    42 state: 'Nebraska',
    43 },
    44 ],
    45 },
    46 {
    47 firstName: 'Raquel',
    48 lastName: 'Kohler',
    49 address: '769 Dominic Grove',
    50 city: 'Columbus',
    51 state: 'Ohio',
    52 subRows: [
    53 {
    54 firstName: 'Branson',
    55 lastName: 'Frami',
    56 address: '32188 Larkin Turnpike',
    57 city: 'Charleston',
    58 state: 'South Carolina',
    59 },
    60 ],
    61 },
    62];
    63
    64const Example = () => {
    65 const columns = useMemo<MRT_ColumnDef<Person>[]>(
    66 //column definitions...
    94 );
    95
    96 return (
    97 <MaterialReactTable
    98 columns={columns}
    99 data={data}
    100 enableExpanding
    101 enableExpandAll //default
    102 />
    103 );
    104};
    105
    106export default Example;
    107

    Expand All Rows Button

    By default, Material React Table will show the expand all button in the expand column header. You can disable this by setting the enableExpandAll prop to false.

    <MaterialReactTable
    columns={columns}
    data={data}
    enableExpanding
    enableExpandAll={false} //hide expand all button in header
    />

    Expanded Rows Pagination Behavior

    By default, Material React Table will treat expanded sub-rows the same as any other row when it comes to pagination. This means that some expanded rows may be on the next page. You can change this behavior by setting the paginateExpandedRows prop to false.

    <MaterialReactTable
    columns={columns}
    data={data}
    enableExpanding
    paginateExpandedRows={false} //expanded rows will be on the same page as their parent row
    />

    Expanded Leaf Row Filtering Behavior

    If you are using the filtering features alongside sub-row features, then there are a few behaviors and customizations you should be aware of.

    Filter From Leaf Rows

    By default, filtering is done from parent rows down (so if a parent row is filtered out, all of its children will be filtered out as well). Setting the filterFromLeafRows prop to true will cause filtering to be done from leaf rows up (which means parent rows will be kept so long as one of their child, or grand-child, etc. rows pass the filtering).

    <MaterialReactTable
    columns={columns}
    data={data}
    enableExpanding
    filterFromLeafRows //search for child rows and preserve parent rows
    />

    Max Leaf Row Filter Depth

    New in v1.3.11 from TanStack Table v8.6.0 and later!

    By default, filtering is done for all rows (max depth of 100), no matter if they are root level parent rows or the child leaf rows of a parent row. Setting the maxLeafRowFilterDepth prop to 0 will cause filtering to only be applied to the root level parent rows, with all sub-rows remaining unfiltered. Similarly, setting this option to 1 will cause filtering to only be applied to child leaf rows 1 level deep, and so on.

    This is useful for situations where you want a row's entire child hierarchy to be visible, regardless of the applied filter.

    <MaterialReactTable
    columns={columns}
    data={data}
    enableExpanding
    maxLeafRowFilterDepth={0} //When filtering root rows, keep all child rows of the passing parent rows
    />

    Expand All Rows By Default

    You can manage the initial state of the expanded rows with the expanded state option in either the initialState or state props.

    For example, you may want all rows to be expanded by default. To do this, you can simply set the expanded state option to true.

    <MaterialReactTable
    columns={columns}
    data={data}
    enableExpanding
    initialState={{ expanded: true }} //all rows expanded by default
    />

    Demo

    DylanMurray261 Erdman FordEast DaphneKentucky
    ErvinReinger566 Brakus InletSouth LindaWest Virginia
    JordaneHomenick1234 Brakus InletSouth LindaWest Virginia
    JordanClarkson4882 Palm RdSan FranciscoCalifornia
    BrittanyMcCullough722 Emie StreamLincolnNebraska
    RaquelKohler769 Dominic GroveColumbusOhio
    BransonFrami32188 Larkin TurnpikeCharlestonSouth Carolina

    Rows per page

    1-2 of 2

    Source Code

    1import React, { useMemo } from 'react';
    2import { MaterialReactTable, type MRT_ColumnDef } from 'material-react-table';
    3
    4export type Person = {
    5 firstName: string;
    6 lastName: string;
    7 address: string;
    8 city: string;
    9 state: string;
    10 subRows?: Person[]; //Each person can have sub rows of more people
    11};
    12
    13export const data: Person[] = [
    14 {
    15 firstName: 'Dylan',
    16 lastName: 'Murray',
    17 address: '261 Erdman Ford',
    18 city: 'East Daphne',
    19 state: 'Kentucky',
    20 subRows: [
    21 {
    22 firstName: 'Ervin',
    23 lastName: 'Reinger',
    24 address: '566 Brakus Inlet',
    25 city: 'South Linda',
    26 state: 'West Virginia',
    27 subRows: [
    28 {
    29 firstName: 'Jordane',
    30 lastName: 'Homenick',
    31 address: '1234 Brakus Inlet',
    32 city: 'South Linda',
    33 state: 'West Virginia',
    34 },
    35 {
    36 firstName: 'Jordan',
    37 lastName: 'Clarkson',
    38 address: '4882 Palm Rd',
    39 city: 'San Francisco',
    40 state: 'California',
    41 },
    42 ],
    43 },
    44 {
    45 firstName: 'Brittany',
    46 lastName: 'McCullough',
    47 address: '722 Emie Stream',
    48 city: 'Lincoln',
    49 state: 'Nebraska',
    50 },
    51 ],
    52 },
    53 {
    54 firstName: 'Raquel',
    55 lastName: 'Kohler',
    56 address: '769 Dominic Grove',
    57 city: 'Columbus',
    58 state: 'Ohio',
    59 subRows: [
    60 {
    61 firstName: 'Branson',
    62 lastName: 'Frami',
    63 address: '32188 Larkin Turnpike',
    64 city: 'Charleston',
    65 state: 'South Carolina',
    66 },
    67 ],
    68 },
    69];
    70
    71const Example = () => {
    72 const columns = useMemo<MRT_ColumnDef<Person>[]>(
    73 //column definitions...
    101 );
    102
    103 return (
    104 <MaterialReactTable
    105 columns={columns}
    106 data={data}
    107 enableExpandAll={false} //hide expand all double arrow in column header
    108 enableExpanding
    109 filterFromLeafRows //apply filtering to all rows instead of just parent rows
    110 initialState={{ expanded: true }} //expand all rows by default
    111 paginateExpandedRows={false} //When rows are expanded, do not count sub-rows as number of rows on the page towards pagination
    112 />
    113 );
    114};
    115
    116export default Example;
    117

    Expand Root Rows Only By Default

    Here is a slightly more complex initial expanded state example where all the root rows are expanded by default, but none of the sub rows themselves are expanded by default. We just need to find all of the root row ids and set their key in the expanded initialState option to true.


    Demo

    DylanMurray261 Erdman FordEast DaphneKentucky
    ErvinReinger566 Brakus InletSouth LindaWest Virginia
    BrittanyMcCullough722 Emie StreamLincolnNebraska
    RaquelKohler769 Dominic GroveColumbusOhio
    BransonFrami32188 Larkin TurnpikeCharlestonSouth Carolina

    Rows per page

    1-5 of 5

    Source Code

    1import React, { useMemo } from 'react';
    2import {
    3 MaterialReactTable,
    4 type MRT_ExpandedState,
    5 type MRT_ColumnDef,
    6} from 'material-react-table';
    7import { Button } from '@mui/material';
    8
    9export type Person = {
    10 id: string;
    11 firstName: string;
    12 lastName: string;
    13 address: string;
    14 city: string;
    15 state: string;
    16 subRows?: Person[]; //Each person can have sub rows of more people
    17};
    18
    19//data definitions...
    95
    96const Example = () => {
    97 const columns = useMemo<MRT_ColumnDef<Person>[]>(
    98 //column definitions...
    126 );
    127
    128 const initialExpandedRootRows = useMemo<MRT_ExpandedState>(
    129 () =>
    130 data
    131 .map((originalRow) => originalRow.id) //get all the root row ids, use recursion for additional levels
    132 .reduce((a, v) => ({ ...a, [v]: true }), {}), //convert to an object with all the ids as keys and `true` as values
    133 [],
    134 );
    135
    136 return (
    137 <MaterialReactTable
    138 columns={columns}
    139 data={data}
    140 enableExpanding
    141 getRowId={(originalRow) => originalRow.id}
    142 initialState={{ expanded: initialExpandedRootRows }} //only expand the root rows by default
    143 renderTopToolbarCustomActions={({ table }) => (
    144 <Button onClick={() => table.resetExpanded()}>Reset Expanded</Button>
    145 )}
    146 />
    147 );
    148};
    149
    150export default Example;
    151