DEV Community: AG Grid

Optimising Large Data Set Visualisations with the M4 Algorithm

James Swinton-Bland — Tue, 14 Jan 2025 15:28:31 +0000

Version 11 of AG Charts, our JavaScript Charting Library, includes significant performance enhancements to our Line Series. These improvements allow you to render over a million data points that can be zoomed, panned, and interacted with at over 60 fps, making these transitions appear seamless to users.

To achieve this level of performance, we implemented the M4 algorithm: an aggregation-based time series dimensionality reduction technique that provides error-free visualizations at high data reduction rates. This blog post details our implementation of this algorithm and the performance improvements we've gained from it.

Challenges in Rendering Large Datasets

AG Charts leverages the HTML5 Canvas API for its drawing operations. We've discussed some of the techniques we apply to optimize HTML5 Canvas rendering in a previous blog post, however, no matter what optimisations are applied, rendering a million data points in a chart is computationally intensive.

If you're not already familiar with the Canvas API, drawing lines is akin to instructing a virtual pen: you issue one command to place the pen nib at specific coordinates on the screen, and another command to move the nib to a different set of coordinates, which then draws a line between the two points. This means that as the size of our data grows, so does the number of drawing operations required, which means more work for us to do.

Introducing the M4 Algorithm

Given the way the Canvas API works, the only way to reduce the work needed to draw a chart is to physically draw less, which is where the M4 algorithm comes in. According to the original paper, the M4 algorithm "exploits the semantics of line rasterization to drive the data reduction of high-volume time series data." In other words, this approach allows us to reduce the number of drawing operations required to render a line chart, whilst retaining its original characteristics.

How the M4 Algorithm Works

This algorithm might sound complicated, but it's actually quite simple. Consider the following line chart, which contains 100 data points:

To apply the M4 algorithm, start by determining the range of your x-values. For instance, if your x-data ranges from 100 to 200, you might divide this range into 10 equal buckets: 100–110, 110–120, and so on. In this case, we've divided our example into 5 buckets:

Next, for each bucket, identify the data points that meet the following criteria:

Minimum x-value
Maximum x-value
Minimum y-value
Maximum y-value

Because a data point may fit more than one criterion, each bucket will have up to four points. These have been highlighted in each bucket below:

Finally, connect the selected data points with lines to draw the simplified Line Series:

And that's it... by applying the M4 algorithm we've reduced the number of drawing operations required from 100 to 18.

We purposefully made our buckets large in this example to illustrate how the algorithm works. To make this optimised chart appear almost indistinguishable from if the algorithm had never been applied, you’ll want your number of buckets set so that each bucket is around a pixel wide.

For example, if you're rendering a chart that's 500 pixels wide and contains one million data points, you would divide the data into 500 buckets - one bucket per pixel. Each bucket would contain 2,000 data points (since 1,000,000 divided by 500 equals 2,000). In this example, applying the M4 algorithm reduces each bucket to a maximum of four points, meaning you'd end up with up to 2,000 points in total (500 buckets × 4 points), which is just 0.2% of the original data.

Optimizing for Interactivity

When implementing this algorithm the first problem we encountered was that iterating over a million points is slow. To achieve 60fps performance we need to render each frame in around 16ms, however, our most optimised implementation took around 100ms to complete, which made features like Zoom feel sluggish.

To fix this, we can pre-compute the M4 algorithm at different zoom levels, much like Google Maps does as you zoom out from a small street to a city. This works by starting with of snapshot of the highest detail you have available, and then gradually reducing the level of detail to generate additional snapshots until there is no value in reducing it further.

For the M4 algorithm, we employ a clever technique to accelerate detail reduction. Instead of processing the original dataset at each level of detail, we utilize the results from a previous run by combining each adjacent pair of buckets, effectively halving the number of buckets.

Below is an illustration of our example after merging the buckets:

This approach allows us to reuse the already filtered data, rather than starting from scratch with the entire dataset. When dealing with a dataset of one million points, reducing the filtered data to just a few thousand points makes a huge difference. As an added bonus, each time this step is repeated, it will take less time than the previous run.

Results

As you can see from the chart below, these optimizations have the biggest impact on large datasets:

Try It Out

Test the performance by yourself by selecting a large data set and zooming / scrolling in our live demo.

Conclusion

By implementing the M4 algorithm and optimizing data processing, AG Charts 11 delivers high-performance rendering of large Line Series datasets. These enhancements enable you to create interactive charts that remain fast & responsive, even with millions of data points.

If you've made it this far, you may be interested in some of our other performance-related blogs, that discuss a range of other optimisations we've made to AG Charts to make it The Best JavaScript Charting Library In The World:

Want to add high-performance JavaScript Charts to your application? Get started today, for free:

Get Started

Building AG Charts: Efficient JavaScript Charting with Tree-Based Scene Graphs

James Swinton-Bland — Thu, 26 Sep 2024 09:33:32 +0000

AG Charts is a high-performance, canvas-based JavaScript charting library, designed for creating complex and interactive JavaScript charts. Initially built to power Integrated Charts in AG Grid (our React Data Table library), it now stands alone with over 1 million npm downloads per month.

In this post, we’ll explore how AG Charts leverages a tree-based scene graph abstraction to efficiently render complex JavaScript charts, offering a powerful solution for developers building data visualizations in JavaScript, React, Angular and Vue.

Challenges in JavaScript Charting with HTML Canvas

Rendering graphics on the web can be a double-edged sword. While the HTML Canvas API provides a solid platform for drawing complex shapes and images, it comes with performance considerations, such as:

Rendering Overhead : Canvas operations involve manipulating the pixels of a bitmap, which means that drawing, compositing, and transformations require direct interaction with the GPU or software rendering pipeline.
Browser API Overhead : Each canvas API call incurs a certain amount of overhead due to interaction with the browser's rendering engine.
Repainting and Redrawing : When you draw on a canvas, the entire pixel area being modified has to be recalculated and redrawn, especially for complex shapes or animations.
Single-threaded Execution : JavaScript and canvas rendering both run on the main thread. Intensive canvas operations can block the main thread, leading to slower response times and reduced performance for other JavaScript tasks.
Lack of Hardware Acceleration in Some Cases : While some canvas operations can be hardware accelerated, not all operations benefit from it. This inconsistency can lead to performance bottlenecks, especially with complex or frequent drawing operations.

Given this, we needed a solution that would allow us to work with the canvas as efficiently as possible.

_Enter the scene graph. _

What is a Scene Graph?

A tree-based scene graph is a hierarchical data structure used in computer graphics to represent the spatial and logical relationships between objects in a scene. Each node in the tree corresponds to an object or entity in the scene, and the parent-child relationships between nodes define transformations such as translation, rotation, and scaling relative to their parents.

In AG Charts, the scene graph is an abstraction layer over the HTML Canvas, providing a higher-level API for constructing and manipulating chart elements, such as markers, lines, circles and shapes. The scene graph also provides a layer where we can perform caching and optimise canvas rendering, negating some of the aforementioned performance considerations.

Why a Scene Graph is Essential for JavaScript Chart Libraries

Higher-Order Abstraction for Rendering: The scene graph in AG Charts was designed to simplify the low-level drawing operations required by the Canvas API. Instead of working directly with pixels, chart renderings could work with higher-order constructs like markers, lines, circles, and shapes.
Caching and Optimization: One key advantage of the scene graph is its ability to cache and optimize canvas rendering. Since canvas operations are typically slower than JavaScript operations, caching results and minimizing redraws are essential for maintaining performance.
Support for Matrix Transformations: Initially, we added support for matrix transformations on the base node class of all scene graph nodes, which includes rotation, scaling and translation operations.
Coordinate Conversion Utilities: We also implemented methods for converting points and boxes to and from canvas coordinates. These utilities were used liberally throughout our codebase to manage positioning and layout tasks.

How the Scene Graph Was Implemented in AG Charts

Our scene graph consists of nodes representing different chart elements, with a base node class that includes properties for positioning, styling, and rendering. Each node type—whether a line, shape, or marker—inherits from this base class and implements its own rendering logic.

The base node class also includes support for matrix transformations. Matrix transformations are mathematical operations used to manipulate the position, scale, and rotation of objects within a 2D space. These transformations are represented as matrices, which, when applied to points or objects, alter their geometric properties. The main types of transformations are:

Translation : Shifts an object from one position to another.
Scaling : Changes the size of an object either uniformly or non-uniformly.
Rotation : Rotates an object around a specific point or axis.

In a scene graph, these transformations are applied hierarchically. Each node in the graph represents an object or a group of objects and holds its transformation matrix. The final transformation of a child node is the result of its own transformation combined with the transformations of all its parent nodes.

In addition to matrix transformations, we also added methods to convert to/from canvas coordinates for points and boxes, which were liberally used around the codebase.

Continuous Improvement of AG Charts JavaScript Charts

Whilst our initial implementation of the scene graph provided many benefits, as AG Charts continues to evolve we've noticed areas for further improvement, namely:

Overhead from Matrix Transformations: Although matrix transformations were supported by default, they were unnecessary for most rendering tasks. In practice, 95% of our scene graph nodes do not require these transformations, leading to unnecessary computational overhead.
Complexity in Coordinate Conversions: The frequent use of coordinate conversion methods added complexity to the codebase, making it harder to maintain and optimize.
Performance Bottlenecks: As our library grew, we noticed that matrix transformations were consuming a non-trivial amount of execution time, even for nodes where these transformations were not needed.

Our Approach to Optimizing the Scene Graph

To address these challenges, we implemented a series of changes aimed at simplifying the scene graph and reducing performance overhead:

Selective Application of Matrix Transformations: We removed all matrix support from the existing scene graph nodes and added mixin classes. This allowed us to selectively re-add matrix transforms to the specific parts of the codebase where they were still needed.
Simplifying Coordinate Transformations: We refactored the base scene-graph nodes by replacing methods that returned canvas coordinates with helper functions using local coordinates, reducing costly matrix operations.
Improving Hit-Testing Performance: We streamlined hit testing (determining whether a mouse or touch event intersects with a specific object drawn on the canvas) by converting to local coordinates upfront and applying transforms as we traverse the scene graph, avoiding the need for continuous coordinate conversions.
Refactoring and Cleanup: As a result of these simplifications and improvements, we were able to generally refactor and clean up redundant operations throughout our codebase, reducing our overall tech debt, and thereby improving maintainability as well as performance.

Key Pull Requests and Changes

These optimizations were implemented across several pull requests. Given AG Charts is entirely open-source, you can dig into these PRs:

Results and Performance Gains

These changes have led to several positive outcomes:

Reduced Overhead from Unnecessary Matrix Transforms: Matrix transformations are now only applied where needed, mostly in rendering leaf nodes of the scene graph, reducing unnecessary computational costs.
Faster Hit-Testing and Rendering: Hit-testing operations are now cheaper and faster, thanks to optimized coordinate handling.
Performance Improvements in Benchmarks: Internal benchmarking shows notable performance gains in large-scale use cases, demonstrating the effectiveness of these optimizations:

bbox caching introduced in b10.1 & Matrix transformations removed in latest (b10.2)

Conclusion

By refining our use of matrix transformations and optimizing the scene graph, we've significantly improved the performance of AG Charts. These changes are now part of the latest (10.2) release, and we're excited to see how they enhance your charting experience. Stay tuned for more updates as we continue to innovate and improve AG Charts!

Want to build JavaScript charts with AG Charts? Get Started today by visiting our documentation:

Get Started with AG Charts JavaScript Charting Library

Introducing AG Charts Enterprise

James Swinton-Bland — Tue, 05 Dec 2023 11:37:40 +0000

Introduction

AG Charts is an open-source JavaScript charting and graphing library from the makers of AG Grid built for React, Angular and Vue. Last week saw the release of AG Charts 9, and, most notably, the introduction of AG Charts Enterprise.

Read on to learn a bit more about the background of AG Charts, how we arrived where we are today, and what you can expect from our brand-new enterprise product 👇

History of AG Charts

AG Charts was built by the AG Grid team in 2019 as a way to power integrated charts in AG Grid - a feature that lets users build charts directly from AG Grid. Sticking to our roots as an open-source company, we released AG Charts as a completely free and stand-alone open-source library. We knew that we had built a great library in its own right, so why not share it? Since then, AG Charts has steadily grown in popularity, now amassing over 300,000 NPM downloads/month (as of 04/12/2023). With this rise in popularity, we decided it was time to invest further in AG Charts which has now culminated in the release of AG Charts 9 and the introduction of AG Charts Enterprise.

