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:

1. Transform the value

   const columns: GridColDef[] = [
     {
       field: 'taxRate',
       valueGetter: (params) => {
         if (!params.value) {
           return params.value;
         }
         // Convert the decimal value to a percentage
         return params.value * 100;
       },
     },
   ];
   

   Copy (or $keyC)

2. Render a combination of different fields

   const columns: GridColDef[] = [
     {
       field: 'fullName',
       valueGetter: (params) => {
         return `${params.row.firstName || ''} ${params.row.lastName || ''}`;
       },
     },
   ];
   

   Copy (or $keyC)

3. Derive a value from a complex value

   const columns: GridColDef[] = [
     {
       field: 'profit',
       valueGetter: ({ row }) => {
         if (!row.gross || !row.costs) {
           return null;
         }
         return row.gross - row.costs;
       },
     },
   ];
   

   Copy (or $keyC)

The value returned by valueGetter is used for:

• Filtering
• Sorting
• Rendering (unless enhanced further by valueFormatter or renderCell)

Value formatter

The value formatter allows you to 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 (e.g. "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 (e.g. 0.2) to a decimal value (e.g. 20), and valueFormatter is used to display it as a percentage (e.g. 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:

1. renderCell() => ReactElement
2. valueFormatter() => string
3. valueGetter() => string
4. row[field]

The renderCell method of the column definitions is similar to valueFormatter. However, it trades to be able to only render in a cell in exchange for allowing to return a React node (instead of a string).

const columns: GridColDef[] = [
  {
    field: 'date',
    headerName: 'Year',
    renderCell: (params: GridRenderCellParams<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 will allow seeing 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.

The following are the native column types:

• 'string' (default)
• 'number'
• 'date'
• 'dateTime'
• 'boolean'
• 'singleSelect'
• 'actions'

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:

• 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']
  }
  

  Copy (or $keyC)

• If the column type is 'actions', you need to provide a getActions function that returns an array of actions available for each row (React elements). You can add the showInMenu prop on the returned React elements to signal the data grid to group these actions inside a row menu.

  {
    field: 'actions',
    type: 'actions',
    getActions: (params: GridRowParams) => [
      <GridActionsCellItem icon={...} onClick={...} label="Delete" />,
      <GridActionsCellItem icon={...} onClick={...} label="Print" showInMenu />,
    ]
  }
  

  Copy (or $keyC)

Custom column types

You can extend the native column types with your own by simply spreading the necessary properties.

The demo below defines a new column type: usdPrice that extends the native number column type.

const usdPrice: GridColTypeDef = {
  type: 'number',
  width: 130,
  valueFormatter: ({ value }) => valueFormatter.format(Number(value)),
  cellClassName: 'font-tabular-nums',
};

Selectors

Visible columns

Those selectors do not take into account hidden columns.

Defined columns

Those selectors consider all the defined columns, including hidden ones.

More information about the selectors and how to use them on the dedicated page.

API

• DataGrid
• DataGridPro
• DataGridPremium