OpenGridJs Documentation

Getting Started

OpenGridJs is a lightweight, zero-dependency JavaScript data grid with virtual scrolling. It only renders rows visible in the viewport, making it efficient for large datasets. Features include click-to-sort, column filtering, drag-and-drop column reordering, resizable columns, real-time record updates with animations, and CSV export.

Installation

Install via npm or include directly from a CDN:

# npm
npm install opengridjs

# CDN (add to your HTML)
<link rel="stylesheet" href="https://unpkg.com/opengridjs@latest/opengrid.min.css">
<script src="https://unpkg.com/opengridjs@latest/opengrid.min.js"></script>

Minimal Example

<div class="myGrid"></div>

<script>
  var data = [
    { id: 1, name: "Alice", email: "[email protected]", age: 28 },
    { id: 2, name: "Bob", email: "[email protected]", age: 34 }
  ];
  var grid = new OpenGrid("myGrid", data, 400);
</script>

That's it — a fully functional grid with automatic column detection, sorting, and filtering.

Browser Support

Chrome 60+, Firefox 55+, Safari 12+, Edge 79+, and modern mobile browsers.

Live Demo

This is a live OpenGridJs instance running on the page. Try clicking column headers to sort, using the search box to filter, or right-clicking a row.

Click column headers to sort. Right-click a row for the context menu. "Simulate Update" changes a random row's score with an animation.

Constructor

new OpenGrid(className, data, height, setup, loadMoreFunction)

Parameter	Type	Required	Description
`className`	string	Yes	CSS class name of the container element (without the leading dot)
`data`	Array \| Function	Yes	Initial data array, or an async function returning one
`height`	number	Yes	Grid height in pixels
`setup`	Object	No	Column config and context menu options
`loadMoreFunction`	Function	No	Called when user scrolls near the bottom (infinite scroll)

Column Configuration

Pass a setup object with columnHeaderNames to customize columns. If omitted, columns are auto-detected from the data.

var setup = {
  columnHeaderNames: [
    {
      columnName: "name",            // data property name
      columnNameDisplay: "Full Name", // header label
      columnWidth: "200px",          // CSS width (optional)
      autoresize: false              // opt out of auto-resize (optional)
    },
    {
      columnName: "score",
      columnNameDisplay: "Score",
      format: function(value) {      // custom cell formatter
        return value + " pts";
      }
    }
  ]
};

var grid = new OpenGrid("myGrid", data, 400, setup);

Column Options

Property	Type	Description
`columnName`	string	Data property name (required)
`columnNameDisplay`	string	Display header label
`columnWidth`	string	CSS width (e.g. `"200px"`, `"20%"`)
`autoresize`	boolean	Enable auto-resize (default: `true`)
`format`	Function	Custom cell formatter: `format(value) => string`

Columns can be reordered by dragging headers and resized by dragging the header edge.

Data Loading

Synchronous (Array)

Pass data as a plain array. Items without an id field get auto-generated GUIDs.

// "myGrid" matches <div class="myGrid">
var grid = new OpenGrid("myGrid", [
  { id: 1, name: "Alice", score: 95 },
  { id: 2, name: "Bob", score: 87 }
], 400);

Asynchronous (Function)

Pass an async function that returns an array. The grid shows a loading state while data is fetched.

async function loadData() {
  var response = await fetch('/api/users');
  return response.json();
}

var grid = new OpenGrid("myGrid", loadData, 400);

Replacing Data

Use updateData() to replace all data. Accepts an array or async function.

grid.updateData([
  { id: 3, name: "Charlie", score: 91 }
]);

Infinite Scrolling

Pass a loadMoreFunction as the fifth constructor argument. It's called automatically when the user scrolls near the bottom of the grid.

var currentPage = 1;

async function loadMore() {
  currentPage++;
  var response = await fetch('/api/users?page=' + currentPage);
  var newData = await response.json();
  grid.appendData(newData);
}

var grid = new OpenGrid("myGrid", loadData, 400, setup, loadMore);

Call grid.stopLoadingMoreData() when there are no more pages to load.

Sorting & Filtering

Click-to-Sort

Click any column header to sort ascending/descending. Sorting is built-in and requires no configuration.

Column Filters

Each column has a filter menu with checkboxes for unique values. Users click the filter icon in the column header to open it.

Global Search

Use searchFilter() to filter all rows by a search term across all columns:

// Filter rows containing "alice"
grid.searchFilter("alice");

// Clear all filters
grid.clearAllFilters();

Real-Time Updates

Update specific records by ID with animated visual feedback. Changed cells flash with color-coded highlights:

Green — numeric value increased
Red — numeric value decreased
Blue — non-numeric value changed

grid.updateRecordData(
  { id: 4, name: "Updated Name", score: 90 },
  {
    animate: true,            // default: true
    preservePosition: true,   // default: true (prevents row reordering)
    highlightDuration: 3000   // default: 2000 (ms)
  }
);

Options

Option	Default	Description
`animate`	`true`	Enable color-coded cell animations
`preservePosition`	`true`	Keep row in current position (don't re-sort)
`highlightDuration`	`2000`	Animation duration in milliseconds

Context Menus

Add a right-click context menu to rows via the setup object:

var setup = {
  contextMenuTitle: "Actions",
  contextMenuOptions: [
    {
      actionName: "Edit",
      actionFunctionName: "editRow",  // global function name
      className: "edit-action"
    },
    {
      actionName: "Delete",
      actionFunctionName: "deleteRow",
      className: "delete-action"
    }
  ]
};

// The global function receives the row data
function editRow(rowData) {
  console.log("Editing:", rowData);
}

function deleteRow(rowData) {
  console.log("Deleting:", rowData);
}

The built-in context menu also includes "Copy Row" functionality by default.

Methods Reference

Method	Description
`appendData(data)`	Add rows (array or async function)
`updateData(data)`	Replace all data (array or async function)
`updateRecordData(data, options)`	Update specific records by ID with animations
`rerender()`	Force a full re-render
`reset()`	Reset grid to initial state
`exportToCSV()`	Download all data as a CSV file
`searchFilter(term)`	Filter rows by search term across all columns
`clearAllFilters()`	Remove all active column filters
`autoResizeColumns()`	Recalculate column widths to fit content
`stopLoadingMoreData()`	Disable infinite scrolling

Source code and issues: github.com/amurgola/OpenGridJs

CSV Export

Export the current grid data (including any active filters) to a CSV file:

grid.exportToCSV();

This triggers a browser download of the data as a .csv file.

Styling & Theming

OpenGridJs uses CSS classes you can override for custom theming:

Class	Description
`.opengridjs-grid`	Grid container
`.opengridjs-grid-header`	Header row
`.opengridjs-grid-row`	Data rows

/* Example: dark theme override */
.opengridjs-grid {
  background: #0d1a30;
  color: #e2e8f0;
  border: 1px solid rgba(134, 249, 248, 0.12);
}

.opengridjs-grid-header {
  background: #111d35;
  border-bottom: 2px solid rgba(134, 249, 248, 0.25);
}

.opengridjs-grid-row:hover {
  background: rgba(134, 249, 248, 0.05);
}