Why AG Charts?

At this point, you may be thinking: "Why another charting library?" or "Why should I use AG Charts?". Our response would be that AG Charts comes with the same performance and reliability our users have come to expect of AG Grid. This reputation, and the subsequent trust we've earned with grid developers, has consistently separated us from our competition. We're confident we can earn that same reputation and trust from Charts developers, too.

Enterprise vs. Community

The obvious next question is, what's the difference between the Enterprise and Community versions of AG Charts? Well, in a nutshell:

AG Charts Community is the original version of AG Charts that is designed to meet most use cases and is free forever.
AG Charts Enterprise is an advanced version of AG Charts, with more series types, features, and dedicated Zendesk support, designed for enterprise use cases and customers.

Let's take a closer look at the series types & features available in AG Charts Enterprise:

Enterprise Series Types

AG Charts Enterprise comes with 13 additional series types - Box Plot, Bullet, Heatmap, Range Area, Range Bar, Radar Area, Radar Line, Radial Bar, Radial Column, Nightingale, Sunburst, Treemap, Waterfall:

See the gallery for a full list of series types & examples.

Enterprise Features

In addition to enhanced series types, AG Charts Enterprise also comes with a range of new features:

Animation of the graph or chart on load or update
Context Menu for additional actions, such as zooming, downloading or whatever else your users may need
Crosshairs for precise analysis of complex graphs
Zoom into and out of data
Error Bars for showing confidence intervals within data
Background Images to brand and style the chart

Check out the animation below that demonstrates some of these features:

0:00
/0:12
1×

Framework Support

AG Charts Community and Enterprise have both been built specifically for React, Angular, and Vue meaning you can build React Charts as easily as you can build JavaScript charts. These aren't just wrappers, either; we've built the library specifically for these frameworks.

Testing and Upgrading

It's free to try out AG Charts Enterprise and you do not need to contact us at all; we just ask that you don't use AG Charts Enterprise in a project intended for production without a licence.

When testing without a valid license key installed, your console log will will show a watermark for 5 seconds and display a series of warnings:

If you would like to remove this watermark or access support via Zendesk, you will need a trial license. Please email info@ag-grid.com to request a trial license key.

Pricing

AG Charts Enterprise pricing at $399 / developer, but there is a limited-time launch price of $199 / developer. Check out the pricing page for more information.

TL;DR

AG Charts was built in 2019 by the AG Grid team to power Integrated Charting within AG Grid.
Sticking to our roots, we released AG Charts as a free, standalone, open-source library.
AG Charts proved to be popular with the community, so we decided to release an Enterprise version in December 2023 with new features, series types and dedicated support.
AG Charts Enterprise requires a license and AG Charts Community will remain free forever
You can trial AG Charts Enterprise for free - it just displays a watermark and a console warning.

Ready to try it out? Get started with AG Charts Enterprise now 👇

Get Started

Introducing the AG Grid Figma Design System

James Swinton-Bland — Tue, 22 Aug 2023 09:01:29 +0000

Intro

If you're a designer working with AG grid it's time to get very excited! With AG Grid version 30.1.0 we've released our new Figma Design System.

If you want to skip the preamble and dig into the design system yourself you can download it directly from our design system documentation page.

Everything you need to design with AG Grid

The new design system implements our Alpine and Alpine Dark themes in Figma. All of the core AG Grid components are fully built out and ready to use, with even more components arriving in future releases. Each component has been carefully crafted to precisely mirror what's available in the AG Grid library.

Make it your own...

And when you're ready to make AG Grid your own we've got you covered. The Alpine and Alpine Dark themes can be extended to create custom AG Grid themes that work with your brand. We even provide a sample style dictionary project so you can export your bespoke themes to json and quickly create custom AG Grid CSS themes.

To learn more about the design system and thow it can help your design workflow watch this short video on Youtube.

Get designing now

Once you're ready to get started with the Figma design system checkout our design system documentation page to download the design system and start creating with AG Grid.

Use AG Grid with Observables as cell values

Stephen Cooper — Thu, 05 Jan 2023 10:23:23 +0000

In this guest post by Nicolas Gehlert, origianlly published here, learn a clean approach to working with Observable data in Angular.

Many thanks again to our user Nicolas for sharing his findings with us!

AG Grid does support observables as data input, but only one dimensional. If you have an observable that contains other observables the values cannot be displayed.

In this post I want to show you scenarios where this might be useful and how you can display those values properly with a loading indicator.

Introduction
Example
Custom cell renderer
Loading overlay
Sorting
Clipboard
CSV export
Excel export
Pitfalls

Introduction

Let me start of by saying, I'm aware that AG Grid is perfectly capable to handle (one dimensional) observables and for all the basic examples out there you probably don't need the approach that is described here.This is useful if you fetch data from different endpoints and they vastly differ in either the purpose or the loading duration.

One real life example where I used this a lot is if you fetch base data of business objects from one endpoint. Those are properties like name and description. But from another endpoint you fetch some reporting information. The latter is drastically slower in performance and usually takes more than 5 seconds.

The idea is to already display the information that is quickly available, while showing a loading indicator for the information that takes longer to fetch.

In this post I will take the very common AG Grid example with car information and simulate a loading for the car costs.

Example

I'm going to reference this in the very beginning. Everything described in this post can be found in action in this
stackblitz or this
GitHub repo.

But it probably still makes sense to check each chapter step by step to follow the thought process.

Base setup

In my example I will use Angular as a framework. But the concept works equally well for others like react or vue. Our base column definition is going to look like this:

class AppComponent {
  public columnDefs: Array<ColDef<ITableEntry>> = [
    {colId: 'car.model', field: 'car.model'},
    {colId: 'car.make', field: 'car.make'},
    {colId: 'price', field: 'pricingData'},
  ];
}

interface ITableEntry {
  car: {
    model: string;
    make: string;
  },
  pricingData?: Observable<number>;
}

Custom cell renderer

When we provide some data to our grid that follows the interface from above we will get the following result.

The result is actually expected, because AG Grid tries to display a string representation of the given object in the DOM and is not actually trying to resolve this observable.

We are going to create a custom cell renderer component that does this for us.

@Component({
    selector: 'grid-text-renderer',
    template: '<span>{{value|async}}</span>',
    changeDetection: ChangeDetectionStrategy.OnPush,
})
class AgGridTextCellRendererComponent implements ICellRendererAngularComp {
    public value: Observable<string> = of('');
    private params!: ICellRendererParams;

    public agInit(params: ICellRendererParams): void {
        this.params = params;
        this.value = params.value;
    }

    public refresh(params: ICellRendererParams): boolean {
        this.agInit(params);

        return true;
    }
}

The interesting part here is the public value property to render the value in the template. The params assignment and the refresh implementation are just my defaults to be consistent and performant for all custom cell renderer components.

The parameter params: ICellRendererParams will get the cell value as defined in our column definition by the field property. You can also use a valueGetter to return an observable. However things like valueFormatter won't work. If you need a custom format you need to implement it in your cell renderer component. You can also use cellRendererParams on the column definition to pass additional properties or values to your component.

As a last step we need to define in our column definition to actually use this component.

{
  colId: 'price', 
  field: 'pricingData', 
  cellRenderer: AgGridTextCellRendererComponent,
}

For more information on custom cell renderers check out the AG Grid docs

Now our result should look something like this:

As you can see the observables are properly resolved and the real number value is being displayed.

Loading overlay

We want to display a loading indicator to show to the user that the value for the cell is currently being loaded and he just needs to wait. There are different approaches how you can do this. You can extend the custom cell renderer we build in the previous step, and add a loading overlay that you trigger with *ngIf and hide it once the observable is resolved. But keep in mind, if you build multiple custom cell renderer for different observable purposes you need to implement this behavior in all of them.

Let me show you another AG Grid feature that is really awesome and pretty much made for cases like this. I'm talking about cellClassRules on the column definition (see docs).

The base idea is that you can add/remove classes to each cell depending on the result of a function. For easier maintainability I've added this to the defaultColDef in my gridOptions so I don't have to redefine it for every column where I need this, but it is just automatically available. You can also add it to the regular column definition if you prefer.

Now let's talk code.

import { first, forkJoin, isObservable, Observable } from 'rxjs';

public getDefaultColumnDefinition(_isServerSideRowModel: boolean = false): ColDef {
  const loadingStateByEntry: Map<unknown, boolean> = new Map<unknown, boolean>();
  const updateTableState: (params: CellClassParams) => void = (params: CellClassParams): void => {
    loadingStateByEntry.set(params.value, false);
    setTimeout(() => {
      params.api.refreshCells({
        suppressFlash: true,
        rowNodes: [params.node],
        columns: [params.column],
      });
    });
  };

  return {
    cellClassRules: {
      'grid-table-cell-loading': (params: CellClassParams): boolean => {
        const mapEntry: boolean | undefined = loadingStateByEntry.get(params.value);
        if (mapEntry !== undefined) {
          return mapEntry;
        }

        // Handle observables
        if (isObservable(params.value)) {
          loadingStateByEntry.set(params.value, true);
          params.value.pipe(first()).subscribe({
            next: (): void => updateTableState(params),
            error: (): void => updateTableState(params),
          });

          return true;
        }

        return false;
      },
    },
  };
}

We create a map loadingStateByEntry that represents the current loading state and whether an observable is already resolved or not. We use the reference of the observable as key and the loading state true|false as value. The benefit of using the reference here, is if multiple rows share the same observable reference it is only added once.

The updateTableState function is used to update the table state and re-trigger the cellClassRules evaluation. Everything from the observable happens outside of any ngZone or grid change detection. The loading state is set to false in our map and with the grid api we refresh our current cell.

The key 'grid-table-cell-loading'in the cellClassRules object is a css class name that will be added to the cell itself whenever the function provided as value is returning true.

First we need to check whether there is already an loading entry for our observable reference. Afterwards an isObservable check to ensure
we only trigger the next code if it is really an observable.

Now we can just subscribe to the observable - we are using the first() pipe to immediately unsubscribe and not create any memory leaks -
and call our updateTableState function.

Last but not least we need to add a global style. In my case I'm just using a simple circle that spins around, but feel free to change it to a bar,
hourglass or something more fancy.

.grid-table-cell-loading::after {
  content: '';
  box-sizing: border-box;
  position: absolute;
  top: 50%;
  left: 50%;
  width: 20px;
  height: 20px;
  margin-top: -10px;
  margin-left: -10px;
  border-radius: 50%;
  border: 2px solid transparent;
  border-top-color: cornflowerblue;
  border-right-color: cornflowerblue;
  animation: spinner 1s linear infinite;
}
.grid-table-cell-loading::before {
  background: transparent;
  content: '';
  position: absolute;
  width: 100%;
  height: 100%;
  left: 0;
}

@keyframes spinner {
  to {transform: rotate(360deg);}
}

And now we should see a beautiful loading indicator while the observable is still loading and as soon as a value is resolved
the loading indicator will disappear.

Tip: If you want to use a different spinner style or want to adjust the styles let the function for the cell class rule return true.

Sorting

Feature wise we can stop after the previous chapter. The next couple of sections are just needed if you use the given feature.

The sorting of AG Grid is not going to work, because the grid has no idea how to sort objects by reference. But AG Grid - like always -
has an awesome option to help us. We can use the postSortRows api for control over the sorted rows (see docs)

The base idea is to resolve all observables for the current sorted column and afterwards trigger the grid sort again to let is sort properly.

postSortRows: (params: PostSortRowsParams): void => {
  if (skipNextPostSort) {
    skipNextPostSort = false;

    return;
  }
  const columnStates: Array<ColumnState> =
    params.columnApi.getColumnState();

  columnStates
    .filter((state: ColumnState) => !!state.sort)
    .forEach((state: ColumnState) => {
      const observables: Array<Observable<unknown>> = [];
      params.api.forEachNode((node: RowNode) => {
        const value: unknown = params.api.getValue(
          state.colId || '',
          node
        );
        if (isObservable(value)) {
          value.subscribe({
            next: (result: unknown) => {
              storeResolvedObservableValue(value, result);
            },
          });
          observables.push(value);
        }
      });
      if (observables.length) {
        forkJoin(observables).subscribe({
          next: () => {
            /**
             * If we re-sort after all observable data for a column sort is resolved we don't want
             * to execute postSort again (infinite loop)
             */
            skipNextPostSort = true;
            params.api.refreshClientSideRowModel('sort');
          },
        });
      }
    });
},

