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';
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.
- The
titleprop has been removed. Render your own heading outside<OGrid>. IFiltersvalues 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. |
sortModel | ISortModelItem[] | undefined | Controlled multi-level sort ({ field, direction } levels, primary first). Takes precedence over sort. |
onSortModelChange | (sortModel: ISortModelItem[]) => void | undefined | Called with every sort level when the sort changes (Shift+click a header or Add to sort adds levels). |
defaultSortModel | ISortModelItem[] | undefined | Initial multi-level sort in uncontrolled mode. Takes precedence over 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. |
quickFilter | string | undefined | Controlled quick filter text: every space-separated term must appear in one of a row's visible columns. Sent to data sources as quickFilter. See Quick filter. |
defaultQuickFilter | string | '' | Starting quick filter text when quickFilter is not set. |
onQuickFilterChange | (text: string) => void | undefined | Fired with the new text when the search box changes it. |
quickFilterBox | boolean | { placeholder?: string; ariaLabel?: string } | false | Show a search box for the quick filter at the start of the toolbar. |
getQuickFilterText | (row: T) => string | null | undefined | undefined | Extra per-row text the quick filter searches besides the visible columns (client-side). |
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). |
defaultColumnVisibility | IColumnVisibilityState | undefined | Starting visibility as a diff from each column's defaultVisible ({ hidden, shown }). Turns on the saved column visibility model. |
columnVisibility | IColumnVisibilityState | undefined | Controlled visibility diff. Takes precedence over visibleColumns. |
onColumnVisibilityChange | (state: IColumnVisibilityState) => void | undefined | Fired with the new diff when the user shows or hides columns. Save this value. |
columnOrder | string[] | undefined | Controlled column order as an array of column IDs. |
onColumnOrderChange | (order: string[]) => void | undefined | Fired with every column id in the new order when columns are reordered. Save this value. |
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. |
Structure Editing
See Structure Editing.
| Name | Type | Default | Description |
|---|---|---|---|
allowStructureEdits | boolean | false | Adds "Insert row above/below", "Delete row", "Insert column left/right" and "Delete column" to the cell context menu, and the column items to the column header menu. The structure methods on the grid API work without it. |
allowHiding | boolean | false | Adds "Hide column" / "Unhide columns" to the column header menu, "Hide row(s)" / "Unhide rows" (and "Hide columns" for a whole-column or multi-column selection) to the cell context menu, and a clickable double-line marker where hidden columns or rows sit. See Hiding Rows and Columns. |
hiddenRowIds | RowId[] | undefined | Hidden rows (controlled). Hidden rows are left out of the display, navigation, copy, aggregations, counts, paging and SUBTOTAL 101-111, with or without allowHiding. |
defaultHiddenRowIds | RowId[] | undefined | Initially hidden rows when hiddenRowIds isn't controlled. |
onHiddenRowIdsChange | (rowIds: RowId[]) => void | undefined | Called with the full new list when the user hides or unhides rows. |
onRowsChange | (event: IRowsChangeEvent<T>) => void | undefined | Fired when rows are inserted or deleted (menu, API, undo/redo). event.data is the complete new array: onRowsChange={(e) => setData(e.data)}. Required to change rows when you pass data. |
onColumnsChange | (event: IColumnsChangeEvent<T>) => void | undefined | Fired when a column is inserted or deleted. event.columns is the complete new columns value. Required for column structure edits. |
createRow | (index: number) => T | undefined | Builds a blank row (with a new unique id) for "Insert row" and insertRows(index) without rows. The insert-row menu items need it. |
rowResize | boolean | false | Drag the bottom edge of a row number to resize that row. Needs showRowNumbers or cellReferences; off with windowed data sources and past the virtual-scroll height cap. |
rowHeights | Record<RowId, number> | undefined | Row heights in pixels by row id (applied with or without rowResize). A manual height wins over wrapped text. Without it the grid keeps resized heights itself. |
onRowResized | (rowId: RowId, height: number) => void | undefined | Fired when the user finishes resizing a row. |
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 column reordering: drag a header, or use Move left / Move right in the header menu. 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. The page behind is scroll-locked while fullscreen, and its scroll position comes back on exit. The layer is --ogrid-z-fullscreen (default 9999); see Theming. |
isFullScreen | boolean | undefined | Controlled fullscreen state. Leave it unset to let the grid keep it. Works without fullScreen, for your own toggle. |
onFullScreenChange | (isFullScreen: boolean) => void | undefined | Called when the toolbar button or Escape enters or leaves fullscreen. With isFullScreen set, update it here. |
fullScreenShortcut | string | false | 'f' | Key that toggles fullscreen while the grid has focus and no cell is being edited ('Shift+F', 'Mod+Shift+F'). A plain key gives way on an editable cell. Active when fullscreen is on offer (fullScreen, headerMenu or isFullScreen). |
headerMenu | boolean | false | Settings button in the header's top-right corner with Columns, Full screen and Autosize all columns. Drops the toolbar's column chooser unless columnChooser is set. See Header Menu. |
onColumnsReset | () => void | undefined | Called after the corner menu's Reset columns restores default visibility, order and widths, e.g. to clear saved column state. |
headerMenuItems | IGridMenuItem[] | (builtIns, { isFullScreen }) => IGridMenuItem[] | undefined | Items for the corner menu: an array is added after the built-ins; a function returns the full list. Items with items open submenus. |
columnMenuItems | IGridMenuItem[] | (builtIns, { columnId }) => IGridMenuItem[] | undefined | Items for each column's menu (options button and header right-click), same shapes. |
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. |
onSheetRename | (sheetId: string, name: string) => void | undefined | Enables renaming: double-click a tab (or F2, or "Rename" in the tab menu). |
onSheetReorder | (sheetIds: string[]) => void | undefined | Enables reordering by dragging tabs (or "Move left/right" in the tab menu). Receives every sheet id in the new order. |
onSheetDelete | (sheetId: string) => void | undefined | Adds "Delete" to the tab menu (disabled for the last sheet). |
onSheetColorChange | (sheetId: string, color: string | undefined) => void | undefined | Adds tab colors and "No color" to the tab menu. |
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}
/>