Animation

withAnimation makes a chart draw itself in rather than appear finished, and move between shapes when its data changes. Bars grow out of the baseline — a stack of them as one column, and a row arriving in or leaving one moves with the column rather than on its own, so its divisions hold throughout — lines and areas are wiped on, and on an update points, bars and axis ticks travel to where the new numbers put them. A radial mark's slices sweep round the ring to their new shares.

Reach for it where the chart is the page's subject and the reader is watching it arrive, or where it restates the same measure as they change a filter or a date range. Leave it off where the chart is one figure among many — a sparkline in a table, a tile on a dashboard of twelve, where a dozen entrances at once is noise — and for anything redrawing faster than it can finish.

Readers who ask for reduced motion get the finished chart, and so does a chart that has only been resized.

Animating a data change

The entrance plays once. After that, animation earns its place on updates: give the chart a new set of marks and the shapes it already has travel to the new values, so the reader can follow which bar became which instead of being handed a different picture.

Sweeping a ring

A radial mark redivides the whole ring when its data changes rather than resizing one wedge, so every slice both changes width and moves round. With withAnimation they sweep round to their new shares together, which is what lets the reader keep hold of a slice across the change instead of being handed a different ring.

Toggling a legend entry is the case this matters most for. A slice arriving grows out of the boundary it is going to occupy and one leaving shrinks back into it, so the ring stays whole the whole way through, and interrupting a sweep picks it up from wherever it has got to. It works the same on a pie, a donut and a gauge — press the entries below and watch the ring redivide.

The ring travels when it changes size, too. Hiding a series can leave the ring a different size, and it grows or shrinks into that size alongside the slices rather than resizing in a single frame.

A legend beside the plot moves with it. Hiding a series can change how much room the column needs, and it slides to its new position on the same timing as the ring rather than jumping there. Resizing the chart is not a change of that kind: the legend lands with the plot in the frame it is dragged through.

A slice is matched across the change by the series that names it, so it stays the same slice however the ring is redivided. Where a mark has no series — a gauge, or a one-color pie — give it key so its rows keep their identity.

Keys and reordering

A mark works out which shape became which from each row's identity, falling back to its position along the category axis and then to its index. That is right for a time series, and wrong for a ranking, where the row that moved from third to first would be animated as the third bar changing height rather than as a bar moving up. key says the entity is the same one:

bar({ data: ranked, x: 'value', y: 'label', key: 'id', orientation: 'horizontal' });

Across series, a shape is matched by the color it is painted in. So a change that hands the palette out differently — new rows in a new order, which is what switching the metric a chart is drawn from usually means — travels each band of a stack to its new share rather than repainting the whole column, even though the series a band stands for has changed.