The core logic is in the params.api.forEachNode. We want to iterate each row and see if the current value is an observable. If it is, we want to subscribe and store the given value with a little helper function I will explain in a second.

With the forkJoin we want to wait for all observables to be resolved and then re-sort the grid again. To store the values I'm using a WeakMap (to prevent any memory issues) and store the value by observable reference.

const valueByObservable: WeakMap<Observable<unknown>, unknown> = new WeakMap<Observable<unknown>, unknown>();
export function storeResolvedObservableValue(observable: Observable<unknown>, value: unknown,): void {
  valueByObservable.set(observable, value);
}
export function getStoredResolvedObservableValue(observable: Observable<unknown>): unknown {
  return valueByObservable.get(observable);
}

If we implement everything so far the result would still not work because AG Grid is still trying to sort by the reference.So we actually need a way to tell AG Grid to use our resolved value instead of the reference. On the column definition there is a comparator property that allows us to specify a custom sort comparator function
(see docs).

export function getObservableNumberComparator(): (valueA: any, valueB: any, nodeA: RowNode, nodeB: RowNode, isInverted: boolean) => number {
  return (valueA: any, valueB: any, _nodeA: RowNode, _nodeB: RowNode) => {
    if (isObservable(valueA) || isObservable(valueB)) {
      return (getStoredResolvedObservableValue(valueA) as number || 0) - (getStoredResolvedObservableValue(valueB) as number || 0);
    }

    return valueA - valueB;
  };
}

The comparator function is very simple in this case. We just check if the provided values are actually observables and then fetch the result from our WeakMap from the previous step.

If we update our column definition to include the comparator it looks like this and we can finally sort our price column.

{
  colId: 'price', 
  field: 'pricingData', 
  cellRenderer: AgGridTextCellRendererComponent,
  comparator: getObservableNumberComparator(),
}

Clipboard

Same story as before. If you just try to use the clipboard copy out of the box you will get [object Object] copied into your clipboard. Like for everything else you can imagine there is a neat little property on the gripdOptions called processCellForClipboard that allows us to hook into the process before the value is passed to the clipboard (see docs).

A simple check whether the given value is actually an observable and then checking our WeakMap for the real value and returning this instead of the
reference.

processCellForClipboard: (params: ProcessCellForExportParams) => {
  if (isObservable(params.value)) {
    return getStoredResolvedObservableValue(params.value) || '';
  }

  return params.value;
},

Note: Keep in mind, this will only save your value to the clipboard if the value has already been resolved. If you try this during the loading, the
result will just be an empty string.

CSV export

Very similar as clipboard export. I'm just gonna link the docs and show the proper gridOptions property.

defaultCsvExportParams: {
  processCellCallback(params: ProcessCellForExportParams) {
    if (isObservable(params.value)) {
      return getStoredResolvedObservableValue(params.value) || '';
    }

    return params.value;
  }
},

Excel export

Ok this is almost too easy… see the docs and check out the gridOptions property.

defaultExcelExportParams: {
  processCellCallback(params: ProcessCellForExportParams) {
    if (isObservable(params.value)) {
      return getStoredResolvedObservableValue(params.value) || '';
    }

    return params.value;
  },
},

If this is only logic you have in your export functions and you actually use all three of them you can extract this logic into a separate function and use this to avoid copy paste.

function processCellCallback(params: ProcessCellForExportParams) {
  if (isObservable(params.value)) {
    return getStoredResolvedObservableValue(params.value) || '';
  }

  return params.value;
}

Then your gridOptions are more readable:

processCellForClipboard: processCellCallback,
defaultCsvExportParams: {
  processCellCallback: processCellCallback,
},
defaultExcelExportParams: {
  processCellCallback: processCellCallback,
},

Pitfalls

In this section I just try to document issues I or others had in the past. If you have anything else to add, please let me know.

DOM Virtualisation / observables are not triggered

If we build everything properly, the observables are only resolved if they are visible - only then a .subscribe() is being called. Be aware that all observables will be resolved upfront if you turn off row- or column virtualisation
(see docs)

And on the other hand don't be surprised if some observables are not triggered if they are currently not visible in the viewport.

HTTP requests are executed multiple times

If you are using HTTP requests for your observables you most like will notice that requests are now done multiple times. For most HTTP client implementations every separate .subscribe() call will actually do a separate request. We are now doing this for example the view in the template, the sorting and the export.

You can use the shareReplay pipe (see docs) to prevent this and all
.subscribe() calls will refer to the same HTTP request. Same concept applies if your original observable is very computation heavy. It's better to use the shareReplay pipe.

Huge tables and sorting

If each cell uses a different observable and you have a grid with thousands of rows, be aware that if you sort for an observable column that every observable gets resolved. It might make sense to disable the sorting in such a case.

Row model type

