wijmo.grid.immutable Class ImmutabilityProvider Wijmo API Class

ImmutabilityProvider Class

The ImmutabilityProvider object, being attached to a wijmo.grid.FlexGrid control, allows the latter to perform data edits without mutating the underlying data. Instead, this class provides a data change event, which can be used to dispatch change actions to the global Store, such as a Redux Store.

In framework interops, this class is usually represented by a framework specific component, like a wijmo.react.grid.immutable.ImmutabilityProvider component for React, which is more convenient to use in the context of the framework.

The controlled FlexGrid control should not specify its itemsSource. Instead, the itemsSource property of this class instance should be assigned with the immutable array from the Store, which grid will display and edit.

When a user edits data via the datagrid, the wijmo.grid.immutable.ImmutabilityProvider.dataChanged event is triggered, bringing all the necessary information to you about the change (which item is affected, if item was changed or added or deleted, and so on). This event should be used to dispatch corresponding data change actions to the Store.

Note that FlexGrid edits data on a row level basis, which means that you can change multiple cell values in the same row, and only after you move focus out of the row, all the changes to the row will be applied simultaneously. Or you can press the Cancel key to cancel all the changes in the row. The same is true for adding a row into the datagrid.

Note also that some changes like pasting a text into the datagrid, or deleting rows, can affect multiple rows. In this case ImmutabilityProvider will trigger the ImmutabilityProvider.dataChanged event multiple times, separately for each affected row. This simplifies data change processing in the Store reducers.

This example demonstrates a fully editable FlexGrid component, with an associated ImmutabilityProvider component bound to an array from the Redux Store. The dataChanged event handler dispatches corresponding data change actions to the Store.

  import { ImmutabilityProvider, DataChangeEventArgs, DataChangeAction } from '@grapecity/wijmo.grid.immutable';
  import { FlexGrid } from '@grapecity/wijmo.grid';
  import { store } from './store';
  import { addItemAction, removeItemAction, changeItemAction } from './actions';

  const grid = new FlexGrid('#grid', {
      allowAddNew: true,
      allowDelete: true
  const provider = new ImmutabilityProvider(grid, {
      itemsSource: store.getState().items,
      dataChanged: (s: ImmutabilityProvider, e: DataChangeEventArgs) => {
         switch (e.action) {
              case DataChangeAction.Add:
              case DataChangeAction.Remove:
                  store.dispatch(removeItemAction(e.newItem, e.itemIndex));
            case DataChangeAction.Change:
                  store.dispatch(changeItemAction(e.newItem, e.itemIndex));
  store.subscribe(() => {
      provider.itemsSource = store.getState().items;


  • ImmutabilityProvider



  • Creates an instance of the ImmutabilityProvider attached to the specified FlexGrid control.


    • grid: FlexGrid

      FlexGrid control to attach to.

    • Optional options: any

      Initialization options for the ImmutabilityProvider instance.

    Returns ImmutabilityProvider



collectionView: CollectionView

Gets a CollectionView object internally maintained by the ImmutabilityProvider. You can not change data in this CollectionView, instead any data changes must be dispatched to the Store. But you can change its sort/group/filter settings, use currency and data change events.


grid: FlexGrid

Gets a FlexGrid instance controlled by the ImmutabilityProvider.


itemsSource: any

Gets or sets a source data array that should be displayed in the controlled FlexGrid. The FlexGrid.itemsSource property should not be assigned. Every time a new version of the source array appears in the Store, this property must be re-assigned with this new array instance. This can be done, for example, in the handler function for the Store change event.






Triggered when FlexGrid needs to create a clone of an item which is about to be changed.

This event allows you to provide a custom logic for cloning items. The cloned item should be assigned to the CloningItemEventArgs.clonedItem property of the event arguments.


Triggered after a user has added, removed or changed a data item in the controlled FlexGrid instance. Can be used to dispatch a corresponding data change action to the Store.