Data Grid - Column definition
Define your columns.
The columns are defined with the
columns prop which has the type
GridColDef[].
field is the only required property
since it's the column identifier. It's
also used to match with
GridRowModel values.
interface GridColDef {
/**
* The column identifier. It's used to match with [[GridRowModel]] values.
*/
field: string;
…
}
Providing content
By default, the Data Grid uses the field of a
column to get its value. For instance, the
column with field name will render
the value stored in row.name. But
for some columns, it can be useful to manually
get and format the value to render.
Value getter
Sometimes a column might not have a desired
value. You can use the
valueGetter attribute of
GridColDef to:
-
Transform the value
const columns: GridColDef[] = [ { field: 'taxRate', valueGetter: (value) => { if (!value) { return value; } // Convert the decimal value to a percentage return value * 100; }, }, ]; -
Render a combination of different fields
const columns: GridColDef[] = [ { field: 'fullName', valueGetter: (value, row) => { return `${row.firstName || ''} ${row.lastName || ''}`; }, }, ]; -
Derive a value from a complex value
const columns: GridColDef[] = [ { field: 'profit', valueGetter: (value, row) => { if (!row.gross || !row.costs) { return null; } return row.gross - row.costs; }, }, ];
The value returned by
valueGetter is used for:
- Filtering
- Sorting
-
Rendering (unless enhanced further by
valueFormatter()orrenderCell())
Value formatter
The value formatter lets you convert the value
before displaying it. Common use cases include
converting a JavaScript Date object
to a date string or a Number into a
formatted number (for example
"1,000.50").
Note, that the value returned by
valueFormatter is only used for
rendering purposes. Filtering and sorting are
based on the raw value (row[field])
or the value returned by
valueGetter.
In the following demo,
valueGetter is used to convert the
tax rate (for example 0.2) to a
decimal value (for example 20), and
valueFormatter is used to display
it as a percentage (for example
20%).
Rendering cells
By default, the Data Grid renders the value as a string in the cell. It resolves the rendered output in the following order:
-
renderCell() => ReactElement -
valueFormatter() => string valueGetter() => stringrow[field]
The renderCell() method of the
column definitions is similar to
valueFormatter(). However, it
trades the ability to only render in a cell in
exchange for letting you return a React node
(instead of a string).
const columns: GridColDef[] = [
{
field: 'date',
headerName: 'Year',
renderCell: (params: GridRenderCellParams<any, Date>) => (
<strong>
{params.value.getFullYear()}
<Button
variant="contained"
size="small"
style={{ marginLeft: 16 }}
tabIndex={params.hasFocus ? 0 : -1}
>
Open
</Button>
</strong>
),
},
];
Styling cells
You can check the styling cells section for more information.
Making accessible cells
Cell content should not be in the tab sequence except if cell is focused. You can check the tab sequence section for more information.
Using hooks inside a renderer
The renderCell() property is a
function that returns a React node, not a React
component.
If you want to use React hooks inside your renderer, you should wrap them inside a component.
// ❌ Not valid
const column = {
// ...other properties,
renderCell: () => {
const [count, setCount] = React.useState(0);
return (
<Button onClick={() => setCount((prev) => prev + 1)}>{count} click(s)</Button>
);
},
};
// ✅ Valid
const CountButton = () => {
const [count, setCount] = React.useState(0);
return (
<Button onClick={() => setCount((prev) => prev + 1)}>{count} click(s)</Button>
);
};
const column = {
// ...other properties,
renderCell: () => <CountButton />,
};
Expand cell renderer
By default, the Data Grid cuts the content of a cell and renders an ellipsis if the content of the cell does not fit in the cell. As a workaround, you can create a cell renderer that lets users see the full content of the cell in the Data Grid.
Column types
To facilitate the configuration of the columns, some column types are predefined. By default, columns are assumed to hold strings, so the default column string type will be applied. As a result, column sorting will use the string comparator, and the column content will be aligned to the left side of the cell. Some column types require that their value have a specific type.
The following are the native column types with their required value types:
Long text keyboard interactions
The 'longText' column type
supports keyboard interactions to expand,
collapse, and edit content when the cell is
focused via click or keyboard navigation.
View mode (expand button focused):
- Space – Toggle popup
- Escape – Close popup
Edit mode (textarea focused):
- Shift+Enter – Insert newline
- Enter – Commit changes
- Escape – Cancel editing
Multi-select keyboard interactions
The 'multiSelect' column
type supports keyboard interactions to expand
overflow chips and edit values when the cell is
focused via click or keyboard navigation.
View mode (cell focused):
- Space – Toggle overflow popup to see all values
- Escape – Close popup
- Enter or F2 – Enter edit mode
Edit mode (autocomplete focused):
- Arrow Up/Arrow Down – Navigate through options
- Ctrl+Enter (or Cmd+Enter on macOS) – Select/deselect highlighted option (dropdown stays open)
- Enter – Commit changes and exit edit mode
- Escape – Cancel editing and close dropdown
- Backspace (empty input) – Remove last selected chip
Converting types
Default methods, such as filtering and sorting,
assume that the type of the values will match
the type of the column specified in
type. For example, values of column
with type: 'dateTime' are
expecting to be stored as a
Date() objects. If for any reason,
your data type is not the correct one, you can
use valueGetter to parse the value
to the correct type.
{
field: 'lastLogin',
type: 'dateTime',
valueGetter: (value) => value && new Date(value),
}
Special properties
To use most of the column types, you only need
to define the type property in your
column definition. However, some types require
additional properties to be set to make them
work correctly:
Single select
If the column type is
'singleSelect', you also
need to set the
valueOptions property in the
respective column definition. These values are
options used for filtering and editing.
{
field: 'country',
type: 'singleSelect',
valueOptions: ['United Kingdom', 'Spain', 'Brazil']
}
Multi select
If the column type is
'multiSelect', you need to
set the valueOptions property
similar to singleSelect. The cell
value should be an array of values from the
options.
{
field: 'tags',
type: 'multiSelect',
valueOptions: ['React', 'TypeScript', 'JavaScript', 'Node.js']
}
The multiSelect column displays values as chips, with overflow handling when the column is narrow. Users can edit cells using a multi-select autocomplete dropdown.
Actions
If the column type is
'actions', you need to
provide a renderCell() function
that renders a
GridActionsCell component with
GridActionsCellItem elements as
children. You can add the
showInMenu prop on the
GridActionsCellItem elements to
signal the Data Grid to group these actions
inside a row menu.
{
field: 'actions',
type: 'actions',
renderCell: (params) => (
<GridActionsCell {...params}>
<GridActionsCellItem icon={...} onClick={...} label="Delete" />
<GridActionsCellItem icon={...} onClick={...} label="Print" showInMenu />
</GridActionsCell>
)
}
By default, actions shown in the menu will close
the menu on click. But in some cases, you might
want to keep the menu open after clicking an
action. You can achieve this by setting the
closeMenuOnClick prop to
false.
In the following example, the "Delete" action opens a confirmation dialog and therefore needs to keep the menu mounted:
Custom column types
Please refer to the custom columns page for documentation and integration examples.
Autogenerated rows
Some features like
row grouping
or
aggregation
create autogenerated rows. These rows also call
functions like valueGetter(),
valueFormatter() and
renderCell(), and that can cause
issues if you're not expecting it because
the row parameter will be an empty
object and the value parameter will
be undefined. If we take for
example the movie dataset, you can detect
autogenerated rows using
isAutogeneratedRow():
{
field: 'title',
valueGetter: (value, row) => {
if (isAutogeneratedRow(row)) {
return '[this is an autogenerated row]';
}
return `title: ${value}`;
},
}
Signature:
gridColumnPositionsSelector: (apiRef: GridApiRef) => number[]
Example
const columnPositions = gridColumnPositionsSelector(apiRef);
Signature:
gridColumnVisibilityModelSelector: (apiRef: GridApiRef) => GridColumnVisibilityModel
Example
const columnVisibilityModel = gridColumnVisibilityModelSelector(apiRef);
Signature:
gridColumnsTotalWidthSelector: (apiRef: GridApiRef) => number
Example
const columnsTotalWidth = gridColumnsTotalWidthSelector(apiRef);
Signature:
gridPinnedColumnsSelector: (apiRef: GridApiRef) => GridPinnedColumnFields
Example
const pinnedColumns = gridPinnedColumnsSelector(apiRef);
Signature:
gridVisibleColumnDefinitionsSelector: (apiRef: GridApiRef) => GridStateColDef[]
Example
const visibleColumnDefinitions = gridVisibleColumnDefinitionsSelector(apiRef);
Signature:
gridVisibleColumnFieldsSelector: (apiRef: GridApiRef) => string[]
Example
const visibleColumnFields = gridVisibleColumnFieldsSelector(apiRef);
Signature:
gridVisiblePinnedColumnDefinitionsSelector: (apiRef: GridApiRef) => { left: GridStateColDef[]; right: GridStateColDef[] }
Example
const visiblePinnedColumnDefinitions = gridVisiblePinnedColumnDefinitionsSelector(apiRef);
Defined columns
Those selectors consider all the defined columns, including hidden ones.
Signature:
gridColumnDefinitionsSelector: (apiRef: GridApiRef) => GridStateColDef[]
Example
const columnDefinitions = gridColumnDefinitionsSelector(apiRef);
Signature:
gridColumnFieldsSelector: (apiRef: GridApiRef) => string[]
Example
const columnFields = gridColumnFieldsSelector(apiRef);
Signature:
gridColumnLookupSelector: (apiRef: GridApiRef) => GridColumnLookup
Example
const columnLookup = gridColumnLookupSelector(apiRef);
Signature:
gridColumnsStateSelector: (apiRef: GridApiRef) => GridColumnsState
Example
const columnsState = gridColumnsStateSelector(apiRef);
Signature:
gridFilterableColumnDefinitionsSelector: (apiRef: GridApiRef) => GridStateColDef[]
Example
const filterableColumnDefinitions = gridFilterableColumnDefinitionsSelector(apiRef);
Signature:
gridFilterableColumnLookupSelector: (apiRef: GridApiRef) => GridColumnLookup
Example
const filterableColumnLookup = gridFilterableColumnLookupSelector(apiRef);
More information about the selectors and how to use them on the dedicated page.