This post was written for the client side row model. Other row models like server side, viewport or infinite (see docs might not work or need additional configuration effort.

Streamed observables

This approach currently works best for observables that are completed after the first result. From my experience that was all the use cases I had. Theoretically this is also possible for observables that emit multiple values, however you probably need to adjust couple of things. Find a better unsubscribe logic in the sort function to replace the first().

Alternatively you can also just create a new observable and re-assign it to the field in your grid data. The big advantage is that you get the loading indicator displayed again if you start a new request/loading time.

Reducing Angular Library Contributions to the Main Bundle

Stephen Cooper — Tue, 06 Dec 2022 09:39:48 +0000

In this guest post by Nicolas Gehlert, origianlly published here, learn the best way to include AG Grid in your own shared Angular library that will not result in AG Grid being included in the main bundle, as long as it is only used in lazy loaded routes.

Many thanks again to our user Nicolas for sharing his findings with us!

Using an Angular workspace with your own library you might've noticed that your main bundle size keeps increasing the more features you are adding - even if you
are not using all features up front. Let me show you how you can build a sustainable and lightweight library structure for your own library.

Introduction
Bundle analyzer
Problem analysis
Solution
Test for yourself

Introduction

Angular libraries are awesome and Angular does a good job giving you a kick start with their documentation.
However this only works for very simple and small libraries. If your library gets bigger and you want to optimize it, I found
there to be very few good resources.

Let me tell you an example. I'm using a big library with dependencies like AG Grid to provide shared components and services
in a multi application Angular workspace. I'm using lazy loading for all my routes but I discovered the main bundle get's increased
for all applications if I add more things to the library. At some point I was just using a simple data service in the main
application and an AG Grid component few lazy loaded modules down the line, but still AG Grid and all components were added to the
main bundle.

In this post I will show you how to analyze your package and how to properly set up your library in order to prevent similar issues.

All examples in this post use a sample project at https://github.com/ngehlert/angular-lazy-load.

Bundle analyzer

A bundle analyzer allows you to get insights in your bundled JavaScript. It shows you what dependencies are included and how much space
each section needs.

The Angular team recommends to use a tool called source-map-explorer. A lot of other post show tools like webpack-bundle-analyzer
or others. To some extend they work as well, but let's stick with the source-map-explorer for now.

First we need to install it with npm or yarn

npm install -g source-map-explorer
yarn global add source-map-explorer

Now build your project with the --source-map=true flag. (If you are using a project with an Angular version prior 12 also add the --prod flag)

ng build app --source-map=true

And now we can have a look at our stats with

source-map-explorer dist/app/main.js

The result looks something like this.

Problem analysis

Let's have a look at our sample application. We are using a small service and a component to display a simple table.

In our app.component.ts we are using the RandomService and in our lazy loaded route the TableComponent.

But if we have a look at our bundle analysis (see screenshot above) we will notice that AG Grid is actually added to the main module, instead of the lazy loaded one.

It turns out by default an Angular library is actually not tree shakeable, and you will always add the entire library to your bundle, even if you are just
importing one service or variable.

Solution - Multiple Entry points

You can create multiple entry points to your library and then you only need to import a specific entry point you are interested in, instead of the entire library.
Angular material is using the same concept, for example import {MatDialog} from '@angular/material/dialog';

Creating separate entry points is actually fairly simple and you only need to create a new directory inside your library and add an ng-package.json file.
Inside the ng-package.json you need to put the following content

{
    "$schema": "../../../../node_modules/ng-packagr/ng-package.schema.json",
    "lib": {
        "entryFile": "public_api.ts"
    }
}

In our example I moved the table directory into a separate grid directory next to the already existing src directory.

If you now run ng build good-lib you will notice that actually two entry points are created

Building Angular Package

------------------------------------------------------------------------------
Building entry point 'good-lib'
------------------------------------------------------------------------------
✔ Compiling with Angular sources in Ivy partial compilation mode.
✔ Writing FESM bundles
✔ Copying assets
✔ Writing package manifest
✔ Built good-lib

------------------------------------------------------------------------------
Building entry point 'good-lib/grid'
------------------------------------------------------------------------------
✔ Compiling with Angular sources in Ivy partial compilation mode.
✔ Writing FESM bundles

Now just one step is missing in order to use the secondary entry points. Go to your tsconfig.json (in your root directory). And extend the path entry for your library with a
placeholder match.

before:

"paths": {
  "good-lib": [
    "dist/good-lib"
  ],
},

after:

"paths": {
  "good-lib/*": [
    "dist/good-lib/*"
  ],
  "good-lib": [
    "dist/good-lib"
  ],
},

Note: You just need to do this once for your first secondary entry point. All future entry points will be resolved as well.

You can now use the TableModule from the secondary entry point like this import { TableModule } from 'good-lib/grid';

How to reference between the different entry points

You can NOT use relative imports between difference entry points. You need to import from the build package like you would from a regular application
as well. In our example this would be import {RandomService} from 'good-lib'; if you want to use it in the grid entry point.

Note: ng-packagr will detect in which order it needs to compile the different entry points so everything can be resolved. You will get an
error if you introduce a circular dependency and two (or more) entry points actually try to import from each other.

Test for yourself

You can clone the https://github.com/ngehlert/angular-lazy-load and just need to change three imports
to switch between the good and the bad library. See what imports to change

In the end with the good library AG Grid gets added to the lazy loaded route instead of the initial bundle. Now our initial bundle is only 200kb instead of 1.3mb!

For further details about minimizing the AG Grid bundle size in your application make sure to also read our other post Minimising Application Bundle Size.

AG Grid Community Roundup July 2022

Alan Richardson — Tue, 02 Aug 2022 13:11:48 +0000

We melted our way through the heat of July to try and find the best of the content on the web related to AG Grid.

We also released a new version of AG Grid

Videos

We found an interesting video from Valispace, I think it is one of their recruitment videos but it describes their evaluation and adoption process for AG Grid:

How AG Grid chosen?
- Aware of the libraries available
- Create a proof of concept using the library quickly
- Explore the main use-cases at a high level
- Evaluate the results
- Test with 100s of thousands of rows

AdapTable Tools have been creating quite a few videos recently. And this one shows a demo of their save charts state feature. Adaptable is a great example of how extensible AG Grid is in the right hands and their AG Grid extension can really add a lot of user focussed features instantly when added to your project.

Philip Eschenbacher has created another video in his Mongo DB and AG Grid series showing how to use enhanced Graph QL Searches.

Blogs

Max Rosenberg wrote a blog post showing how to combine React Query with AG Grid. This has been on our internal todo list for quite some time so we are grateful to Max for creating such a good post we can point people towards.

Brian Love on his consultancy Live Live App posted a blog post about AG Grid Rendering pipeline this explains in detail the ordering and scope of rendering features in AG Grid: value getters then formatters, then renderers.

We also released a few blog posts on the AG Grid blog:

Apps

We found quite a few apps using AG Grid that we were not aware of and added a Github section on our sample apps page which lists interesting projects that use AG Grid and release their code on Github.

A few projects to take a look at that we became aware of recently:

Lowdefy is a low code tool that uses AG Grid as a block component, allowing you to create apps which render data in AG Grid without a lot of coding knowledge. There is a Lowdefy example using AG Grid here.
The Systelab Component Library has common components for Angular. AG Grid is used as the grid component in their 'tables' component showcase.
Consta Design have created a React component that wraps AG Grid to provide some formatting and editing components. You can see it in action in their Storybook implementation.

There are many more on the Sample Apps Page

Podcasts

Stephen Cooper and Mana Peirov from the AG Grid team appeared on the Adventures in Angular podcast discussing Testing and Charting.

You can listen to the podcast here.

Using Playwright to Test AG Grid React Apps

Alan Richardson — Fri, 22 Jul 2022 12:37:00 +0000

This article contributed to the AG Grid blog by Cameron Pavey

Playwright is a testing tool created and maintained by Microsoft geared primarily toward end-to-end (E2E) tests. It boasts several features that make it a compelling choice for teams considering different E2E tools, including a cross-language API that lets you write your tests in various languages (JavaScript, TypeScript, Python, .NET, and Java) and cross-platform support for all major browsers.

Similar to Cypress and Selenium, Playwright’s primary use case is E2E testing; however, recently, it has also gained experimental support for component testing. Component testing allows you to validate individual UI components’ functionality in isolation without invoking the whole application as you typically would in an E2E test.

In this tutorial, you’ll learn more about the distinction between E2E testing and component testing before seeing how Playwright facilitates both kinds of tests. You’ll learn how to create a simple React application that utilizes AG Grid and how to validate the functionality of that application at an E2E and component testing level using Playwright.

What Are E2E Tests

E2E tests are one of the three tiers of testing described by the testing pyramid. They are typically regarded as one of the slower and more expensive types of tests because they usually invoke the entire system and simulate user interactions with a fully composed system. This inevitably leads to longer-running tests (compared to unit tests and integration tests, which both reside closer to the base of the pyramid), with often fragile imperative instructions describing how the test runner should interact with the application. While this tutorial will primarily focus on Playwright, Cypress is also a very compelling option, and it recently released the beta of their component testing solution, similar to Playwright.

One of the big differences between Playwright and Cypress is the philosophies that they follow. Playwright endorses the use of the Page Object Model (POM) pattern. However, Cypress suggests that code being reused through custom commands is an effective alternative, although the POM pattern is still achievable in Cypress if you prefer it. AG Grid has a blog post about using a Cypress plug-in for testing AG Grid applications that eloquently demonstrates the virtues of Cypress’s custom command functionality. Either way, both tools are effective for E2E testing, but what about component testing?

Component Testing Challenges

Component testing can be tricky because, depending on your interpretation, there are various places it could fit in the testing pyramid. You can treat it like an E2E test, as it typically deals with the same UI components, but this approach has some drawbacks. Using the full E2E setup for component testing will be slower than potential alternatives because it still needs to invoke the entire application and its dependencies. This also poses a challenge if you are dealing with a component library with no distinct application to invoke. In this case, you need to make a simple application that mounts your components to test this. This increases the amount of setup and the amount of overhead involved in running these tests, and makes them generally less appealing when viewed from a cost/benefit perspective.

Another approach is to treat them more like unit tests. You can achieve this by using tools like Jest as your test runner and Testing Library, which is a testing utility library that exposes some functions to help you test your components in isolation. This is typically a good approach in terms of effort, maintainability, and general developer experience. However, there are still some drawbacks, the most notable of which is that the tests don’t run in a real browser. Instead, the tests use JSDom in most cases. This is where the component testing functionality of Playwright comes in.

With Playwright, you can run your component tests in real browsers, using the same sort of tests that you would write for your E2E tests but without the drawbacks of using the full E2E setup, with additional overhead and unrelated application code being included.

E2E and Component Testing with Playwright

Before getting started, there are a few things you will need:

A recent version of Node.js (which comes with npm). This tutorial uses v14.19.3.
A code editor of your choice. Visual Studio Code is a good choice if you don’t already have a code editor you prefer.

If you wish to see the completed code for the tutorial, you can find it in this public GitHub repo. Otherwise, if you’d prefer to build it yourself, or see how it’s done, keep following along.

Once you have your prerequisites, the first thing you need to do is create a new project. You can use Vite for this tutorial, as it is fast, minimal, and easy to get started with, but other app starters, like create-react-app and Next.js, should also work. To create your new project, open a terminal and run the following commands:

npm create vite@latest ag-grid-playwright --template react
cd ag-grid-playwright
npm install

This will create a directory named ag-grid-playwright/ with a minimalist project inside it before navigating into the directory and installing all the current node dependencies. Next, you can install Playwright with the following command:

npm init playwright@latest

The installer will ask you questions like whether you want to use JavaScript or TypeScript, where you want to store the test files, and whether you want to create a GitHub Action. If you are following along, select JavaScript when prompted and then accept the default answers for the other questions, as these will work for this tutorial.

Once Playwright is installed, you can test that it works as expected. By default, it comes with an example test spec that runs twenty-five sample assertions in each of the three major browsers: Chrome, Firefox, and WebKit. To run this spec file, run the following command:

npx playwright test

If all is well so far, you should see an output like this:

To simplify the output later when you add your tests, you can delete the example located at tests/example.spec.js.

Now that you have Playwright set up, you can install a couple more dependencies that you will need to build the actual application, AG Grid. To do this, use the following command:

npm install ag-grid-react ag-grid-community

Creating the Application

With the dependencies installed, you need to create the components you will use in this application. So that there is a level of contrived complexity in the application, you will create two main components: the DataGrid and the CustomRenderer for one of the columns in your grid. You can do this by running the following commands:

mkdir src/components
touch src/components/DataGrid.jsx
touch src/components/CustomRenderer.jsx

This will create the directory and files for the components you need. Next, open the CustomRenderer.jsx file in your editor and paste in the following content:

export const CustomRenderer = (props) => {
  return <span>{`$${props.value.toLocaleString()}`}</span>;
};

This simple component will be responsible for rendering the integer values in your data, formatted as monetary values. After this, open the DataGrid.jsx file and paste in the following content:

import React, { useState } from "react";
import { AgGridReact } from "ag-grid-react";

import "ag-grid-community/dist/styles/ag-grid.css";
import "ag-grid-community/dist/styles/ag-theme-alpine.css";
import { CustomRenderer } from "./CustomRenderer";

export const DataGrid = () => {
  const [rowData] = useState([
    { make: "Toyota", model: "Celica", price: 35000 },
    { make: "Ford", model: "Mondeo", price: 32000 },
    { make: "Porsche", model: "Boxster", price: 72000 },
  ]);

  const [columnDefs] = useState([
    { field: "make" },
    { field: "model" },
    { field: "price", cellRenderer: CustomRenderer },
  ]);

  return (
    <div className="ag-theme-alpine" style={{ height: 400, width: 600 }}>
    <AgGridReact rowData={rowData} columnDefs={columnDefs}></AgGridReact>
    </div>
  );
};

This code is a slightly modified version of the example from the AG Grid documentation. The modification to this code is simply to use the CustomRenderer component for the price column, which will display the value as a formatted monetary value rather than just a number. You will need to change one more file to ensure the application renders correctly. Open src/App.jsx and replace its content with the following:

import { DataGrid } from "./components/DataGrid";

function App() {
  return <DataGrid />;
}

export default App;

Before proceeding to the E2E test, you should verify that the app is working as expected. To do this, from your terminal, run npm run dev, which will tell Vite to start a dev server, allowing you to access your application, typically located at http://localhost:3000 if the port is free. If it needs to run on a different port for whatever reason, the terminal output will tell you where it is running when you execute the command. When you visit that URL, you should see something like this:

Although the application is very simple, it gives you a few things that you can test with both E2E and component tests and, as such, serves as an excellent example for this kind of tutorial.

The E2E Test

For your E2E test, you want to ensure that the application works as expected. In the case of this simple application, that essentially amounts to showing the correct data. To do this, make a new file located at tests/app.spec.jsx and give it the following content:

import { test, expect } from "@playwright/test";

test("Check that all expected data is present", async ({ page }) => {
  await page.goto("http://localhost:3000");

  // Verify that the title is correct
  await expect(page).toHaveTitle("Vite App");

  // Specify the data that we expect to be present
  const expectedData = [
    ["Toyota", "Celica", "$35,000"],
    ["Ford", "Mondeo", "$32,000"],
    ["Porsche", "Boxster", "$72,000"],
  ];

  // Verify that the data is correct
  for (let index = 0; index < expectedData.length; index++) {
    const row = await page.locator("role=row").nth(index + 1);
    const [make, model, price] = expectedData[index];
    await expect(row).toContainText([make, model, price]);
  }
});

This test will instruct Playwright to navigate to your application, hosted by Vite’s dev server. Check that the page title is correct and that the three expected rows of data are present and correct. You can add a script to your package.json file to help run your E2E tests. Open your package.json file and add the following line to your scripts object:

…
"test": "playwright test"
…

Now, ensure that your Vite dev server is still running so that your application is available on port 3000, and then in a new terminal window (navigate back to the project directory if you need to), run the following command:

npm run test

You should see an output like this:

Even though you only have one test at the moment, Playwright is configured to run three different projects, one with each of the three major browsers. You can see this configuration in playwright.config.js.

This E2E test requires your application to be running and will load your entire application for each test. That isn’t a problem for a small application like this one. With larger, more complex real-world applications, however, it isn’t ideal to have that overhead if you aren’t testing the whole application.

Next, you’ll see how you can use Playwright to create some simple component tests for your CustomRenderer and DataGrid components.

The Component Tests

Getting started with Playwright component testing is similar to the initial setup for Playwright E2E testing. However, you should note that at the time of writing this, component testing support in Playwright is still regarded as experimental, so it’s possible things will change in the future. If you find that these instructions do not work as expected, please refer to the official documentation for further guidance.

To get started, run the following command from the root of your project directory:

npm init playwright@latest --ct

This will prompt you with similar questions to the initial setup, but if you are following along, answer with “JavaScript” and “React” when prompted for your language and framework, respectively. When this command finishes, you should have a new file called playwright-ct.config.js. Open this file and edit the testDir property as follows:

…
testDir: ‘./src’,
…

This change is necessary because the default value of './' will include your E2E tests, which you don’t necessarily want to run alongside your component tests in the same command. After making this change, you can create your two component tests. For the first one, create a file at src/components/CustomRenderer.spec.jsx and give it the following content:

import { test, expect } from "@playwright/experimental-ct-react";
import { CustomRenderer } from "./CustomRenderer";

test.use({ viewport: { width: 500, height: 500 } });

test("formats value correctly", async ({ mount }) => {
  const component = await mount(<CustomRenderer value={10000} />);
  await expect(component).toContainText("$10,000");
});

This test will ensure that the CustomRenderer parses numeric values into monetary values correctly. Next, create a file at src/components/DataGrid.spec.jsx and give it the following content:

import { test, expect } from "@playwright/experimental-ct-react";
import { DataGrid } from "./DataGrid";

test.use({ viewport: { width: 500, height: 500 } });

test("contains the expected data", async ({ mount }) => {
  const component = await mount(<DataGrid />);

  const expectedData = [
    ["Toyota", "Celica", "$35,000"],
    ["Ford", "Mondeo", "$32,000"],
    ["Porsche", "Boxster", "$72,000"],
  ];

  // Verify that the data is correct
  for (let index = 0; index < expectedData.length; index++) {
    const row = await component.locator("role=row").nth(index + 1);
    const [make, model, price] = expectedData[index];
    await expect(row).toContainText([make, model, price]);
  }
});

You will notice that this test borrows heavily from the E2E test in terms of logic. It is, after all, performing very similar assertions due to the limited scope of the application. The key difference here, however, is that it will not instantiate your whole application, nor does it require your Vite dev server to be running. With both of these tests created, you can run the following command to execute them:

npm run test-ct

From this command, you should see similar output to your E2E test, except it will be 6 now instead of 3 (because you have two tests and three browsers):

Being able to test components in isolation, away from the rest of your application, is important because not only will the tests run faster than heavier E2E tests but, more importantly, the tests will not be affected by external factors and unrelated code. Performing your component tests with the same tools as your E2E tests (as opposed to using Jest and Testing Library) is a huge advantage. It opens the door for productivity boosts, such as sharing test helpers between E2E and component tests, allowing you to share abstractions and utilities between these two testing domains without the drawbacks that traditionally come with fully merging them.

Summary of Github Steps

You can find the code for this tutorial in this public GitHub repo.

First, clone or download and unzip the repo code, then install the dependencies:

npm install

Second, install Playwright and browsers:

npx playwright install

To run the component tests:

npm run test-ct

To run the end to end tests we need to run the dev server from one console with npm run dev to start the app running on localhost. Then run the end to end tests with:

npm run test

After each test run you can use npx playwright show-report to see the execution report.

Wrapping Up

In this tutorial, you learned how to create a simple application with React, Vite, and AG Grid, and then test that application at an E2E and component level using Playwright. You’ve also learned about the differences between E2E and component testing, as well as some tools that can help you create those kinds of tests, like Playwright, Cypress, Jest, and Testing Library.

If you want to learn more about Playwright, the official documentation is a great place to get started.

Using AG Grid in Electron Applications

Alan Richardson — Thu, 21 Jul 2022 14:06:03 +0000

This post contributed to the AG Grid blog by Arek Nawo

Electron is a cross-platform framework for building native desktop applications with web technologies. It’s built on top of Node.js and the Chromium browser, allowing you to use all of the latest features and improvements from the browser and JavaScript language.

Electron enables you to create the best user experience while taking care of all the complex parts of making a native app. With Electron, you can reuse both your knowledge and codebase across the web and all desktop platforms. If you already know how to develop frontend web apps and Node.js backends, you’ll feel right at home with Electron as it basically combines those two into a single app.

In this article, you’ll learn how to integrate AG Grid—an advanced and performant JavaScript grid library—into your Electron app. You’ll create a simple to-do app with native functionality to save and restore its state from a JSON file.

You can follow along with this GitHub repo.

How Does Electron Work?

A basic Electron app consists of two processes. The main process acts as an entry point for the app, with access to Node.js APIs and modules (including native ones). It also controls the app’s lifecycle and manages its windows using Electron-provided APIs.

So while the main process is like your web app’s backend, the renderer process is more like its frontend. It’s responsible for rendering the app’s UI and runs in every opened window. Thus, it should follow web standards (such as HTML5, CSS3, and ECMAScript) and use browser Web APIs. No Node-specific code is allowed.

To communicate between processes (e.g., to handle data transfer or invoke native functionality from the UI), you can use preload scripts and inter-process communication (IPC). Preload scripts run in the renderer process before the main script and have access to the Node.js API. You can use them with the Electron’s contextBridge module to safely expose privileged APIs to the renderer process. Most notably, you can expose helpers leveraging the ipcRenderer module to communicate with the main process.

Using AG Grid with Electron

A good way to get started with Electron is with Electron Forge—“a complete tool for creating, publishing, and installing modern Electron applications.” Electron Forge has everything you need to work on your Electron app, including a Webpack-powered template.

Setting Up the Project

To initiate a new project with Electron Forge, ensure you have git and Node.js v12.13.0 or newer installed. Then, run the following commands to create the project, install additional dependencies, and start the development server:

npx create-electron-app@latest project --template=webpack
cd project
npm install ag-grid-community
npm run start

Managing the App’s Window

By default, the template includes files for main and renderer processes. Inside the src/main.js file, you’ll see the starting point of your app. Take a closer look at the createWindow() function and event listeners below:

const { app, BrowserWindow } = require("electron");
// ...

const createWindow = () => {
  const mainWindow = new BrowserWindow();

  mainWindow.loadURL(MAIN_WINDOW_WEBPACK_ENTRY);
  mainWindow.webContents.openDevTools();
};

app.on("ready", createWindow);
app.on("window-all-closed", () => {
  if (process.platform !== "darwin") {
    app.quit();
  }
});
app.on("activate", () => {
  if (BrowserWindow.getAllWindows().length === 0) {
    createWindow();
  }
});

The app module controls your app’s event lifecycle. When the app is ready, it creates a new window by calling createWindow(), which in turn creates a new instance of BrowserWindow. Using the loadURL() method, the window loads the content served by Webpack’s development server. It also opens dev tools for easier debugging using the webContents.openDevTools() method.

The other event listeners handle macOS-specific edge cases, like keeping the app open without any windows (window-all-closed) or opening a new window when activated from the dock (activate).

Adding Preload Script

To allow native API access from the renderer process, you’ll have to expose some functions in the preload script. Although the template doesn’t include it by default, adding it yourself is easy.

Create a new src/preload.js file and edit the config.forge.plugins field in package.json to inform Electron Forge about the preload script:

{
  /* ... */
  "config": {
    "forge": {
      "packagerConfig": {},
      /* ... */
      "plugins": [
        [
          "@electron-forge/plugin-webpack",
          {
            "mainConfig": "./webpack.main.config.js",
            "renderer": {
              "config": "./webpack.renderer.config.js",
              "entryPoints": [
                {
                  "html": "./src/index.html",
                  "js": "./src/renderer.js",
                  "preload": {
                    "js": "./src/preload.js"
                  },
                  "name": "main_window"
                }
              ]
            }
          }
        ]
      ]
    }
  }
  /* ... */
}

To initialize the script, specify it when creating a BrowserWindow in the src/main.js file using the Webpack-provided global variable:

// ...
const createWindow = () => {
  const mainWindow = new BrowserWindow({
    webPreferences: {
      preload: MAIN_WINDOW_PRELOAD_WEBPACK_ENTRY,
    },
  });

  // ...
};
// ...

Building the Renderer Process UI

With essential window management ready, you can start working on the renderer process. You’ll use AG Grid to create a simple to-do list with the ability to add, remove, and mark items as complete.

Developing a renderer process is very similar to creating a frontend web application. You can use all the frontend frameworks and APIs available in the browser environment. In this tutorial, you’ll use plain HTML, JS, and CSS to keep things simple.

Start by creating your UI’s structure in the src/index.html file:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <title>AG Grid + Electron</title>
  </head>
  <body>
    <div class="container">
      <h1>Electron TO-DO</h1>
      <div class="btn-container">
        <button id="save-btn" class="btn">Save</button>
        <button id="restore-btn" class="btn">Restore</button>
        <button id="add-btn" class="btn add-btn">Add</button>
      </div>
      <div class="divider"></div>
      <div id="grid" class="ag-theme-alpine"></div>
    </div>
  </body>
</html>

Then, add the necessary styling in src/index.css :

html,
body {
  height: 100%;
  margin: 0;
}
#grid {
  width: 100%;
  flex: 1;
}
.container {
  margin: auto;
  display: flex;
  justify-content: center;
  align-items: center;
  flex-direction: column;
  height: calc(100% - 2rem);
  padding: 1rem;
  width: 30rem;
}
.btn-container {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(100px, 1fr));
  gap: 0.5rem;
  width: 100%;
}
.divider {
  margin: 0.5rem 0;
  background: #e6e6e6;
  height: 0.125rem;
}
.checkbox {
  height: 100%;
  margin: 0;
  width: 1.25rem;
}
.btn {
  flex: 1;
  padding: 0.5rem;
  background: #6b7280;
  border: none;
  color: #fff;
  font-size: 1rem;
}
.btn:hover {
  background: #9ca3af;
  cursor: pointer;
}
.add-btn {
  padding: 0.5rem;
  background: #f97316;
  border: none;
}
.add-btn:hover {
  background: #fb923c;
  cursor: pointer;
}
.remove-btn {
  display: inline-flex;
  max-height: 1.25rem;
  max-width: 1.25rem;
  font-size: 1.25rem;
  justify-content: center;
  align-items: center;
  background-color: #ef4444;
}
.remove-btn:hover {
  background-color: #f87171;
}

