OGrid Props

Complete reference for IOGridProps<T>, the props accepted by the OGrid component in all UI packages (@alaarab/ogrid-react-radix, @alaarab/ogrid-react-fluent).

import { OGrid } from '@alaarab/ogrid-react-radix'; // Radix (default)
import { OGrid } from '@alaarab/ogrid-react-fluent';

Headless alternative

Own your table markup? useHeadlessGrid accepts the same columns, data, getRowId, dataSource, and controlled sort / filter / page props as plain hook parameters, and the spreadsheet hooks cover editing, selection, clipboard, and undo.

v1.6.0 Breaking Changes

• The title prop has been removed. Render your own heading outside <OGrid>.
• IFilters values are now discriminated unions: { type: 'text', value: string } instead of raw strings. See Filtering for the new format.

Data

Name	Type	Default	Description
columns	(IColumnDef<T> | IColumnGroupDef<T>)[]	Required	Array of column definitions and optional column groups. See Column Definition.
getRowId	(item: T) => RowId	Required	Function that returns a unique identifier for each row. Must be stable across re-renders.
data	T[]	undefined	Array of row data for client-side mode. Mutually exclusive with dataSource. When provided, sorting, filtering, and pagination are handled in-memory.
dataSource	IDataSource<T>	undefined	Server-side data source. Mutually exclusive with data. See Server-Side Data.
dataSourceKey	string | number	undefined	Identity of dataSource. When set, the grid refetches, drops cached rows and reloads filter options only when the key changes, so dataSource can be an inline object. When omitted, a new object counts as a new source unless its own properties are all identical to the previous one's. See Replacing the data source.
isLoading	boolean	false	Whether the grid is in a loading state. When true, the grid displays a loading indicator.

Sorting

Name	Type	Default	Description
sort	{ field: string; direction: 'asc' | 'desc' }	undefined	Controlled sort state. When provided, the grid uses this value and calls onSortChange when the user clicks a sortable column header.
onSortChange	(sort: { field: string; direction: 'asc' | 'desc' }) => void	undefined	Callback fired when the user changes the sort. Required for controlled sort mode.
defaultSortBy	string	first sortable column	Column ID to sort by initially in uncontrolled mode. Columns with sortable: false are never used as the default.
defaultSortDirection	'asc' | 'desc'	undefined	Initial sort direction in uncontrolled mode. Used together with defaultSortBy.
workerSort	boolean | 'auto'	false	Offload sorting to a Web Worker to keep the main thread responsive. true always uses the worker; 'auto' uses it past ~5000 rows. Columns with a custom compare fall back to synchronous sort.

Filtering

Name	Type	Default	Description
filters	IFilters	undefined	Controlled filter state. A record mapping field names to filter values. See Types for IFilters.
onFiltersChange	(filters: IFilters) => void	undefined	Callback fired when the user applies or clears a filter. Required for controlled filter mode.

Pagination

Name	Type	Default	Description
page	number	undefined	Controlled current page (1-based).
pageSize	number	undefined	Controlled page size.
onPageChange	(page: number) => void	undefined	Callback fired when the user navigates to a different page.
onPageSizeChange	(size: number | 'all') => void	undefined	Callback fired when the user changes the page size.
defaultPageSize	number | 'all'	25	Initial page size in uncontrolled mode. 'all' shows every row on one page.
pageSizeOptions	(number | 'all')[]	[10, 25, 50, 100]	Options shown in the page size dropdown. Include 'all' to offer an "All" entry that shows every filtered row on one page. The active page size is auto-inserted if missing.

Column Visibility and Order

Name	Type	Default	Description
visibleColumns	Set<string>	undefined	Controlled set of visible column IDs. When provided, only these columns are displayed.
onVisibleColumnsChange	(cols: Set<string>) => void	undefined	Callback fired when column visibility changes (e.g., via the column chooser).
columnOrder	string[]	undefined	Controlled column order as an array of column IDs.
onColumnOrderChange	(order: string[]) => void	undefined	Callback fired when the user reorders columns.
onColumnResized	(columnId: string, width: number) => void	undefined	Callback fired when the user finishes resizing a column.
responsiveColumns	boolean | IResponsiveColumnsConfig	false	Auto-hide columns by their responsivePriority as the container narrows. true uses default breakpoints (576/768/992/1200px); pass a config object for custom thresholds.

Editing

