[DataGrid] Allow to control the grid density

docs/data/data-grid/accessibility/DensitySelectorSmallGrid.js

@@ -15,6 +15,8 @@ function CustomToolbar() {
 }
 
 export default function DensitySelectorSmallGrid() {
+  const [density, setDensity] = React.useState('compact');
+
   const { data } = useDemoData({
     dataSet: 'Commodity',
     rowLength: 4,
@@ -25,7 +27,11 @@ export default function DensitySelectorSmallGrid() {
     <div style={{ height: 300, width: '100%' }}>
       <DataGrid
         {...data}
-        density="compact"
+        density={density}
+        onDensityChange={(newDensity) => {
+          console.info(`Density updated to: ${newDensity}`);
+          setDensity(newDensity);
+        }}
         slots={{
           toolbar: CustomToolbar,
         }}

docs/data/data-grid/accessibility/DensitySelectorSmallGrid.tsx

@@ -3,6 +3,7 @@ import {
   DataGrid,
   GridToolbarContainer,
   GridToolbarDensitySelector,
+  GridDensity,
 } from '@mui/x-data-grid';
 import { useDemoData } from '@mui/x-data-grid-generator';
 
@@ -15,6 +16,8 @@ function CustomToolbar() {
 }
 
 export default function DensitySelectorSmallGrid() {
+  const [density, setDensity] = React.useState<GridDensity>('compact');
+
   const { data } = useDemoData({
     dataSet: 'Commodity',
     rowLength: 4,
@@ -25,7 +28,11 @@ export default function DensitySelectorSmallGrid() {
     <div style={{ height: 300, width: '100%' }}>
       <DataGrid
         {...data}
-        density="compact"
+        density={density}
+        onDensityChange={(newDensity) => {
+          console.info(`Density updated to: ${newDensity}`);
+          setDensity(newDensity);
+        }}
         slots={{
           toolbar: CustomToolbar,
         }}

docs/data/data-grid/accessibility/DensitySelectorSmallGrid.tsx.preview

@@ -1,6 +1,10 @@
 <DataGrid
   {...data}
-  density="compact"
+  density={density}
+  onDensityChange={(newDensity) => {
+    console.info(`Density updated to: ${newDensity}`);
+    setDensity(newDensity);
+  }}
   slots={{
     toolbar: CustomToolbar,
   }}

docs/data/data-grid/accessibility/accessibility.md

@@ -22,22 +22,56 @@ The [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/patterns/grid
 
 You can change the density of the rows and the column header.
 
-### Density selector
+### Density selection from the toolbar
 
-To enable the density selector, create a toolbar containing the `GridToolbarDensitySelector` component and apply it using the `toolbar` property in the Data Grid's `slots` prop.
-The user can then change the density of the Data Grid by using the density selector from the toolbar, as the following demo illustrates:
+To enable the density selection from the toolbar, you can do one of the following:
+
+1. Enable the default toolbar component by passing the `slots.toolbar` prop to the Data Grid.
+2. Create a specific toolbar containing only the `GridToolbarDensitySelector` component and apply it using the `toolbar` property in the Data Grid's `slots` prop.
+
+The user can then change the density of the Data Grid by using the density selection menu from the toolbar, as the following demo illustrates:
 
 {{"demo": "DensitySelectorGrid.js", "bg": "inline"}}
 
-To hide the density selector, add the `disableDensitySelector` prop to the Data Grid.
+To disable the density selection menu, pass the `disableDensitySelector` prop to the Data Grid.
+
+### Set the density programmatically
+
+The Data Grid exposes the `density` prop which supports the following values:
+
+- `standard` (default)
+- `compact`
+- `comfortable`
+
+You can set the density programmatically in one of the following ways:
+
+1. Uncontrolled – initialize the density with the `initialState.density` prop.
+
+   ```tsx
+   <DataGrid
+     initialState={{
+       density: 'compact',
+     }}
+   />
+   ```
+
+2. Controlled – pass the `density` and `onDensityChange` props. For more advanced use cases, you can also subscribe to the `densityChange` grid event.
+
+   ```tsx
+   const [density, setDensity] = React.useState<GridDensity>('compact');
 
-### Density prop
+   return (
+     <DataGrid
+       density={density}
+       onDensityChange={(newDensity) => setDensity(newDensity)}
+     />
+   );
+   ```
 
-Set the vertical density of the Data Grid using the `density` prop.
-This prop applies the values determined by the `rowHeight` and `columnHeaderHeight` props, if supplied.
+The `density` prop applies the values determined by the `rowHeight` and `columnHeaderHeight` props, if supplied.
 The user can override this setting with the optional toolbar density selector.
 
-The following demo shows a Data Grid with the default density set to `compact`:
+The following demo shows a Data Grid with the controlled density set to `compact` and outputs the current density to the console when the user changes it using the density selector from the toolbar:
 
 {{"demo": "DensitySelectorSmallGrid.js", "bg": "inline"}}
 

docs/data/data-grid/events/events.json

@@ -202,6 +202,13 @@
     "event": "MuiEvent<{}>",
     "componentProp": "onResize"
   },
+  {
+    "projects": ["x-data-grid", "x-data-grid-pro", "x-data-grid-premium"],
+    "name": "densityChange",
+    "description": "Fired when the density changes.",
+    "params": "GridDensity",
+    "event": "MuiEvent<{}>"
+  },
   {
     "projects": ["x-data-grid-premium"],
     "name": "excelExportStateChange",

docs/data/migration/migration-data-grid-v6/migration-data-grid-v6.md

@@ -303,6 +303,32 @@ See the [Direct state access](/x/react-data-grid/state/#direct-selector-access)
   + groupingValueGetter: (value: { name: string }) => value.name,
   ```
 
+### Density
+
+- The `density` is a [controlled prop](/x/react-data-grid/accessibility/#set-the-density-programmatically) now, if you were previously passing the `density` prop to the Data Grid, you will need to do one of the following:
+
+1. Move it to the `initialState.density` to initialize it.
+
+```diff
+ <DataGrid
+-  density="compact"
++  initialState={{ density: "compact" }}
+ />
+```
+
+2. Move it to the state and use `onDensityChange` callback to update the `density` prop accordingly for it to work as expected.
+
+```diff
+ const [density, setDensity] = React.useState<GridDensity>('compact');
+ <DataGrid
+-  density="compact"
++  density={density}
++  onDensityChange={(newDensity) => setDensity(newDensity)}
+ />
+```
+
+- The selector `gridDensityValueSelector` was removed, use the `gridDensitySelector` instead.
+
 <!-- ### Rows
 
 - -->

docs/pages/x/api/data-grid/data-grid-premium.json

@@ -361,6 +361,13 @@
         "describedArgs": ["params", "event", "details"]
       }
     },
+    "onDensityChange": {
+      "type": { "name": "func" },
+      "signature": {
+        "type": "function(density: GridDensity) => void",
+        "describedArgs": ["density"]
+      }
+    },
     "onDetailPanelExpandedRowIdsChange": {
       "type": { "name": "func" },
       "signature": {

docs/pages/x/api/data-grid/data-grid-pro.json

@@ -318,6 +318,13 @@
         "describedArgs": ["params", "event", "details"]
       }
     },
+    "onDensityChange": {
+      "type": { "name": "func" },
+      "signature": {
+        "type": "function(density: GridDensity) => void",
+        "describedArgs": ["density"]
+      }
+    },
     "onDetailPanelExpandedRowIdsChange": {
       "type": { "name": "func" },
       "signature": {

docs/pages/x/api/data-grid/data-grid.json

@@ -278,6 +278,13 @@
         "describedArgs": ["params", "event", "details"]
       }
     },
+    "onDensityChange": {
+      "type": { "name": "func" },
+      "signature": {
+        "type": "function(density: GridDensity) => void",
+        "describedArgs": ["density"]
+      }
+    },
     "onFilterModelChange": {
       "type": { "name": "func" },
       "signature": {

docs/pages/x/api/data-grid/selectors.json

@@ -124,15 +124,9 @@
   },
   {
     "name": "gridDensitySelector",
-    "returnType": "GridDensityState",
-    "description": "",
-    "supportsApiRef": false
-  },
-  {
-    "name": "gridDensityValueSelector",
     "returnType": "GridDensity",
     "description": "",
-    "supportsApiRef": true
+    "supportsApiRef": false
   },
   {
     "name": "gridDetailPanelExpandedRowIdsSelector",

docs/translations/api-docs/data-grid/data-grid-premium/data-grid-premium.json

@@ -394,6 +394,10 @@
         "details": "Additional details for this callback."
       }
     },
+    "onDensityChange": {
+      "description": "Callback fired when the density changes.",
+      "typeDescriptions": { "density": "New density value." }
+    },
     "onDetailPanelExpandedRowIdsChange": {
       "description": "Callback fired when the detail panel of a row is opened or closed.",
       "typeDescriptions": {

docs/translations/api-docs/data-grid/data-grid-pro/data-grid-pro.json

@@ -351,6 +351,10 @@
         "details": "Additional details for this callback."
       }
     },
+    "onDensityChange": {
+      "description": "Callback fired when the density changes.",
+      "typeDescriptions": { "density": "New density value." }
+    },
     "onDetailPanelExpandedRowIdsChange": {
       "description": "Callback fired when the detail panel of a row is opened or closed.",
       "typeDescriptions": {

docs/translations/api-docs/data-grid/data-grid/data-grid.json

@@ -295,6 +295,10 @@
         "details": "Additional details for this callback."
       }
     },
+    "onDensityChange": {
+      "description": "Callback fired when the density changes.",
+      "typeDescriptions": { "density": "New density value." }
+    },
     "onFilterModelChange": {
       "description": "Callback fired when the Filter model changes before the filters are applied.",
       "typeDescriptions": {

packages/x-data-grid-premium/src/DataGridPremium/DataGridPremium.tsx

@@ -678,6 +678,11 @@ DataGridPremiumRaw.propTypes = {
    * @param {GridCallbackDetails} details Additional details for this callback.
    */
   onColumnWidthChange: PropTypes.func,
+  /**
+   * Callback fired when the density changes.
+   * @param {GridDensity} density New density value.
+   */
+  onDensityChange: PropTypes.func,
   /**
    * Callback fired when the detail panel of a row is opened or closed.
    * @param {GridRowId[]} ids The ids of the rows which have the detail panel open.

packages/x-data-grid-pro/src/DataGridPro/DataGridPro.tsx

@@ -591,6 +591,11 @@ DataGridProRaw.propTypes = {
    * @param {GridCallbackDetails} details Additional details for this callback.
    */
   onColumnWidthChange: PropTypes.func,
+  /**
+   * Callback fired when the density changes.
+   * @param {GridDensity} density New density value.
+   */
+  onDensityChange: PropTypes.func,
   /**
    * Callback fired when the detail panel of a row is opened or closed.
    * @param {GridRowId[]} ids The ids of the rows which have the detail panel open.

packages/x-data-grid/src/DataGrid/DataGrid.tsx

@@ -506,6 +506,11 @@ DataGridRaw.propTypes = {
    * @param {GridCallbackDetails} details Additional details for this callback.
    */
   onColumnWidthChange: PropTypes.func,
+  /**
+   * Callback fired when the density changes.
+   * @param {GridDensity} density New density value.
+   */
+  onDensityChange: PropTypes.func,
   /**
    * Callback fired when the Filter model changes before the filters are applied.
    * @param {GridFilterModel} model With all properties from [[GridFilterModel]].

packages/x-data-grid/src/DataGrid/useDataGridProps.ts

@@ -36,7 +36,6 @@ export const DATA_GRID_PROPS_DEFAULT_VALUES: DataGridPropsWithDefaultValues = {
   columnThreshold: 3,
   rowThreshold: 3,
   rowSelection: true,
-  density: 'standard',
   disableColumnFilter: false,
   disableColumnMenu: false,
   disableColumnSelector: false,

packages/x-data-grid/src/components/containers/GridRoot.tsx

@@ -14,7 +14,7 @@ import { useGridSelector } from '../../hooks/utils/useGridSelector';
 import { useGridPrivateApiContext } from '../../hooks/utils/useGridPrivateApiContext';
 import { useGridRootProps } from '../../hooks/utils/useGridRootProps';
 import { getDataGridUtilityClass } from '../../constants/gridClasses';
-import { gridDensityValueSelector } from '../../hooks/features/density/densitySelector';
+import { gridDensitySelector } from '../../hooks/features/density/densitySelector';
 import { DataGridProcessedProps } from '../../models/props/DataGridProps';
 import { GridDensity } from '../../models/gridDensity';
 
@@ -55,13 +55,13 @@ const GridRoot = React.forwardRef<HTMLDivElement, GridRootProps>(function GridRo
   const rootProps = useGridRootProps();
   const { children, className, ...other } = props;
   const apiRef = useGridPrivateApiContext();
-  const densityValue = useGridSelector(apiRef, gridDensityValueSelector);
+  const density = useGridSelector(apiRef, gridDensitySelector);
   const rootElementRef = apiRef.current.rootElementRef;
   const handleRef = useForkRef(rootElementRef, ref);
 
   const ownerState = {
     ...rootProps,
-    density: densityValue,
+    density,
   };
 
   const classes = useUtilityClasses(ownerState);

packages/x-data-grid/src/components/toolbar/GridToolbarDensitySelector.tsx

@@ -6,7 +6,7 @@ import { ButtonProps } from '@mui/material/Button';
 import { TooltipProps } from '@mui/material/Tooltip';
 import MenuItem from '@mui/material/MenuItem';
 import ListItemIcon from '@mui/material/ListItemIcon';
-import { gridDensityValueSelector } from '../../hooks/features/density/densitySelector';
+import { gridDensitySelector } from '../../hooks/features/density/densitySelector';
 import { GridDensity } from '../../models/gridDensity';
 import { isHideMenuKey, isTabKey } from '../../utils/keyboardUtils';
 import { useGridApiContext } from '../../hooks/utils/useGridApiContext';
@@ -33,7 +33,7 @@ const GridToolbarDensitySelector = React.forwardRef<
   const tooltipProps = slotProps.tooltip || {};
   const apiRef = useGridApiContext();
   const rootProps = useGridRootProps();
-  const densityValue = useGridSelector(apiRef, gridDensityValueSelector);
+  const density = useGridSelector(apiRef, gridDensitySelector);
   const densityButtonId = useId();
   const densityMenuId = useId();
 
@@ -60,15 +60,15 @@ const GridToolbarDensitySelector = React.forwardRef<
   ];
 
   const startIcon = React.useMemo<React.ReactElement>(() => {
-    switch (densityValue) {
+    switch (density) {
       case 'compact':
         return <rootProps.slots.densityCompactIcon />;
       case 'comfortable':
         return <rootProps.slots.densityComfortableIcon />;
       default:
         return <rootProps.slots.densityStandardIcon />;
     }
-  }, [densityValue, rootProps]);
+  }, [density, rootProps]);
 
   const handleDensitySelectorOpen = (event: React.MouseEvent<HTMLButtonElement>) => {
     setOpen((prevOpen) => !prevOpen);
@@ -100,7 +100,7 @@ const GridToolbarDensitySelector = React.forwardRef<
     <MenuItem
       key={index}
       onClick={() => handleDensityUpdate(option.value)}
-      selected={option.value === densityValue}
+      selected={option.value === density}
     >
       <ListItemIcon>{option.icon}</ListItemIcon>
       {option.label}