With this setup, you can now move to the src/renderer.js file to initialize the grid:

import "ag-grid-community/dist/styles/ag-grid.css";
import "ag-grid-community/dist/styles/ag-theme-alpine.css";
import "./index.css";
import { Grid } from "ag-grid-community";

let rowData = [];

const columnDefs = [
  // ...
];
const gridOptions = {
  columnDefs,
  rowData,
};
const saveBtn = document.getElementById("save-btn");
const restoreBtn = document.getElementById("restore-btn");
const addBtn = document.getElementById("add-btn");
const addTodo = () => {
  // ...
};
const removeTodo = (rowIndex) => {
  // ...
};
const saveToFile = () => {
  // ...
};
const restoreFromFile = async () => {
  // ...
};
const setupGrid = () => {
  const gridDiv = document.getElementById("grid");

  new Grid(gridDiv, gridOptions);
  addBtn.addEventListener("click", addTodo);
  saveBtn.addEventListener("click", saveToFile);
  restoreBtn.addEventListener("click", restoreFromFile);
};

document.addEventListener("DOMContentLoaded", setupGrid);

All setup, including creating a Grid instance and adding event handlers, happens after the DOM is loaded. The grid is created using the provided configuration, defining its columns and input data:

// ...
let rowData = [];

const columnDefs = [
  { field: "task", editable: true, flex: 1 },
  {
    field: "completed",
    width: 120,
    cellRenderer(params) {
      const input = document.createElement("input");

      input.type = "checkbox";
      input.checked = params.value;
      input.classList.add("checkbox");
      input.addEventListener("change", (event) => {
        params.setValue(input.checked);
      });

      return input;
    },
  },
  {
    field: "remove",
    width: 100,
    cellRenderer(params) {
      const button = document.createElement("button");

      button.textContent = "✕";
      button.classList.add("btn", "remove-btn");
      button.addEventListener("click", () => removeTodo(params.rowIndex));

      return button;
    },
  },
];
// ...

The columns are defined by certain parameters such as field name, width, or custom cellRenderer in case you want to display the data differently. editable enables built-in editing support, allowing the user to change the task’s name. At the same time, flex is an alternative to width, indicating that the column should fill the remaining space.

For “completed” and “remove” columns, custom cell renderers render a checkbox and button to, respectively, change the status of the task or remove it from the list entirely. The actual change to the grid’s data is done with params.setValue() and a separate removeTodo() function.

Both addTodo() and removeTodo() operate using the gridOptions.api object. After being provided to the grid, gridOptions gets the api property to allow control of the grid:

// ...
const addTodo = () => {
  rowData = [...rowData, { task: "New Task", completed: false }];
  gridOptions.api.setRowData(rowData);
};
const removeTodo = (rowIndex) => {
  rowData = rowData.filter((value, index) => {
    return index !== rowIndex;
  });
  gridOptions.api.setRowData(rowData);
};
// ...

Values from rowData items are also bound to the grid, meaning that if the user changes the completion status or the task’s name, the new value is reflected in one of the rowData items.

With all these changes, the app’s UI is now fully functional and looks like this:

All that’s left is to implement save and restore functionality. For that, you’ll have to return to the main process.

Adding Native Functionality

Inside the src/main.js file, create a new function, handleCommunication(), for handling IPC implementation:

const { app, BrowserWindow, ipcMain, dialog } = require("electron");
// ...

const handleCommunication = () => {
  ipcMain.removeHandler("save-to-file");
  ipcMain.removeHandler("restore-from-file");
  ipcMain.handle("save-to-file", async (event, data) => {
    try {
      const { canceled, filePath } = await dialog.showSaveDialog({
        defaultPath: "todo.json",
      });

      if (!canceled) {
        await fs.writeFile(filePath, data, "utf8");

        return { success: true };
      }
      return {
        canceled,
      };
    } catch (error) {
      return { error };
    }
  });
  ipcMain.handle("restore-from-file", async () => {
    try {
      const { canceled, filePaths } = await dialog.showOpenDialog({
        properties: ["openFile"],
        filters: [
          {
            name: "json",
            extensions: ["json"],
          },
        ],
      });

      if (!canceled) {
        const [filePath] = filePaths;
        const data = await fs.readFile(filePath, "utf8");

        return { success: true, data };
      } else {
        return { canceled };
      }
    } catch (error) {
      return { error };
    }
  });
};
// ...

First, using ipcMain.removeHandler(), ensure that no existing handlers are attached to the used channels in case the window was reactivated (macOS-specific). The ipcMain.handle() method allows you to handle specific events and respond with data by simply returning a value from the handler.

For this app, the channels used are ”save-to-file” and ”restore-from-file”. Their handlers use the dialog module to bring up the system’s native open or save dialogues. The resulting paths are then provided to Node.js’s built-in fs module to read from or write to the provided file.

handleCommunication() should be called from the createWindow() function:

// ...
const createWindow = () => {
  const mainWindow = new BrowserWindow({
    webPreferences: {
      preload: MAIN_WINDOW_PRELOAD_WEBPACK_ENTRY,
    },
  });

  mainWindow.loadURL(MAIN_WINDOW_WEBPACK_ENTRY);
  mainWindow.webContents.openDevTools();
  handleCommunication();
};
// ...

To be able to send an IPC message from the renderer process, you’ll have to use the preload script and the contextBridge module:

// src/preload.js
const { contextBridge, ipcRenderer } = require("electron");

