DataGridTable

The core data grid component that renders the table structure, headers, rows, cells, and inline editing UI. DataGridTable is typically used internally by OGrid, but can also be used standalone for custom layouts.

Import

React

import { DataGridTable } from '@alaarab/ogrid-react-radix';
// or
import { DataGridTable } from '@alaarab/ogrid-react-fluent';

Props (React)

DataGridTable receives IOGridDataGridProps<T> which includes:

Prop	Type	Default	Description
items	T[]	Required	Array of data items to render (paginated subset).
columns	(IColumnDef<T> | IColumnGroupDef<T>)[]	Required	Column definitions (flat or grouped).
getRowId	(item: T) => RowId	Required	Function to extract a unique ID from each row item.
sortBy	string	undefined	Currently sorted column ID.
sortDirection	'asc' | 'desc'	undefined	Sort direction.
onSortChange	(field: string, direction: 'asc' | 'desc') => void	undefined	Callback when user clicks a sortable column header.
filters	IFilters	{}	Active filter values (column ID to FilterValue).
onFiltersChange	(filters: IFilters) => void	undefined	Callback when filters are applied or cleared.
visibleColumns	Set<string>	All columns	Set of visible column IDs.
onVisibilityChange	(columnId: string, visible: boolean) => void	undefined	Callback when column visibility changes.
onSetVisibleColumns	(columns: Set<string>) => void	undefined	Bulk-set all visible columns (used by Select All / Clear All).
editable	boolean	false	Enable inline cell editing.
cellSelection	boolean	true	Enable spreadsheet-like cell selection (active cell, range, fill handle, clipboard).
onCellValueChanged	(event: ICellValueChangedEvent<T>) => void	undefined	Callback when a cell value is committed after edit.
rowSelection	RowSelectionMode	'none'	Row selection mode: 'none', 'single', or 'multiple'.
selectedRows	Set<RowId>	new Set()	Set of selected row IDs.
onSelectionChange	(event: IRowSelectionChangeEvent<T>) => void	undefined	Callback when row selection changes.
showRowNumbers	boolean	false	Show Excel-style row numbers column at the start (1, 2, 3...).
statusBar	boolean | IStatusBarProps	false	Show status bar below the grid with row counts and aggregations.
emptyState	{ message?: ReactNode; render?: () => ReactNode }	undefined	Custom empty state when no rows are available.
density	'compact' | 'normal' | 'comfortable'	'normal'	Cell spacing/padding preset.
suppressHorizontalScroll	boolean	false	Suppress horizontal scrolling (overflow-x hidden).
virtualScroll	IVirtualScrollConfig	undefined	Enable virtual scrolling for large datasets.
columnReorder	boolean	false	Enable drag-and-drop column reordering.
dataSource	IDataSource<T>	undefined	Server-side data source (for filter options and people search).
onCellError	(error: Error, errorInfo: ErrorInfo) => void	undefined	Error boundary callback for cell rendering errors.
aria-label	string	undefined	Accessible label for the grid.
aria-labelledby	string	undefined	ID of element that labels the grid.

Usage

Basic Example (React)

import { DataGridTable } from '@alaarab/ogrid-react-radix';
import type { IColumnDef } from '@alaarab/ogrid-react-radix';

interface Product {
  id: number;
  name: string;
  price: number;
}

const columns: IColumnDef<Product>[] = [
  { columnId: 'name', name: 'Product Name', type: 'text' },
  { columnId: 'price', name: 'Price', type: 'numeric' },
];

const data: Product[] = [
  { id: 1, name: 'Widget', price: 29.99 },
  { id: 2, name: 'Gadget', price: 49.99 },
];

function MyGrid() {
  return (
    <DataGridTable
      items={data}
      columns={columns}
      getRowId={(item) => item.id}
      aria-label="Product catalog"
    />
  );
}

With Sorting and Filtering (React)

import { DataGridTable } from '@alaarab/ogrid-react-radix';
import { useState } from 'react';

function MyGrid() {
  const [sortBy, setSortBy] = useState<string>('name');
  const [sortDirection, setSortDirection] = useState<'asc' | 'desc'>('asc');
  const [filters, setFilters] = useState<IFilters>({});

  const handleSortChange = (field: string, direction: 'asc' | 'desc') => {
    setSortBy(field);
    setSortDirection(direction);
  };

  return (
    <DataGridTable
      items={data}
      columns={columns}
      getRowId={(item) => item.id}
      sortBy={sortBy}
      sortDirection={sortDirection}
      onSortChange={handleSortChange}
      filters={filters}
      onFiltersChange={setFilters}
    />
  );
}

