feat(animations): tailored initial-mount animations per chart type, progressive marker reveal, reduced-motion

Each chart type gets a default animation tuned for its data shape:
Line/area/rangeArea: pen-stroke draw via stroke-dashoffset + per-series mask wipe for fills; forecast paths preserve dasharray through mask reveal
Bar/stacked/range-bar/funnel: left-to-right grow with stagger auto-scaled to bar count; stacked cascade bottom-to-top; non-trapezoid funnel/pyramid wipe outward from center
Scatter/bubble: scale-up pop with easeOutBack overshoot + x-stagger
HeatMap: diagonal-wave cell reveal ordered by (row + col)
Treemap: largest-tile-first cascade — bigger tiles land before smaller ones
Radar: stroke-draw around the perimeter + radial mask blooming from centroid
Pie/donut/polarArea: center label fades in after slices land; pre-selected slice pull-out deferred until after sweep
Gauge: needle settles from startAngle with easeOutBack overshoot; ticks/labels fade in after sweep
Progressive marker reveal: markers, data labels, datalabel pills, and xaxis/point annotations snap in at the moment the line tip reaches their x — rAF-synced and inverse-eased to match easeOutCubic

Stagger across all chart types driven by the existing animateGradually config

Author: junedchhipa

src/apexcharts.js

@@ -12,6 +12,7 @@ import { getThemePalettes } from './utils/ThemePalettes.js'
 import XAxis from './modules/axes/XAxis'
 import YAxis from './modules/axes/YAxis'
 import InitCtxVariables from './modules/helpers/InitCtxVariables'
+import { applyAnimationPolicy } from './modules/Animations'
 import Destroy from './modules/helpers/Destroy'
 import { register } from './modules/ChartFactory'
 import { addResizeListener, removeResizeListener } from './utils/Resize'
