Grid API

The IOGridApi ref gives you imperative control over the grid: set data, manage loading state, save and restore column state, control filters, and manage row selection -- all from outside the grid component.

Live Demo

Use the buttons to control the grid programmatically

Live

Try it in your framework

The demo above uses Radix UI for styling. To see this feature with your framework's design system (Fluent UI, Material UI, Vuetify, PrimeNG, etc.), click "Open in online demo" below the demo.

Quick Example

React

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

interface Row {
  id: number;
  name: string;
  department: string;
  salary: number;
}

function App() {
  const gridRef = useRef<IOGridApi<Row>>(null);

  const handleRefresh = async () => {
    gridRef.current?.setLoading(true);
    const data = await fetchEmployees();
    gridRef.current?.setRowData(data);
    gridRef.current?.setLoading(false);
  };

  return (
    <>
      <button onClick={handleRefresh}>Refresh</button>
      <OGrid
        ref={gridRef}
        columns={columns}
        data={initialData}
        getRowId={(r) => r.id}
      />
    </>
  );
}

Switching UI libraries

The OGrid component has the same props across all React UI packages. To switch, just change the import:

• Radix (lightweight, default): from '@alaarab/ogrid-react-radix'
• Fluent UI (Microsoft 365 / SPFx): from '@alaarab/ogrid-react-fluent' - wrap in <FluentProvider>
• Material UI (MUI v7): from '@alaarab/ogrid-react-material' - wrap in <ThemeProvider>

Angular

import { Component } from '@angular/core';
import { OGridComponent, type IOGridApi } from '@alaarab/ogrid-angular-material';

interface Row {
  id: number;
  name: string;
  department: string;
  salary: number;
}

@Component({
  standalone: true,
  imports: [OGridComponent],
  template: `
    <button (click)="handleRefresh()">Refresh</button>
    <ogrid [props]="gridProps" />
  `
})
export class GridComponent {
  gridProps = {
    columns: columns,
    data: initialData,
    getRowId: (r: Row) => r.id,
  };

  async handleRefresh() {
    // Use the grid API via ViewChild or service
    const data = await fetchEmployees();
    this.gridProps = { ...this.gridProps, data };
  }
}

Switching UI libraries

Same component API across Angular packages. To switch, just change the import:

• Radix (CDK): from '@alaarab/ogrid-angular-radix' (default, lightweight)
• Angular Material: from '@alaarab/ogrid-angular-material'
• PrimeNG: from '@alaarab/ogrid-angular-primeng'

All components are standalone - no NgModule required.

Vue

<script setup lang="ts">
import { ref } from 'vue';
import { OGrid } from '@alaarab/ogrid-vue-vuetify';

interface Row {
  id: number;
  name: string;
  department: string;
  salary: number;
}

const data = ref<Row[]>(initialData);

const gridProps = {
  columns,
  data: data.value,
  getRowId: (r: Row) => r.id,
};

async function handleRefresh() {
  const fresh = await fetchEmployees();
  data.value = fresh;
}
</script>

<template>
  <button @click="handleRefresh">Refresh</button>
  <OGrid :gridProps="gridProps" />
</template>

Switching UI libraries

Same component API across Vue packages. To switch, just change the import:

• Radix (Headless UI): from '@alaarab/ogrid-vue-radix' (default, lightweight)
• Vuetify: from '@alaarab/ogrid-vue-vuetify' - wrap in <v-app> for theming
• PrimeVue: from '@alaarab/ogrid-vue-primevue'

Vanilla JS

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

const grid = new OGrid(document.getElementById('grid'), {
  columns: columns,
  data: initialData,
  getRowId: (r) => r.id,
});

// Use the grid API directly
async function handleRefresh() {
  grid.api.setLoading(true);
  const data = await fetchEmployees();
  grid.api.setRowData(data);
  grid.api.setLoading(false);
}

How It Works

Pass a ref to the OGrid component. The ref exposes the IOGridApi<T> interface with methods for programmatic grid control.

API Methods