Accessibility

DataGridTable implements WCAG 2.1 AA standards with comprehensive keyboard navigation and screen reader support.

ARIA Attributes

The grid uses semantic HTML with proper ARIA roles:

<div role="grid" aria-label="Product catalog" aria-rowcount="1000">
  <table>
    <thead>
      <tr role="row">
        <th role="columnheader" aria-sort="ascending" scope="col">
          Product Name
        </th>
      </tr>
    </thead>
    <tbody>
      <tr role="row" aria-rowindex="1">
        <td role="gridcell" tabindex="-1">Widget</td>
      </tr>
    </tbody>
  </table>
</div>

Attribute	Element	Purpose
role="grid"	Grid wrapper	Identifies the grid container for screen readers
role="row"	<tr>	Identifies table rows
role="columnheader"	<th>	Identifies column headers
role="gridcell"	<td>	Identifies data cells
aria-label	Grid wrapper	Provides accessible name (pass via aria-label prop)
aria-rowcount	Grid wrapper	Total number of rows in dataset (server-side pagination)
aria-rowindex	<tr>	Row's position in the full dataset (1-indexed)
aria-sort	<th>	Current sort state: "ascending", "descending", or "none"
aria-colindex	<th>, <td>	Column's position (1-indexed)
tabindex="-1"	<td>	Enables programmatic focus for keyboard navigation
aria-readonly	<td>	Indicates whether cell is editable ("false" when editable: true)

Keyboard Navigation

Complete Excel-style keyboard navigation:

Arrow Keys:

• ↑ ↓ ← to - Move active cell one cell in the direction pressed
• Ctrl+↑ / Ctrl+↓ - Jump to first/last row
• Ctrl+← / Ctrl+ to - Jump to first/last column
• Home / End - Jump to start/end of row
• Ctrl+Home / Ctrl+End - Jump to first/last cell in grid

Selection:

• Shift+Arrows - Extend cell selection range
• Ctrl+A - Select all cells
• Shift+Space - Toggle the active row's selection
• ← from the first column - Move to the row's checkbox cell; Space there toggles the row, Shift+Space selects a range

Editing:

• Enter or F2 - Start editing active cell
• Escape - Cancel editing and revert
• Enter (while editing) - Commit and move down
• Tab (while editing) - Commit and move right

Clipboard:

• Ctrl+C / Cmd+C - Copy selected cells
• Ctrl+X / Cmd+X - Cut selected cells
• Ctrl+V / Cmd+V - Paste
• Delete - Clear selected cells

Undo/Redo:

• Ctrl+Z / Cmd+Z - Undo last edit
• Ctrl+Y / Cmd+Shift+Z - Redo

Context Menu:

• Shift+F10 - Open context menu for active cell

See the Accessibility Guide for complete keyboard shortcuts.

Focus Management

• Focus visible: :focus-visible styles show a 2px solid outline (--ogrid-accent) only when navigating via keyboard
• Focus restoration: After closing dialogs or exiting edit mode, focus returns to the active cell
• Tab order: Header controls (including the select-all checkbox) are tab stops; the body is a single tab stop (the active cell). Row and boolean checkboxes have tabindex="-1"

Screen Reader Support

Screen readers announce:

• Cell navigation: "Product Name, cell, row 1, column 2"
• Sort changes: "Sorted by Product Name, ascending"
• Edit mode: "Editing Product Name, row 1, column 2"
• Value changes: "Product Name changed from Widget to Gadget"

Tested with NVDA, JAWS, VoiceOver, and Narrator.

High Contrast Mode

All colors use CSS custom properties with system color fallbacks for Windows High Contrast Mode:

• Focus indicators use system Highlight color
• Borders use system ButtonText color
• Text remains visible in all contrast themes

Usage Example

import { OGrid } from '@alaarab/ogrid-react-radix';

function AccessibleGrid() {
  return (
    <OGrid
      data={products}
      columns={columns}
      getRowId={(item) => item.id}
      aria-label="Product catalog"
      rowSelection="multiple"
      editable={true}
    />
  );
}

For complete accessibility documentation, see the Accessibility Guide.

Related Components

• OGrid - Top-level wrapper that includes toolbar and pagination
• ColumnHeaderFilter - Column filtering UI
• StatusBar - Status bar below the grid
• PaginationControls - Pagination UI

See Also

• Column Definition - Complete column definition reference
• Grid API - Imperative grid API reference
• Accessibility Guide - Complete accessibility documentation