@@ -83,6 +84,8 @@ export default class ApexCharts {
       ? Utils.escapeString(this.w.config.chart.id)
       : this.w.globals.cuid
 
+    applyAnimationPolicy(this.w)
+
     const initCtx = new InitCtxVariables(this)
     initCtx.initModules()
 

src/charts/Bar.js

@@ -5,6 +5,7 @@ import CoreUtils from '../modules/CoreUtils'
 import Utils from '../utils/Utils'
 import Filters from '../modules/Filters'
 import Graphics from '../modules/Graphics'
+import { computeStagger } from '../modules/Animations'
 import Series from '../modules/Series'
 
 /**
@@ -456,10 +457,40 @@ class Bar {
       pathFill = 'none'
     }
 
-    const delay =
-      ((j / w.config.chart.animations.animateGradually.delay) *
-        (w.config.chart.animations.speed / w.globals.dataPoints)) /
-      2.4
+    // Per-bar stagger delay. The base step is auto-scaled so total stagger
+    // (across all bars in a row/column) caps at ~half the animation speed —
+    // a 5-bar chart and a 50-bar chart finish in similar wall-clock time.
+    // For stacked bars: bottom layers (lower `i`) animate first, top layers
+    // cascade on a smaller offset so each stack visibly "builds up".
+    //
+    // Note: animatePathsGradually() multiplies the passed `animationDelay` by
+    // `animateGradually.delay` (the "delayFactor"). To express the stagger in
+    // real milliseconds we divide by that factor here so the multiplication
+    // cancels — otherwise a 40ms intended delay would become 40×150=6000ms.
+    const animCfg = w.config.chart.animations
+    const gradCfg = animCfg.animateGradually
+    const staggerEnabled = gradCfg && gradCfg.enabled !== false
+    let delay = 0
+    if (staggerEnabled) {
+      const totalBars = w.globals.dataPoints || 1
+      const configStep = gradCfg.delay || 0
+      const baseDelayMs = Math.min(
+        configStep,
+        (animCfg.speed * 0.5) / Math.max(1, totalBars),
+      )
+      let delayMs = computeStagger({
+        style: 'sequential',
+        index: j,
+        baseDelay: baseDelayMs,
+      })
+      if (w.config.chart.stacked) {
+        delayMs += i * baseDelayMs * 0.5
+      }
+      // Convert ms → delayFactor units so animatePathsGradually's
+      // `delay * delayFactor` reproduces our intended ms delay.
+      const delayFactor = configStep || 1
+      delay = delayMs / delayFactor
+    }
 
     if (!skipDrawing) {
       const renderedPath = /** @type {any} */ (

src/charts/HeatMap.js

@@ -1,5 +1,5 @@
 // @ts-check
-import Animations from '../modules/Animations'
+import Animations, { computeStagger } from '../modules/Animations'
 import Graphics from '../modules/Graphics'
 import Fill from '../modules/Fill'
 import Series from '../modules/Series'
@@ -164,7 +164,7 @@ export default class HeatMap {
           if (!w.globals.resized) {
             speed = w.config.chart.animations.speed
           }
-          this.animateHeatMap(rect, x1, y1, xDivision, yDivision, speed)
+          this.animateHeatMap(rect, x1, y1, xDivision, yDivision, speed, i, j)
         }
 
         if (w.globals.dataChanged) {
@@ -241,9 +241,38 @@ export default class HeatMap {
    * @param {number} width
    * @param {number} height
    * @param {number} speed
+   * @param {number} [row] - series index (heatmap row)
+   * @param {number} [col] - data point index (heatmap column)
    */
-  animateHeatMap(el, x, y, width, height, speed) {
+  animateHeatMap(el, x, y, width, height, speed, row = 0, col = 0) {
+    const w = this.w
     const animations = new Animations(this.w)
+
+    // Diagonal-wave stagger: cells animate in order of (row + col), so the
+    // reveal travels from top-left to bottom-right. Total stagger is capped
+    // at ~half the animation speed regardless of grid size.
+    const animCfg = w.config.chart.animations
+    const gradCfg = animCfg.animateGradually
+    const staggerEnabled = gradCfg && gradCfg.enabled !== false
+
+    let delay = 0
+    if (staggerEnabled) {
+      const seriesCount = (w.seriesData.series || []).length || 1
+      const pointsCount = w.globals.dataPoints || 1
+      const maxDiag = seriesCount + pointsCount - 2
+      const baseDelay = Math.min(
+        gradCfg.delay || 0,
+        (speed * 0.5) / Math.max(1, maxDiag),
+      )
+      delay = computeStagger({
+        style: 'diagonal',
+        index: col,
+        row,
+        col,
+        baseDelay,
+      })
+    }
+
     animations.animateRect(
       el,
       {
@@ -262,6 +291,7 @@ export default class HeatMap {
       () => {
         animations.animationCompleted(el)
       },
+      delay,
     )
   }
 

src/charts/Line.js

@@ -818,7 +818,11 @@ class Line {
     const dataLabels = new DataLabels(this.w, this.ctx)
 
     if (!this.pointsChart) {
-      if (w.seriesData.series[i].length > 1) {
+      // Progressive marker reveal handles per-marker opacity timing (synced
+      // to the line draw), so the legacy group-level hide is bypassed on
+      // initial mount. Data updates and resizes still use the old code path.
+      const useProgressive = !w.globals.dataChanged && !w.globals.resized
+      if (!useProgressive && w.seriesData.series[i].length > 1) {
         this.elPointsMain.node.classList.add('apexcharts-element-hidden')
       }
 

src/charts/Pie.js

@@ -197,17 +197,33 @@ class Pie {
     elPie.add(elSeries)
 
     if (this.donutDataLabels.show) {
+      // On initial mount with animations enabled, the center label starts
+      // hidden and fades in after the last slice finishes its sweep — so the
+      // total/center value lands *with* the chart instead of before it.
+      const shouldFadeInLabels =
+        this.initialAnim &&
+        !w.globals.resized &&
+        !w.globals.dataChanged &&
+        this.animDur > 0
       const dataLabels = this.renderInnerDataLabels(
         this.dataLabelsGroup,
         this.donutDataLabels,
         {
           hollowSize: this.donutSize,
           centerX: this.centerX,
           centerY: this.centerY,
-          opacity: this.donutDataLabels.show,
+          opacity: shouldFadeInLabels ? 0 : this.donutDataLabels.show,
         },
       )
 
+      if (shouldFadeInLabels) {
+        const labelsNode = this.dataLabelsGroup.node
+        labelsNode.style.transition = 'opacity 280ms ease-out'
+        setTimeout(() => {
+          labelsNode.style.opacity = '1'
+        }, this.animDur)
+      }
+
       elPie.add(dataLabels)
     }
 
@@ -392,7 +408,21 @@ class Pie {
         typeof w.interact.selectedDataPoints[0] !== 'undefined' &&
         w.interact.selectedDataPoints[0].indexOf(i) > -1
       ) {
-        this.pieClicked(i)
+        // Defer the "pulled out" offset for pre-selected slices until after
+        // the sweep finishes. Otherwise the slice translates while it's still
+        // growing, which makes both motions hard to read.
+        if (
+          this.initialAnim &&
+          !w.globals.resized &&
+          !w.globals.dataChanged &&
+          this.animDur > 0
+        ) {
+          const _this = this
+          const _i = i
+          setTimeout(() => _this.pieClicked(_i), this.animDur)
+        } else {
+          this.pieClicked(i)
+        }
       }
 
       if (w.config.dataLabels.enabled) {

src/charts/Radar.js

@@ -224,6 +224,9 @@ class Radar {
           strokeWidth: 0,
           fill: pathFill,
           drawShadow: false,
+          // Radial mask: the area fill blooms outward from the radar's center
+          // (in this group's local coords) instead of the default L→R rect wipe.
+          drawMask: { type: 'radial', cx: 0, cy: 0, r: this.size },
         })
 
         if (w.config.chart.dropShadow.enabled) {

src/charts/Radial.js

@@ -5,6 +5,8 @@ import Fill from '../modules/Fill'
 import Graphics from '../modules/Graphics'
 import Filters from '../modules/Filters'
 import Series from '../modules/Series'
+import { BrowserAPIs } from '../ssr/BrowserAPIs'
+import { Environment } from '../utils/Environment'
 
 /**
  * ApexCharts Radial Class for drawing Circle / Semi Circle Charts.
@@ -116,6 +118,20 @@ class Radial extends Pie {
         centerY,
         series,
       })
+      // On initial mount, ticks/labels fade in after the value arc + needle
+      // finish their sweep — so they read as a "settled" annotation rather
+      // than competing for attention during the gauge animation.
+      const isInitialMount =
+        this.initialAnim && !w.globals.dataChanged && !w.globals.resized
+      if (isInitialMount && Environment.isBrowser() && w.globals.shouldAnimate) {
+        const ticksNode = elTicks.node
+        ticksNode.style.opacity = '0'
+        ticksNode.style.transition = 'opacity 280ms ease-out'
+        const sweepDur = w.config.chart.animations.speed || 800
+        setTimeout(() => {
+          ticksNode.style.opacity = '1'
+        }, sweepDur)
+      }
       elSeries.add(elTicks)
     }
 
@@ -786,10 +802,42 @@ class Radial extends Pie {
     // chart center, transform-origin set to (cx, cy).
     const value = Number(opts.series[0])
     const targetAngle = this._angleAtValue(value)
-    g.attr({
-      'transform-origin': `${cx} ${cy}`,
-      transform: `rotate(${targetAngle})`,
-    })
+
+    const isInitialMount =
+      this.initialAnim && !w.globals.dataChanged && !w.globals.resized
+    if (isInitialMount && Environment.isBrowser() && w.globals.shouldAnimate) {
+      // Animate the needle from the gauge's start angle to its target with an
+      // ease-out-back curve so it visibly settles past the target and bounces
+      // back, like a real spring-loaded gauge needle.
+      const fromAngle = this.startAngle
+      const node = g.node
+      node.setAttribute('transform-origin', `${cx} ${cy}`)
+      node.setAttribute('transform', `rotate(${fromAngle})`)
+
+      const speed =
+        (cfg.animationSpeed && Number(cfg.animationSpeed)) ||
+        w.config.chart.animations.speed ||
+        800
+      const c1 = 1.70158
+      const c3 = c1 + 1
+      /** @param {number} t */
+      const ease = (t) => 1 + c3 * Math.pow(t - 1, 3) + c1 * Math.pow(t - 1, 2)
+
+      const startAt = performance.now()
+      /** @param {number} now */
+      const step = (now) => {
+        const t = Math.max(0, Math.min(1, (now - startAt) / speed))
+        const angle = fromAngle + (targetAngle - fromAngle) * ease(t)
+        node.setAttribute('transform', `rotate(${angle})`)
+        if (t < 1) BrowserAPIs.requestAnimationFrame(step)
+      }
+      BrowserAPIs.requestAnimationFrame(step)
+    } else {
+      g.attr({
+        'transform-origin': `${cx} ${cy}`,
+        transform: `rotate(${targetAngle})`,
+      })
+    }
 
     return g
   }

src/charts/Scatter.js

@@ -1,5 +1,5 @@
 // @ts-check
-import Animations from '../modules/Animations'
+import Animations, { computeStagger } from '../modules/Animations'
 import Fill from '../modules/Fill'
 import Filters from '../modules/Filters'
 import Graphics from '../modules/Graphics'
@@ -168,18 +168,26 @@ export default class Scatter {
     }
 
     if (this.initialAnim && !w.globals.dataChanged && !w.globals.resized) {
-      const speed = w.config.chart.animations.speed
-
-      anim.animateMarker(
-        el,
-        speed,
-        /** @type {any} */ (w.globals).easing,
-        () => {
-          window.setTimeout(() => {
-            anim.animationCompleted(el)
-          }, 100)
-        },
-      )
+      const animCfg = w.config.chart.animations
+      // Pop effect: scale + opacity per marker. Per-point left-to-right
+      // stagger is driven by `animateGradually`.
+      const popSpeed = animCfg.speed
+      const totalPoints = w.globals.dataPoints || 1
+      const gradCfg = animCfg.animateGradually
+      const gradEnabled = gradCfg && gradCfg.enabled !== false
+      const baseDelay = gradEnabled
+        ? Math.min(20, (popSpeed * 0.5) / Math.max(1, totalPoints))
+        : 0
+      const delay = computeStagger({
+        style: baseDelay > 0 ? 'sequential' : 'none',
+        index: dataPointIndex,
+        baseDelay,
+      })
+      anim.animatePop(el, {
+        speed: popSpeed,
+        delay,
+        onComplete: () => anim.animationCompleted(el),
+      })
     } else {
       w.globals.animationEnded = true
     }