Method	Signature	Description
setRowData	(data: T[]) => void	Replace all row data (client-side only; no-op with dataSource)
setLoading	(loading: boolean) => void	Show or hide the loading overlay
getDisplayedRows	() => T[]	Get the currently displayed (filtered, sorted, paginated) rows
refreshData	() => void	Re-trigger a data fetch (server-side only; no-op for client-side)
getColumnState	() => IGridColumnState	Get current column visibility, sort, order, widths, and 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	Programmatically set the column display order
setFilterModel	(filters: IFilters) => void	Set the active filter model
clearFilters	() => void	Clear all active filters
clearSort	() => void	Reset the sort to no active sort
resetGridState	(options?: { keepSelection?: boolean }) => void	Reset all grid state (filters, sort, and optionally selection)
getSelectedRows	() => RowId[]	Get the IDs of currently selected rows
setSelectedRows	(rowIds: RowId[]) => void	Set which rows are selected
selectAll	() => void	Select all rows
deselectAll	() => void	Deselect all rows
scrollToRow	(index: number, options?: { align?: 'start' | 'center' | 'end' }) => void	Scroll to a row by index (virtual scrolling only)

Save and Restore Column State

getColumnState() returns an IGridColumnState object that is fully JSON-serializable. Store it in localStorage, a database, or a URL parameter, and restore it later with applyColumnState().

// Save to localStorage
const handleSave = () => {
  const state = gridRef.current?.getColumnState();
  if (state) {
    localStorage.setItem('grid-state', JSON.stringify(state));
  }
};

// Restore from localStorage
const handleRestore = () => {
  const saved = localStorage.getItem('grid-state');
  if (saved) {
    gridRef.current?.applyColumnState(JSON.parse(saved));
  }
};

IGridColumnState Fields

interface IGridColumnState {
  visibleColumns: string[];
  sort?: { field: string; direction: 'asc' | 'desc' };
  columnOrder?: string[];
  columnWidths?: Record<string, number>;
  filters?: IFilters;
  pinnedColumns?: Record<string, 'left' | 'right'>;
}

Field	Description
visibleColumns	Array of visible column IDs
sort	Active sort column and direction
columnOrder	Column display order (array of column IDs)
columnWidths	Column width overrides in pixels
filters	Active filter values by field
pinnedColumns	Pinned column positions by column ID

All fields in applyColumnState are optional. Pass only what you want to restore.

// Restore only sort and filters, leave visibility and widths unchanged
gridRef.current?.applyColumnState({
  sort: { field: 'salary', direction: 'desc' },
  filters: { department: { type: 'multiSelect', value: ['Engineering'] } },
});

Programmatic Filtering

Use setFilterModel to apply filters from outside the grid.

gridRef.current?.setFilterModel({
  department: { type: 'multiSelect', value: ['Engineering', 'Design'] },
  name: { type: 'text', value: 'John' },
});

Filter values use the FilterValue discriminated union type:

• { type: 'text', value: string } for text filters
• { type: 'multiSelect', value: string[] } for multi-select filters
• { type: 'people', value: UserLike } for people filters
• { type: 'date', value: IDateFilterValue } for date range filters

Row Selection Control

// Select specific rows
gridRef.current?.setSelectedRows([1, 5, 12]);

// Get current selection
const selected = gridRef.current?.getSelectedRows(); // [1, 5, 12]

// Select all / deselect all
gridRef.current?.selectAll();
gridRef.current?.deselectAll();

Updating Data

For client-side grids, use setRowData to replace the data without re-mounting the component.

const refreshData = async () => {
  gridRef.current?.setLoading(true);
  const fresh = await fetch('/api/employees').then((r) => r.json());
  gridRef.current?.setRowData(fresh);
  gridRef.current?.setLoading(false);
};

Props Reference

Type	Field	Description
OGrid	ref	React.Ref<IOGridApi<T>>
IOGridProps<T>	onColumnResized	(columnId: string, width: number) => void -- notified on user column resize

Related

• Column Chooser -- the Column Chooser modifies the same visibility state accessible via getColumnState
• Server-Side Data -- setFilterModel triggers a re-fetch in server-side mode
• Status Bar -- reflects the state managed by the API
• CSV Export -- combine with getColumnState to export only visible columns