Skip to main content

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​

NameTypeDefaultDescription
columns(IColumnDef<T> | IColumnGroupDef<T>)[]RequiredArray of column definitions and optional column groups. See Column Definition.
getRowId(item: T) => RowIdRequiredFunction that returns a unique identifier for each row. Must be stable across re-renders.
dataT[]undefinedArray of row data for client-side mode. Mutually exclusive with dataSource. When provided, sorting, filtering, and pagination are handled in-memory.
dataSourceIDataSource<T>undefinedServer-side data source. Mutually exclusive with data. See Server-Side Data.
dataSourceKeystring | numberundefinedIdentity 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.
isLoadingbooleanfalseWhether the grid is in a loading state. When true, the grid displays a loading indicator.

Sorting​

NameTypeDefaultDescription
sort{ field: string; direction: 'asc' | 'desc' }undefinedControlled 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' }) => voidundefinedCallback fired when the user changes the sort. Required for controlled sort mode.
defaultSortBystringfirst sortable columnColumn ID to sort by initially in uncontrolled mode. Columns with sortable: false are never used as the default.
defaultSortDirection'asc' | 'desc'undefinedInitial sort direction in uncontrolled mode. Used together with defaultSortBy.
sortModelISortModelItem[]undefinedControlled multi-level sort ({ field, direction } levels, primary first). Takes precedence over sort.
onSortModelChange(sortModel: ISortModelItem[]) => voidundefinedCalled with every sort level when the sort changes (Shift+click a header or Add to sort adds levels).
defaultSortModelISortModelItem[]undefinedInitial multi-level sort in uncontrolled mode. Takes precedence over defaultSortBy.
workerSortboolean | 'auto'falseOffload 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​

NameTypeDefaultDescription
filtersIFiltersundefinedControlled filter state. A record mapping field names to filter values. See Types for IFilters.
onFiltersChange(filters: IFilters) => voidundefinedCallback fired when the user applies or clears a filter. Required for controlled filter mode.
quickFilterstringundefinedControlled 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.
defaultQuickFilterstring''Starting quick filter text when quickFilter is not set.
onQuickFilterChange(text: string) => voidundefinedFired with the new text when the search box changes it.
quickFilterBoxboolean | { placeholder?: string; ariaLabel?: string }falseShow a search box for the quick filter at the start of the toolbar.
getQuickFilterText(row: T) => string | null | undefinedundefinedExtra per-row text the quick filter searches besides the visible columns (client-side).

Pagination​

NameTypeDefaultDescription
pagenumberundefinedControlled current page (1-based).
pageSizenumberundefinedControlled page size.
onPageChange(page: number) => voidundefinedCallback fired when the user navigates to a different page.
onPageSizeChange(size: number | 'all') => voidundefinedCallback fired when the user changes the page size.
defaultPageSizenumber | 'all'25Initial 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​

NameTypeDefaultDescription
visibleColumnsSet<string>undefinedControlled set of visible column IDs. When provided, only these columns are displayed.
onVisibleColumnsChange(cols: Set<string>) => voidundefinedCallback fired when column visibility changes (e.g., via the column chooser).
defaultColumnVisibilityIColumnVisibilityStateundefinedStarting visibility as a diff from each column's defaultVisible ({ hidden, shown }). Turns on the saved column visibility model.
columnVisibilityIColumnVisibilityStateundefinedControlled visibility diff. Takes precedence over visibleColumns.
onColumnVisibilityChange(state: IColumnVisibilityState) => voidundefinedFired with the new diff when the user shows or hides columns. Save this value.
columnOrderstring[]undefinedControlled column order as an array of column IDs.
onColumnOrderChange(order: string[]) => voidundefinedFired with every column id in the new order when columns are reordered. Save this value.
onColumnResized(columnId: string, width: number) => voidundefinedCallback fired when the user finishes resizing a column.
responsiveColumnsboolean | IResponsiveColumnsConfigfalseAuto-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​