contextBridge.exposeInMainWorld("electronAPI", {
  saveToFile(data) {
    return ipcRenderer.invoke("save-to-file", data);
  },
  restoreFromFile() {
    return ipcRenderer.invoke("restore-from-file");
  },
});

contextBridge.exposeInMainWorld() safely exposes the provided API to the renderer process. Keep in mind that, in preload script, you’ve got access to privileged APIs, which, for security reasons, should be freely available from the frontend of your Electron app.

The exposed methods use the ipcRenderer module to send messages to the ipcMain listener on the other process. In the case of the ”save-to-file” channel, additional data in the form of a JSON string to save is provided.

With the bridge ready, you can return to the renderer process and finish the integration by adding proper handlers for the last two buttons:

// ...
const saveToFile = () => {
  window.electronAPI.saveToFile(JSON.stringify(rowData));
};
const restoreFromFile = async () => {
  const result = await window.electronAPI.restoreFromFile();

  if (result.success) {
    rowData = JSON.parse(result.data);
    gridOptions.api.setRowData(rowData);
  }
};
// ...

Each handler uses methods from the electronAPI object available on the window. In saveToFile(), the rowData is stringified and sent to the main process for writing it to the file. In the case of the restore operation, it first awaits the file’s stringified content to then parse and assign it to the grid.

Now your app can use the native file dialog to restore and save its state:

The final app outputs a JSON file like the following:

[{"task":"Learn Electron","completed":true},{"task":"Learn AG Grid","completed":false}]

Conclusion

Now you know how to use AG Grid in an Electron app. You’ve learned about Electron processes—what they are and how they work. Finally, you established IPC to communicate between them to implement native functionality into your app.

As you’ve seen, thanks to Electron, you can quickly transform your web app into an installable native desktop app with all the functionality that comes alongside it.

AG Grid is a high-performance JavaScript table library that’s easy to set up. It integrates well with your favorite frameworks, like React, and works great with other parts of the JavaScript ecosystem, such as Electron. Check out the official documentation to learn more.

Using React-Bootstrap and AG Grid

Alan Richardson — Wed, 20 Jul 2022 13:24:24 +0000

This post contributed to the AG Grid blog by Arek Nawo

Bootstrap is one of the most popular CSS frameworks, so it’s no surprise that many libraries integrate it with the top JavaScript UI frameworks. One such library is React-Bootstrap.

React-Bootstrap provides Bootstrap-powered React components with built-in reactivity. Every component is compatible with Bootstrap themes, optimized for accessibility, and can be controlled with React props. As one of the oldest React component libraries, React-Bootstrap is an excellent choice for building modern, responsive UI.

In this article, you’ll learn how to integrate React-Bootstrap with AG Grid, a batteries-included JavaScript grid with first-party React integration. You’ll see how easy it is to use both tools to build a compelling, user-friendly UI.

You can find the complete code for this tutorial in this GitHub repo.

AG Grid vs. React-Bootstrap Table

Before getting into the code, you should know the differences between AG Grid and React-Bootstrap’s built-in Table component.

At its core, the Table component is a traditional HTML table with a header, body, rows, and cells. React-Bootstrap makes the often-tedious process of creating an HTML table easier, not only with React’s reactivity and JSX but also with a faster styling process. You can set basic styles, add a row hover effect or dark theme, and make the table responsive with just a few props. However, it’s still a simple table that’s meant for basic use cases.

On the other hand, AG Grid is a full-blown, high-performance grid library. It provides you with everything you need to create an advanced, highly interactive grid-based UI, including filtering, data streaming, charting, and more. It’s your go-to solution if you need anything beyond a static table.

Using AG Grid with React-Bootstrap

To get started, make sure you’ve got NPM v7 and Node.js v12.2.0 or newer installed. Then, run the following commands to scaffold your project using Vite—a fast ES module-based bundler—and install necessary dependencies:

npm create vite project --template react
cd project
npm install
npm install bootstrap react-bootstrap ag-grid-community ag-grid-react

The installed dependencies include the following:

React-Bootstrap and “vanilla” Bootstrap for CSS styles loading
AG Grid’s core “community” package and React Data Grid for rendering

To start the development server, use npm run dev.

Creating Card Container

To learn how to integrate React-Bootstrap with AG Grid, you’ll build a simple app listing countries to visit. You use React-Bootstrap to add functionality and visuals to the grid with images and buttons.

Inside the src/App.jsx file, you initialize AG Grid together with React-Bootstrap. Start by creating a Bootstrap card for holding the grid:

import Card from "react-bootstrap/Card";
import Stack from "react-bootstrap/Stack";
import "bootstrap/dist/css/bootstrap.min.css";

const App = () => {
  return (
    <Card body className="h-100">
      <Stack className="h-100">
        <Card.Title>Countries to visit</Card.Title>
        [Grid]
      </Stack>
    </Card>
  );
};

export default App;

Using the Card and Stack components, you just built a full-height card with vertically stacked content. The grid will be placed just below the title.

To center the card in the body, add some CSS in the src/index.css file:

html {
  height: 100%;
  width: 100%;
}
body {
  margin: 0;
  padding: 1rem;
  height: 100%;
}
#root {
  margin: auto;
  height: 100%;
  width: 100%;
  max-width: 48rem;
}

With these changes, the card should now look like this:

Creating Basic AG Grid

To add the grid to the setup, you have to create a data source, which can be done using the useState() hook:

// ...
import { useState } from "react";
// ...

const App = () => {
  const [columnDefs] = useState([
    {
      headerName: "Country",
      field: "country",
    },
    {
      headerName: "Image",
      field: "image",
      flex: 1,
    },
    {
      headerName: "Visited",
      field: "visited",
    },
  ]);
  const [rowData] = useState([
    {
      country: "United Kingdom",
      image:
        "https://images.unsplash.com/photo-1486299267070-83823f5448dd?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=2371&q=80",
      visited: false,
    },
    {
      country: "United States",
      image:
        "https://images.unsplash.com/photo-1501594907352-04cda38ebc29?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=2832&q=80",
      visited: false,
    },
    {
      country: "India",
      visited: false,
      image:
        "https://images.unsplash.com/photo-1524492412937-b28074a5d7da?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=2371&q=80",
    },
    {
      country: "Canada",
      visited: false,
      image:
        "https://images.unsplash.com/photo-1519832979-6fa011b87667?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=2353&q=80",
    },
    {
      country: "Brazil",
      visited: false,
      image:
        "https://images.unsplash.com/photo-1483729558449-99ef09a8c325?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=2370&q=80",
    },
    {
      country: "Germany",
      visited: false,
      image:
        "https://images.unsplash.com/photo-1554072675-66db59dba46f?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=2373&q=80",
    },
    {
      country: "France",
      visited: false,
      image:
        "https://images.unsplash.com/photo-1431274172761-fca41d930114?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=2370&q=80",
    },
  ]);

  // ...
};
// ...

Each data row contains the name of the country, a related Unsplash image URL, and a Boolean indicating whether it was already visited. In addition, columnDefs define how the grid’s columns should be structured—e.g., their headers and width. In this case, all columns are displayed as text, with the image column taking the remaining horizontal space with flex: 1.

To display the grid, use the AgGridReact component passing the row data, column definition, and any additional properties—rowHeight in pixels in this case—as props:

// ...
import { AgGridReact } from "ag-grid-react";
import "ag-grid-community/dist/styles/ag-grid.css";
import "ag-grid-community/dist/styles/ag-theme-material.css";
// ...

const App = () => {
  // ...
  return (
    <Card body className="h-100">
      <Stack className="h-100 ag-theme-material">
        <Card.Title>Countries to visit</Card.Title>
        <AgGridReact
          columnDefs={columnDefs}
          rowData={rowData}
          rowHeight={200}
        ></AgGridReact>
      </Stack>
    </Card>
  );
};

// ...

The grid also comes with CSS of its own, which you also have to import. The ag-theme-material class on the grid’s wrapper indicates what theme to use.

The grid is now ready, but it displays all columns as text:

Let’s use React-Bootstrap and replace URLs with images.

Displaying Images

To display images in the grid, you’ll have to create a new component to be used as a cell renderer.

Create a new file at src/ImageRenderer.jsx with the following content:

import Image from "react-bootstrap/Image";
import Stack from "react-bootstrap/Stack";

const ImageRenderer = (props) => {
  return (
    <Stack direction="horizontal" className="h-100">
      <Image rounded src={props.getValue()} className="h-auto w-100" />
    </Stack>
  );
};

export default ImageRenderer;

Cell-renderer components receive data about the grid and current cell as props. You can use props.getValue() to get the cell’s current value, an image URL in this example. This value is then provided to React-Bootstrap’s Image component, along with other props. Additional Bootstrap class names and horizontally aligned Stack assure centered positioning and grid-adjusted sizing of the image.

To use ImageRenderer in the grid, return to src/App.jsx and set it as a cell renderer for the image column:

// ...
import ImageRenderer from "./ImageRenderer";
// ...

const App = () => {
  const [columnDefs] = useState([
    {
      headerName: "Country",
      field: "country",
    },
    {
      headerName: "Image",
      field: "image",
      flex: 1,
      // Set ImageRenderer component as cell renderer
      cellRenderer: ImageRenderer,
    },
    {
      headerName: "Visited",
      field: "visited",
    },
  ]);
  // ...
};

// ...

With these improvements, the grid already looks a lot better:

Adding Toggle Buttons

Besides seeing images, the user should be able to mark countries as visited. Currently, the visited column is empty as it contains only Boolean false values. To show a toggle button instead, create a new cell renderer at src/VisitedRenderer.jsx :

import ToggleButton from "react-bootstrap/ToggleButton";

const VisitedRenderer = (props) => {
  return (
    <ToggleButton
      size="sm"
      id={`visited-${props.rowIndex}`}
      type="checkbox"
      variant={props.getValue() ? "outline-primary" : "outline-secondary"}
      checked={props.getValue()}
      value="1"
      onChange={(e) => {
        props.setValue(e.currentTarget.checked);
      }}
    >
      {props.getValue() ? "YES" : "NO"}
    </ToggleButton>
  );
};

export default VisitedRenderer;

Using React-Bootstrap’s ToggleButton, you can easily create a button-style checkbox. The button is styled and labeled according to the prop’s value, which is set on every toggle with props.setValue().

Pay special attention to the id prop. It’s important for it to be unique, as React-Bootstrap uses it as an HTML id attribute, matching the underlying <input> checkbox and button-styled <label>.

Now all you have to do is load the cell renderer in src/App.jsx , and you should see toggle buttons appear in the column:

// ...
import VisitedRenderer from "./VisitedRenderer";
// ...

const App = () => {
  const [columnDefs] = useState([
    {
      headerName: "Country",
      field: "country",
    },
    {
      headerName: "Image",
      field: "image",
      flex: 1,
      cellRenderer: ImageRenderer,
    },
    {
      headerName: "Visited",
      field: "visited",
      // Set VisitedRenderer component as cell renderer
      cellRenderer: VisitedRenderer,
    },
  ]);
  // ...
};

// ...

Customizing Column Header

One of many great things about AG Grid is that it’s very customizable, far beyond custom cell renderers. You can utilize this customizability together with React-Bootstrap to build—e.g., custom column headers with different functionalities.

Setting up External Filter

For this example, you’ll build a custom header for the visited column with the ability to filter the list for only the visited countries. Start by adding an external filter to the grid in src/App.jsx :

import { useEffect, useState, useRef } from "react";
// ...

const App = () => {
  const gridRef = useRef();
  const [filterEnabled, setFilterEnabled] = useState(false);
  // ...
  const doesExternalFilterPass = (node) => {
    return node.data.visited;
  };

  useEffect(() => {
    if (gridRef.current && gridRef.current.api) {
      gridRef.current.api.onFilterChanged();
    }
  }, [filterEnabled]);

  return (
    <Card body className="h-100">
      <Stack className="h-100">
        <Card.Title>Countries to visit</Card.Title>
        <div className="ag-theme-material h-100 w-100">
          <AgGridReact
            ref={gridRef}
            columnDefs={columnDefs}
            rowData={rowData}
            rowHeight={200}
            doesExternalFilterPass={doesExternalFilterPass}
            isExternalFilterPresent={() => filterEnabled}
          ></AgGridReact>
        </div>
      </Stack>
    </Card>
  );
};

// ...

