[DataGrid] Add Skeleton loading overlay support

packages/x-data-grid/src/components/GridLoadingOverlay.tsx

@@ -1,13 +1,66 @@
 import * as React from 'react';
 import PropTypes from 'prop-types';
+import LinearProgress from '@mui/material/LinearProgress';
 import CircularProgress from '@mui/material/CircularProgress';
+import { Theme, SystemStyleObject } from '@mui/system';
 import { GridOverlay, GridOverlayProps } from './containers/GridOverlay';
+import { GridSkeletonLoadingOverlay } from './GridSkeletonLoadingOverlay';
+import { useGridApiContext } from '../hooks/utils/useGridApiContext';
 
-const GridLoadingOverlay = React.forwardRef<HTMLDivElement, GridOverlayProps>(
+type GridLoadingOverlayVariant = 'circular-progress' | 'linear-progress' | 'skeleton';
+
+export interface GridLoadingOverlayProps extends GridOverlayProps {
+ /**
+ * The variant of the overlay.
+ * @default 'circular-progress'
+ */
+ variant?: GridLoadingOverlayVariant;
+ /**
+ * The variant of the overlay when no rows are displayed.
+ * @default 'circular-progress'
+ */
+ noRowsVariant?: GridLoadingOverlayVariant;
+}
+
+const LOADING_VARIANTS: Record<
+ GridLoadingOverlayVariant,
+ {
+ component: React.ComponentType;
+ sx: SystemStyleObject<Theme>;
+ }
+> = {
+ 'circular-progress': {
+ component: CircularProgress,
+ sx: {},
+ },
+ 'linear-progress': {
+ component: LinearProgress,
+ sx: { display: 'block' },
+ },
+ skeleton: {
+ component: GridSkeletonLoadingOverlay,
+ sx: {
+ display: 'block',
+ background: 'var(--DataGrid-containerBackground)',
+ },
+ },
+};
+
+const GridLoadingOverlay = React.forwardRef<HTMLDivElement, GridLoadingOverlayProps>(
  function GridLoadingOverlay(props, ref) {
+ const {
+ variant = 'circular-progress',
+ noRowsVariant = 'circular-progress',
+ sx,
+ ...other
+ } = props;
+ const apiRef = useGridApiContext();
+ const rowsCount = apiRef.current.getRowsCount();
+ const activeVariant = LOADING_VARIANTS[rowsCount === 0 ? noRowsVariant : variant];
+
  return (
- <GridOverlay ref={ref} {...props}>
- <CircularProgress />
+ <GridOverlay ref={ref} sx={{ ...activeVariant.sx, ...sx }} {...other}>
+ <activeVariant.component />
  </GridOverlay>
  );
  },
@@ -18,11 +71,21 @@ GridLoadingOverlay.propTypes = {
  // | These PropTypes are generated from the TypeScript type definitions |
  // | To update them edit the TypeScript types and run "pnpm proptypes" |
  // ----------------------------------------------------------------------
+ /**
+ * The variant of the overlay when no rows are displayed.
+ * @default 'circular-progress'
+ */
+ noRowsVariant: PropTypes.oneOf(['circular-progress', 'linear-progress', 'skeleton']),
  sx: PropTypes.oneOfType([
  PropTypes.arrayOf(PropTypes.oneOfType([PropTypes.func, PropTypes.object, PropTypes.bool])),
  PropTypes.func,
  PropTypes.object,
  ]),
+ /**
+ * The variant of the overlay.
+ * @default 'circular-progress'
+ */
+ variant: PropTypes.oneOf(['circular-progress', 'linear-progress', 'skeleton']),
 } as any;
 
 export { GridLoadingOverlay };

packages/x-data-grid/src/components/GridSkeletonLoadingOverlay.tsx

@@ -0,0 +1,139 @@
+import * as React from 'react';
+import Skeleton from '@mui/material/Skeleton';
+import { styled } from '@mui/system';
+import { unstable_useForkRef as useForkRef } from '@mui/utils';
+import { useGridApiContext } from '../hooks/utils/useGridApiContext';
+import {
+ gridColumnPositionsSelector,
+ gridColumnsTotalWidthSelector,
+ gridDimensionsSelector,
+ gridVisibleColumnDefinitionsSelector,
+ useGridApiEventHandler,
+ useGridSelector,
+} from '../hooks';
+import { GridColType, GridEventListener } from '../models';
+import { createRandomNumberGenerator } from '../utils/utils';
+
+const DEFAULT_COLUMN_WIDTH_RANGE = [40, 80] as const;
+
+const COLUMN_WIDTH_RANGE_BY_TYPE: Partial<Record<GridColType, [number, number]>> = {
+ number: [40, 60],
+ string: [40, 80],
+ date: [40, 60],
+ dateTime: [60, 80],
+ singleSelect: [40, 80],
+} as const;
+
+const colWidthVar = (index: number) => `--colWidth-${index}`;
+
+const SkeletonOverlay = styled('div')({
+ display: 'grid',
+ overflow: 'hidden',
+});
+
+const SkeletonCell = styled('div')({
+ display: 'flex',
+ flexDirection: 'row',
+ alignItems: 'center',
+ borderBottom: '1px solid var(--DataGrid-rowBorderColor)',
+});
+
+const GridSkeletonLoadingOverlay = React.forwardRef<
+ HTMLDivElement,
+ React.HTMLAttributes<HTMLDivElement>
+>(function GridSkeletonLoadingOverlay(props, forwardedRef) {
+ const ref = React.useRef<HTMLDivElement>(null);
+ const handleRef = useForkRef(ref, forwardedRef);
+
+ const apiRef = useGridApiContext();
+
+ const dimensions = useGridSelector(apiRef, gridDimensionsSelector);
+ const viewportHeight = dimensions?.viewportInnerSize.height ?? 0;
+
+ const skeletonRowsCount = Math.ceil(viewportHeight / dimensions.rowHeight);
+
+ const totalWidth = useGridSelector(apiRef, gridColumnsTotalWidthSelector);
+ const positions = useGridSelector(apiRef, gridColumnPositionsSelector);
+ const inViewportCount = React.useMemo(
+ () => positions.filter((value) => value <= totalWidth).length,
+ [totalWidth, positions],
+ );
+ const allVisibleColumns = useGridSelector(apiRef, gridVisibleColumnDefinitionsSelector);
+ const columns = allVisibleColumns.slice(0, inViewportCount);
+
+ const children = React.useMemo(() => {
+ // The random number generator is used to determine the width of each skeleton element.
+ // The seed ensures the width of each skeleton element width remains the same across renders and does not flicker.
+ const randomNumberBetween = createRandomNumberGenerator(12345);
+ const array: React.ReactNode[] = [];
+
+ for (let i = 0; i < skeletonRowsCount; i += 1) {
+ // eslint-disable-next-line no-restricted-syntax
+ for (const column of columns) {
+ const [min, max] = column.type
+ ? COLUMN_WIDTH_RANGE_BY_TYPE[column.type] ?? DEFAULT_COLUMN_WIDTH_RANGE
+ : DEFAULT_COLUMN_WIDTH_RANGE;
+ const width = Math.round(randomNumberBetween(min, max));
+ const isCircular = column.type === 'boolean' || column.type === 'actions';
+
+ array.push(
+ <SkeletonCell
+ key={`skeleton-column-${i}-${column.field}`}
+ sx={{ justifyContent: column.align }}
+ >
+ <Skeleton
+ width={isCircular ? '1.3em' : `${width}%`}
+ height={isCircular ? '1.3em' : '1.2em'}
+ variant={isCircular ? 'circular' : 'text'}
+ sx={{ mx: 1 }}
+ />
+ </SkeletonCell>,
+ );
+ }
+ array.push(<SkeletonCell key={`skeleton-filler-column-${i}`} />);
+ }
+ return array;
+ }, [skeletonRowsCount, columns]);
+
+ const [initialColWidthVariables, gridTemplateColumns] = columns.reduce(
+ ([initialSize, templateColumn], column, i) => {
+ const varName = colWidthVar(i);
+ initialSize[varName] = `${column.computedWidth}px`;
+ templateColumn += ` var(${varName})`;
+ return [initialSize, templateColumn];
+ },
+ [{} as Record<string, string>, ''],
+ );
+
+ // Sync the horizontal scroll of the overlay with the grid
+ const handleScrollChange: GridEventListener<'scrollPositionChange'> = (params) => {
+ if (ref.current) {
+ ref.current.scrollLeft = params.left;
+ }
+ };
+ useGridApiEventHandler(apiRef, 'scrollPositionChange', handleScrollChange);
+
+ // Sync the column resize of the overlay columns with the grid
+ const handleColumnResize: GridEventListener<'columnResize'> = (params) => {
+ const columnIndex = columns.findIndex((column) => column.field === params.colDef.field);
+ ref.current?.style.setProperty(colWidthVar(columnIndex), `${params.width}px`);
+ };
+ useGridApiEventHandler(apiRef, 'columnResize', handleColumnResize);
+
+ return (
+ <SkeletonOverlay
+ ref={handleRef}
+ {...props}
+ style={{
+ gridTemplateColumns: `${gridTemplateColumns} 1fr`,
+ gridAutoRows: dimensions.rowHeight,
+ ...initialColWidthVariables,
+ ...props.style,
+ }}
+ >
+ {children}
+ </SkeletonOverlay>
+ );
+});
+
+export { GridSkeletonLoadingOverlay };

packages/x-data-grid/src/components/cell/GridSkeletonCell.tsx

@@ -6,12 +6,12 @@ import {
  unstable_capitalize as capitalize,
 } from '@mui/utils';
 import { fastMemo } from '../../utils/fastMemo';
-import { randomNumberBetween } from '../../utils/utils';
+import { createRandomNumberGenerator } from '../../utils/utils';
 import { useGridRootProps } from '../../hooks/utils/useGridRootProps';
 import { getDataGridUtilityClass } from '../../constants/gridClasses';
 import { DataGridProcessedProps } from '../../models/props/DataGridProps';
 
-const randomWidth = randomNumberBetween(10000, 20, 80);
+const randomWidth = createRandomNumberGenerator(10000);
 
 export interface GridSkeletonCellProps {
  width: number;
@@ -39,7 +39,7 @@ function GridSkeletonCell(props: React.HTMLAttributes<HTMLDivElement> & GridSkel
  const rootProps = useGridRootProps();
  const ownerState = { classes: rootProps.classes, align };
  const classes = useUtilityClasses(ownerState);
- const contentWidth = Math.round(randomWidth());
+ const contentWidth = Math.round(randomWidth(20, 80));
 
  return (
  <div className={classes.root} style={{ height, maxWidth: width, minWidth: width }} {...other}>

packages/x-data-grid/src/models/gridSlotsComponentsProps.ts

@@ -27,6 +27,7 @@ import type { GridColumnHeadersProps } from '../components/GridColumnHeaders';
 import type { GridDetailPanelsProps } from '../components/GridDetailPanels';
 import type { GridPinnedRowsProps } from '../components/GridPinnedRows';
 import type { GridColumnsManagementProps } from '../components/columnsManagement/GridColumnsManagement';
+import type { GridLoadingOverlayProps } from '../components/GridLoadingOverlay';
 import type { GridRowCountProps } from '../components';
 
 // Overrides for module augmentation
@@ -91,7 +92,7 @@ export interface GridSlotProps {
  filterPanel: GridFilterPanelProps & FilterPanelPropsOverrides;
  footer: GridFooterContainerProps & FooterPropsOverrides;
  footerRowCount: GridRowCountProps & FooterRowCountOverrides;
- loadingOverlay: GridOverlayProps & LoadingOverlayPropsOverrides;
+ loadingOverlay: GridLoadingOverlayProps & LoadingOverlayPropsOverrides;
  noResultsOverlay: GridOverlayProps & NoResultsOverlayPropsOverrides;
  noRowsOverlay: GridOverlayProps & NoRowsOverlayPropsOverrides;
  pagination: Partial<TablePaginationProps> & PaginationPropsOverrides;

packages/x-data-grid/src/utils/utils.ts

@@ -190,9 +190,16 @@ function mulberry32(a: number): () => number {
  };
 }
 
-export function randomNumberBetween(seed: number, min: number, max: number): () => number {
+/**
+ * Create a random number generator from a seed. The seed
+ * ensures that the random number generator produces the
+ * same sequence of 'random' numbers on every render. It
+ * returns a function that generates a random number between
+ * a specified min and max.
+ */
+export function createRandomNumberGenerator(seed: number): (min: number, max: number) => number {
  const random = mulberry32(seed);
- return () => min + (max - min) * random();
+ return (min: number, max: number) => min + (max - min) * random();
 }
 
 export function deepClone(obj: Record<string, any>) {