NameTypeDefaultDescription
editablebooleanfalseWhether inline cell editing is enabled globally. Individual columns can override this via IColumnDef.editable.
onCellValueChanged(event: ICellValueChangedEvent<T>) => voidundefinedCallback fired after a cell value is committed. The event contains item, columnId, oldValue, newValue, and rowIndex.
onUndo() => voidundefinedCallback 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() => voidundefinedCallback fired when the user triggers redo (Ctrl+Y or context menu).
canUndobooleanfalseWhether undo is available. Controls the enabled state of the undo context menu item.
canRedobooleanfalseWhether redo is available. Controls the enabled state of the redo context menu item.

Structure Editing​

See Structure Editing.

NameTypeDefaultDescription
allowStructureEditsbooleanfalseAdds "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.
allowHidingbooleanfalseAdds "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.
hiddenRowIdsRowId[]undefinedHidden rows (controlled). Hidden rows are left out of the display, navigation, copy, aggregations, counts, paging and SUBTOTAL 101-111, with or without allowHiding.
defaultHiddenRowIdsRowId[]undefinedInitially hidden rows when hiddenRowIds isn't controlled.
onHiddenRowIdsChange(rowIds: RowId[]) => voidundefinedCalled with the full new list when the user hides or unhides rows.
onRowsChange(event: IRowsChangeEvent<T>) => voidundefinedFired 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>) => voidundefinedFired when a column is inserted or deleted. event.columns is the complete new columns value. Required for column structure edits.
createRow(index: number) => TundefinedBuilds a blank row (with a new unique id) for "Insert row" and insertRows(index) without rows. The insert-row menu items need it.
rowResizebooleanfalseDrag 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.
rowHeightsRecord<RowId, number>undefinedRow 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) => voidundefinedFired when the user finishes resizing a row.

Cell Selection​

NameTypeDefaultDescription
cellSelectionbooleantrueWhether cell selection (active cell, range selection, drag selection) is enabled. When false, clicking cells does not highlight them.

Row Selection​

NameTypeDefaultDescription
rowSelectionRowSelectionMode'none'Row selection mode: 'none', 'single', or 'multiple'. When enabled, a checkbox column is added.
selectedRowsSet<RowId>undefinedControlled set of selected row IDs.
onSelectionChange(event: IRowSelectionChangeEvent<T>) => voidundefinedCallback fired when row selection changes. The event contains selectedRowIds and selectedItems.

Status Bar​

NameTypeDefaultDescription
statusBarboolean | IStatusBarPropsfalseControls 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.
NameTypeDefaultDescription
sideBarboolean | ISideBarDefundefinedControls 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​

NameTypeDefaultDescription
columnChooserboolean | 'toolbar' | 'sidebar'trueWhere 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​

NameTypeDefaultDescription
columnReorderbooleanfalseEnable column reordering: drag a header, or use Move left / Move right in the header menu. See Column Reordering.

Virtual Scrolling​

NameTypeDefaultDescription
virtualScrollIVirtualScrollConfigundefinedVirtual scrolling configuration. See Virtual Scrolling and Types for IVirtualScrollConfig.

Layout​