In AG Grid, external filters allow you to mix your custom filtering logic with the mechanisms already integrated into the grid. To enable them, you have to provide two additional props:

doesExternalFilterPass: This is the actual filter function; given a node, it should return a Boolean indicating whether or not to include the row in the result.
isExternalFilterPresent: This is a function returning a Boolean that informs the grid about the presence of the external filter.

In the code above, the external filter is controlled by a filterEnabled state property and a doesExternalFilterPass() function, which extracts the visited boolean from row data to filter the grid.

To make the grid process the filter accordingly on filterEnabled change, you must first inform it about a change in the filter configuration using api.onFilterChanged().

The api object is accessible on the grid element; thus, you should use the useRef() hook to create a reference to it first. Then, with the useEffect() hook, call api.onFilterChanged() every time filterEnabled changes.

Adding Toggle Button Header

With the external filter ready, now it’s just a matter of creating a custom header component that will set filterEnabled.

In src/VisitedHeader.jsx , create the following component:

import { useState, useEffect } from "react";
import ToggleButton from "react-bootstrap/ToggleButton";

const VisitedHeader = (props) => {
  const [checked, setChecked] = useState(false);

  useEffect(() => {
    props.setFilterEnabled(checked);
  }, [checked]);

  return (
    <ToggleButton
      id="filter-visited"
      type="checkbox"
      variant={checked ? "outline-primary" : "outline-secondary"}
      checked={checked}
      value="1"
      onChange={(e) => {
        setChecked(e.currentTarget.checked);
      }}
    >
      Visited
    </ToggleButton>
  );
};

export default VisitedHeader;

VisitedHeader once again uses React-Bootstrap’s ToggleButton with custom id and value-based styling. On top of that, it has its own state property, checked, to keep track of the toggle button. The parent component is notified about every change with the useEffect() and setFilterEnabled() method passed through the props.

Back in the src/App.jsx file, you should set the header component and pass the required setFilterEnabled prop:

// ...
import VisitedHeader from "./VisitedHeader";
// ...

const App = () => {
  // ...
  const [columnDefs] = useState([
    {
      headerName: "Country",
      field: "country",
    },
    {
      headerName: "Image",
      field: "image",
      flex: 1,
      cellRenderer: ImageRenderer,
    },
    {
      headerName: "Visited",
      // Set VisitedHeader component as header component
      headerComponent: VisitedHeader,
      // Pass additional props to the header component
      headerComponentParams: {
        setFilterEnabled,
      },
      field: "visited",
      cellRenderer: VisitedRenderer,
    },
  ]);

  // ...
};

// ...

It’s worth noting that AG Grid also provides a distinctive headerComponentParams property to pass custom props to the header component (aside from the grid-provided ones). The component itself can be set using the headerComponent property.

The final result looks like this:

Conclusion

In this article, you’ve learned how you can use AG Grid and React-Bootstrap together, as well as how customizable AG Grid really is. By using AG Grid’s React Data Grid, you not only get a great, highly advanced grid view but also easy access to the ecosystem of the leading JS UI framework. With such powerful tools, the only limit to your app is your imagination.

AG Grid is the leading JavaScript Grid. It should be your go-to open source tool whenever you need a batteries-included grid solution, with advanced features like live data streaming, charting, editing, and more. Check out AG Grid’s official documentation to learn more.

How to Optimize a React Application Using Hooks and AG Grid

Alan Richardson — Mon, 18 Jul 2022 11:28:52 +0000

This post contributed to the AG Grid blog by Cameron Pavey.

React describes itself as a “JavaScript library for building user interfaces.” Its internal workings are quite complex, but there are essentially two main pieces: React itself and the React renderer, which is react-dom in the case of web browsers.

The main React library is responsible for taking your code and converting it to a structure that a React renderer, such as react-dom, can then use to reconcile the desired state with the current state, and make the necessary changes for those two states to converge. How you write your code can have a great impact on the magnitude of these changes. It’s not uncommon for React to make more changes than strictly necessary when reconciling the Document Object Model (DOM). These changes, or “renders,” can typically be reduced by optimizing your code in various ways. Such optimizations are generally desirable, but even more so when dealing with large volumes of data or many DOM nodes. While unoptimized code may not be problematic in small quantities, at scale, it can quickly affect user experience.

In this guide, you’ll learn about some of these optimizations. You’ll also learn about some common mistakes that can lead to unnecessary renders, and you’ll see how you can avoid them.

AG Grid, a high-performance Data Grid, plays a large role in this guide. It works well with most leading frontend libraries, including React, and provides a good use case for the optimizations discussed here for two reasons. Firstly, AG Grid itself is optimized internally, and thus the impact of poorly optimized code surrounding it is more apparent. Secondly, AG Grid is capable of dealing with tremendous amounts of data, which can often have an adverse impact on performance if mishandled, but is also an excellent way to test the efficacy of supposed code optimizations at scale.

Profiling the Unoptimized Grid

In order to focus on the optimizations themselves, this guide won’t cover the building of the unoptimized application step by step. Instead, if you’d like to follow along, you can clone the unoptimized source code for this guide from the public GitHub repo.

You also need the following prerequisites:

a recent version of Node.js and npm
a code editor (VS Code is a good choice if you don’t have an existing preference.)

As mentioned before, AG Grid is already quite heavily optimized, so much so that any adverse performance issues you may encounter while using it are likely to be in your application code, and the code surrounding your usage of the Grid component. To this end, the optimizations covered in this article will primarily focus on this surrounding code to help ensure that you’re using AG Grid as responsibly as possible.

To establish a baseline for these optimizations, you need to see how the current unoptimized application performs. There are a few different ways to do this. The most common way is to use the React Developer Tools browser extension, which includes a purpose-built profiler. This profiler lets you see details about your application, like which components were re-rendered in a given commit, why they were re-rendered, and how long it took to do so. If you want to follow along with this tutorial, go ahead and add this extension to your browser.

Once you’ve cloned the demo application from the public GitHub repo, navigate into the newly created directory, and run the following commands:

npm install
npm run start

This command installs the code dependencies and starts the development server. Once started, the development server will indicate which port it’s running on (typically port 3000) and open the demo application in your default browser.

When the page has loaded, you should see something like this:

Open the developer tools by right-clicking somewhere on the page and selecting Inspect. By default, this will open the Elements tab. You can find the React DevTools Profiler by selecting the Profiler tab. You may need to click the arrow icon at the end of the tabs to see it:

The DevTools are quite extensive, and their full functionality is beyond the scope of this guide. If you want to learn more about the DevTools as a whole, you can start with this guide that focuses primarily on the profiling functionality.

The unoptimized Grid has a few issues that cause unnecessary re-renders. To help identify these, some visual aids have been added, but it’s also possible to see them in the profiler. To get a consistent baseline for later measurements, it helps to do some controlled checks that you can replicate later. In this initial measurement, perform the following actions:

Start the profiler recording
For each of the first four cells in the First_name column, click on the cell once
Next, click the Change Columns button four times
Stop the profiler recording

As you interact with the table, you’ll notice that some visual aspects changed like the color of the Id column and the numbers prefixing the First_name values. These are visual helpers added to show when certain components have re-rendered. Before you learn about this in more detail, let’s take a look at the results in the profiler:

Your exact output may vary if you didn’t follow the actions outlined above precisely. Near the top of the profiler, there is a small chart that you can cycle through, along with some numbers:

This chart represents the commits made by React and their relative durations. The larger the bar, the longer the commit took. In this scenario, the commits don’t take very long (the largest one only takes about 12 ms). However, the principles here apply equally to larger React applications that may be affected by more adverse performance issues, with renders that take anywhere from 100 ms to full seconds.

As you cycle through the commits, different parts of the flame graph will be highlighted, representing the re-rendered components in a given commit. Looking at the previous screenshot, you can see that in the highlighted commit (and the other similar spikes in the graph), all of the rows re-rendered. This results in the slowest commits out of those that the profiler captured. If you go back and look at the first few commits, you can similarly see that each time you clicked on one of the cells, it caused two cells to be re-rendered—the one that you clicked on and the one that you were already focused on:

This can cause inefficiencies if those cells are using expensive, poorly optimized custom cell renderers. The First_name column uses a custom cell renderer to display the counter in parenthesis. This counter will increment by one, each time the component is re-rendered. This is a fairly inexpensive operation, but you can see how often it’s triggered by clicking around on these cells. If this were a more expensive operation, it could have a significant impact. Similarly, each time you click the Change Columns button, the columnDefs prop on the AG Grid component is updated with a similar (though not identical) value. As a side effect of this, the object that defines the column’s coloring gets recreated each time this happens with a random color:

Optimizing the Grid

In the next section, you’ll learn a few techniques that you can use to optimize your application and reduce some of the unnecessary re-renders. After the optimizations, you can run the profiler again while performing the same actions listed above. This will give you clear data showing what impact the optimizations had. Before proceeding, you may want to download the data in this profile for future comparison. You can do this by clicking the down arrow icon in the top left corner:

Memoized Components

If you haven’t already done so, open the cloned codebase in your editor of choice. The first optimization to look at relates to the custom cell renderers. The counter included in this component increments each time it is re-rendered, but essentially all of these re-renders are wasted because the cell’s content doesn’t change. You can alleviate this issue with the React.memo Higher-Order Component (HOC) that wraps your components and essentially returns the previously computed value if none of the inputs changed.

Begin by opening the file located at src/components/name-formatter.jsx, which is currently just a normal Function Component. To stop it from needlessly re-computing its output, all you need to do is wrap it in the HOC like this:

import * as React from 'react';

const NameFormatter = React.memo(({ value }) => {
  const renderCountRef = React.useRef(1);
  return (
    <strong>
    {`(${renderCountRef.current++}) ${value}`}
    </strong>
  );
});

export default NameFormatter;

Please note: It’s inadvisable to simply wrap all of your components with this HOC. There is a time and a place for it, but generally, if you have a component that renders often and renders deterministically, that is, for a given set of input props, it will always give the same output. Wrapping it with React.memo can help you eliminate some excess renders.

After the application has reloaded, save your changes, and then click on the First_name cells. You should find that doing so no longer causes the counters to increment. React simply uses the previously returned value rather than rendering a newly computed value because the input props don’t change:

Caching Expensive Values

You may have noticed that when you interact with the unoptimized Grid and click the Change Columns button, the rows in the table change. This data is randomly generated with a library called @faker-js/faker. In real life, this data would likely be coming from an API endpoint. For simplicity, this data generator is being used in favor of a real API. However, the principle behind this optimization remains the same.

In this instance, the value produced by the fake data generator is not being preserved when the Grid component re-renders. Each time input props change, all of the data is regenerated. If this was an API call, it would likely be making network requests each time the props change instead. This behavior is not optimal because of its impact on performance and, in most cases, it wastes resources. Typically, it would be better to cache this value and reuse it between renders. There are some cases where you might want to regenerate or re-fetch the data, but this should be done deliberately and not as a side effect of poorly optimized code.

There are a few different React hooks that you can use to cache your data, depending on the scenario. For reference, the current unoptimized implementation in src/components/grid.jsx has the data generator function being called without any hooks, so it will be called on each render:

// Unoptimized
function Grid({ columnDefs, defaultColDef }) {
  // This will be called on each render  
  const data = getData(10);

  return (
    <div className="ag-theme-alpine" style={{ height: '98vh' }}>
    <AgGridReact
        maintainColumnOrder
        defaultColDef={defaultColDef}
        rowData={data}
        columnDefs={columnDefs}
    />
    </div>
  );
}

If your data is coming from a synchronous function, as is the case here, you can wrap the value with the React.useMemo hook. This behaves similarly to the aforementioned React.memo, but rather than being a HOC, it’s a hook that you can apply to values other than just components and its approach looks like this:

function Grid({ columnDefs, defaultColDef }) {
  // This value will now persist between renders
  const data = React.useMemo(() => getData(10), []);

  return (
    <div className="ag-theme-alpine" style={{ height: '98vh' }}>
    <AgGridReact
        maintainColumnOrder
        defaultColDef={defaultColDef}
        rowData={data}
        columnDefs={columnDefs}
    />
    </div>
  );
}

This approach works well for functions like getData here, but does not work so well for asynchronous operations like API calls. In such cases, you can instead use a combination of React.useState and React.useEffect to asynchronously call the API, and set the value into a state hook when it resolves. That approach looks like this:

