Vanilla JS API

Complete reference for @alaarab/ogrid-js - the framework-free data grid.

OGrid Class

import { OGrid } from '@alaarab/ogrid-js';
import '@alaarab/ogrid-js/styles'; // optional default theme

const grid = new OGrid(container, options);

Constructor

Parameter	Type	Description
container	HTMLElement	DOM element to render into. OGrid fills this container.
options	OGridOptions<T>	Configuration object (see below).

Instance Methods

Method	Description
grid.api	The imperative API object (see API Methods below).
grid.on(event, handler)	Subscribe to a grid event. Returns void.
grid.off(event, handler)	Unsubscribe from a grid event.
grid.destroy()	Tear down the grid - removes DOM, listeners, and ResizeObservers.

---

OGridOptions<T>

All configuration is passed to the constructor.

Data

Option	Type	Default	Description
columns	(IColumnDef<T> | IColumnGroupDef<T>)[]	required	Column definitions.
getRowId	(item: T) => RowId	required	Returns a unique string | number per row.
data	T[]	-	Client-side data. Mutually exclusive with dataSource.
dataSource	IDataSource<T>	-	Server-side data source. Mutually exclusive with data.

Pagination & Sorting

Option	Type	Default	Description
page	number	1	Initial page (1-based).
pageSize	number	20	Rows per page.
sort	{ field: string; direction: 'asc' | 'desc' }	-	Initial sort state.
filters	IFilters	-	Initial filter state.

Interaction

Option	Type	Default	Description
editable	boolean	false	Enable inline cell editing.
cellSelection	boolean	false	Enable spreadsheet-style cell/range selection.
rowSelection	'single' | 'multiple'	-	Row checkbox selection mode.
selectedRows	Set<RowId>	-	Controlled selected row IDs.
pinnedColumns	Record<string, 'left' | 'right'>	-	Pin columns to left/right edges.
visibleColumns	Set<string>	all	Initially visible column IDs.

Layout

Option	Type	Default	Description
layoutMode	'fill' | 'content'	'fill'	'fill' stretches to container; 'content' sizes to data.
suppressHorizontalScroll	boolean	false	Prevent horizontal scrollbar.
sideBar	boolean | ISideBarDef	-	Show sidebar with columns/filters panels.
emptyMessage	string	'No data'	Custom empty state text.
aria-label	string	-	Accessible label for the grid.

Callbacks

Option	Type	Description
onCellValueChanged	(event: ICellValueChangedEvent<T>) => void	Fired when a cell edit is committed.
onSelectionChange	(event: IRowSelectionChangeEvent<T>) => void	Fired when row selection changes.
onError	(error: unknown) => void	Fired on server-side data source failures.
onFirstDataRendered	() => void	Fired once when the first data render completes.

---

API Methods

Access via grid.api:

Data

Method	Signature	Description
setRowData	(data: T[]) => void	Replace the entire dataset (client-side only; no-op with dataSource).
setLoading	(loading: boolean) => void	Show or hide the loading overlay.
getDisplayedRows	() => T[]	Get the currently visible (filtered, sorted, paginated) rows.
refreshData	() => void	Re-fetch from dataSource (server-side only).

Sorting & Filtering

Method	Signature	Description
setFilterModel	(filters: IFilters) => void	Set the full filter model. Pass {} to clear all filters.
clearFilters	() => void	Clear all active filters. Shorthand for setFilterModel({}).
clearSort	() => void	Reset the sort to no active sort.
resetGridState	(options?: { keepSelection?: boolean }) => void	Reset all grid state (filters, sort, and optionally selection).

Columns

Method	Signature	Description
getColumnState	() => IGridColumnState	Get current column state (visibility, sort, order, widths, filters).
applyColumnState	(state: Partial<IGridColumnState>) => void	Bulk-restore any combination of column state fields.
getColumnOrder	() => string[]	Get the current column display order (array of column IDs).
setColumnOrder	(order: string[]) => void	Set the column display order programmatically.

Selection

Method	Signature	Description
selectAll	() => void	Select all rows (requires rowSelection: 'multiple').
deselectAll	() => void	Deselect all rows.
getSelectedRows	() => RowId[]	Get the IDs of currently selected rows.
setSelectedRows	(rowIds: RowId[]) => void	Set which rows are selected by their IDs.

Export

Method	Signature	Description
exportToCsv	(filename?: string) => void	Export displayed rows to CSV and trigger a browser download.

Virtual Scrolling

Method	Signature	Description
scrollToRow	(index: number, options?: { align?: 'start' | 'center' | 'end' }) => void	Scroll to a specific row by index. Only effective when virtual scrolling is enabled.

---

Events

Subscribe with grid.on(eventName, handler).

Event	Payload Type	Fired When
cellValueChanged	ICellValueChangedEvent<T>	A cell edit is committed
selectionChange	IRowSelectionChangeEvent<T>	Row selection changes
sortChange	{ sort: { field: string; direction: 'asc' | 'desc' } | undefined }	Sort state changes
filterChange	{ filters: IFilters }	Filter state changes
pageChange	{ page: number }	Current page changes

ICellValueChangedEvent<T>

{
  item: T;           // The row data object
  columnId: string;  // Which column was edited
  oldValue: unknown; // Previous cell value
  newValue: unknown; // New cell value
  rowIndex: number;  // Row index of the edited cell
}

---

IColumnDef<T> (JS-specific)

The JS package extends the core IColumnDef<T> with DOM-aware fields:

Field	Type	Description
renderCell	(cell: HTMLTableCellElement, item: T, value: unknown) => void	Custom cell renderer - mutate the <td> DOM directly.
cellStyle	Partial<CSSStyleDeclaration>	Inline styles applied to each cell.
cellEditor	string | (container: HTMLElement, params: object) => { getValue: () => unknown; destroy: () => void }	Built-in editor name ('text', 'select', 'richSelect', 'checkbox', 'date') or a factory function for custom editors.

All other IColumnDef fields (columnId, name, sortable, filterable, type, editable, valueFormatter, valueGetter, valueParser, minWidth, defaultWidth, idealWidth, pinned, required, defaultVisible) follow the shared column-definition contract used across the framework packages. See Column Definitions.

---

CSS Classes

The JS package renders semantic HTML with ogrid-* class names. Import the default theme or write your own CSS targeting these selectors:

Layout

ogrid-container, ogrid-toolbar, ogrid-body-area, ogrid-table-container, ogrid-sidebar-container, ogrid-status-bar-container, ogrid-pagination-container

Table

ogrid-wrapper, ogrid-table, ogrid-header-cell, ogrid-group-header, ogrid-sortable, ogrid-sort-indicator, ogrid-resize-handle, ogrid-filter-icon, ogrid-row, ogrid-cell, ogrid-checkbox-header, ogrid-checkbox-cell, ogrid-fill-handle, ogrid-empty-state

Data Attributes

[data-active-cell], [data-in-range], [data-drag-range], [data-row-selected], [data-pinned="left|right"], [data-column-id], [data-row-index], [data-col-index]

CSS Variables

Override --ogrid-bg, --ogrid-fg, --ogrid-border, --ogrid-primary, --ogrid-selection, --ogrid-bg-subtle, --ogrid-bg-hover, --ogrid-muted, and more. See Theming.