react-data-grid

[![npm-badge]][npm-url]
[![type-badge]][npm-url]
[![size-badge]][size-url]
[![codecov-badge]][codecov-url]
[![ci-badge]][ci-url]

[npm-badge]: https://img.shields.io/npm/v/react-data-grid
[npm-url]: https://www.npmjs.com/package/react-data-grid
[size-badge]: https://img.shields.io/bundlephobia/minzip/react-data-grid
[size-url]: https://bundlephobia.com/package/react-data-grid
[type-badge]: https://img.shields.io/npm/types/react-data-grid
[codecov-badge]: https://codecov.io/gh/Comcast/react-data-grid/branch/main/graph/badge.svg?token=cvrRSWiz0Q
[codecov-url]: https://app.codecov.io/gh/Comcast/react-data-grid
[ci-badge]: https://github.com/Comcast/react-data-grid/workflows/CI/badge.svg
[ci-url]: https://github.com/Comcast/react-data-grid/actions

The DataGrid component is designed to handle large datasets efficiently while offering a rich set of features for customization and interactivity.

Features

- React 19.2+ support
- Evergreen browsers and server-side rendering support
- Tree-shaking support with no external dependencies to keep your bundles slim
- Great performance thanks to virtualization: columns and rows outside the viewport are not rendered
- Strictly typed with TypeScript
- Keyboard accessibility
- Light and dark mode support out of the box.
- Frozen columns: Freeze columns to keep them visible during horizontal scrolling.
- Column resizing
- Multi-column sorting
- Click on a sortable column header to toggle between its ascending/descending sort order
- Ctrl+Click / Meta+Click to sort an additional column
- Column spanning
- Column grouping
- Row selection
- Row grouping
- Summary rows
- Dynamic row heights
- No rows fallback
- Cell formatting
- Cell editing
- Cell copy / pasting
- Cell value dragging / filling
- Customizable Renderers
- Right-to-left (RTL) support.

Links

- Examples website
- Source code
- Changelog
- Contributing

> Important

> rolldown-vite by default uses lightningcss to minify css which has a bug minifying light-dark syntax. You can switch to esbuild as a workaround

``ts
build: {
....,
cssMinify: 'esbuild'
}
`

Installation

Install react-data-grid using your favorite package manager:

`sh
npm i react-data-grid
`

`sh
pnpm add react-data-grid
`

`sh
yarn add react-data-grid
`

`sh
bun add react-data-grid
`

Additionally, import the default styles in your application:

`tsx
import 'react-data-grid/lib/styles.css';
`

react-data-grid is published as ECMAScript modules for evergreen browsers, bundlers, and server-side rendering.

Getting started

Here is a basic example of how to use react-data-grid in your React application:

`tsx
import 'react-data-grid/lib/styles.css';

import { DataGrid, type Column } from 'react-data-grid';

interface Row {
id: number;
title: string;
}

const columns: readonly Column[] = [
{ key: 'id', name: 'ID' },
{ key: 'title', name: 'Title' }
];

const rows: readonly Row[] = [
{ id: 0, title: 'Example' },
{ id: 1, title: 'Demo' }
];

function App() {
return ;
}
`

Styling and Customization

The DataGrid provides multiple ways to customize its appearance and behavior.

$3

The DataGrid supports both light and dark color schemes out of the box using CSS's light-dark() function. The theme automatically adapts based on the user's system preference when color-scheme: light dark; is set.

To enforce a specific theme, we recommend setting the standard color-scheme CSS property on the :root:

`css
:root {
color-scheme: light; / or 'dark', or 'light dark' for auto /
}
`

Alternatively, you can add the rdg-light or rdg-dark class to individual grids:

`tsx
// Force light theme


// Force dark theme

