# Dimension Animation
URL: https://pro.rv-grid.com/guides/grid-utilities/dimension-animation/
Source: src/content/docs/guides/grid-utilities/dimension-animation.mdx
Description: Animate row and column dimension sizes for custom collapse, expand, and resize flows.
`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

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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](/api/dimension-animation/)
- [Tree guide](/guides/data-manage/tree/)