Name	Type	Default	Description
editable	boolean	false	Whether inline cell editing is enabled globally. Individual columns can override this via IColumnDef.editable.
onCellValueChanged	(event: ICellValueChangedEvent<T>) => void	undefined	Callback fired after a cell value is committed. The event contains item, columnId, oldValue, newValue, and rowIndex.
onUndo	() => void	undefined	Callback fired when the user triggers undo (Ctrl+Z or context menu). Replaces the grid's internal history; with formulas, formula edits then arrive through onCellValueChanged as formula text (see Formulas).
onRedo	() => void	undefined	Callback fired when the user triggers redo (Ctrl+Y or context menu).
canUndo	boolean	false	Whether undo is available. Controls the enabled state of the undo context menu item.
canRedo	boolean	false	Whether redo is available. Controls the enabled state of the redo context menu item.

Cell Selection

Name	Type	Default	Description
cellSelection	boolean	true	Whether cell selection (active cell, range selection, drag selection) is enabled. When false, clicking cells does not highlight them.

Row Selection

Name	Type	Default	Description
rowSelection	RowSelectionMode	'none'	Row selection mode: 'none', 'single', or 'multiple'. When enabled, a checkbox column is added.
selectedRows	Set<RowId>	undefined	Controlled set of selected row IDs.
onSelectionChange	(event: IRowSelectionChangeEvent<T>) => void	undefined	Callback fired when row selection changes. The event contains selectedRowIds and selectedItems.

Status Bar

Name	Type	Default	Description
statusBar	boolean | IStatusBarProps	false	Controls the status bar at the bottom of the grid. Pass true to show a default status bar with item counts, or pass an IStatusBarProps object for full control. See Types for IStatusBarProps.

Side Bar

Name	Type	Default	Description
sideBar	boolean | ISideBarDef	undefined	Controls the side bar panel. Pass true for default side bar, or an ISideBarDef object to configure panels and position. See Types for ISideBarDef.

Column Chooser

Name	Type	Default	Description
columnChooser	boolean | 'toolbar' | 'sidebar'	true	Where to render the column chooser. true/'toolbar' shows it in the toolbar. 'sidebar' moves it to the sidebar columns panel. false hides it entirely.

Column Reordering

Name	Type	Default	Description
columnReorder	boolean	false	Enable drag-and-drop column reordering via header cells. See Column Reordering.

Virtual Scrolling

Name	Type	Default	Description
virtualScroll	IVirtualScrollConfig	undefined	Virtual scrolling configuration. See Virtual Scrolling and Types for IVirtualScrollConfig.

Layout

Name	Type	Default	Description
layoutMode	'content' | 'fill'	'fill'	How the grid sizes itself. 'content' sizes to fit content. 'fill' expands to fill its container.
suppressHorizontalScroll	boolean	false	When true, disables horizontal scrolling by setting overflow-x: hidden on the grid wrapper.
stickyHeader	boolean	true	When true, column headers stick to the top of the scroll container during vertical scrolling. Set to false to let headers scroll with data.
fullScreen	boolean	false	When true, renders a fullscreen toggle button in the toolbar. Clicking it expands the grid to fill the entire viewport. Press Escape or click the button again to exit.
rowHeight	number	36	Fixed row height in pixels. Affects layout and virtual scrolling row height calculation.
density	'compact' | 'normal' | 'comfortable'	'normal'	Cell spacing preset. Controls cell padding throughout the grid.
showRowNumbers	boolean	false	Show Excel-style row number column (1, 2, 3...) at the start of the grid.
cellReferences	boolean	false	Excel-style cell references: column-letter headers (A, B, C…), a row-number gutter, and a name box showing the active cell (e.g. "A1"). Implies showRowNumbers.
className	string	undefined	Additional CSS class name applied to the root grid element.
toolbar	ReactNode	undefined	Custom toolbar content rendered in the left side of the primary toolbar strip.
toolbarBelow	ReactNode	undefined	Secondary toolbar row rendered below the primary toolbar. Use for active filter chips, breadcrumbs, or other contextual controls.
entityLabelPlural	string	undefined	Plural label for the entity type (e.g., "projects", "users"). Used in status bar text and empty state messages.
emptyState	{ message?: ReactNode; render?: () => ReactNode }	undefined	Custom empty state configuration. Provide message for a simple text override, or render for a fully custom empty state component.

Formulas

