import Head from 'next/head'; import TableOptionsTable from '../../../components/prop-tables/TableOptionsTable'; import StateOptionsTable from '../../../components/prop-tables/StateOptionsTable'; import EnableExample from '../../../examples/enable-row-selection'; import SingleExample from '../../../examples/single-row-selection'; import ManualExample from '../../../examples/manual-selection'; import CustomizeExample from '../../../examples/customize-row-selection'; import PinningExample from '../../../examples/enable-row-pinning-select';
<title>{'Row Selection Guide - Material React Table V2 Docs'}</title>Material React Table has a built-in row selection feature and makes it easy to manage the selection state yourself. This guide demonstrates how to enable row selection and customize the selection behavior.
<TableOptionsTable onlyOptions={ new Set([ 'enableBatchRowSelection', 'enableMultiRowSelection', 'enableRowSelection', 'enableSelectAll', 'enableSubRowSelection', 'getRowId', 'muiSelectAllCheckboxProps', 'muiSelectCheckboxProps', 'onRowSelectionChange', 'positionToolbarAlertBanner', 'rowPinningDisplayMode', 'selectAllMode', ]) } />
<StateOptionsTable onlyOptions={new Set(['rowSelection'])} />
Selection checkboxes can be enabled with the enableRowSelection
table option.
const table = useMaterialReactTable({
columns,
data,
enableRowSelection: true,
});
return <MaterialReactTable table={table} />;
You can also enable row selection conditionally per row with the same enableRowSelection
table option, but with a callback function instead of a boolean.
const table = useMaterialReactTable({
columns,
data,
enableRowSelection: (row) => row.original.age > 18, //disable row selection for rows with age <= 18
});
New in v2.11.0
By default, when the user holds down the Shift key and clicks a row, all rows between the last selected row and the clicked row will be selected. This can be disabled with the enableBatchRowSelection
table option.
const table = useMantineReactTable({
columns,
data,
enableRowSelection: true,
enableBatchRowSelection: false, //disable batch row selection with shift key
});
There are two ways to access the selection state. You can either manage the selection state yourself or read it from the table instance.
The row selection state is managed internally by default, but you will more than likely want to have access to that state yourself. Here is how you can simply get access to the row selection state, specifically:
const [rowSelection, setRowSelection] = useState<MRT_RowSelectionState>({}); //ts type available
const table = useMaterialReactTable({
columns,
data,
enableRowSelection: true,
onRowSelectionChange: setRowSelection,
state: { rowSelection },
});
return <MaterialReactTable table={table} />;
Alternatively, you can read the selection state directly from the table
instance like so:
const table = useMaterialReactTable({
columns,
data,
enableRowSelection: true,
renderTopToolbarCustomActions: ({ table }) => (
<Button
onClick={() => {
const rowSelection = table.getState().rowSelection; //read state
const selectedRows = table.getSelectedRowModel().rows; //or read entire rows
}}
>
Download Selected Users
</Button>
),
});
useEffect(() => {
//fetch data based on row selection state or something
}, [table.getState().rowSelection]);
return <MaterialReactTable table={table} />;
Note:
table.getSelectedRowModel().rows
only really works with client-side pagination. UserowSelection
state if you are using server-side pagination. Row Models only contain rows based on thedata
you pass in.
By default, the row.id
for each row in the table is simply the index of the row in the table. You can override this and instruct Material React Table to use a more useful Row ID with the getRowId
table option. For example, you may want something like this:
const table = useMaterialReactTable({
columns,
data,
enableRowSelection: true,
getRowId: (originalRow) => originalRow.userId,
});
As rows get selected, the rowSelection
state will look like this:
{
"3f25309c-8fa1-470f-811e-cdb082ab9017": true,
"be731030-df83-419c-b3d6-9ef04e7f4a9f": true,
...
}
This can be very useful when you are trying to read your selection state and do something with your data as the row selection changes.
By default, a row can only be selected by either clicking the checkbox or radio button in the mrt-row-select
column. If you want to be able to select a row by clicking anywhere on the row, you can add your own onClick
function to a table body row like this:
const table = useMaterialReactTable({
columns,
data,
enableRowSelection: true,
//clicking anywhere on the row will select it
muiTableBodyRowProps: ({ row, staticRowIndex, table }) => ({
onClick: (event) =>
getMRT_RowSelectionHandler({ row, staticRowIndex, table })(event), //import this helper function from material-react-table
sx: { cursor: 'pointer' },
}),
});
By default, if you enable selection for each row, there will also be a select all checkbox in the header of the checkbox column. It can be hidden with the enableSelectAll
table option.
const table = useMaterialReactTable({
columns,
data,
enableRowSelection: true,
enableSelectAll: false,
});
By default, an alert banner will be show as rows are selected. You can use the positionToolbarAlertBanner
table option to show the alert banner in the top toolbar, bottom toolbar, as an overlay in the table head, or hide it completely.
const table = useMaterialReactTable({
columns,
data,
enableRowSelection: true,
positionToolbarAlertBanner: 'head-overlay', //show alert banner over table head, top toolbar, or bottom toolbar
});
By default, the enableMultiRowSelection
table option is set to true
, which means that multiple rows can be selected at once with a checkbox. If you want to only allow a single row to be selected at a time, you can set this table option to false
and a radio button will be used instead of a checkbox.
const table = useMaterialReactTable({
columns,
data,
enableMultiRowSelection: false, //shows radio buttons instead of checkboxes
enableRowSelection: true,
});
The selection checkboxes can be customized with the muiSelectCheckboxProps
table option. Any prop that can be passed to a Mui Checkbox component can be specified here. For example, you may want to use a different color for the checkbox or use some logic to disable certain rows from being selected.
const table = useMaterialReactTable({
columns,
data,
enableRowSelection: true,
muiSelectCheckboxProps: {
color: 'secondary',
},
});
You may have a use case where you want to be able to select rows by clicking them, but you do not want to show any checkboxes or radio buttons. You can do this by implementing a row selection feature yourself while keeping the enableRowSelection
table option false
so that the default selection behavior is disabled.
You can combine the row pinning feature with the row selection feature to create a cool user experience where selected rows always stay within view.
View Extra Storybook Examples