add cell keyboard navigation feature

Author: KevinVandy

packages/material-react-table/src/components/body/MRT_TableBodyCell.tsx

@@ -16,7 +16,11 @@ import {
   type MRT_RowData,
   type MRT_TableInstance,
 } from '../../types';
-import { isCellEditable, openEditingCell } from '../../utils/cell.utils';
+import {
+  isCellEditable,
+  navigateToNextCell,
+  openEditingCell,
+} from '../../utils/cell.utils';
 import { getCommonMRTCellStyles } from '../../utils/style.utils';
 import { parseFromValuesOrFunc } from '../../utils/utils';
 import { MRT_CopyButton } from '../buttons/MRT_CopyButton';
@@ -54,6 +58,7 @@ export const MRT_TableBodyCell = <TData extends MRT_RowData>({
       enableColumnOrdering,
       enableColumnPinning,
       enableGrouping,
+      enableCellNavigation,
       layoutMode,
       mrtTheme: { draggingBorderColor },
       muiSkeletonProps,
@@ -227,12 +232,21 @@ export const MRT_TableBodyCell = <TData extends MRT_RowData>({
     }
   };
 
+  const handleKeyDown = (e: React.KeyboardEvent<HTMLTableCellElement>) => {
+    if (enableCellNavigation) {
+      navigateToNextCell(e);
+    }
+    tableCellProps?.onKeyDown?.(e);
+  };
+
   return (
     <TableCell
       align={theme.direction === 'rtl' ? 'right' : 'left'}
       data-index={staticColumnIndex}
       data-pinned={!!isColumnPinned || undefined}
+      tabIndex={enableCellNavigation ? 0 : undefined}
       {...tableCellProps}
+      onKeyDown={handleKeyDown}
       onContextMenu={handleContextMenu}
       onDoubleClick={handleDoubleClick}
       onDragEnter={handleDragEnter}

packages/material-react-table/src/components/footer/MRT_TableFooterCell.tsx

@@ -7,6 +7,7 @@ import {
 } from '../../types';
 import { getCommonMRTCellStyles } from '../../utils/style.utils';
 import { parseFromValuesOrFunc } from '../../utils/utils';
+import { navigateToNextCell } from '../../utils/cell.utils';
 
 export interface MRT_TableFooterCellProps<TData extends MRT_RowData>
   extends TableCellProps {
@@ -24,7 +25,11 @@ export const MRT_TableFooterCell = <TData extends MRT_RowData>({
   const theme = useTheme();
   const {
     getState,
-    options: { enableColumnPinning, muiTableFooterCellProps },
+    options: {
+      enableColumnPinning,
+      muiTableFooterCellProps,
+      enableCellNavigation,
+    },
   } = table;
   const { density } = getState();
   const { column } = footer;
@@ -43,6 +48,13 @@ export const MRT_TableFooterCell = <TData extends MRT_RowData>({
     ...rest,
   };
 
+  const handleKeyDown = (e: React.KeyboardEvent<HTMLTableCellElement>) => {
+    if (enableCellNavigation) {
+      navigateToNextCell(e);
+    }
+    tableCellProps?.onKeyDown?.(e);
+  };
+
   return (
     <TableCell
       align={
@@ -57,6 +69,7 @@ export const MRT_TableFooterCell = <TData extends MRT_RowData>({
       data-pinned={!!isColumnPinned || undefined}
       variant="footer"
       {...tableCellProps}
+      onKeyDown={handleKeyDown}
       sx={(theme) => ({
         fontWeight: 'bold',
         p:

packages/material-react-table/src/components/head/MRT_TableHeadCell.tsx

@@ -17,6 +17,7 @@ import {
 } from '../../types';
 import { getCommonMRTCellStyles } from '../../utils/style.utils';
 import { parseFromValuesOrFunc } from '../../utils/utils';
+import { navigateToNextCell } from '../../utils/cell.utils';
 
 export interface MRT_TableHeadCellProps<TData extends MRT_RowData>
   extends TableCellProps {
@@ -45,6 +46,7 @@ export const MRT_TableHeadCell = <TData extends MRT_RowData>({
       enableColumnOrdering,
       enableColumnPinning,
       enableGrouping,
+      enableCellNavigation,
       enableMultiSort,
       layoutMode,
       mrtTheme: { draggingBorderColor },
@@ -147,6 +149,13 @@ export const MRT_TableHeadCell = <TData extends MRT_RowData>({
     }
   };
 
+  const handleKeyDown = (e: React.KeyboardEvent<HTMLTableCellElement>) => {
+    if (enableCellNavigation) {
+      navigateToNextCell(e);
+    }
+    tableCellProps?.onKeyDown?.(e);
+  };
+
   const HeaderElement =
     parseFromValuesOrFunc(columnDef.Header, {
       column,
@@ -185,7 +194,9 @@ export const MRT_TableHeadCell = <TData extends MRT_RowData>({
           }
         }
       }}
+      tabIndex={enableCellNavigation ? 0 : undefined}
       {...tableCellProps}
+      onKeyDown={handleKeyDown}
       sx={(theme: Theme) => ({
         '& :hover': {
           '.MuiButtonBase-root': {

packages/material-react-table/src/hooks/useMRT_TableOptions.ts

@@ -76,6 +76,7 @@ export const useMRT_TableOptions: <TData extends MRT_RowData>(
   enableGlobalFilterRankedResults = true,
   enableGrouping = false,
   enableHiding = true,
+  enableCellNavigation = true,
   enableMultiRowSelection = true,
   enableMultiSort = true,
   enablePagination = true,
@@ -203,6 +204,7 @@ export const useMRT_TableOptions: <TData extends MRT_RowData>(
     enableGlobalFilterRankedResults,
     enableGrouping,
     enableHiding,
+    enableCellNavigation,
     enableMultiRowSelection,
     enableMultiSort,
     enablePagination,

packages/material-react-table/src/types.ts

@@ -246,6 +246,7 @@ export interface MRT_Localization {
 
 export interface MRT_Theme {
   baseBackgroundColor: string;
+  cellNavigationOutlineColor: string;
   draggingBorderColor: string;
   matchHighlightColor: string;
   menuBackgroundColor: string;
@@ -867,6 +868,7 @@ export interface MRT_TableOptions<TData extends MRT_RowData>
   enableFullScreenToggle?: boolean;
   enableGlobalFilterModes?: boolean;
   enableGlobalFilterRankedResults?: boolean;
+  enableCellNavigation?: boolean;
   enablePagination?: boolean;
   enableRowActions?: boolean;
   enableRowDragging?: boolean;

packages/material-react-table/src/utils/cell.utils.ts

@@ -48,3 +48,50 @@ export const openEditingCell = <TData extends MRT_RowData>({
     });
   }
 };
+
+export const navigateToNextCell = (
+  e: React.KeyboardEvent<HTMLTableCellElement>,
+) => {
+  if (['ArrowRight', 'ArrowLeft', 'ArrowUp', 'ArrowDown'].includes(e.key)) {
+    e.preventDefault();
+    const currentCell = e.currentTarget;
+    const tableElement = currentCell.closest('table');
+    if (!tableElement) return;
+
+    const currentIndex = parseInt(
+      currentCell.getAttribute('data-index') || '0',
+    );
+    let nextCell: HTMLElement | undefined = undefined;
+
+    const findNextCell = (index: number, searchDirection: 'f' | 'b') => {
+      const allCells = Array.from(tableElement.querySelectorAll('th, td'));
+      const currentCellIndex = allCells.indexOf(currentCell);
+      const searchArray =
+        searchDirection === 'f'
+          ? allCells.slice(currentCellIndex + 1)
+          : allCells.slice(0, currentCellIndex).reverse();
+      return searchArray.find((cell) =>
+        cell.matches(`[data-index="${index}"]`),
+      ) as HTMLElement | undefined;
+    };
+
+    switch (e.key) {
+      case 'ArrowRight':
+        nextCell = findNextCell(currentIndex + 1, 'f');
+        break;
+      case 'ArrowLeft':
+        nextCell = findNextCell(currentIndex - 1, 'b');
+        break;
+      case 'ArrowUp':
+        nextCell = findNextCell(currentIndex, 'b');
+        break;
+      case 'ArrowDown':
+        nextCell = findNextCell(currentIndex, 'f');
+        break;
+    }
+
+    if (nextCell) {
+      nextCell.focus();
+    }
+  }
+};

packages/material-react-table/src/utils/style.utils.ts

@@ -27,6 +27,7 @@ export const getMRTTheme = <TData extends MRT_RowData>(
       : muiTheme.palette.background.default);
   return {
     baseBackgroundColor,
+    cellNavigationOutlineColor: muiTheme.palette.primary.main,
     draggingBorderColor: muiTheme.palette.primary.main,
     matchHighlightColor:
       muiTheme.palette.mode === 'dark'
@@ -170,6 +171,10 @@ export const getCommonMRTCellStyles = <TData extends MRT_RowData>({
         : columnDefType !== 'group' && isColumnPinned
           ? 1
           : 0,
+    '&:focus-visible': {
+      outline: `2px solid ${table.options.mrtTheme.cellNavigationOutlineColor}`,
+      outlineOffset: '-2px',
+    },
     ...pinnedStyles,
     ...widthStyles,
     ...(parseFromValuesOrFunc(tableCellProps?.sx, theme) as any),