NameTypeDefaultDescription
layoutMode'content' | 'fill''fill'How the grid sizes itself. 'content' sizes to fit content. 'fill' expands to fill its container.
suppressHorizontalScrollbooleanfalseWhen true, disables horizontal scrolling by setting overflow-x: hidden on the grid wrapper.
stickyHeaderbooleantrueWhen true, column headers stick to the top of the scroll container during vertical scrolling. Set to false to let headers scroll with data.
fullScreenbooleanfalseWhen 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.
isFullScreenbooleanundefinedControlled fullscreen state. Leave it unset to let the grid keep it. Works without fullScreen, for your own toggle.
onFullScreenChange(isFullScreen: boolean) => voidundefinedCalled when the toolbar button or Escape enters or leaves fullscreen. With isFullScreen set, update it here.
fullScreenShortcutstring | 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).
headerMenubooleanfalseSettings 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() => voidundefinedCalled after the corner menu's Reset columns restores default visibility, order and widths, e.g. to clear saved column state.
headerMenuItemsIGridMenuItem[] | (builtIns, { isFullScreen }) => IGridMenuItem[]undefinedItems for the corner menu: an array is added after the built-ins; a function returns the full list. Items with items open submenus.
columnMenuItemsIGridMenuItem[] | (builtIns, { columnId }) => IGridMenuItem[]undefinedItems for each column's menu (options button and header right-click), same shapes.
rowHeightnumber36Fixed 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.
showRowNumbersbooleanfalseShow Excel-style row number column (1, 2, 3...) at the start of the grid.
cellReferencesbooleanfalseExcel-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.
classNamestringundefinedAdditional CSS class name applied to the root grid element.
toolbarReactNodeundefinedCustom toolbar content rendered in the left side of the primary toolbar strip.
toolbarBelowReactNodeundefinedSecondary toolbar row rendered below the primary toolbar. Use for active filter chips, breadcrumbs, or other contextual controls.
entityLabelPluralstringundefinedPlural label for the entity type (e.g., "projects", "users"). Used in status bar text and empty state messages.
emptyState{ message?: ReactNode; render?: () => ReactNode }undefinedCustom empty state configuration. Provide message for a simple text override, or render for a fully custom empty state component.

Formulas​

NameTypeDefaultDescription
formulasbooleanfalseEnable Excel-like formulas. When on, cells starting with = are evaluated by the built-in formula engine.
initialFormulasArray<{ col: number; row: number; formula: string }>undefinedFormulas to load when the engine initializes.
onFormulaRecalc(result: IRecalcResult) => voidundefinedCalled when a recalculation updates cell values (e.g. a cascade from an edited cell).
formulaFunctionsRecord<string, IFormulaFunction>undefinedCustom functions to register with the formula engine.
namedRangesRecord<string, string>undefinedNamed ranges for formulas, mapping a name to a cell/range ref (e.g. { Revenue: 'A1:A10' }).
formulaLimitsIFormulaLimitsundefinedPer-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.
sheetsRecord<string, IGridDataAccessor>undefinedAccessors 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.

NameTypeDefaultDescription
sheetDefsISheetDef[]undefinedSheet definitions. When set, renders a bottom tab bar (the SheetTabs component).
activeSheetstringundefinedThe currently active sheet id.
onSheetChange(sheetId: string) => voidundefinedCalled when the user switches sheets.
onSheetAdd() => voidundefinedCalled when the user clicks the add-sheet button.
onSheetRename(sheetId: string, name: string) => voidundefinedEnables renaming: double-click a tab (or F2, or "Rename" in the tab menu).
onSheetReorder(sheetIds: string[]) => voidundefinedEnables reordering by dragging tabs (or "Move left/right" in the tab menu). Receives every sheet id in the new order.
onSheetDelete(sheetId: string) => voidundefinedAdds "Delete" to the tab menu (disabled for the last sheet).
onSheetColorChange(sheetId: string, color: string | undefined) => voidundefinedAdds tab colors and "No color" to the tab menu.

See Multi-Sheet.

Callbacks​

NameTypeDefaultDescription
onFirstDataRendered() => voidundefinedFired once when the grid first renders with data. Useful for restoring column state.
onColumnPinned(columnId: string, pinned: 'left' | 'right' | null) => voidundefinedFired when a column is pinned or unpinned.

Error Handling​

NameTypeDefaultDescription
onError(error: unknown) => voidundefinedCallback fired when the grid encounters an error (e.g., a failed server-side fetch).
onCellError(error: Error, errorInfo: React.ErrorInfo) => voidundefinedCallback fired when a cell renderer or custom editor throws an error.
onClipboardError(error: unknown) => voidundefinedCallback 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​

NameTypeDefaultDescription
aria-labelstringundefinedAccessible label for the grid. Use this or aria-labelledby, not both.
aria-labelledbystringundefinedID 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}
/>