Dimension Animation

DimensionAnimationPlugin is a plugin that animates grid dimension sizes. Use it when a feature needs rows or columns to collapse, expand, or move between explicit sizes without replacing the grid’s own virtualization and dimension systems.

The plugin only animates sizes. It does not own row visibility, trimming, grouping, ordering, or business state. Callers decide what should become hidden or visible, then use the plugin to make the size transition smooth.

When to use it

• Animate custom row or column collapse and expand flows.
• Animate explicit size changes when you already know the start and end sizes.
• Coordinate delayed state changes around animation completion.
• Support integrations such as tree rows, where TreeDataPlugin handles trim state and DimensionAnimationPlugin handles the visual transition.

Installation

import { DimensionAnimationPlugin } from '@revolist/revogrid-pro';

const grid = document.querySelector('revo-grid');

grid.plugins = [DimensionAnimationPlugin];
grid.dimensionAnimation = {
  duration: 180,
  easing: 'easeOutCubic',
  types: ['rgRow'],
};

Configure the plugin through grid.dimensionAnimation. The older additionalData.dimensionAnimation path is still accepted for compatibility, but grid.dimensionAnimation is the supported API.

Property	Default	Description
duration	180	Animation duration in milliseconds. Use 0 to apply sizes synchronously.
easing	'easeOutCubic'	Easing used while interpolating sizes. Supports 'linear', 'easeOutCubic', or a custom (progress) => number function.
types	All row and column dimensions	Dimensions affected by requests that do not pass a specific type.

Controller API

After the plugin is registered, use its controller methods to animate indexes or explicit frames.

const plugins = await grid.getPlugins();
const dimensionAnimation = plugins.find(
  plugin => plugin instanceof DimensionAnimationPlugin,
);

await dimensionAnimation?.collapse([0, 1, 2], {
  type: 'rgRow',
  indexKind: 'visual',
});

await dimensionAnimation?.expand([0, 1, 2], {
  type: 'rgRow',
  indexKind: 'visual',
});

Use indexKind: 'physical' when indexes refer to source rows or columns. Use indexKind: 'visual' when indexes refer to the current rendered order after sorting, filtering, trimming, pinning, or other view changes.

Explicit frames

Use animate() when you already know the visual indexes and target sizes.

await dimensionAnimation?.animate([
  {
    type: 'rgCol',
    visualIndex: 0,
    from: 220,
    to: 80,
  },
]);

The plugin cancels any in-flight animation that targets the same dimension index before starting the next one. Call cancel() directly to stop matching animations, or omit arguments to cancel all dimension animations.

dimensionAnimation?.cancel('rgRow', [0, 1]);
dimensionAnimation?.cancel();

Event API

You can also request animations by dispatching the dimensionanimate event from the grid element. The plugin attaches detail.done synchronously, so event-driven integrations can wait before applying follow-up logic.

const detail = {
  action: 'collapse',
  indexes: [0],
  type: 'rgRow',
  indexKind: 'visual',
};

grid.dispatchEvent(new CustomEvent('dimensionanimate', { detail }));

await detail.done;

Listen to beforedimensionanimate to cancel an operation before it starts. Listen to afterdimensionanimate to react after the animation completes or is cancelled.

grid.addEventListener('beforedimensionanimate', event => {
  if (event.detail.action === 'collapse' && shouldBlockCollapse()) {
    event.preventDefault();
  }
});

grid.addEventListener('afterdimensionanimate', event => {
  console.log(event.detail.results);
});

Tree integration

Tree rows can use dimension animation automatically. Enable tree.animation; TreeDataPlugin registers DimensionAnimationPlugin when it is not already present.

import { TreeDataPlugin } from '@revolist/revogrid-pro';

grid.plugins = [TreeDataPlugin];
grid.tree = {
  animation: true,
};
grid.dimensionAnimation = {
  duration: 180,
};

In this flow, TreeDataPlugin owns tree trim state and expansion state. DimensionAnimationPlugin only animates the affected row sizes during collapse and expand.

API reference

• Dimension Animation API
• Tree guide