Name	Type	Default	Description
formulas	boolean	false	Enable Excel-like formulas. When on, cells starting with = are evaluated by the built-in formula engine.
initialFormulas	Array<{ col: number; row: number; formula: string }>	undefined	Formulas to load when the engine initializes.
onFormulaRecalc	(result: IRecalcResult) => void	undefined	Called when a recalculation updates cell values (e.g. a cascade from an edited cell).
formulaFunctions	Record<string, IFormulaFunction>	undefined	Custom functions to register with the formula engine.
namedRanges	Record<string, string>	undefined	Named ranges for formulas, mapping a name to a cell/range ref (e.g. { Revenue: 'A1:A10' }).
formulaLimits	IFormulaLimits	undefined	Per-formula limits: maxRangeCells (default 5,000,000) and maxWork (default 20,000,000). A formula over a limit returns #VALUE!. Lower them for untrusted workbooks.
sheets	Record<string, IGridDataAccessor>	undefined	Accessors for cross-sheet formula references (e.g. { Sheet2: accessor }).

See Formulas for the full guide.

Multi-Sheet

Excel-style sheet tabs along the bottom of the grid.

Name	Type	Default	Description
sheetDefs	ISheetDef[]	undefined	Sheet definitions. When set, renders a bottom tab bar (the SheetTabs component).
activeSheet	string	undefined	The currently active sheet id.
onSheetChange	(sheetId: string) => void	undefined	Called when the user switches sheets.
onSheetAdd	() => void	undefined	Called when the user clicks the add-sheet button.

See Multi-Sheet.

Callbacks

Name	Type	Default	Description
onFirstDataRendered	() => void	undefined	Fired once when the grid first renders with data. Useful for restoring column state.
onColumnPinned	(columnId: string, pinned: 'left' | 'right' | null) => void	undefined	Fired when a column is pinned or unpinned.

Error Handling

Name	Type	Default	Description
onError	(error: unknown) => void	undefined	Callback fired when the grid encounters an error (e.g., a failed server-side fetch).
onCellError	(error: Error, errorInfo: React.ErrorInfo) => void	undefined	Callback fired when a cell renderer or custom editor throws an error.
onClipboardError	(error: unknown) => void	undefined	Callback fired when reading the system clipboard fails on paste (e.g., permission denied). The paste is abandoned instead of pasting stale in-grid content.

Accessibility

Name	Type	Default	Description
aria-label	string	undefined	Accessible label for the grid. Use this or aria-labelledby, not both.
aria-labelledby	string	undefined	ID of an element that labels the grid. Use this or aria-label, not both.

Ref

The OGrid component accepts a ref prop that exposes the IOGridApi<T> imperative API. See Grid API for full details.

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

function MyGrid() {
  const apiRef = useRef<IOGridApi<MyRow>>(null);

  return (
    <OGrid
      ref={apiRef}
      columns={columns}
      data={data}
      getRowId={(row) => row.id}
    />
  );
}

Minimal Example

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

interface Person {
  id: number;
  name: string;
  age: number;
}

const columns = [
  { columnId: 'name', name: 'Name' },
  { columnId: 'age', name: 'Age', type: 'numeric' as const },
];

const data: Person[] = [
  { id: 1, name: 'Alice', age: 30 },
  { id: 2, name: 'Bob', age: 25 },
];

function App() {
  return (
    <OGrid<Person>
      columns={columns}
      data={data}
      getRowId={(row) => row.id}
    />
  );
}

Controlled vs Uncontrolled

OGrid supports both controlled and uncontrolled modes for pagination, sorting, filtering, column visibility, column order, and row selection.

Uncontrolled (default): The grid manages state internally. Use default* props to set initial values.

<OGrid
  columns={columns}
  data={data}
  getRowId={(row) => row.id}
  defaultPageSize={25}
  defaultSortBy="name"
  defaultSortDirection="asc"
/>

Controlled: You own the state and pass values + callbacks. The grid never updates these values on its own.

const [page, setPage] = useState(1);
const [pageSize, setPageSize] = useState(25);
const [sort, setSort] = useState({ field: 'name', direction: 'asc' as const });

<OGrid
  columns={columns}
  data={data}
  getRowId={(row) => row.id}
  page={page}
  pageSize={pageSize}
  sort={sort}
  onPageChange={setPage}
  onPageSizeChange={setPageSize}
  onSortChange={setSort}
/>