diff --git a/README.md b/README.md index d8f15085a9..7c963f0e92 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ The DataGrid component is designed to handle large datasets efficiently while of - Great performance thanks to virtualization: columns and rows outside the viewport are not rendered - Strictly typed with TypeScript - [Keyboard accessibility](https://comcast.github.io/react-data-grid/#/CommonFeatures) -- Light and dark mode support out of the box via `color-scheme`. +- Light and dark mode support out of the box via `color-scheme` - [Frozen columns](https://comcast.github.io/react-data-grid/#/CommonFeatures): Freeze columns to keep them visible during horizontal scrolling. - [Column resizing](https://comcast.github.io/react-data-grid/#/CommonFeatures) - [Multi-column sorting](https://comcast.github.io/react-data-grid/#/CommonFeatures) @@ -53,7 +53,7 @@ The DataGrid component is designed to handle large datasets efficiently while of - [Cell copy / pasting](https://comcast.github.io/react-data-grid/#/AllFeatures) - [Cell value dragging / filling](https://comcast.github.io/react-data-grid/#/AllFeatures) - [Customizable Renderers](https://comcast.github.io/react-data-grid/#/CustomizableRenderers) -- Right-to-left (RTL) support. +- Right-to-left (RTL) support ## Links @@ -90,7 +90,7 @@ import 'react-data-grid/lib/styles.css'; `react-data-grid` is published as ECMAScript modules for evergreen browsers, bundlers, and server-side rendering. > **Important**
-> Vite 8+ by default uses `lightningcss` to minify css which has a [bug minifying light-dark syntax](https://github.com/parcel-bundler/lightningcss/issues/873). You can tweak the `cssMinify` or `cssTarget` [settings](https://main.vite.dev/config/build-options) as a workaround. +> Vite 8+ by default uses `lightningcss` to minify CSS which has a [bug minifying light-dark syntax](https://github.com/parcel-bundler/lightningcss/issues/873). You can tweak the `cssMinify` or `cssTarget` [settings](https://main.vite.dev/config/build-options) as a workaround. ```ts build: { @@ -257,7 +257,7 @@ An array of column definitions and/or column groups. See the [`ColumnOrColumnGro ###### `rows: readonly R[]` -An array of rows, the rows data can be of any type. +An array of rows. Row data can be of any type. :bulb: **Performance:** The grid is optimized for efficient rendering: @@ -316,7 +316,7 @@ function MyGrid() { 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. +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. See the [`RowsChangeData`](#rowschangedatatrow-tsummaryrow) type. ```tsx import { useState } from 'react'; @@ -374,7 +374,7 @@ Height of each summary row in pixels. ###### `columnWidths?: Maybe` -A map of column widths containing both measured and resized widths. If not provided then an internal state is used. +A map of column widths containing both measured and resized widths. If not provided then an internal state is used. See the [`ColumnWidths`](#columnwidths) type. ```tsx const [columnWidths, setColumnWidths] = useState((): ColumnWidths => new Map()); @@ -390,13 +390,13 @@ return void>` -Callback triggered when column widths change. If not provided then an internal state is used. +Callback triggered when column widths change. If not provided then an internal state is used. See the [`ColumnWidths`](#columnwidths) type. ###### `selectedRows?: Maybe>` A set of selected row keys. `rowKeyGetter` is required for row selection to work. -###### `isRowSelectionDisabled?: Maybe<(row: NoInfer) => boolean>` +###### `isRowSelectionDisabled?: Maybe<(row: R) => boolean>` Function to determine if row selection is disabled for a specific row. @@ -406,7 +406,7 @@ Callback triggered when the selection changes. ```tsx import { useState } from 'react'; -import { DataGrid, SelectColumn } from 'react-data-grid'; +import { DataGrid, SelectColumn, type Column } from 'react-data-grid'; const rows: readonly Row[] = [...]; @@ -441,7 +441,7 @@ function MyGrid() { ###### `sortColumns?: Maybe` -An array of sorted columns. +An array of sorted columns. See the [`SortColumn`](#sortcolumn) type. Sorting is controlled: the grid does not reorder `rows` for you. Apply the sorting to your `rows` state (or derived rows) based on `sortColumns`. @@ -451,7 +451,7 @@ Callback triggered when sorting changes. ```tsx import { useState } from 'react'; -import { DataGrid, SelectColumn } from 'react-data-grid'; +import { DataGrid, type Column, type SortColumn } from 'react-data-grid'; const rows: readonly Row[] = [...]; @@ -478,7 +478,7 @@ function MyGrid() { } ``` -More than one column can be sorted via `ctrl (command) + click`. To disable multiple column sorting, change the `onSortColumnsChange` function to +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[]) { @@ -488,7 +488,7 @@ function onSortColumnsChange(sortColumns: SortColumn[]) { ###### `defaultColumnOptions?: Maybe>` -Default options applied to all columns. +Default options applied to all columns. See the [`DefaultColumnOptions`](#defaultcolumnoptionstrow-tsummaryrow) type. ```tsx function MyGrid() { @@ -509,7 +509,7 @@ function MyGrid() { ###### `onCellMouseDown?: CellMouseEventHandler` -Callback triggered when a pointer becomes active in a cell. The default behavior is to focus the cell. Call `preventGridDefault` to prevent the default behavior. +Callback triggered when a pointer becomes active in a cell. The default behavior is to focus the cell. Call `preventGridDefault` to prevent the default behavior. See the [`CellMouseArgs`](#cellmouseargstrow-tsummaryrow) and [`CellMouseEvent`](#cellmouseevent) types. ```tsx function onCellMouseDown(args: CellMouseArgs, event: CellMouseEvent) { @@ -523,7 +523,7 @@ function onCellMouseDown(args: CellMouseArgs, event: CellMouseEvent) { ###### `onCellClick?: CellMouseEventHandler` -Callback triggered when a cell is clicked. +Callback triggered when a cell is clicked. See the [`CellMouseArgs`](#cellmouseargstrow-tsummaryrow) and [`CellMouseEvent`](#cellmouseevent) types. ```tsx function onCellClick(args: CellMouseArgs, event: CellMouseEvent) { @@ -535,7 +535,7 @@ function onCellClick(args: CellMouseArgs, event: CellMouseEvent) { ; ``` -This event can be used to open cell editor on single click +This event can be used to open the cell editor on a single click. ```tsx function onCellClick(args: CellMouseArgs, event: CellMouseEvent) { @@ -547,7 +547,7 @@ function onCellClick(args: CellMouseArgs, event: CellMouseEvent) { ###### `onCellDoubleClick?: CellMouseEventHandler` -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. +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. See the [`CellMouseArgs`](#cellmouseargstrow-tsummaryrow) and [`CellMouseEvent`](#cellmouseevent) types. ```tsx function onCellDoubleClick(args: CellMouseArgs, event: CellMouseEvent) { @@ -561,7 +561,7 @@ function onCellDoubleClick(args: CellMouseArgs, event: CellMouseEvent) { ###### `onCellContextMenu?: CellMouseEventHandler` -Callback triggered when a cell is right-clicked. +Callback triggered when a cell is right-clicked. See the [`CellMouseArgs`](#cellmouseargstrow-tsummaryrow) and [`CellMouseEvent`](#cellmouseevent) types. ```tsx function onCellContextMenu(args: CellMouseArgs, event: CellMouseEvent) { @@ -576,7 +576,7 @@ function onCellContextMenu(args: CellMouseArgs, event: CellMouseEvent) { ###### `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. +Callback triggered when a keydown event occurs on a cell. This can be used to customize cell navigation and editing behavior. See the [`CellKeyDownArgs`](#cellkeydownargstrow-tsummaryrow) and [`CellKeyboardEvent`](#cellkeyboardevent) types. **Examples** @@ -602,35 +602,47 @@ function onCellKeyDown(args: CellKeyDownArgs, event: CellKeyboardEvent) { Check [more examples](website/routes/CellNavigation.tsx) -###### `onCellCopy?: Maybe<(args: CellCopyArgs, NoInfer>, event: CellClipboardEvent) => void>` +###### `onCellCopy?: Maybe<(args: CellCopyArgs, event: CellClipboardEvent) => void>` -Callback triggered when a cell's content is copied. +Callback triggered when a cell's content is copied. See the [`CellCopyArgs`](#cellcopyargstrow-tsummaryrow) type. -###### `onCellPaste?: Maybe<(args: CellPasteArgs, NoInfer>, event: CellClipboardEvent) => R>` +###### `onCellPaste?: Maybe<(args: CellPasteArgs, event: CellClipboardEvent) => R>` -Callback triggered when content is pasted into a cell. +Callback triggered when content is pasted into a cell. See the [`CellPasteArgs`](#cellpasteargstrow-tsummaryrow) type. Return the updated row; the grid will call `onRowsChange` with it. ###### `onActivePositionChange?: Maybe<(args: PositionChangeArgs) => void>` -Triggered when the active position changes. - -See the [`PositionChangeArgs`](#positionchangeargstrow-tsummaryrow) type in the Types section below. +Callback triggered when the active position changes. See the [`PositionChangeArgs`](#positionchangeargstrow-tsummaryrow) type. ###### `onFill?: Maybe<(event: FillEvent) => R>` +Callback triggered when a cell value is dragged to fill other cells. Return the updated target row with the filled value applied. The grid will call `onRowsChange` with the result. + +See the [`FillEvent`](#filleventtrow) type for the event shape. + +> **Note:** This prop is not supported on `TreeDataGrid`. + +```tsx +function onFill(event: FillEvent): Row { + return { ...event.targetRow, [event.columnKey]: event.sourceRow[event.columnKey] }; +} + +; +``` + ###### `onScroll?: Maybe<(event: React.UIEvent) => void>` -Callback triggered when the grid is scrolled. +Callback triggered when the grid is scrolled. Fires on both vertical and horizontal scrolling. ###### `onColumnResize?: Maybe<(column: CalculatedColumn, width: number) => void>` -Callback triggered when column is resized. +Callback triggered when a column is resized. The `column` parameter is the full [`CalculatedColumn`](#calculatedcolumntrow-tsummaryrow) object, and `width` is the new width in pixels. ###### `onColumnsReorder?: Maybe<(sourceColumnKey: string, targetColumnKey: string) => void>` -Callback triggered when columns are reordered. +Callback triggered when columns are reordered. The parameters are the `key` values of the source and target columns. ###### `enableVirtualization?: Maybe` @@ -677,7 +689,7 @@ const customRenderers: Renderers = { ; ``` -The default `` component can be wrapped via the `renderRow` prop to add contexts or tweak props: +The default `` component can be wrapped via `renderers.renderRow` to add contexts or tweak props: ```tsx import { DataGrid, Row, type RenderRowProps } from 'react-data-grid'; @@ -727,7 +739,7 @@ Custom class name for the header row. ###### `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: +This property sets the text direction of the grid. It defaults to `'ltr'` (left-to-right). See the [`Direction`](#direction) type. Setting `direction` to `'rtl'` has the following effects: - Columns flow from right to left - Frozen columns are pinned on the right @@ -748,11 +760,11 @@ ARIA role for the grid container. Defaults to `grid`. ###### `'aria-label'?: string | undefined` -The label of the grid. We recommend providing a label using `aria-label` or `aria-labelledby` +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` +The id of the element containing a label for the grid. We recommend providing a label using `aria-label` or `aria-labelledby`. ###### `'aria-rowcount'?: number | undefined` @@ -760,6 +772,8 @@ Total number of rows for assistive technologies. ###### `'aria-description'?: string | undefined` +A human-readable description of the grid. + ###### `'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. @@ -960,6 +974,10 @@ ID of the element that labels the checkbox. Low-level component used by `renderToggleGroup` to render the expand/collapse control. Useful if you build a custom group cell renderer. +##### Props + +[`RenderGroupCellProps`](#rendergroupcellpropstrow-tsummaryrow) + ### Hooks #### `useHeaderRowSelection()` @@ -1076,7 +1094,7 @@ Renders the sort direction arrow icon. **Props:** -- `sortDirection: SortDirection | undefined` - 'ASC', 'DESC', or undefined +- `sortDirection: SortDirection | undefined` - `'ASC'`, `'DESC'`, or `undefined` #### `renderSortPriority(props: RenderSortPriorityProps)` @@ -1092,11 +1110,11 @@ 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 +- `checked?: boolean` - Whether the checkbox is checked +- `indeterminate?: boolean` - Whether the checkbox is in an indeterminate state - `disabled?: boolean` - Whether the checkbox is disabled - `onChange: (checked: boolean, shift: boolean) => void` - Change handler -- `tabIndex: number` - Tab index for keyboard navigation +- `tabIndex?: number` - Tab index for keyboard navigation - `aria-label?: string` - Accessible label - `aria-labelledby?: string` - ID of labeling element @@ -1246,13 +1264,13 @@ The name of the column. Displayed in the header cell by default. ##### `key: string` -A unique key to distinguish each column +A unique key to distinguish each column. ##### `width?: Maybe` -**Default** `auto` +**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. +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[] = [ @@ -1290,7 +1308,7 @@ width: 'minmax(100px, max-content)', ##### `minWidth?: Maybe` -**Default**: `50` pixels +**Default:** `50` pixels Minimum column width in pixels. @@ -1350,7 +1368,7 @@ Render function to render the content of the header cell. ##### `renderSummaryCell?: Maybe<(props: RenderSummaryCellProps) => ReactNode>` -Render function to render the content of summary cells +Render function to render the content of summary cells. ##### `renderGroupCell?: Maybe<(props: RenderGroupCellProps) => ReactNode>` @@ -1358,7 +1376,7 @@ 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 +Render function to render the content of edit cells. When set, the column is automatically set to be editable. ##### `editable?: Maybe boolean)>` @@ -1366,7 +1384,7 @@ 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`](#colspanargstrow-tsummaryrow) type in the Types section below. +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`](#colspanargstrow-tsummaryrow) type. **Example:** @@ -1389,33 +1407,33 @@ const columns: readonly Column[] = [ ##### `frozen?: Maybe` -**Default**: `false` +**Default:** `false` -Determines whether column is frozen. Frozen columns are pinned to the start edge (left in LTR, right in RTL). Per-column pinning to the end edge is not supported at the moment. +Determines whether the column is frozen. Frozen columns are pinned to the start edge (left in LTR, right in RTL). Per-column pinning to the end edge is not supported at the moment. ##### `resizable?: Maybe` -**Default**: `false` +**Default:** `false` -Enable resizing of the column +Enable resizing of the column. ##### `sortable?: Maybe` -**Default**: `false` +**Default:** `false` -Enable sorting of the column +Enable sorting of the column. ##### `draggable?: Maybe` -**Default**: `false` +**Default:** `false` -Enable dragging of the column +Enable dragging of the column. ##### `sortDescendingFirst?: Maybe` -**Default**: `false` +**Default:** `false` -Sets the column sort order to be descending instead of ascending the first time the column is sorted +Sets the column sort order to be descending instead of ascending the first time the column is sorted. ##### `editorOptions` @@ -1423,22 +1441,24 @@ Options for cell editing. ###### `displayCellContent?: Maybe` -**Default**: `false` +**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` +**Default:** `true` Commit changes when clicking outside the cell. ###### `closeOnExternalRowChange?: Maybe` -**Default**: `true` +**Default:** `true` Close the editor when the row value changes externally. +**See also:** `columns` prop on `` + #### `ColumnGroup` Defines a group of columns that share a common header. @@ -1467,10 +1487,14 @@ const columns: readonly ColumnOrColumnGroup[] = [ ]; ``` +**See also:** [`ColumnOrColumnGroup`](#columnorcolumngrouptrow-tsummaryrow) + #### `ColumnOrColumnGroup` Union type representing either a `Column` or a `ColumnGroup`. +**See also:** `columns` prop on `` + #### `CalculatedColumn` Extends `Column` with additional computed properties used internally by the grid. This is the type passed to render functions. @@ -1480,7 +1504,9 @@ Extends `Column` with additional computed properties used internally by the grid - `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 +- Optional Column properties are set to their default values + +**See also:** [`Column`](#columntrow-tsummaryrow), `onColumnResize` prop on `` #### `CalculatedColumnParent` @@ -1497,6 +1523,8 @@ interface CalculatedColumnParent { } ``` +**See also:** [`CalculatedColumn`](#calculatedcolumntrow-tsummaryrow) + #### `CalculatedColumnOrColumnGroup` Union type representing either a `CalculatedColumnParent` or a `CalculatedColumn`. @@ -1505,27 +1533,28 @@ Union type representing either a `CalculatedColumnParent` or a `CalculatedColumn type CalculatedColumnOrColumnGroup = CalculatedColumnParent | CalculatedColumn; ``` -#### `RowHeightArgs` - -Arguments passed to `TreeDataGrid`'s `rowHeight` prop when it is a function. +**See also:** [`CalculatedColumn`](#calculatedcolumntrow-tsummaryrow), [`CalculatedColumnParent`](#calculatedcolumnparenttrow-tsummaryrow) -```tsx -type RowHeightArgs = { type: 'ROW'; row: TRow } | { type: 'GROUP'; row: GroupRow }; -``` +#### `DefaultColumnOptions` -**Example:** +Default options applied to all columns. ```tsx -function getRowHeight(args: RowHeightArgs): number { - if (args.type === 'GROUP') { - return 40; - } - return args.row.isLarge ? 60 : 35; -} - - +type DefaultColumnOptions = Pick< + Column, + | 'renderCell' + | 'renderHeaderCell' + | 'width' + | 'minWidth' + | 'maxWidth' + | 'resizable' + | 'sortable' + | 'draggable' +>; ``` +**See also:** `defaultColumnOptions` prop on `` + #### `RenderCellProps` Props passed to custom cell renderers. @@ -1556,6 +1585,8 @@ function renderCell({ row, column, onRowChange }: RenderCellProps) { } ``` +**See also:** `Column.renderCell`, `renderValue` function + #### `RenderHeaderCellProps` Props passed to custom header cell renderers. @@ -1569,6 +1600,8 @@ interface RenderHeaderCellProps { } ``` +**See also:** `Column.renderHeaderCell`, `renderHeaderCell` function + #### `RenderEditCellProps` Props passed to custom edit cell renderers (editors). @@ -1600,6 +1633,8 @@ function CustomEditor({ row, column, onRowChange, onClose }: RenderEditCellProps } ``` +**See also:** `Column.renderEditCell`, `renderTextEditor` function + #### `RenderSummaryCellProps` Props passed to summary cell renderers. @@ -1612,6 +1647,8 @@ interface RenderSummaryCellProps { } ``` +**See also:** `Column.renderSummaryCell` + #### `RenderGroupCellProps` Props passed to group cell renderers when using `TreeDataGrid`. @@ -1628,6 +1665,8 @@ interface RenderGroupCellProps { } ``` +**See also:** `Column.renderGroupCell`, `renderToggleGroup` function + #### `RenderRowProps` Props passed to custom row renderers. @@ -1646,15 +1685,87 @@ interface RenderRowProps { onRowChange: (column: CalculatedColumn, rowIdx: number, newRow: TRow) => void; rowClass: Maybe<(row: TRow, rowIdx: number) => Maybe>; isTreeGrid: boolean; - // ... and event handlers + setActivePosition: (position: Position, options?: SetActivePositionOptions) => void; + // ... and DOM props, cell event handlers (onCellMouseDown, onCellClick, onCellDoubleClick, onCellContextMenu) } ``` +**See also:** `Renderers.renderRow`, `` + #### `CellRendererProps` Props passed to the cell renderer when using `renderers.renderCell`. -Shares a base type with row render props (DOM props and cell event handlers) but only includes cell-specific fields like `column`, `row`, `rowIdx`, `colSpan`, and position state. +```tsx +interface CellRendererProps { + column: CalculatedColumn; + row: TRow; + rowIdx: number; + colSpan: number | undefined; + isDraggedOver: boolean; + isCellActive: boolean; + onRowChange: (column: CalculatedColumn, rowIdx: number, newRow: TRow) => void; + setActivePosition: (position: Position, options?: SetActivePositionOptions) => void; + // ... and DOM props, cell event handlers (onCellMouseDown, onCellClick, onCellDoubleClick, onCellContextMenu) +} +``` + +**See also:** `Renderers.renderCell`, `` + +#### `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; +} +``` + +**See also:** `renderCheckbox` function, `Renderers.renderCheckbox` + +#### `RenderSortStatusProps` + +Props for custom sort status renderers. + +```tsx +interface RenderSortStatusProps { + sortDirection: SortDirection | undefined; + priority: number | undefined; +} +``` + +**See also:** `Renderers.renderSortStatus` + +#### `RenderSortIconProps` + +Props for custom sort icon renderers. + +```tsx +interface RenderSortIconProps { + sortDirection: SortDirection | undefined; +} +``` + +**See also:** `renderSortIcon` function + +#### `RenderSortPriorityProps` + +Props for custom sort priority renderers. + +```tsx +interface RenderSortPriorityProps { + priority: number | undefined; +} +``` + +**See also:** `renderSortPriority` function #### `Renderers` @@ -1670,6 +1781,8 @@ interface Renderers { } ``` +**See also:** `renderers` prop on ``, [`DataGridDefaultRenderersContext`](#datagriddefaultrendererscontext) + #### `CellMouseArgs` Arguments passed to cell mouse event handlers. @@ -1698,6 +1811,8 @@ function onCellClick(args: CellMouseArgs, event: CellMouseEvent) { } ``` +**See also:** `onCellMouseDown`, `onCellClick`, `onCellDoubleClick`, and `onCellContextMenu` props on `` + #### `CellMouseEventHandler` (internal) Handler type used by `onCellMouseDown`, `onCellClick`, `onCellDoubleClick`, and `onCellContextMenu`. This helper type is not exported; the shape is shown for reference. @@ -1732,25 +1847,7 @@ function onCellClick(args: CellMouseArgs, event: CellMouseEvent) { } ``` -#### `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; -``` +**See also:** `onCellMouseDown`, `onCellClick`, `onCellDoubleClick`, and `onCellContextMenu` props on `` #### `CellKeyDownArgs` @@ -1794,27 +1891,32 @@ function onCellKeyDown(args: CellKeyDownArgs, event: CellKeyboardEvent) { } ``` -#### `PositionChangeArgs` +**See also:** `onCellKeyDown` prop on `` -Arguments passed to `onActivePositionChange`. +#### `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. + +**See also:** `onCellKeyDown` prop on `` + +#### `CellClipboardEvent` (internal) + +Type alias for `React.ClipboardEvent`. Used for copy and paste events. This helper type is not exported; the shape is shown for reference. ```tsx -interface PositionChangeArgs { - /** row index of the active position */ - rowIdx: number; - /** - * row object of the active position, - * undefined if the active position is on a header or summary row - */ - row: TRow | undefined; - /** - * column object of the active position, - * undefined if the active position is a row instead of a cell - */ - column: CalculatedColumn | undefined; -} +type CellClipboardEvent = React.ClipboardEvent; ``` +**See also:** `onCellCopy` and `onCellPaste` props on `` + #### `CellCopyArgs` Arguments passed to `onCellCopy`. @@ -1826,6 +1928,8 @@ interface CellCopyArgs { } ``` +**See also:** `onCellCopy` prop on `` + #### `CellPasteArgs` Arguments passed to `onCellPaste`. @@ -1837,6 +1941,31 @@ interface CellPasteArgs { } ``` +**See also:** `onCellPaste` prop on `` + +#### `PositionChangeArgs` + +Arguments passed to `onActivePositionChange`. + +```tsx +interface PositionChangeArgs { + /** row index of the active position */ + rowIdx: number; + /** + * row object of the active position, + * undefined if the active position is on a header or summary row + */ + row: TRow | undefined; + /** + * column object of the active position, + * undefined if the active position is a row instead of a cell + */ + column: CalculatedColumn | undefined; +} +``` + +**See also:** `onActivePositionChange` prop on `` + #### `ColSpanArgs` Arguments passed to the `colSpan` function. @@ -1867,6 +1996,31 @@ const columns: readonly Column[] = [ ]; ``` +**See also:** `Column.colSpan` + +#### `RowHeightArgs` + +Arguments passed to `TreeDataGrid`'s `rowHeight` prop when it is 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; +} + + +``` + +**See also:** `rowHeight` prop on `` + #### `SortColumn` Describes a sorted column. @@ -1878,12 +2032,16 @@ interface SortColumn { } ``` +**See also:** `sortColumns` and `onSortColumnsChange` props on `` + #### `SortDirection` ```tsx type SortDirection = 'ASC' | 'DESC'; ``` +**See also:** [`SortColumn`](#sortcolumn) + #### `RowsChangeData` Data provided to `onRowsChange` callback. @@ -1898,6 +2056,8 @@ interface RowsChangeData { - `indexes`: Array of row indexes that changed - `column`: The column where changes occurred +**See also:** `onRowsChange` prop on `` + #### `SelectRowEvent` Event object for row selection changes. @@ -1910,6 +2070,8 @@ interface SelectRowEvent { } ``` +**See also:** [`useRowSelection`](#userowselection) hook + #### `SelectHeaderRowEvent` Event object for header row selection changes. @@ -1920,6 +2082,8 @@ interface SelectHeaderRowEvent { } ``` +**See also:** [`useHeaderRowSelection`](#useheaderrowselection) hook + #### `FillEvent` Event object for drag-fill operations. @@ -1932,44 +2096,42 @@ interface FillEvent { } ``` -Used with the `onFill` prop to handle cell value dragging. +**See also:** `onFill` prop on `` -#### `GroupRow` (internal) +#### `DataGridHandle` -Represents a grouped row in `TreeDataGrid`. This helper type is not exported; the shape is shown for reference. +Handle type assigned to a grid's `ref` for programmatic grid control. ```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; +interface DataGridHandle { + element: HTMLDivElement | null; + scrollToCell: (position: PartialPosition) => void; + setActivePosition: (position: Position, options?: SetActivePositionOptions) => void; } ``` -#### `ColumnWidths` - -A map of column widths. +**Example:** ```tsx -type ColumnWidths = ReadonlyMap; +import { useRef } from 'react'; +import { DataGrid, DataGridHandle } from 'react-data-grid'; -interface ColumnWidth { - readonly type: 'resized' | 'measured'; - readonly width: number; +function MyGrid() { + const gridRef = useRef(null); + + function scrollToTop() { + gridRef.current?.scrollToCell({ rowIdx: 0 }); + } + + return ; } ``` -Used with `columnWidths` and `onColumnWidthsChange` props to control column widths externally. +**See also:** `ref` prop on `` -#### `Position` +#### `Position` (internal) -Represents a cell position in the grid. +Represents a cell position in the grid. This helper type is not exported; the shape is shown for reference. ```tsx interface Position { @@ -1978,119 +2140,90 @@ interface Position { } ``` -#### `SetActivePositionOptions` - -Options for programmatically updating the grid's active position. - -```tsx -interface SetActivePositionOptions { - enableEditor?: Maybe; - shouldFocus?: Maybe; -} -``` +**See also:** [`DataGridHandle`](#datagridhandle), [`CellKeyDownArgs`](#cellkeydownargstrow-tsummaryrow) -#### `RenderCheckboxProps` +#### `PartialPosition` (internal) -Props for custom checkbox renderers. +Position for scrolling to a cell. Both fields are optional: omit `idx` to scroll to a row, or omit `rowIdx` to scroll to a column. This helper type is not exported; the shape is shown for reference. ```tsx -interface RenderCheckboxProps { - checked: boolean; - indeterminate?: boolean; - disabled?: boolean; - onChange: (checked: boolean, shift: boolean) => void; - tabIndex: number; - 'aria-label'?: string; - 'aria-labelledby'?: string; +interface PartialPosition { + readonly idx?: Maybe; + readonly rowIdx?: Maybe; } ``` -#### `RenderSortStatusProps` - -Props for custom sort status renderers. +**See also:** [`DataGridHandle`](#datagridhandle) -```tsx -interface RenderSortStatusProps { - sortDirection: SortDirection | undefined; - priority: number | undefined; -} -``` - -#### `RenderSortIconProps` +#### `SetActivePositionOptions` -Props for custom sort icon renderers. +Options for programmatically updating the grid's active position. ```tsx -interface RenderSortIconProps { - sortDirection: SortDirection | undefined; +interface SetActivePositionOptions { + enableEditor?: Maybe; + shouldFocus?: Maybe; } ``` -#### `RenderSortPriorityProps` +**See also:** [`DataGridHandle`](#datagridhandle), [`CellKeyDownArgs`](#cellkeydownargstrow-tsummaryrow) -Props for custom sort priority renderers. +#### `ColumnWidths` + +A map of column widths. ```tsx -interface RenderSortPriorityProps { - priority: number | undefined; -} +type ColumnWidths = ReadonlyMap; ``` -#### `DataGridHandle` +**See also:** `columnWidths` and `onColumnWidthsChange` props on `` -Handle type assigned to a grid's `ref` for programmatic grid control. +#### `ColumnWidth` + +Represents a single column's width measurement. ```tsx -interface DataGridHandle { - element: HTMLDivElement | null; - scrollToCell: (position: PartialPosition) => void; - setActivePosition: (position: Position, options?: SetActivePositionOptions) => void; +interface ColumnWidth { + readonly type: 'resized' | 'measured'; + readonly width: number; } ``` -**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 }); - } +- `type`: `'resized'` when set by the user via column resizing, `'measured'` when auto-measured by the grid +- `width`: The width in pixels - return ; -} -``` +**See also:** [`ColumnWidths`](#columnwidths) -#### `DefaultColumnOptions` +#### `Direction` -Default options applied to all columns. +Grid layout bidirectionality. ```tsx -type DefaultColumnOptions = Pick< - Column, - | 'renderCell' - | 'renderHeaderCell' - | 'width' - | 'minWidth' - | 'maxWidth' - | 'resizable' - | 'sortable' - | 'draggable' ->; +type Direction = 'ltr' | 'rtl'; ``` -#### `Direction` +**See also:** `direction` prop on `` -Grid layout bidirectionality. +#### `GroupRow` (internal) + +Represents a grouped row in `TreeDataGrid`. This helper type is not exported; the shape is shown for reference. ```tsx -type Direction = 'ltr' | 'rtl'; +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; +} ``` +**See also:** [`RenderGroupCellProps`](#rendergroupcellpropstrow-tsummaryrow), `` + #### `Maybe` (internal) Utility type for optional values. This helper type is not exported; the shape is shown for reference.