`

$3

The DataGrid supports the following CSS variables for customization:

`css
.rdg {
/ Selection /
--rdg-selection-width: 2px;
--rdg-selection-color: hsl(207, 75%, 66%);

/ Typography /
--rdg-font-size: 14px;

/ Colors (using light-dark() for automatic theme switching) /
--rdg-color: light-dark(#000, #ddd);
--rdg-background-color: light-dark(hsl(0deg 0% 100%), hsl(0deg 0% 13%));

/ Header /
--rdg-header-background-color: light-dark(hsl(0deg 0% 97.5%), hsl(0deg 0% 10.5%));
--rdg-header-draggable-background-color: light-dark(hsl(0deg 0% 90.5%), hsl(0deg 0% 17.5%));

/ Rows /
--rdg-row-hover-background-color: light-dark(hsl(0deg 0% 96%), hsl(0deg 0% 9%));
--rdg-row-selected-background-color: light-dark(hsl(207deg 76% 92%), hsl(207deg 76% 42%));
--rdg-row-selected-hover-background-color: light-dark(hsl(207deg 76% 88%), hsl(207deg 76% 38%));

/ Borders /
--rdg-border-width: 1px;
--rdg-border-color: light-dark(#ddd, #444);
--rdg-summary-border-width: calc(var(--rdg-border-width) * 2);
--rdg-summary-border-color: light-dark(#aaa, #555);

/ Frozen columns /
--rdg-cell-frozen-box-shadow: 2px 0 5px -2px rgba(136, 136, 136, 0.3);

/ Checkboxes /
--rdg-checkbox-focus-color: hsl(207deg 100% 69%);
}
`

Example of customizing colors:

`css
.my-custom-grid {
--rdg-background-color: #f0f0f0;
--rdg-selection-color: #ff6b6b;
--rdg-font-size: 16px;
}
`

`tsx

`

$3

The DataGrid accepts standard className and style props:

`tsx
columns={columns}
rows={rows}
className="my-grid custom-theme"
style={{ width: 800, height: 600 }}
/>
`

$3

#### Row Heights

Control row heights using the rowHeight, headerRowHeight, and summaryRowHeight props. The rowHeight prop supports both fixed heights and dynamic heights per row.

#### Row Classes

Apply custom CSS classes to rows using the rowClass prop, and to header rows using the headerRowClass prop.

#### Cell Classes

Apply custom CSS classes to cells using the cellClass property in column definitions. You can also use headerCellClass and summaryCellClass for header and summary cells respectively.

#### Column Widths

Control column widths using the width, minWidth, and maxWidth properties in column definitions. Enable column resizing using the resizable property, or use defaultColumnOptions to apply it to all columns.

$3

Replace default components with custom implementations using the renderers prop. Columns can also have custom renderers using the renderCell, renderHeaderCell, renderSummaryCell, renderGroupCell, and renderEditCell properties.

API Reference

$3

####

##### DataGridProps

###### columns: readonly Column[]

An array of column definitions. Each column should have a key and name. See the Column type for all available options.

:warning: Performance: Passing a new columns array will trigger a re-render and recalculation for the entire grid. Always memoize this prop using useMemo or define it outside the component to avoid unnecessary re-renders.

###### rows: readonly R[]

An array of rows, the rows data can be of any type.

:bulb: Performance: The grid is optimized for efficient rendering:

- Virtualization: Only visible rows are rendered in the DOM
- Individual row updates: Row components are memoized, so updating a single row object will only re-render that specific row, not all rows
- Array reference matters: Changing the array reference itself (e.g., setRows([...rows])) triggers viewport and layout recalculations, even if the row objects are unchanged
- Best practice: When updating rows, create a new array but reuse unchanged row objects. For example:

`tsx
// ✅ Good: Only changed row is re-rendered
setRows(rows.map((row, idx) => (idx === targetIdx ? { ...row, updated: true } : row)));

// ❌ Avoid: Creates new references for all rows, causing all visible rows to re-render
setRows(rows.map((row) => ({ ...row })));
`

###### topSummaryRows?: Maybe

Rows pinned at the top of the grid for summary purposes.

###### bottomSummaryRows?: Maybe

Rows pinned at the bottom of the grid for summary purposes.

###### rowKeyGetter?: Maybe<(row: R) => K>

Function to return a unique key/identifier for each row. rowKeyGetter is required for row selection to work.

`tsx
import { DataGrid } from 'react-data-grid';

interface Row {
id: number;
name: string;
}

function rowKeyGetter(row: Row) {
return row.id;
}

function MyGrid() {
return ;
}
`

:bulb: While optional, setting this prop is recommended for optimal performance as the returned value is used to set the key prop on the row elements.

:warning: Performance: Define this function outside your component or memoize it with useCallback to prevent unnecessary re-renders.

###### onRowsChange?: Maybe<(rows: R[], data: RowsChangeData) => void>

Callback triggered when rows are changed.

The first parameter is a new rows array with both the updated rows and the other untouched rows.
The second parameter is an object with an indexes array highlighting which rows have changed by their index, and the column where the change happened.

`tsx
import { useState } from 'react';
import { DataGrid } from 'react-data-grid';

function MyGrid() {
const [rows, setRows] = useState(initialRows);

return ;
}
`

###### rowHeight?: Maybe number)>

Default: 35 pixels

Height of each row in pixels. A function can be used to set different row heights.

`tsx
// Fixed height for all rows
;

// Dynamic height per row
function getRowHeight(row) {
return row.isExpanded ? 100 : 35;
}

;
`

:warning: Performance: When using a function, the heights of all rows are processed upfront. For large datasets (1000+ rows), this can cause performance issues if the identity of the function changes and invalidates internal memoization. Consider using a static function when possible, or memoize the rowHeight function.

###### headerRowHeight?: Maybe

Default: 35 pixels

Height of the header row in pixels.

###### summaryRowHeight?: Maybe

Default: 35 pixels

Height of each summary row in pixels.

`tsx
columns={columns}
rows={rows}
rowHeight={35}
headerRowHeight={45}
summaryRowHeight={40}
topSummaryRows={topSummaryRows}
/>
`

###### columnWidths?: Maybe

A map of column widths containing both measured and resized widths. If not provided then an internal state is used.

`tsx
const [columnWidths, setColumnWidths] = useState((): ColumnWidths => new Map());

function addNewRow() {
setRows(...);
// reset column widths after adding a new row
setColumnWidths(new Map());
}

return
`

###### onColumnWidthsChange?: Maybe<(columnWidths: ColumnWidths) => void>

Callback triggered when column widths change. If not provided then an internal state is used.

###### selectedRows?: Maybe>

A set of selected row keys. rowKeyGetter is required for row selection to work.

###### isRowSelectionDisabled?: Maybe<(row: NoInfer) => boolean>

Function to determine if row selection is disabled for a specific row.

###### onSelectedRowsChange?: Maybe<(selectedRows: Set) => void>

Callback triggered when the selection changes.

`tsx
import { useState } from 'react';
import { DataGrid, SelectColumn } from 'react-data-grid';

const rows: readonly Rows[] = [...];

const columns: readonly Column[] = [
SelectColumn,
// other columns
];

function rowKeyGetter(row: Row) {
return row.id;
}

function isRowSelectionDisabled(row: Row) {
return !row.isActive;
}

function MyGrid() {
const [selectedRows, setSelectedRows] = useState((): ReadonlySet => new Set());

return (
rowKeyGetter={rowKeyGetter}
columns={columns}
rows={rows}
selectedRows={selectedRows}
isRowSelectionDisabled={isRowSelectionDisabled}
onSelectedRowsChange={setSelectedRows}
/>
);
}
`

###### sortColumns?: Maybe

An array of sorted columns.

###### onSortColumnsChange?: Maybe<(sortColumns: SortColumn[]) => void>

Callback triggered when sorting changes.

`tsx
import { useState } from 'react';
import { DataGrid, SelectColumn } from 'react-data-grid';

const rows: readonly Rows[] = [...];

const columns: readonly Column[] = [
{
key: 'name',
name: 'Name',
sortable: true
},
// other columns
];

function MyGrid() {
const [sortColumns, setSortColumns] = useState([]);

return (
columns={columns}
rows={rows}
sortColumns={sortColumns}
onSortColumnsChange={setSortColumns}
/>
);
}
`

More than one column can be sorted via ctrl (command) + click. To disable multiple column sorting, change the onSortColumnsChange function to

`tsx
function onSortColumnsChange(sortColumns: SortColumn[]) {
setSortColumns(sortColumns.slice(-1));
}
`

###### defaultColumnOptions?: Maybe>

Default options applied to all columns.

`tsx
function MyGrid() {
return (
columns={columns}
rows={rows}
defaultColumnOptions={{
minWidth: 100,
resizable: true,
sortable: true,
draggable: true
}}
/>
);
}
`

###### onFill?: Maybe<(event: FillEvent) => R>

###### onCellMouseDown: Maybe<(args: CellMouseArgs, event: CellMouseEvent) => void>

Callback triggered when a pointer becomes active in a cell. The default behavior is to select the cell. Call preventGridDefault to prevent the default behavior.

`tsx
function onCellMouseDown(args: CellMouseDownArgs, event: CellMouseEvent) {
if (args.column.key === 'id') {
event.preventGridDefault();
}
}

;
`

###### onCellClick?: Maybe<(args: CellMouseArgs, event: CellMouseEvent) => void>

Callback triggered when a cell is clicked.

`tsx
function onCellClick(args: CellMouseArgs, event: CellMouseEvent) {
if (args.column.key === 'id') {
event.preventGridDefault();
}
}

;
`

This event can be used to open cell editor on single click

`tsx
function onCellClick(args: CellMouseArgs, event: CellMouseEvent) {
if (args.column.key === 'id') {
args.selectCell(true);
}
}
`

###### onCellDoubleClick?: Maybe<(args: CellMouseArgs, event: CellMouseEvent) => void>

Callback triggered when a cell is double-clicked. The default behavior is to open the editor if the cell is editable. Call preventGridDefault to prevent the default behavior.

`tsx
function onCellDoubleClick(args: CellMouseArgs, event: CellMouseEvent) {
if (args.column.key === 'id') {
event.preventGridDefault();
}
}

;
`

###### onCellContextMenu?: Maybe<(args: CellMouseArgs, event: CellMouseEvent) => void>

Callback triggered when a cell is right-clicked.

`tsx
function onCellContextMenu(args: CellMouseArgs, event: CellMouseEvent) {
if (args.column.key === 'id') {
event.preventDefault();
// open custom context menu
}
}

;
`

###### onCellKeyDown?: Maybe<(args: CellKeyDownArgs, event: CellKeyboardEvent) => void>

A function called when keydown event is triggered on a cell. This event can be used to customize cell navigation and editing behavior.

Examples

- Prevent editing on Enter

`tsx
function onCellKeyDown(args: CellKeyDownArgs, event: CellKeyboardEvent) {
if (args.mode === 'SELECT' && event.key === 'Enter') {
event.preventGridDefault();
}
}
`

- Prevent navigation on Tab

`tsx
function onCellKeyDown(args: CellKeyDownArgs, event: CellKeyboardEvent) {
if (args.mode === 'SELECT' && event.key === 'Tab') {
event.preventGridDefault();
}
}
`

Check more examples

###### onCellCopy?: Maybe<(args: CellCopyArgs, NoInfer>, event: CellClipboardEvent) => void>

Callback triggered when a cell's content is copied.

###### onCellPaste?: Maybe<(args: CellPasteArgs, NoInfer>, event: CellClipboardEvent) => void>

Callback triggered when content is pasted into a cell.

###### onSelectedCellChange?: Maybe<(args: CellSelectArgs) => void>;

Triggered when the selected cell is changed.

Arguments:

- args.rowIdx: number - row index
- args.row: R - row object of the currently selected cell
- args.column: CalculatedColumn - column object of the currently selected cell

###### onScroll?: Maybe<(event: React.UIEvent) => void>

Callback triggered when the grid is scrolled.

###### onColumnResize?: Maybe<(column: CalculatedColumn, width: number) => void>

Callback triggered when column is resized.

###### onColumnsReorder?: Maybe<(sourceColumnKey: string, targetColumnKey: string) => void>

Callback triggered when columns are reordered.

###### enableVirtualization?: Maybe

Default: true

This prop can be used to disable virtualization.

###### renderers?: Maybe>

Custom renderers for cells, rows, and other components.

`tsx
interface Renderers {
renderCell?: Maybe<(key: Key, props: CellRendererProps) => ReactNode>;
renderCheckbox?: Maybe<(props: RenderCheckboxProps) => ReactNode>;
renderRow?: Maybe<(key: Key, props: RenderRowProps) => ReactNode>;
renderSortStatus?: Maybe<(props: RenderSortStatusProps) => ReactNode>;
noRowsFallback?: Maybe;
}
`

Example of replacing default components:

`tsx
import { DataGrid, type Renderers } from 'react-data-grid';

const customRenderers: Renderers = {
// Custom row render function
renderRow(key, props) {
return ;
},

// Custom cell render function
renderCell(key, props) {
return ;
},

// Custom checkbox render function
renderCheckbox(props) {
return ;
},

// Custom sort status indicator
renderSortStatus(props) {
return ;
},

// Custom empty state
noRowsFallback:

};

;
`

The default component can be wrapped via the renderRow prop to add contexts or tweak props:

`tsx
import { DataGrid, RenderRowProps, Row } from 'react-data-grid';

function myRowRenderer(key: React.Key, props: RenderRowProps) {
return (



);
}

function MyGrid() {
return ;
}
`

###### rowClass?: Maybe<(row: R, rowIdx: number) => Maybe>

Function to apply custom class names to rows.

`tsx
import { DataGrid } from 'react-data-grid';

function rowClass(row: Row, rowIdx: number) {
return rowIdx % 2 === 0 ? 'even' : 'odd';
}

function MyGrid() {
return ;
}
`

:warning: Performance: Define this function outside your component or memoize it with useCallback to avoid re-rendering all rows on every render.

###### headerRowClass?: Maybe>

Custom class name for the header row.

`tsx

`

###### direction?: Maybe<'ltr' | 'rtl'>

This property sets the text direction of the grid, it defaults to 'ltr' (left-to-right). Setting direction to 'rtl' has the following effects:

- Columns flow from right to left
- Frozen columns are pinned on the right
- Column resize cursor is shown on the left edge of the column
- Scrollbar is moved to the left

###### className?: string | undefined

Custom class name for the grid.

###### style?: CSSProperties | undefined

Custom styles for the grid.

###### 'aria-label'?: string | undefined

The label of the grid. We recommend providing a label using aria-label or aria-labelledby

###### 'aria-labelledby'?: string | undefined

The id of the element containing a label for the grid. We recommend providing a label using aria-label or aria-labelledby

###### 'aria-description'?: string | undefined

###### 'aria-describedby'?: string | undefined

If the grid has a caption or description, aria-describedby can be set on the grid element with a value referring to the element containing the description.

###### 'data-testid'?: Maybe

This prop can be used to add a testid for testing. We recommend querying the grid by by its role and name.

`tsx
function MyGrid() {
return ;
}

test('grid', async () => {
await render();
const grid = screen.getByRole('grid', { name: 'my-grid' });
});
`

####

TreeDataGrid is a component built on top of DataGrid to add hierarchical row grouping. This implements the Treegrid pattern.

How it works:

1. The groupBy prop specifies which columns should be used for grouping
2. The rowGrouper function groups rows by the specified column keys
3. Group rows are rendered with expand/collapse toggles
4. Child rows are nested under their parent groups
5. Groups can be expanded/collapsed by clicking the toggle or using keyboard navigation (←, →)

Keyboard Navigation:

- → (Right Arrow): Expand a collapsed group row when focused
- ← (Left Arrow): Collapse an expanded group row when focused, or navigate to parent group

Unsupported Props:

The following DataGrid props are not supported in TreeDataGrid:

- onFill - Drag-fill is disabled for tree grids
- isRowSelectionDisabled - Row selection disabling is not available

Caveats:

- Group columns cannot be rendered under one column
- Group columns are automatically frozen and cannot be unfrozen
- Cell copy/paste does not work on group rows

##### TreeDataGridProps

All DataGridProps are supported except those listed above, plus the following additional props:

###### groupBy: readonly string[]

Required. An array of column keys to group by. The order determines the grouping hierarchy (first key is the top level, second key is nested under the first, etc.).

`tsx
import { TreeDataGrid, type Column } from 'react-data-grid';

interface Row {
id: number;
country: string;
city: string;
name: string;
}

const columns: readonly Column[] = [
{ key: 'country', name: 'Country' },
{ key: 'city', name: 'City' },
{ key: 'name', name: 'Name' }
];

function MyGrid() {
return (
columns={columns}
rows={rows}
groupBy={['country', 'city']}
// ... other props
/>
);
}
`

###### rowGrouper: (rows: readonly R[], columnKey: string) => Record

Required. A function that groups rows by the specified column key. Returns an object where keys are the group values and values are arrays of rows belonging to that group.

`tsx
function rowGrouper(rows: Row[], columnKey: string) {
return Object.groupBy(rows, (row) => row[columnKey]);
}
`

###### expandedGroupIds: ReadonlySet

Required. A set of group IDs that are currently expanded. Group IDs are generated by groupIdGetter.

`tsx
import { useState } from 'react';
import { TreeDataGrid } from 'react-data-grid';

function MyGrid() {
const [expandedGroupIds, setExpandedGroupIds] = useState((): ReadonlySet => new Set());

return (
expandedGroupIds={expandedGroupIds}
onExpandedGroupIdsChange={setExpandedGroupIds}
// ... other props
/>
);
}
`

###### onExpandedGroupIdsChange: (expandedGroupIds: Set) => void

Required. Callback triggered when groups are expanded or collapsed.

###### groupIdGetter?: Maybe<(groupKey: string, parentId?: string) => string>

Function to generate unique IDs for group rows. If not provided, a default implementation is used that concatenates parent and group keys with __.

###### rowHeight?: Maybe) => number)>

Note: Unlike DataGrid, the rowHeight function receives RowHeightArgs which includes a type property to distinguish between regular rows and group rows:

`tsx
function getRowHeight(args: RowHeightArgs): number {
if (args.type === 'GROUP') {
return 50; // Custom height for group rows
}
return 35; // Height for regular rows
}


`

####

The default row component. Can be wrapped via the renderers.renderRow prop.

##### Props

RenderRowProps

####

The default cell component. Can be wrapped via the renderers.renderCell prop.

##### Props

CellRendererProps

####

A formatter component for rendering row selection checkboxes.

##### Props

###### value: boolean

Whether the checkbox is checked.

###### tabIndex: number

The tab index for keyboard navigation.

###### disabled?: boolean | undefined

Whether the checkbox is disabled.

###### onChange: (value: boolean, isShiftClick: boolean) => void

Callback when the checkbox state changes.

###### onClick?: MouseEventHandler | undefined

Optional click handler.

###### 'aria-label'?: string | undefined

Accessible label for the checkbox.

###### 'aria-labelledby'?: string | undefined

ID of the element that labels the checkbox.

$3

#### useHeaderRowSelection()

Hook for managing header row selection state. Used within custom header cell renderers to implement custom "select all" functionality.

Returns:

- isIndeterminate: boolean - Whether some (but not all) rows are selected
- isRowSelected: boolean - Whether all rows are selected
- onRowSelectionChange: (event: SelectHeaderRowEvent) => void - Callback to change selection state

Example:

`tsx
function CustomHeaderCell() {
const { isIndeterminate, isRowSelected, onRowSelectionChange } = useHeaderRowSelection();

return (
type="checkbox"
checked={isRowSelected}
indeterminate={isIndeterminate}
onChange={(event) => onRowSelectionChange({ checked: event.target.checked })}
/>
);
}
`

#### useRowSelection()

Hook for managing row selection state. Used within custom cell renderers to implement custom row selection.

Returns:

- isRowSelectionDisabled: boolean - Whether selection is disabled for this row
- isRowSelected: boolean - Whether this row is selected
- onRowSelectionChange: (event: SelectRowEvent) => void - Callback to change selection state

Example:

`tsx
function CustomSelectCell({ row }: RenderCellProps) {
const { isRowSelectionDisabled, isRowSelected, onRowSelectionChange } = useRowSelection();

return (
type="checkbox"
disabled={isRowSelectionDisabled}
checked={isRowSelected}
onChange={(event) =>
onRowSelectionChange({
row,
checked: event.target.checked,
isShiftClick: event.nativeEvent.shiftKey
})
}
/>
);
}
`

$3

#### renderHeaderCell(props: RenderHeaderCellProps)

The default header cell renderer. Renders sortable columns with sort indicators.

Example:

`tsx
import { renderHeaderCell, type Column } from 'react-data-grid';

const columns: readonly Column[] = [
{
key: 'name',
name: 'Name',
sortable: true,
renderHeaderCell
}
];
`

#### renderTextEditor(props: RenderEditCellProps)

A basic text editor provided for convenience.

Example:

`tsx
import { renderTextEditor, type Column } from 'react-data-grid';

const columns: readonly Column[] = [
{
key: 'title',
name: 'Title',
renderEditCell: renderTextEditor
}
];
`

#### renderSortIcon(props: RenderSortIconProps)

Renders the sort direction arrow icon.

Props:

- sortDirection: SortDirection | undefined - 'ASC', 'DESC', or undefined

#### renderSortPriority(props: RenderSortPriorityProps)

Renders the sort priority number for multi-column sorting.

Props:

- priority: number | undefined - The sort priority (1, 2, 3, etc.)

#### renderCheckbox(props: RenderCheckboxProps)

Renders a checkbox input with proper styling and accessibility.

Props:

- checked: boolean - Whether the checkbox is checked
- indeterminate?: boolean - Whether the checkbox is in indeterminate state
- disabled?: boolean - Whether the checkbox is disabled
- onChange: (checked: boolean, shift: boolean) => void - Change handler
- tabIndex: number - Tab index for keyboard navigation
- aria-label?: string - Accessible label
- aria-labelledby?: string - ID of labeling element

Example:

`tsx
import { DataGrid, renderCheckbox } from 'react-data-grid';

renderers={{
renderCheckbox: (props) => renderCheckbox({ ...props, 'aria-label': 'Select row' })
}}
/>;
`

#### renderToggleGroup(props: RenderGroupCellProps)

The default group cell renderer used by the columns used for grouping (groupBy prop). This renders the expand/collapse toggle.

##### Props

RenderGroupCellProps

Example:

`tsx
import { renderToggleGroup, type Column } from 'react-data-grid';

const columns: readonly Column[] = [
{
key: 'group',
name: 'Group',
renderGroupCell: renderToggleGroup
}
];
`

#### renderValue(props: RenderCellProps)

The default cell renderer that renders the value of row[column.key].

Example:

`tsx
import { renderValue, type Column } from 'react-data-grid';

const columns: readonly Column[] = [
{
key: 'title',
name: 'Title',
renderCell: renderValue
}
];
`

$3

#### DataGridDefaultRenderersContext

Context for providing default renderers to DataGrids in your app.

Example:

`tsx
import { DataGridDefaultRenderersContext, type Renderers } from 'react-data-grid';

// custom implementations of renderers
const defaultGridRenderers: Renderers = {
renderCheckbox,
renderSortStatus
};

function AppProvider({ children }) {
return (

{children}

);
}
`

$3

#### SelectColumn: Column

A pre-configured column for row selection.
Includes checkbox renderers for header, regular rows, and grouped rows.

Example:

`tsx
import { DataGrid, SelectColumn, type Column } from 'react-data-grid';

const columns: readonly Column[] = [SelectColumn, ...otherColumns];

function rowKeyGetter(row: Row) {
return row.id;
}

function MyGrid() {
return (
columns={columns}
rows={rows}
rowKeyGetter={rowKeyGetter}
selectedRows={selectedRows}
onSelectedRowsChange={setSelectedRows}
/>
);
}
`

#### SELECT_COLUMN_KEY = 'rdg-select-column'

The key used for the SelectColumn. Useful for identifying or filtering the select column.

Example:

`tsx
import { SELECT_COLUMN_KEY } from 'react-data-grid';

const nonSelectColumns = columns.filter((column) => column.key !== SELECT_COLUMN_KEY);
`

$3

#### Column

Defines the configuration for a column in the grid.

##### name: string | ReactElement

The name of the column. Displayed in the header cell by default.

##### key: string

A unique key to distinguish each column

##### width?: Maybe

Default auto

Width can be any valid css grid column value. If not specified, it will be determined automatically based on grid width and specified widths of other columns.

`tsx
const columns: Column[] = [
{
key: 'id',
name: 'ID',
width: 80, // Fixed width in pixels
resizable: false
},
{
key: 'name',
name: 'Name',
width: '30%', // Percentage width
minWidth: 100,
maxWidth: 400
},
{
key: 'description',
name: 'Description'
// No width specified - automatically sized
}
];
`

Other examples:

`tsx
width: 80, // pixels
width: '25%',
width: 'max-content',
width: 'minmax(100px, max-content)',
`

max-content can be used to expand the column to show all the content. Note that the grid is only able to calculate column width for visible rows.

##### minWidth?: Maybe

Default: 50 pixels

Minimum column width in pixels.

##### maxWidth?: Maybe

Maximum column width in pixels.

##### cellClass?: Maybe Maybe)>

Class name(s) for cells. Can be a string or a function that returns a class name based on the row.

`tsx
const columns: Column[] = [
{
key: 'status',
name: 'Status',
cellClass: (row) => status-${row.status}
},
{
key: 'price',
name: 'Price',
cellClass: 'text-right' // Static class
}
];
`

`css
.status-active {
color: green;
font-weight: bold;
}

.status-inactive {
color: grey;
}

.text-right {
text-align: right;
}
`

##### headerCellClass?: Maybe

Class name(s) for the header cell.

##### summaryCellClass?: Maybe Maybe)>

Class name(s) for summary cells. Can be a string or a function that returns a class name based on the summary row.

##### renderCell?: Maybe<(props: RenderCellProps) => ReactNode>

Render function to render the content of cells.

##### renderHeaderCell?: Maybe<(props: RenderHeaderCellProps) => ReactNode>

Render function to render the content of the header cell.

##### renderSummaryCell?: Maybe<(props: RenderSummaryCellProps) => ReactNode>

Render function to render the content of summary cells

##### renderGroupCell?: Maybe<(props: RenderGroupCellProps) => ReactNode>

Render function to render the content of group cells when using TreeDataGrid.

##### renderEditCell?: Maybe<(props: RenderEditCellProps) => ReactNode>

Render function to render the content of edit cells. When set, the column is automatically set to be editable

##### editable?: Maybe boolean)>

Control whether cells can be edited with renderEditCell.

##### colSpan?: Maybe<(args: ColSpanArgs) => Maybe>

Function to determine how many columns this cell should span. Returns the number of columns to span, or undefined for no spanning. See the ColSpanArgs type in the Types section below.

Example:

`tsx
import type { Column } from 'react-data-grid';

const columns: readonly Column[] = [
{
key: 'title',
name: 'Title',
colSpan(args) {
if (args.type === 'ROW' && args.row.isFullWidth) {
return 5; // Span 5 columns for full-width rows
}
return undefined;
}
}
];
`

##### frozen?: Maybe

Default: false

Determines whether column is frozen. Frozen columns are pinned on the left. At the moment we do not support pinning columns on the right.

##### resizable?: Maybe

Default: false

Enable resizing of the column

##### sortable?: Maybe

Default: false

Enable sorting of the column

##### draggable?: Maybe

Default: false

Enable dragging of the column

##### sortDescendingFirst?: Maybe

Default: false

Sets the column sort order to be descending instead of ascending the first time the column is sorted

##### editorOptions

Options for cell editing.

###### displayCellContent?: Maybe

Default: false

Render the cell content in addition to the edit cell content. Enable this option when the editor is rendered outside the grid, like a modal for example.

###### commitOnOutsideClick?: Maybe

Default: true

Commit changes when clicking outside the cell.

###### closeOnExternalRowChange?: Maybe

Default: true

Close the editor when the row value changes externally.

#### ColumnGroup

Defines a group of columns that share a common header.

`tsx
interface ColumnGroup {
readonly name: string | ReactElement;
readonly headerCellClass?: Maybe;
readonly children: readonly ColumnOrColumnGroup[];
}
`

Example:

`tsx
import type { ColumnOrColumnGroup } from 'react-data-grid';

const columns: readonly ColumnOrColumnGroup[] = [
{
name: 'Personal Info',
children: [
{ key: 'firstName', name: 'First Name' },
{ key: 'lastName', name: 'Last Name' }
]
}
];
`

#### ColumnOrColumnGroup

Union type representing either a Column or a ColumnGroup.

#### CalculatedColumn

Extends Column with additional computed properties used internally by the grid. This is the type passed to render functions.

Additional properties:

- idx: number - The column index
- level: number - Nesting level when using column groups
- parent: CalculatedColumnParent | undefined - Parent column group if nested
- Multiple Column properties have their values set to their default value

#### CalculatedColumnParent

Represents a parent column group in the calculated column structure.

`tsx
interface CalculatedColumnParent {
readonly name: string | ReactElement;
readonly parent: CalculatedColumnParent | undefined;
readonly idx: number;
readonly colSpan: number;
readonly level: number;
readonly headerCellClass?: Maybe;
}
`

#### CalculatedColumnOrColumnGroup

Union type representing either a CalculatedColumnParent or a CalculatedColumn.

`tsx
type CalculatedColumnOrColumnGroup = CalculatedColumnParent | CalculatedColumn;
`

#### RowHeightArgs

Arguments passed to the rowHeight function when it's a function.

`tsx
type RowHeightArgs = { type: 'ROW'; row: TRow } | { type: 'GROUP'; row: GroupRow };
`

Example:

`tsx
function getRowHeight(args: RowHeightArgs): number {
if (args.type === 'GROUP') {
return 40;
}
return args.row.isLarge ? 60 : 35;
}


`

#### RenderCellProps

Props passed to custom cell renderers.

`tsx
interface RenderCellProps {
column: CalculatedColumn;
row: TRow;
rowIdx: number;
isCellEditable: boolean;
tabIndex: number;
onRowChange: (row: TRow) => void;
}
`

Example:

`tsx
import type { RenderCellProps } from 'react-data-grid';

function renderCell({ row, column, onRowChange }: RenderCellProps) {
return (



);
}
`

#### RenderHeaderCellProps

Props passed to custom header cell renderers.

`tsx
interface RenderHeaderCellProps {
column: CalculatedColumn;
sortDirection: SortDirection | undefined;
priority: number | undefined;
tabIndex: number;
}
`

#### RenderEditCellProps

Props passed to custom edit cell renderers (editors).

`tsx
interface RenderEditCellProps {
column: CalculatedColumn;
row: TRow;
rowIdx: number;
onRowChange: (row: TRow, commitChanges?: boolean) => void;
onClose: (commitChanges?: boolean, shouldFocusCell?: boolean) => void;
}
`

Example:

`tsx
import type { RenderEditCellProps } from 'react-data-grid';

function CustomEditor({ row, column, onRowChange, onClose }: RenderEditCellProps) {
return (
autoFocus
value={row[column.key]}
onChange={(event) => onRowChange({ ...row, [column.key]: event.target.value })}
onBlur={() => onClose(true)}
/>
);
}
`

#### RenderSummaryCellProps

Props passed to summary cell renderers.

`tsx
interface RenderSummaryCellProps {
column: CalculatedColumn;
row: TSummaryRow;
tabIndex: number;
}
`

#### RenderGroupCellProps

Props passed to group cell renderers when using TreeDataGrid.

`tsx
interface RenderGroupCellProps {
groupKey: unknown;
column: CalculatedColumn;
row: GroupRow;
childRows: readonly TRow[];
isExpanded: boolean;
tabIndex: number;
toggleGroup: () => void;
}
`

#### RenderRowProps

Props passed to custom row renderers.

`tsx
interface RenderRowProps {
row: TRow;
viewportColumns: readonly CalculatedColumn[];
rowIdx: number;
selectedCellIdx: number | undefined;
isRowSelected: boolean;
isRowSelectionDisabled: boolean;
gridRowStart: number;
lastFrozenColumnIndex: number;
draggedOverCellIdx: number | undefined;
selectedCellEditor: ReactElement> | undefined;
onRowChange: (column: CalculatedColumn, rowIdx: number, newRow: TRow) => void;
rowClass: Maybe<(row: TRow, rowIdx: number) => Maybe>;
// ... and event handlers
}
`

#### CellRendererProps

Props passed to the cell renderer when using renderers.renderCell.

Extends RenderRowProps with cell-specific properties like column, colSpan, isCellSelected, etc.

#### Renderers

Custom renderer configuration for the grid.

`tsx
interface Renderers {
renderCell?: Maybe<(key: Key, props: CellRendererProps) => ReactNode>;
renderCheckbox?: Maybe<(props: RenderCheckboxProps) => ReactNode>;
renderRow?: Maybe<(key: Key, props: RenderRowProps) => ReactNode>;
renderSortStatus?: Maybe<(props: RenderSortStatusProps) => ReactNode>;
noRowsFallback?: Maybe;
}
`

#### CellMouseArgs

Arguments passed to cell mouse event handlers.

`tsx
interface CellMouseArgs {
column: CalculatedColumn;
row: TRow;
rowIdx: number;
selectCell: (enableEditor?: boolean) => void;
}
`

##### column: CalculatedColumn

The column object of the cell.

##### row: TRow

The row object of the cell.

##### rowIdx: number

The row index of the cell.

##### selectCell: (enableEditor?: boolean) => void

Function to manually select the cell. Pass true to immediately start editing.

Example:

`tsx
import type { CellMouseArgs, CellMouseEvent } from 'react-data-grid';

function onCellClick(args: CellMouseArgs, event: CellMouseEvent) {
console.log('Clicked cell at row', args.rowIdx, 'column', args.column.key);
args.selectCell(true); // Select and start editing
}
`

#### CellMouseEvent

Extends React.MouseEvent with grid-specific methods.

##### event.preventGridDefault(): void

Prevents the default grid behavior for this event.

##### event.isGridDefaultPrevented(): boolean

Returns whether preventGridDefault was called.

Example:

`tsx
import type { CellMouseArgs, CellMouseEvent } from 'react-data-grid';

function onCellClick(args: CellMouseArgs, event: CellMouseEvent) {
if (args.column.key === 'actions') {
event.preventGridDefault(); // Prevent cell selection
}
}
`

#### CellKeyboardEvent

Extends React.KeyboardEvent with grid-specific methods.

##### event.preventGridDefault(): void

Prevents the default grid behavior for this keyboard event.

##### event.isGridDefaultPrevented(): boolean

Returns whether preventGridDefault was called.

#### CellClipboardEvent

Type alias for React.ClipboardEvent. Used for copy and paste events.

`tsx
type CellClipboardEvent = React.ClipboardEvent;
`

#### CellKeyDownArgs

Arguments passed to the onCellKeyDown handler. The shape differs based on whether the cell is in SELECT or EDIT mode.

SELECT mode:

`tsx
interface SelectCellKeyDownArgs {
mode: 'SELECT';
column: CalculatedColumn;
row: TRow;
rowIdx: number;
selectCell: (position: Position, options?: SelectCellOptions) => void;
}
`

EDIT mode:

`tsx
interface EditCellKeyDownArgs {
mode: 'EDIT';
column: CalculatedColumn;
row: TRow;
rowIdx: number;
navigate: () => void;
onClose: (commitChanges?: boolean, shouldFocusCell?: boolean) => void;
}
`

Example:

`tsx
import type { CellKeyboardEvent, CellKeyDownArgs } from 'react-data-grid';

function onCellKeyDown(args: CellKeyDownArgs, event: CellKeyboardEvent) {
if (args.mode === 'EDIT' && event.key === 'Escape') {
args.onClose(false); // Close without committing
event.preventGridDefault();
}
}
`

#### CellSelectArgs

Arguments passed to onSelectedCellChange.

`tsx
interface CellSelectArgs {
rowIdx: number;
row: TRow | undefined;
column: CalculatedColumn;
}
`

#### CellCopyArgs

Arguments passed to onCellCopy.

`tsx
interface CellCopyArgs {
column: CalculatedColumn;
row: TRow;
}
`

#### CellPasteArgs

Arguments passed to onCellPaste.

`tsx
interface CellPasteArgs {
column: CalculatedColumn;
row: TRow;
}
`

#### ColSpanArgs

Arguments passed to the colSpan function.

`tsx
type ColSpanArgs =
| { type: 'HEADER' }
| { type: 'ROW'; row: TRow }
| { type: 'SUMMARY'; row: TSummaryRow };
`

Example:

`tsx
import type { Column } from 'react-data-grid';

const columns: readonly Column[] = [
{
key: 'title',
name: 'Title',
colSpan(args) {
if (args.type === 'ROW' && args.row.isFullWidth) {
return 3; // Span 3 columns
}
return undefined;
}
}
];
`

#### SortColumn

Describes a sorted column.

`tsx
interface SortColumn {
readonly columnKey: string;
readonly direction: SortDirection;
}
`

#### SortDirection

`tsx
type SortDirection = 'ASC' | 'DESC';
`

#### RowsChangeData

Data provided to onRowsChange callback.

`tsx
interface RowsChangeData {
indexes: number[];
column: CalculatedColumn;
}
`

- indexes: Array of row indexes that changed
- column: The column where changes occurred

#### SelectRowEvent

Event object for row selection changes.

`tsx
interface SelectRowEvent {
row: TRow;
checked: boolean;
isShiftClick: boolean;
}
`

#### SelectHeaderRowEvent

Event object for header row selection changes.

`tsx
interface SelectHeaderRowEvent {
checked: boolean;
}
`

#### FillEvent

Event object for drag-fill operations.

`tsx
interface FillEvent {
columnKey: string;
sourceRow: TRow;
targetRow: TRow;
}
`

Used with the onFill prop to handle cell value dragging.

#### GroupRow

Represents a grouped row in TreeDataGrid.

`tsx
interface GroupRow {
readonly childRows: readonly TRow[];
readonly id: string;
readonly parentId: unknown;
readonly groupKey: unknown;
readonly isExpanded: boolean;
readonly level: number;
readonly posInSet: number;
readonly setSize: number;
readonly startRowIndex: number;
}
`

#### ColumnWidths

A map of column widths.

`tsx
type ColumnWidths = ReadonlyMap;

interface ColumnWidth {
readonly type: 'resized' | 'measured';
readonly width: number;
}
`

Used with columnWidths and onColumnWidthsChange props to control column widths externally.

#### Position

Represents a cell position in the grid.

`tsx
interface Position {
readonly idx: number; // Column index
readonly rowIdx: number; // Row index
}
`

#### SelectCellOptions

Options for programmatically selecting a cell.

`tsx
interface SelectCellOptions {
enableEditor?: Maybe;
shouldFocusCell?: Maybe;
}
`

#### RenderCheckboxProps

Props for custom checkbox renderers.

`tsx
interface RenderCheckboxProps {
checked: boolean;
indeterminate?: boolean;
disabled?: boolean;
onChange: (checked: boolean, shift: boolean) => void;
tabIndex: number;
'aria-label'?: string;
'aria-labelledby'?: string;
}
`

#### RenderSortStatusProps

Props for custom sort status renderers.

`tsx
interface RenderSortStatusProps {
sortDirection: SortDirection | undefined;
priority: number | undefined;
}
`

#### RenderSortIconProps

Props for custom sort icon renderers.

`tsx
interface RenderSortIconProps {
sortDirection: SortDirection | undefined;
}
`

#### RenderSortPriorityProps

Props for custom sort priority renderers.

`tsx
interface RenderSortPriorityProps {
priority: number | undefined;
}
`

#### DataGridHandle

Handle type assigned to a grid's ref for programmatic grid control.

`tsx
interface DataGridHandle {
element: HTMLDivElement | null;
scrollToCell: (position: Partial) => void;
selectCell: (position: Position, options?: SelectCellOptions) => void;
}
`

Example:

`tsx
import { useRef } from 'react';
import { DataGrid, DataGridHandle } from 'react-data-grid';

function MyGrid() {
const gridRef = useRef(null);

function scrollToTop() {
gridRef.current?.scrollToCell({ rowIdx: 0 });
}

return ;
}
`

#### DefaultColumnOptions

Default options applied to all columns.

`tsx
type DefaultColumnOptions = Pick<
Column,
'minWidth' | 'maxWidth' | 'resizable' | 'sortable' | 'draggable'
>;
`

#### Direction

Grid layout bidirectionality.

`tsx
type Direction = 'ltr' | 'rtl';
`

#### Maybe

Utility type for optional values.

`tsx
type Maybe = T | undefined | null;
`

$3

- R, TRow: Row type
- SR, TSummaryRow: Summary row type
- K`: Row key type