function Grid({ columnDefs, defaultColDef }) {
  const [data, setData] = React.useState([]);

  // This effect will be invoked the first time the component renders
  React.useEffect(() => {
    (async () => {
            // This value will be persisted between renders
    setData(getData(10));
    })();
  }, []);

  return (
    <div className="ag-theme-alpine" style={{ height: '98vh' }}>
    <AgGridReact
        maintainColumnOrder
        defaultColDef={defaultColDef}
        rowData={data}
        columnDefs={columnDefs}
    />
    </div>
  );
}

Note that while getData is not an asynchronous function, this pattern works here and can be used with asynchronous API calls. Deciding which pattern is best for you will depend on the specifics of your application; however, between React.useState, React.useEffect, and React.useMemo, you should be able to derive a solution for most scenarios. It’s a good idea to familiarize yourself with React Hooks if you have not already done so, as they have some rather nuanced behavior but are generally quite powerful.

After applying either of these optimizations (the useMemo approach or the useEffect approach), you will discover that the rows themselves no longer change when you click Change Columns. The data is now persisted between renders:

The next optimization addresses the random colors being assigned to the Id column.

Extracting Static Values

If you look at src/app.jsx, you’ll see the following block of code:

  const updateColumns = () => {
    setColumnDefs([
    { field: 'id', cellStyle: { background: randomColor() } },
    { field: 'first_name', cellRenderer: NameFormatter },
    { field: 'last_name' },
    { field: 'email' },
    { field: 'gender' },
    { field: 'ip_address' },
    ]);
  };

The first object in this array has a property called cellStyle. This property contains a CSS style object that will be applied to all of the cells in this column. In this instance, the value of this property is dynamically computed each time the updateColumns function is called, which is why the column color changes each time you click the Change Columns button. This is a contrived example to demonstrate that passing objects by value like this results in a new instance of the object being created each time and is not desirable behavior. Even if the column definitions were to change, it’s unnecessary to recompute all of the values for all of their properties. You can eliminate the color-changing behavior of the column by making the following optimizations:

// 1. Extract the value of the cellStyle property to outside of the App component
const cellStyle = { background: randomColor() };

function App() {
…
// 2. Update the updateColumns function to use this extracted value
  const updateColumns = () => {
    setColumnDefs([
    { field: 'id', cellStyle },
    { field: 'first_name', cellRenderer: NameFormatter },
    { field: 'last_name' },
    { field: 'email' },
    { field: 'gender' },
    { field: 'ip_address' },
    ]);
  };

Now, whenever updateColumns is called, although the columnDefs prop will still change, the style object applied to the Id column will remain consistent, thus eliminating the random color changes. It should be noted that it will still change color after the first time you click the Change Columns button, as the initial value supplied to the useState hook does not have a cellStyle supplied for that column.

Profiling the Optimized Grid

With these optimizations applied, you can see that AG Grid’s behavior is perceptibly less erratic. Now it’s time to profile the application again to see if these optimizations have a measurable impact. To do this, run through the same actions taken during the first measurements, listed here again for your convenience:

Start the profiler recording
For each of the first four cells in the First_name column, click on the cell once
Next, click the Change Columns button four times
Stop the profiler recording

After stopping the profiler, you should see something like this:

You will note that the number of commits is down to twelve (from the original twenty-six), and there is only one large spike this time (instead of four), which corresponds with the one time the cellStyle changes. The optimizations have had a respectable impact on the render performance of this application.

Understanding how and why these optimizations work puts you in a position to apply them at your discretion. Not every application will be as simple as this contrived example, but the patterns used here are generally applicable in many real-world scenarios.

Increasing the Amount of Data

In a real application, you will likely be dealing with much larger volumes of data than the ten rows in this demo application. To ensure these optimizations hold up under load, you can easily tweak the random data generator call found in src/components/grid.jsx to generate 100,000 rows of data or more. To do this, tweak the useEffect block this way:

  React.useEffect(() => {
    (async () => {
    setData(getData(100000));
    })();
  }, []);

Now, if you save and reload the page, you should see a lot more data. You can run the profiler and step through the actions again, but you will likely find that there isn’t any perceptible performance difference. This is largely thanks to optimizations built into AG Grid, including virtualization.

A source of performance issues for many browsers is the DOM. When the DOM has too many nodes (such as 100,000 table rows), it’s easy for performance to suffer if these nodes exhibit any kind of complexity beyond being simple text containers. One of the most common ways to solve this is through DOM Virtualization, where only the visible elements are rendered. As the user scrolls, React will render new elements as they come into view, and old elements will be removed once they are no longer visible. You can see this in practice using React DevTools.

Aside from the profiler, there is also a Components tab that you can access. This tab will show you all of the React components rendered on the page and details about them. If you navigate to this view and scroll down the Grid, you will notice that the number of row components doesn’t increase or decrease much (there is slight fluctuation when rows are half visible), but the rows themselves change. This is virtualization in action:

Conclusion

In this article, you’ve seen how poorly optimized code can have a detrimental impact on the render performance of your application. You have also learned how to leverage React Hooks to apply optimizations to reduce this impact. It’s important to be aware of optimizations like these to avoid making such mistakes in your applications. Those mistakes can lead to unnecessary re-renders even when using highly optimized libraries like AG Grid.

Aside from DOM virtualization, AG Grid applies numerous optimizations internally to ensure that there are no wasted renders from the library itself. Keenly optimized performance is just one of the benefits. AG Grid also has numerous powerful features, from handling massive amounts of data to livestreaming data updates and integrated charting. If you’re looking for a robust all-in-one Data Grid solution, and performance is a must, give AG Grid a try.

All the code samples in this article can be found in this GitHub repo.

AG Grid: Typescript Generics

Stephen Cooper — Thu, 14 Jul 2022 10:31:53 +0000

In this article, we will show you how to make the most of Typescript Generics in AG Grid v28. We will demonstrate the great developer experience it unlocks with the help of code examples.

AG Grid Generic Types

There are two generic types that you can pass to AG Grid interfaces. They are: TData and TValue.

TData - Row Data Type

TData is used to represent the shape of row data items. This generic parameter should match the interface used when defining your row data. If an AG Grid interface has a TData generic parameter this will always refer to the row data type.



interface GridOptions<TData = any>{
    rowData: TData[] : null;
}

To maintain backwards compatibility a default type of any is provided. This mimics the behaviour of previous versions of AG Grid that explicitly type the rowData as any[].

TValue - Cell Value Type

TValue is used to represent the type of a specific cell value. This generic type is more limited in scope and can be used within cell renderers/value getters when you want to give a type to the value property.



export interface GetQuickFilterTextParams<TData = any, TValue = any> {
    /** Value for the cell. */
    value: TValue;
}

As with TData, we also default TValue to any to maintain backwards compatibility.

Using Generic Types

In the examples below we use the ICar interface to represent row data.



// Row Data interface
interface ICar {
    make: string;
    model: string;
    price: number;
}

var rowData: ICar[] = [
  { make: "Toyota", model: "Celica", price: 35000 },
  { make: "Porsche", model: "Boxster", price: 72000 }
];

The best place to assign ICar to the TData generic parameter is via the GridOptions interface. This will cascade the generic type down the interface hierarchy.



// Pass ICar to GridOptions as a generic
const gridOptions: GridOptions<ICar> = {
    // rowData is typed as ICar[]
    rowData: [ { make: 'Ford', model: 'Galaxy', price: 200 } ]
}

With the generic parameter set to ICar, the rowData property has the type ICar[] instead of the default any[]. This means that if you mistype one of the properties you will get a compile-time error.

It is worth noting that it is not just rowData where the interface is used. For example, in the getRowId callback, the params.data property is typed as ICar instead of any. This is a result of AG Grid cascading the generic type down from GridOptions.

This also applies to all the grid events that contain a data property. i.e onRowSelected.



const gridOptions: GridOptions<ICar> = {
    // Callback with params type: GetRowIdParams<ICar>
    getRowId: (params) => {
        // params.data : ICar
        return params.data.make + params.data.model;
    },

    // Event with type: RowSelectedEvent<ICar>
    onRowSelected: (event) => {
        // event.data: ICar | undefined
        if (event.data) {
            const price = event.data.price;
        }
    }
}

If you use the grid api via gridOptions.api or callback params.api properties, then the api will be aware of the row data type too. This means that the method api.getSelectedRows() will return rows as ICar[].



// Grid Api methods use ICar interface
function onSelection() {
  const cars: ICar[] = gridOptions.api!.getSelectedRows();  
}

Configure via Individual Interfaces

While it is possible to configure everything inline within a gridOptions object, you may want to split things out for readability / re-usability. To benefit from Typescript generics we can provide our ICar interface to any AG Grid interface that accepts a TData generic parameter.

For example, we could configure our event handler with
RowSelectedEvent<ICar>. This results in the event.data property being typed as ICar | undefined. (See Generic Type or Undefined below for more details on the additional undefined type).



function onRowSelected(event: RowSelectedEvent<ICar>) {
    if (event.data) {
        // event.data: ICar | undefined
        const price = event.data.price;
    }
}

Advantages over any

There are two main reasons to provide generic types to AG Grid:

Compile-time errors
Auto-completion in your IDE

Compile Time Errors

Say we mistyped price as prive. Without generics, your application code would compile but your grid would no longer show prices in the grid. You would then have to track down the source of the bug. It could even be possible that this type of bug escapes into production if it slips past your tests.

However, if you supply generic types your application would not compile and would tell you the exact location of the bug. This enables you to instantly correct the code, instead of having to track down the bug. It will also be underlined with a red squiggle in your IDE!

Auto-Completion

As Typescript knows that our data object conforms to the ICar interface our IDE can suggest properties to us. This speeds up your development process as you do not have to spend time thinking about property names as they are suggested to you automatically.

Framework Specific Demo

React

If you are using AG Grid via the React component then you can pass your row data type to the AgGridReact component via this syntax: <AgGridReact<ICar>.

This will validate that all props conform to the row data type.



<AgGridReact<ICar>
   ref={gridRef}
   rowData={rowData}
   columnDefs={columnDefs}
   onGridReady={onGridReady}
></AgGridReact>

If you provide conflicting types you will get a compile-time error. For example, here we have provided a different generic type, INotCar to the onGridReady event which does not match our rowData of ICar.

Angular

For Angular, providing a type to your rowData property is enough to enable generics for the entire component.



 public rowData: ICar[];



 <ag-grid-angular
      [columnDefs]="columnDefs"
      [rowData]="rowData"
      (gridReady)="onGridReady($event)"
    ></ag-grid-angular>

If you are not using the rowData property, then type any other input/output that takes the generic parameter. For example, setting the following type on the onGridReady event would set the generic type for the entire component.



onGridReady(event: GridReadyEvent<ICar>) { }

Generic Type or Undefined

One thing you may notice when adding generic support to an existing application is that you may get errors relating to the data property potentially being undefined. You will not have seen this previously as the data property was typed as any which silently includes undefined. By specifying the type explicitly, AG Grid has the opportunity to warn you, via typings, that the data property could be undefined under some circumstances.

To demonstrate this we will look at a common pitfall that users have when adding custom cell renderers while supporting row grouping.

Common Pitfall with Cell Renderers

When writing a custom cell renderer you are likely to access the data property from the ICellRendererParams interface. Your first attempt may have code that accesses data properties with no undefined checks.



init(params: ICellRendererParams) => {
   this.total = params.data.gold + params.data.silver + params.data.bronze;
};

This may work in your application but it is not technically correct or future-proof.

If you have row grouping enabled then as soon as the user groups by a column your cell renderer will fail. This is because when grouping the data property is undefined.

However, if you provide a generic type to ICellRendererParams, such as IOlympicData, your code will warn that the data property can be undefined.

With the generic type supplied you are more likely to correctly write the cell renderer to handle this case.



init(params: ICellRendererParams<IOlympicData>) => {
    if(params.data){
        this.total = params.data.gold + params.data.silver + params.data.bronze;
    }else{
        this.total = undefined;
    }
};

While it is possible to silence the "Object is possibly 'undefined'" errors with a non-null operator !. such as params.data!.gold, we would recommend writing your code defensively in line with the AG Grid interfaces.

Conclusion

If you are using Typescript then we would encourage you to take advantage of our generic types to give you:

Compile-time errors
Auto-completion in your IDE
Improved code typings

It is a small change in your type definitions that results in a greatly improved developer experience!

For more details visit our Typescript Generics documentation.