apexcharts-skill 3.1.0 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/.cursorrules +71 -44
  2. package/README.md +8 -8
  3. package/SKILL.md +97 -70
  4. package/package.json +1 -1
  5. package/references/bar-charts.md +17 -4
  6. package/references/cartesian-charts.md +8 -1
  7. package/references/circular-charts.md +20 -7
  8. package/references/feature-platform.md +83 -22
  9. package/references/financial-charts.md +28 -12
  10. package/references/framework-wrappers.md +36 -6
  11. package/references/grid-charts.md +10 -7
  12. package/references/ssr.md +22 -10
  13. package/references/tree-shaking.md +77 -45
package/SKILL.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: apexcharts
3
3
  description: >
4
- AI skill for building ApexCharts.js charts and data visualizations (targets v7).
4
+ AI skill for building ApexCharts.js charts and data visualizations (targets v8).
5
5
  Use when the user asks to create, configure, or troubleshoot any chart using ApexCharts
6
6
  (line, area, bar, pie, donut, radialBar, scatter, bubble, heatmap, candlestick, boxPlot,
7
7
  violin, histogram, radar, polarArea, rangeBar, rangeArea, treemap, funnel, pyramid, gauge,
@@ -9,14 +9,14 @@ description: >
9
9
  correct data formats, lifecycle, formatters, tree-shaking, SSR, and the feature
10
10
  platform (plugins, canvas renderer, custom series, small multiples, undo/redo,
11
11
  shareable views, themes, crossfilter, annotation authoring, storyboard, streaming,
12
- drilldown). Knows which features ship in the default v7 bundle and which are an
13
- explicit import. In React /
12
+ drilldown, highlight filter). Knows which chart types and features ship in the
13
+ default v8 bundle and which need an explicit import or the full bundle. In React /
14
14
  Vue / Angular projects, prefer the framework wrapper packages
15
15
  (`react-apexcharts`, `vue3-apexcharts`, `ng-apexcharts`) over the core API.
16
16
  metadata:
17
17
  author: ApexCharts
18
- version: "3.1.0"
19
- library_version: "7.6.1"
18
+ version: "4.0.0"
19
+ library_version: "8.0.0"
20
20
  category: data-visualization
21
21
  tags: [charts, visualization, javascript, typescript, svg, apexcharts]
22
22
  docs: https://apexcharts.com/docs/
@@ -33,40 +33,43 @@ metadata:
33
33
  >
34
34
  > Wrappers handle `destroy()` automatically on unmount, accept reactive props, and forward events as idiomatic framework events. Use the core API directly only when no framework is detected, or when the user explicitly asks for vanilla. See `references/framework-wrappers.md`.
35
35
 
36
- > **Targets ApexCharts v7.** Read the next box before writing any feature code: v7's headline change is that the default bundle no longer contains every feature.
36
+ > **Targets ApexCharts v8.** Read the next box before writing any chart or feature code: the default bundle does not contain every chart type or feature.
37
37
  >
38
- > **⚠️ v7.0 breaking change: nine features left the default bundle.** In v6, `import ApexCharts from 'apexcharts'` gave you every feature. In v7 it does not. These nine are **Tier 2**: present in the package, absent from the default bundle, and reachable only through an explicit import.
38
+ > **⚠️ v8.0 breaking change: three chart types and four features left the default bundle.** `import ApexCharts from 'apexcharts'` (script tag: `dist/apexcharts.min.js`) registers line, area, scatter, bubble, rangeArea, bar (and `column`), rangeBar, candlestick, boxPlot, histogram, funnel, pyramid, pie, donut, polarArea, radialBar, gauge, radar, heatmap and treemap, plus axes, tooltips and the **Tier 1** features: exports, legend, toolbar, annotations, keyboard navigation, morph, stats, themes (Facet), plugins (Weave) and custom series (Marks). Everything else is **Tier 2**: present in the package, absent from the default bundle, and reachable through its own import next to it.
39
39
  >
40
40
  > ```js
41
41
  > import ApexCharts from 'apexcharts'
42
- > import 'apexcharts/features/trellis' // ESM
42
+ > import 'apexcharts/sunburst' // a Tier 2 chart type
43
+ > import 'apexcharts/features/drilldown' // a Tier 2 feature
43
44
  > ```
44
45
  > ```html
45
- > <script src=".../dist/apexcharts.js"></script>
46
- > <script src=".../dist/features/trellis.js"></script> <!-- script tag -->
46
+ > <script src=".../dist/apexcharts.min.js"></script>
47
+ > <script src=".../dist/sunburst.js"></script>
48
+ > <script src=".../dist/features/drilldown.js"></script>
47
49
  > ```
48
50
  >
49
- > | Tier 2 feature | Import | gzip |
50
- > |---|---|---|
51
- > | Trellis (small multiples) | `apexcharts/features/trellis` | 25.7 KB |
52
- > | Storyboard (scrollytelling) | `apexcharts/features/storyboard` | 8.0 KB |
53
- > | Perspectives (shareable views) | `apexcharts/features/perspectives` | 6.7 KB |
54
- > | Ink (annotation authoring) | `apexcharts/features/ink` | 6.2 KB |
55
- > | Canvas renderer (Strata) | `apexcharts/features/renderer-canvas` | 6.0 KB |
56
- > | Linked views & crossfilter | `apexcharts/features/link` | 5.3 KB |
57
- > | Measure ruler | `apexcharts/features/measure` | 4.6 KB |
58
- > | Rewind (undo / redo) | `apexcharts/features/history` | 3.2 KB |
59
- > | Context menu | `apexcharts/features/context-menu` | 2.3 KB |
51
+ > | Tier 2 | Import next to `apexcharts` | Script tag | Tier 2 since |
52
+ > |---|---|---|---|
53
+ > | `unit` and its `waffle` alias | `apexcharts/unit` | `dist/unit.js` | 8.0 |
54
+ > | `sunburst` | `apexcharts/sunburst` | `dist/sunburst.js` | 8.0 |
55
+ > | `violin` | `apexcharts/violin` | `dist/violin.js` | 8.0 |
56
+ > | `icicle` | `apexcharts/icicle` | `dist/icicle.js` | 7.6 (new) |
57
+ > | `raincloud` | `apexcharts/raincloud` (the violin renderer plus the raincloud feature) | `dist/violin.js`, then `dist/features/raincloud.js` | 7.1 (new); needs violin since 8.0 |
58
+ > | `drilldown`, and the `waterfall`, `dumbbell` and `streamgraph` chart types | `apexcharts/features/<name>` | `dist/features/<name>.js` | 8.0 |
59
+ > | `highlight-filter` (`highlightFilter`) | `apexcharts/features/highlight-filter` | `dist/features/highlight-filter.js` | 7.9 (new) |
60
+ > | `trellis`, `storyboard`, `perspectives`, `ink`, `renderer-canvas`, `link`, `measure`, `history`, `context-menu` | `apexcharts/features/<name>` | `dist/features/<name>.js` | 7.0 |
60
61
  >
61
- > The `raincloud` chart type (7.1) is Tier 2 on the same terms: `import 'apexcharts/raincloud'`. Storyboard registers Perspectives, so importing both costs no more than Storyboard alone. **Nothing fails silently**: each warns in the console when its config is present but the module is not, and degrades where it can (a trellis renders as one chart; `renderer: 'canvas'` falls back to SVG). Default bundle: 291,654 B gzipped in 6.10, 252,005 B in 7.0, 264,326 B in 7.1, about 270 KB in 7.6.
62
+ > Waterfall and dumbbell draw through rangeBar and streamgraph through rangeArea, which the default bundle has, so next to it you add only the feature. Storyboard registers Perspectives, so importing both costs no more than Storyboard alone.
62
63
  >
63
- > Everything else stays in the default bundle: **all chart types except `raincloud` and `icicle`**, axes, tooltips, legend, toolbar, exports, annotations, keyboard navigation, stats, morph, drilldown, themes (Facet), plugins (Weave) and custom series (Marks). See `references/tree-shaking.md` for the full tier table and `references/feature-platform.md` for each feature's API.
64
+ > **The full bundle** (v8.0) loads everything at once: `import ApexCharts from 'apexcharts/full'` in a bundler, `dist/apexcharts.full.min.js` from a script tag. It carries every chart type and feature plus the unit-shapes and pictograms catalogs, and needs no add-on import (premium items stay license-gated). Gzipped at 8.0.0: default bundle 263,188 B, full bundle 381,135 B.
65
+ >
66
+ > **Nothing fails silently**: when the import is missing, the console names it. A Tier 2 chart type makes `render()` reject; a `waterfall`, `dumbbell` or `streamgraph` draws an empty plot; a Tier 2 feature degrades where it can (a trellis renders as one chart; `renderer: 'canvas'` falls back to SVG). Unversioned CDN URLs serve 8.0; pin `apexcharts@7` to stay on 7, where unit, sunburst, violin, drilldown, waterfall, dumbbell and streamgraph are still in the default bundle. The split began in v7.0, which moved the nine features in the last table row out of a default bundle that had carried every feature. See `references/tree-shaking.md` for the full tier table and `references/feature-platform.md` for each feature's API.
64
67
  >
65
68
  > **Other v7.0 breaking changes.** (1) `plotOptions.bar.borderRadiusWhenStacked` was dropped as dead config in v7.0 and is a **working option again in v7.4**: `'all'` (the default) rounds both stack ends, `'last'` rounds only the far end and leaves the baseline square. Do not delete it from a config. (2) `dataLabels.animate.enabled` now defaults to `true` (bar/column only): labels ride to their new position on a data update instead of snapping. Set `dataLabels: { animate: { enabled: false } }` for the old behavior. Everything else from v5 and v6 keeps working unchanged.
66
69
  >
67
- > **Behaviors that are on by default** (both respect `prefers-reduced-motion`): data updates that add/remove points animate coherently, and one-finger kinetic pan is enabled (`chart.pan.inertia`). The two-finger gestures, pinch-zoom and two-finger pan, sit behind `chart.zoom.pinch`, which defaults to `'auto'`: **on only where the toolbar reset button is present**, so an unintended zoom is always undoable. `chart.zoom.allowMouseWheelZoom` is gated the same way. Set `pinch: true` to force the gestures on a toolbar-less chart, or see `chart.zoom.resetControl` (v7.4) for the other way to satisfy the gate.
70
+ > **Behaviors that are on by default** (both respect `prefers-reduced-motion`): data updates that add/remove points animate coherently, and one-finger kinetic pan is enabled (`chart.pan.inertia`). Since v7.8, data labels that land on each other are nudged apart (`dataLabels.avoidOverlap`, see section 5). The two-finger gestures, pinch-zoom and two-finger pan, sit behind `chart.zoom.pinch`, which defaults to `'auto'`: **on only where the toolbar reset button is present**, so an unintended zoom is always undoable. `chart.zoom.allowMouseWheelZoom` is gated the same way. Set `pinch: true` to force the gestures on a toolbar-less chart, or see `chart.zoom.resetControl` (v7.4) for the other way to satisfy the gate.
68
71
  >
69
- > **Premium features and licensing.** Eight features are premium: `trellis` (small multiples, 7.0), `storyboard`, `link` (crossfilter / linked views), `ink` (annotation authoring), `measure`, `context-menu`, `perspectives` (shareable views), and `history` (undo/redo). Two chart types are premium: `unit` / `waffle`, and `raincloud` (7.1). These still function fully, but render an `APEXCHARTS` trial watermark until an entitled license is set via `ApexCharts.setLicense(key)` (static) or per-chart `chart.license`. They require a `premium` or `enterprise` plan; a `pro` key or the free tier keeps the watermark. Every other chart type and free module is never gated. Note that premium and Tier 2 are independent axes: `waterfall`, `dumbbell` and `streamgraph` are free *and* in the default bundle, while `trellis` is both premium *and* an explicit import. See the Licensing section in `references/feature-platform.md`.
72
+ > **Premium features and licensing.** Nine features are premium: `trellis` (small multiples, 7.0), `storyboard`, `link` (crossfilter / linked views), `ink` (annotation authoring), `measure`, `context-menu`, `perspectives` (shareable views), `history` (undo/redo) and `highlight-filter` (`highlightFilter`, 7.9). Two chart types are premium: `unit` / `waffle`, and `raincloud` (7.1). These still function fully, but render an `APEXCHARTS` trial watermark until an entitled license is set via `ApexCharts.setLicense(key)` (static) or per-chart `chart.license`. They require a `premium` or `enterprise` plan; a `pro` key or the free tier keeps the watermark. Every other chart type and free module is never gated. Premium and Tier 2 are separate axes: since 8.0 every premium item is Tier 2, but not every Tier 2 item is premium (`renderer-canvas`, `drilldown`, `waterfall`, `dumbbell`, `streamgraph`, `sunburst`, `violin` and `icicle` are free and need an import). See the Licensing section in `references/feature-platform.md`.
70
73
 
71
74
  ## 1. Critical Rules
72
75
 
@@ -76,20 +79,21 @@ metadata:
76
79
  4. **`yaxis` must be an array** when using multiple y-axes. Each entry needs a `seriesName` to map to the correct series.
77
80
  5. **`tooltip.shared` and `tooltip.intersect` are mutually exclusive.** `shared: true` shows all series at an x-position. `intersect: true` shows only the hovered point.
78
81
  6. **Use `null` (not `undefined` or empty string)** for missing data points. `undefined` is silently ignored and breaks the chart.
79
- 7. **`chart.stacked: true`** only works with `bar` and `area` chart types.
82
+ 7. **`chart.stacked: true`** stacks `bar`, `area` and `line` series. In a mixed chart only the bar series stack by default (`chart.stackOnlyBar` defaults to `true`); set `stackOnlyBar: false` to stack its line and area series too. `waterfall`, `dumbbell` and `streamgraph` force it off, since they do their own accumulation.
80
83
  8. **Responsive breakpoints** must be in ascending order in the `responsive` array.
81
84
  9. **For mixed/combo charts**, set `type` on each individual series object, not just on `chart.type`.
82
- 10. **RadialBar values must be 0–100** (they represent percentages).
85
+ 10. **RadialBar values sit on the `plotOptions.radialBar.min` to `max` domain** (default 0 to 100, so percentages by default). Set `min` / `max` to plot raw values; a value outside the domain is clamped to the end of the arc.
83
86
  11. **Color hex values must include the `#` prefix** (e.g., `'#FF5733'`, not `'FF5733'`).
84
- 12. **Nine features are NOT in the v7 default bundle.** Before writing config for `trellis`, `storyboard`, `perspectives`, `ink`, `renderer: 'canvas'`, `link`, `measure`, `history` or the context menu, add its `apexcharts/features/*` import. Same for the `raincloud` and `icicle` chart types, which are not in the default bundle either. Full-bundle users need this too, not just tree-shakers. See the box above.
87
+ 12. **The default `apexcharts` bundle is not everything (v8).** Next to `import ApexCharts from 'apexcharts'`, add `import 'apexcharts/unit'` (also for `waffle`), `'apexcharts/sunburst'`, `'apexcharts/violin'`, `'apexcharts/icicle'` or `'apexcharts/raincloud'` before writing that chart type. Add `import 'apexcharts/features/<name>'` before writing a `waterfall`, `dumbbell` or `streamgraph` chart, or using `drilldown`, `highlightFilter` (`highlight-filter`), `trellis`, `storyboard`, `perspectives`, `ink`, `renderer: 'canvas'` (`renderer-canvas`), `link`, `measure`, `history` or the context menu (`context-menu`). `import ApexCharts from 'apexcharts/full'` (script tag: `dist/apexcharts.full.min.js`) is the one entry that needs none of these. See the box above.
85
88
  13. **Tree-shaking**: importing `apexcharts/core` gives you a bare class, and you must also import chart-type entries and feature entries separately.
86
89
  14. **First-class aliases**: `funnel` and `pyramid` render through the bar engine; `gauge` renders through radialBar. Use them as `chart.type` directly (no `plotOptions.bar.isFunnel` needed). They are covered by the `apexcharts/bar` and `apexcharts/radialBar` tree-shaking entries respectively.
87
90
  15. **`violin` (statistical)** uses a per-point density profile: `data: [{ x, y: { density: [[value, weight], ...], points?: [number] } }]`, not a plain number. Since v6.9 a datum may instead supply only raw observations (`points: [number]`, no `y`) and the library derives the density via KDE (needs `apexcharts/features/stats` when tree-shaking).
88
91
  16. **`render()` is idempotent**: calling `render()` twice on the same instance returns the same promise instead of building a duplicate chart. You still must `destroy()` before creating a *new* instance on the same element.
89
- 17. **`histogram` (v6.9)** series carry **raw observations** (one number per event), not pre-aggregated counts; the chart chooses bin edges and counts them. Binning ships behind the stats feature: use the `apexcharts/histogram` entry, or `import 'apexcharts/features/stats'` alongside `apexcharts/bar` (the full `apexcharts` bundle already includes it).
92
+ 17. **`histogram` (v6.9)** series carry **raw observations** (one number per event), not pre-aggregated counts; the chart chooses bin edges and counts them. Binning ships behind the stats feature: use the `apexcharts/histogram` entry, or `import 'apexcharts/features/stats'` alongside `apexcharts/bar` (the default `apexcharts` bundle already includes it).
90
93
  18. **`waterfall` (v7.1) accumulates for you.** The series carries the **deltas**, not the running total. A row that should show the running total carries `isSubtotal` or `isTotal` and **no `y`**; the library measures it. Do not pre-compute cumulative values.
91
94
  19. **`dumbbell` (v7.1) takes one series per measure**, each with the same `x` categories: `[{ name: '2020', data: [{ x, y }] }, { name: '2025', data: [{ x, y }] }]`. Do **not** zip the values into `y: [low, high]` pairs; that is the older `plotOptions.bar.isDumbbell` range-bar form, which still works but is a different chart.
92
95
  20. **`raincloud` (v7.1) takes the raw sample**, one datum per category: `data: [{ x, points: [number] }]`. It is a premium Tier 2 type, so it needs `import 'apexcharts/raincloud'` on top of the default bundle.
96
+ 21. **Unknown names fail loudly (v7.9).** An unknown `chart.type` throws when the chart is constructed or updated, and the message names the closest real type (`'column'` is valid, a synonym for `'bar'`; `''` and `null` draw a line chart). An unknown top-level option key is kept but never read. Numeric-string axis bounds such as `yaxis.min: '10'` work, and a bound that cannot be parsed is ignored (the axis scales to the data). Both cases log a console warning, except in `apexcharts.min.js` and the CommonJS builds (the `*.common.js` files `require('apexcharts')` loads), which strip `console.warn`.
93
97
 
94
98
  ---
95
99
 
@@ -103,23 +107,23 @@ This is the most critical reference. Using the wrong data format is the #1 cause
103
107
  |---|---|---|---|
104
108
  | Line | `'line'` | `[{ name, data: [number \| null] }]` or `[{ name, data: [{ x, y }] }]` | `series: [{ name: 'Sales', data: [30, 40, null, 50] }]` |
105
109
  | Area | `'area'` | Same as line | `series: [{ name: 'Views', data: [10, 20, 30] }]` |
106
- | Bar / Column | `'bar'` | Same as line. Defaults to **vertical columns**; set `plotOptions.bar.horizontal: true` for horizontal bars. | `series: [{ name: 'Revenue', data: [44, 55, 41] }]` |
110
+ | Bar / Column | `'bar'` (or `'column'`, a synonym since v7.9) | Same as line. Defaults to **vertical columns**; set `plotOptions.bar.horizontal: true` for horizontal bars. | `series: [{ name: 'Revenue', data: [44, 55, 41] }]` |
107
111
  | Scatter | `'scatter'` | `[{ name, data: [{ x, y }] }]` — always use XY format | `series: [{ name: 'Points', data: [{ x: 1, y: 5 }, { x: 2, y: 10 }] }]` |
108
112
  | Bubble | `'bubble'` | `[{ name, data: [{ x, y, z }] }]` — **z is required** (bubble size) | `series: [{ name: 'Data', data: [{ x: 1, y: 30, z: 10 }] }]` |
109
113
  | Range Area | `'rangeArea'` | `[{ name, data: [{ x, y: [low, high] }] }]` | `series: [{ name: 'Temp', data: [{ x: 'Jan', y: [5, 15] }] }]` |
110
114
  | Range Bar | `'rangeBar'` | `[{ name, data: [{ x, y: [start, end] }] }]` — for timeline/Gantt, use timestamps | `series: [{ name: 'Tasks', data: [{ x: 'Design', y: [1, 5] }] }]` |
111
115
  | Candlestick | `'candlestick'` | `[{ data: [{ x, y: [O, H, L, C] }] }]` — array of 4: Open, High, Low, Close | `series: [{ data: [{ x: new Date('2024-01-01'), y: [51, 56, 48, 53] }] }]` |
112
116
  | Box Plot | `'boxPlot'` | `[{ data: [{ x, y: [min, Q1, median, Q3, max] }] }]` — array of 5. *(v6.9)* Or supply the raw sample instead: `[{ data: [{ x, points: [number] }] }]` and the quartiles are computed (R type 7; needs the stats feature). | `series: [{ data: [{ x: 'Group A', y: [10, 20, 30, 40, 50] }] }]` |
113
- | Violin *(v6)* | `'violin'` | `[{ name, data: [{ x, y: { density: [[value, weight], ...], points?: [number] } }] }]`. *(v6.9)* Or supply the raw sample instead: `[{ name, data: [{ x, points: [number] }] }]` and the density is derived via KDE (needs the stats feature). | `series: [{ name: 'Sessions', data: [{ x: 'A', y: { density: [[20, 0.1], [30, 0.2]], points: [21, 29] } }] }]` |
117
+ | Violin *(v6, Tier 2 since v8)* | `'violin'` | `[{ name, data: [{ x, y: { density: [[value, weight], ...], points?: [number] } }] }]`. *(v6.9)* Or supply the raw sample instead: `[{ name, data: [{ x, points: [number] }] }]` and the density is derived via KDE (needs the stats feature). Needs `import 'apexcharts/violin'`. | `series: [{ name: 'Sessions', data: [{ x: 'A', y: { density: [[20, 0.1], [30, 0.2]], points: [21, 29] } }] }]` |
114
118
  | Histogram *(v6.9)* | `'histogram'` | `[{ name, data: [number] }]`: **raw observations**, one number per event, NOT pre-binned counts. The chart bins them (needs the stats feature). | `series: [{ name: 'Latency', data: [102, 87, 143, 91] }]` |
115
119
  | Heatmap | `'heatmap'` | `[{ name, data: [{ x, y: number }] }]` — y is the intensity value | `series: [{ name: 'Mon', data: [{ x: '10am', y: 45 }] }]` |
116
120
  | Treemap | `'treemap'` | `[{ data: [{ x, y: number }] }]` — y is the area/value. *(v6.9)* A datum may carry `children` to any depth for a nested treemap (see `references/grid-charts.md`). | `series: [{ data: [{ x: 'Item A', y: 100 }, { x: 'Item B', y: 60 }] }]` |
117
121
  | Radar | `'radar'` | `[{ name, data: [number] }]` + `xaxis: { categories: [...] }` | `series: [{ name: 'Skill', data: [80, 50, 30, 40, 100] }]` |
118
122
  | Funnel *(v6)* | `'funnel'` | `[{ name, data: [number] }]` + `xaxis: { categories: [...] }`. Order values **largest→smallest**. | `series: [{ data: [1380, 990, 548, 200] }]` |
119
123
  | Pyramid *(v6)* | `'pyramid'` | Same as funnel; order values **smallest→largest** (wide base at bottom). | `series: [{ data: [200, 548, 990, 1380] }]` |
120
- | Waterfall *(v7.1)* | `'waterfall'` | `[{ name, data: [{ x, y }] }]` where **`y` is the signed delta**, not a running total. A running-total row carries `isSubtotal` (sum since the last cut) or `isTotal` (sum from zero) and **omits `y`**. | `series: [{ data: [{ x: 'Revenue', y: 8786 }, { x: 'Costs', y: -2786 }, { x: 'Gross', isSubtotal: true }] }]` |
121
- | Dumbbell *(v7.1)* | `'dumbbell'` | **One series per measure**, sharing x categories: `[{ name, data: [{ x, y }] }, ...]`. Not `[low, high]` pairs. | `series: [{ name: '2020', data: [{ x: 'Backend', y: 92 }] }, { name: '2025', data: [{ x: 'Backend', y: 118 }] }]` |
122
- | Streamgraph *(v7.1)* | `'streamgraph'` | Same as area: `[{ name, data: [{ x, y }] }]`. Stacking, baseline and band order are the chart's job, so do **not** set `chart.stacked`. | `series: [{ name: 'Drama', data: [{ x: '2024-01-01', y: 32 }] }]` |
124
+ | Waterfall *(v7.1, Tier 2 since v8)* | `'waterfall'` | `[{ name, data: [{ x, y }] }]` where **`y` is the signed delta**, not a running total. A running-total row carries `isSubtotal` (sum since the last cut) or `isTotal` (sum from zero) and **omits `y`**. Needs `import 'apexcharts/features/waterfall'`. | `series: [{ data: [{ x: 'Revenue', y: 8786 }, { x: 'Costs', y: -2786 }, { x: 'Gross', isSubtotal: true }] }]` |
125
+ | Dumbbell *(v7.1, Tier 2 since v8)* | `'dumbbell'` | **One series per measure**, sharing x categories: `[{ name, data: [{ x, y }] }, ...]`. Not `[low, high]` pairs. Needs `import 'apexcharts/features/dumbbell'`. | `series: [{ name: '2020', data: [{ x: 'Backend', y: 92 }] }, { name: '2025', data: [{ x: 'Backend', y: 118 }] }]` |
126
+ | Streamgraph *(v7.1, Tier 2 since v8)* | `'streamgraph'` | Same as area: `[{ name, data: [{ x, y }] }]`. Stacking, baseline and band order are the chart's job, so do **not** set `chart.stacked`. Needs `import 'apexcharts/features/streamgraph'`. | `series: [{ name: 'Drama', data: [{ x: '2024-01-01', y: 32 }] }]` |
123
127
  | Raincloud *(v7.1, premium, Tier 2)* | `'raincloud'` | `[{ name, data: [{ x, points: [number] }] }]`: the **raw sample** per category; the density, box and rain are derived. Needs `import 'apexcharts/raincloud'`. | `series: [{ name: 'Weight gain', data: [{ x: 'Control', points: [3.1, 4.7, 2.9] }] }]` |
124
128
 
125
129
  ### Non-Axis Charts (pie, donut, radialBar, polarArea, gauge, unit, waffle)
@@ -137,13 +141,13 @@ These use a **flat number array** for `series`, NOT the object format:
137
141
 
138
142
  **Gauge *(v6)*** is a single-value radialBar alias: `series: [72]`, `labels: ['Progress']`. Configure the arc/needle, colored bands, ticks, and `min`/`max` domain through `plotOptions.radialBar` (see `references/circular-charts.md`).
139
143
 
140
- **Unit / Waffle *(v6.6, premium)*** render one mark per unit of value (dot clusters, pictograms, waffles, beeswarms). Same flat-array + `labels` shape as pie; layout is chosen through `plotOptions.unit.layout`. A per-mark object form (`series: [{ name, data: [{ value, x, z, name, fillColor, id }] }]`) gives each mark its own color, position, size, and tooltip. `waffle` is a preset alias of `unit` (grid layout). Both render an `APEXCHARTS` watermark until an entitled license is set. See `references/circular-charts.md`.
144
+ **Unit / Waffle *(v6.6, premium, Tier 2 since v8)*** need `import 'apexcharts/unit'` (both types). They render one mark per unit of value (dot clusters, pictograms, waffles, beeswarms). Same flat-array + `labels` shape as pie; layout is chosen through `plotOptions.unit.layout`. A per-mark object form (`series: [{ name, data: [{ value, x, z, name, fillColor, id }] }]`) gives each mark its own color, position, size, and tooltip. `waffle` is a preset alias of `unit` (grid layout). Both render an `APEXCHARTS` watermark until an entitled license is set. See `references/circular-charts.md`.
141
145
 
142
146
  ### Hierarchical Charts (sunburst, icicle)
143
147
 
144
148
  Both take the same tree, and the choice between them is a layout one: a sunburst spends the plot radially, an icicle spends it along a straight axis.
145
149
 
146
- **Sunburst *(v6.7, free)*** draws tree-structured data as concentric rings (a nested pie / donut). It uses the axis-style `[{ data: [...] }]` wrapper, but each datum is an `{ x, y, children }` node nested to any depth:
150
+ **Sunburst *(v6.7, free, Tier 2 since v8)*** draws tree-structured data as concentric rings (a nested pie / donut) and needs `import 'apexcharts/sunburst'`. It uses the axis-style `[{ data: [...] }]` wrapper, but each datum is an `{ x, y, children }` node nested to any depth:
147
151
 
148
152
  ```js
149
153
  {
@@ -162,10 +166,11 @@ Both take the same tree, and the choice between them is a layout one: a sunburst
162
166
 
163
167
  Configure the centre hole, corner rounding, and inter-arc gap through `plotOptions.sunburst` (see `references/circular-charts.md`).
164
168
 
165
- **Icicle *(v7.6, free, opt-in import)*** is the same partition in cartesian coordinates: one band per depth level, each child sized inside its parent's extent. Same data shape as the sunburst, and it also reads an existing `drilldown` config as plain data (no drilldown runtime needed). Labels stay horizontal at every depth and same-depth siblings line up across branches, which is what makes it the better pick for deep trees, call stacks and path funnels.
169
+ **Icicle *(v7.6, free, Tier 2)*** is the same partition in cartesian coordinates: one band per depth level, each child sized inside its parent's extent. Same data shape as the sunburst, and it also reads an existing `drilldown` config as plain data (no drilldown runtime needed). Labels stay horizontal at every depth and same-depth siblings line up across branches, which is what makes it the better pick for deep trees, call stacks and path funnels.
166
170
 
167
171
  ```js
168
- import ApexCharts from 'apexcharts/icicle' // NOT in the default bundle
172
+ import ApexCharts from 'apexcharts'
173
+ import 'apexcharts/icicle' // Tier 2: NOT in the default bundle
169
174
 
170
175
  {
171
176
  chart: { type: 'icicle' },
@@ -181,13 +186,18 @@ A branch may omit its own `y` and be the sum of its children *(fixed in v7.6 for
181
186
  ## 3. Package / Module Map
182
187
 
183
188
  ```
184
- # Default bundle (every chart type except raincloud and icicle, plus the Tier 1 features)
189
+ # Default bundle (the standard chart types plus the Tier 1 features; see the box at the top)
185
190
  import ApexCharts from 'apexcharts'
186
191
 
192
+ # Full bundle (v8.0): every chart type and feature, plus the unit-shapes and pictograms catalogs. No add-on needed.
193
+ import ApexCharts from 'apexcharts/full'
194
+
187
195
  # Bare core (no chart types, no optional features — must register manually)
188
196
  import ApexCharts from 'apexcharts/core'
189
197
 
190
- # Per-type entry points (registers specific chart types + core)
198
+ # Per-type entry points (registers specific chart types + core, plus any feature the type needs; no legend, toolbar or exports unless you import them).
199
+ # For a Tier 2 type (unit, sunburst, violin, icicle, raincloud) the usual form is
200
+ # import 'apexcharts/<type>' next to the default bundle.
191
201
  import ApexCharts from 'apexcharts/line' # line, area, scatter, bubble, rangeArea
192
202
  import ApexCharts from 'apexcharts/area' # same as /line
193
203
  import ApexCharts from 'apexcharts/scatter' # same as /line
@@ -201,8 +211,8 @@ import ApexCharts from 'apexcharts/dumbbell' # dumbbell (v7.1): bar engine
201
211
  import ApexCharts from 'apexcharts/streamgraph' # streamgraph (v7.1): rangeArea engine + the streamgraph feature
202
212
  import ApexCharts from 'apexcharts/candlestick' # candlestick, boxPlot
203
213
  import ApexCharts from 'apexcharts/boxPlot' # same as /candlestick
204
- import ApexCharts from 'apexcharts/violin' # violin
205
- import ApexCharts from 'apexcharts/raincloud' # raincloud (v7.1, premium): violin engine + the raincloud feature
214
+ import ApexCharts from 'apexcharts/violin' # violin (Tier 2 since v8). Carries no bar renderer: on this lean path also import 'apexcharts/bar'
215
+ import ApexCharts from 'apexcharts/raincloud' # raincloud (v7.1, premium): violin + the raincloud feature; on this lean path also import 'apexcharts/bar'
206
216
  import ApexCharts from 'apexcharts/histogram' # histogram (v6.9): bar engine + the stats feature
207
217
  import ApexCharts from 'apexcharts/pie' # pie, donut, polarArea
208
218
  import ApexCharts from 'apexcharts/donut' # same as /pie
@@ -211,9 +221,9 @@ import ApexCharts from 'apexcharts/radialBar' # radialBar + gauge
211
221
  import ApexCharts from 'apexcharts/radar' # radar only
212
222
  import ApexCharts from 'apexcharts/heatmap' # heatmap only
213
223
  import ApexCharts from 'apexcharts/treemap' # treemap only
214
- import ApexCharts from 'apexcharts/sunburst' # sunburst (v6.7, hierarchical)
215
- import ApexCharts from 'apexcharts/icicle' # icicle (v7.6, hierarchical): opt-in, NOT in the default bundle
216
- import ApexCharts from 'apexcharts/unit' # unit + waffle (v6.6, premium)
224
+ import ApexCharts from 'apexcharts/sunburst' # sunburst (v6.7, hierarchical): Tier 2 since v8
225
+ import ApexCharts from 'apexcharts/icicle' # icicle (v7.6, hierarchical): Tier 2, NOT in the default bundle
226
+ import ApexCharts from 'apexcharts/unit' # unit + waffle (v6.6, premium): Tier 2 since v8
217
227
  # funnel + pyramid render through the bar engine; use apexcharts/bar
218
228
 
219
229
  # Unit-chart shape kit (v6.10): named exports, tree-shaken per shape (~4 KB gzipped each)
@@ -231,15 +241,16 @@ import 'apexcharts/features/annotations' # X/Y/point/text/image annotations
231
241
  import 'apexcharts/features/keyboard' # Keyboard navigation (accessibility)
232
242
  import 'apexcharts/features/stats' # Statistics (v6.9): histogram binning, boxPlot/violin raw samples, rowSeries()
233
243
  import 'apexcharts/features/morph' # Animated chart-type morphs
234
- import 'apexcharts/features/drilldown' # Hierarchical drill-down
235
244
  import 'apexcharts/features/facet' # Design tokens + OS-aware themes
236
245
  import 'apexcharts/features/weave' # Public plugin platform
237
246
  import 'apexcharts/features/marks' # Custom series types (registerSeriesType)
238
- import 'apexcharts/features/waterfall' # (v7.1) waterfall chart type
239
- import 'apexcharts/features/dumbbell' # (v7.1) dumbbell chart type
240
- import 'apexcharts/features/streamgraph' # (v7.1) streamgraph chart type
241
247
 
242
- # TIER 2 features: NOT in the default bundle. Required even on the full bundle.
248
+ # TIER 2: NOT in the default bundle (all are in apexcharts/full).
249
+ import 'apexcharts/features/drilldown' # Hierarchical drill-down (Tier 2 since v8)
250
+ import 'apexcharts/features/waterfall' # (v7.1) waterfall chart type (Tier 2 since v8)
251
+ import 'apexcharts/features/dumbbell' # (v7.1) dumbbell chart type (Tier 2 since v8)
252
+ import 'apexcharts/features/streamgraph' # (v7.1) streamgraph chart type (Tier 2 since v8)
253
+ import 'apexcharts/features/highlight-filter' # (v7.9) Part-of-whole highlight, highlightFilter (premium)
243
254
  import 'apexcharts/features/trellis' # (v7.0) Small multiples (premium)
244
255
  import 'apexcharts/features/storyboard' # Scrollytelling (premium; registers perspectives)
245
256
  import 'apexcharts/features/perspectives' # Shareable view state (premium)
@@ -249,16 +260,16 @@ import 'apexcharts/features/link' # Crossfilter / linked views (premi
249
260
  import 'apexcharts/features/measure' # Measure / delta ruler (premium)
250
261
  import 'apexcharts/features/history' # Undo/redo (Rewind, premium)
251
262
  import 'apexcharts/features/context-menu' # Right-click / long-press context menu (premium)
252
- import 'apexcharts/features/raincloud' # (v7.1) raincloud chart type (premium)
263
+ import 'apexcharts/raincloud' # (v7.1) raincloud (premium): the violin renderer plus the raincloud feature. features/raincloud alone works only where violin is already registered (v8)
253
264
 
254
265
  import 'apexcharts/features/all' # Tier 1 only. Does NOT pull in Tier 2.
255
266
 
256
267
  # SSR (server-side rendering)
257
- import ApexCharts from 'apexcharts/ssr' # Node.js: renderToString, renderToHTML
258
- import ApexCharts from 'apexcharts/client' # Browser: explicit client import for hydration
268
+ import ApexCharts from 'apexcharts/ssr' # Node.js: renderToString, renderToHTML. Also the only entry with hydrate() (browser-safe)
269
+ import ApexCharts from 'apexcharts/client' # Browser build, explicitly. No hydrate(): hydrate from apexcharts/ssr
259
270
  ```
260
271
 
261
- **Note (v7):** `apexcharts` gives you every chart type except `raincloud` and `icicle`, plus the Tier 1 features. The nine Tier 2 features, `raincloud` and `icicle` need their own import **whatever entry point you started from**. `apexcharts/features/all` is the Tier 1 set, so it is not a shortcut past this. Tree-shaking entries (`/core`, `/line`, etc.) are for reducing bundle size below the default.
272
+ **Note (v8):** `apexcharts` gives you the standard chart types and the Tier 1 features. The Tier 2 chart types (`unit` / `waffle`, `sunburst`, `violin`, `icicle`, `raincloud`) and Tier 2 features need their own import **unless you started from `apexcharts/full`**. `apexcharts/features/all` is the Tier 1 set, so it is not a shortcut past this. Tree-shaking entries (`/core`, `/line`, etc.) are for reducing bundle size below the default. On the lean core, `violin` and `raincloud` also need `apexcharts/bar`, and a boxPlot or violin of raw observations needs `apexcharts/features/stats` (the console says so).
262
273
 
263
274
  **Note (v6.9):** ApexCharts is no longer dependency-free: it depends on `apex-commons` at runtime. npm resolves it automatically and the browser (script-tag) bundles inline it, so no action is needed; it only matters for tooling that assumed zero dependencies.
264
275
 
@@ -314,7 +325,7 @@ chart.destroy()
314
325
  | `xaxis.labels.formatter` | `(value: string \| number, timestamp?: number, opts?) => string` | Formatted x-axis tick label |
315
326
  | `yaxis.labels.formatter` | `(value: number, opts?) => string` | Formatted y-axis tick label |
316
327
  | `tooltip.x.formatter` | `(value: number, opts?) => string` | Tooltip x-value text |
317
- | `tooltip.y.formatter` | `(value: number, opts?) => string` | Tooltip y-value text |
328
+ | `tooltip.y.formatter` | `(value: number \| null, opts?) => string` | Tooltip y-value text. `value` is `null` at a gap, so guard before a number method: `(val) => val == null ? 'n/a' : val.toFixed(2)` |
318
329
  | `tooltip.y.title.formatter` | `(seriesName: string, opts?) => string` | Tooltip series title |
319
330
  | `tooltip.z.formatter` | `(value: number) => string` | Tooltip z-value (bubble) |
320
331
  | `dataLabels.formatter` | `(value: number \| string \| number[], opts?) => string \| number` | Data label text |
@@ -325,7 +336,7 @@ chart.destroy()
325
336
 
326
337
  **Important:** All formatters must return a `string` (or `number` for `dataLabels.formatter`). Never return `undefined`.
327
338
 
328
- **Per-point data label offsets (v6.8):** `dataLabels.offsetX` and `dataLabels.offsetY` accept `number | ((opts) => number)`. The function receives `{ series, seriesIndex, dataPointIndex, w }` (same signature as `dataLabels.style.colors` functions), so colliding labels from two series at the same x can be pushed apart, e.g. `offsetY: ({ seriesIndex }) => (seriesIndex === 0 ? -12 : 12)`. Keep it pure; it may be called more than once per label.
339
+ **Per-point data label offsets (v6.8):** `dataLabels.offsetX` and `dataLabels.offsetY` accept `number | ((opts) => number)`. The function receives `{ series, seriesIndex, dataPointIndex, w }` (same signature as `dataLabels.style.colors` functions). Use it for deliberate placement; keep it pure, since it may be called more than once per label. Collisions do not need it: since v7.8 `dataLabels.avoidOverlap` (on by default) nudges labels that land on each other apart along the value axis, across series as well as within one, after the offsets are applied (radial types keep their own placement). Tune it with `{ gap, maxShift, hide }`, or set `avoidOverlap: false` to keep each label exactly at its mark and offset.
329
340
 
330
341
  ---
331
342
 
@@ -475,11 +486,13 @@ Also: do NOT use `xaxis.categories` when your data already has `{ x, y }` format
475
486
  { chart: { type: 'scatter', stacked: true } }
476
487
  ```
477
488
 
478
- ✅ **CORRECT** — stacking only works on bar and area:
489
+ ✅ **CORRECT**: stacking works on bar, area and line:
479
490
  ```js
480
491
  { chart: { type: 'bar', stacked: true } }
481
492
  // or
482
493
  { chart: { type: 'area', stacked: true } }
494
+ // or
495
+ { chart: { type: 'line', stacked: true } }
483
496
  ```
484
497
 
485
498
  ### Pitfall 10: Mixed/combo charts missing per-series type
@@ -506,16 +519,19 @@ Also: do NOT use `xaxis.categories` when your data already has `{ x, y }` format
506
519
  }
507
520
  ```
508
521
 
509
- ### Pitfall 11: RadialBar values > 100
522
+ ### Pitfall 11: RadialBar values outside the min/max domain
510
523
 
511
- ❌ **WRONG** — raw values (renders incorrectly):
524
+ ❌ **WRONG**: raw values on the default 0 to 100 domain (each arc is clamped to full):
512
525
  ```js
513
526
  { chart: { type: 'radialBar' }, series: [340, 520, 190] }
514
527
  ```
515
528
 
516
- ✅ **CORRECT** — use percentages 0–100:
529
+ ✅ **CORRECT**: use percentages, or set the domain to fit the raw values:
517
530
  ```js
518
531
  { chart: { type: 'radialBar' }, series: [76, 67, 61], labels: ['A', 'B', 'C'] }
532
+ // or
533
+ { chart: { type: 'radialBar' }, series: [340, 520, 190], labels: ['A', 'B', 'C'],
534
+ plotOptions: { radialBar: { min: 0, max: 600 } } }
519
535
  ```
520
536
 
521
537
  ### Pitfall 12: Colors without # prefix
@@ -560,21 +576,27 @@ import 'apexcharts/features/toolbar'
560
576
  import 'apexcharts/features/annotations'
561
577
  ```
562
578
 
563
- **(b) *(v7)* The full bundle no longer carries the nine Tier 2 features.** This one catches people who never tree-shook anything, and it is the most common v6 → v7 upgrade failure.
579
+ **(b) *(v8)* The default bundle does not carry the Tier 2 chart types and features.** This one catches people who never tree-shook anything. It is the most common upgrade failure: v6 to v7 for the nine 7.0 features, v7 to v8 for unit, sunburst, violin, drilldown, waterfall, dumbbell and streamgraph.
564
580
 
565
- ❌ **WRONG**: the config is right, the module is absent, so the chart renders as one plain chart and logs a warning:
581
+ ❌ **WRONG**: the config is right, the module is absent, so `render()` rejects and nothing draws:
566
582
  ```js
567
583
  import ApexCharts from 'apexcharts'
568
- new ApexCharts(el, { chart: { type: 'line' }, series, trellis: { by: 'region' } })
584
+ new ApexCharts(el, { chart: { type: 'sunburst' }, series }).render()
569
585
  ```
570
586
 
571
587
  ✅ **CORRECT**:
572
588
  ```js
573
589
  import ApexCharts from 'apexcharts'
574
- import 'apexcharts/features/trellis'
590
+ import 'apexcharts/sunburst'
575
591
  ```
576
592
 
577
- Same for `storyboard`, `perspectives`, `ink`, `renderer: 'canvas'`, `link`, `measure`, `history`, `contextMenu`, and the `raincloud` chart type. Check the console: each one names both import routes when its config is present without it. `icicle` is the exception to the "warns and degrades" rule: an unregistered chart type **throws**, and the thrown message names both routes.
593
+ The console names the import in every case (since 7.9.1 the minified bundle prints it too), but what the chart does depends on what is missing:
594
+
595
+ - **A Tier 2 chart type** (`unit`, `waffle`, `sunburst`, `violin`, `icicle`, and `raincloud`, which draws through violin): `render()` rejects and nothing draws. An `updateOptions`, `updateSeries` or `appendSeries` that asks for one is refused, and the chart stays as it was.
596
+ - **`waterfall`, `dumbbell` or `streamgraph`** without its feature (or a `raincloud` on a page that has violin but not the raincloud feature): one warning and an empty plot.
597
+ - **A Tier 2 feature** (`drilldown`, `highlightFilter`, `trellis`, `storyboard`, `perspectives`, `ink`, `renderer: 'canvas'`, `link`, `measure`, `history`, `contextMenu`): the chart draws without it, with a warning when its config is present. A trellis renders as one plain chart; a drilldown chart draws its root level and never navigates, and `chart.drillDown()` throws.
598
+
599
+ Or start from `import ApexCharts from 'apexcharts/full'`, which needs none of these.
578
600
 
579
601
  ### Pitfall 15: SSR — wrong import path
580
602
 
@@ -586,10 +608,12 @@ const svg = await ApexCharts.renderToString(options)
586
608
 
587
609
  // On client (for hydration): target the wrapper renderToHTML emitted,
588
610
  // which carries data-apexcharts-hydrate and NO id.
589
- import ApexCharts from 'apexcharts' // or 'apexcharts/client'
611
+ import ApexCharts from 'apexcharts/ssr' // hydrate() lives only on this entry; it is browser-safe
590
612
  ApexCharts.hydrateAll() // or hydrate(document.querySelector('[data-apexcharts-hydrate]'))
591
613
  ```
592
614
 
615
+ In a browser, `apexcharts`, `apexcharts/client` and `apexcharts/full` have no `hydrate` / `hydrateAll`, and the types declare them on every entry, so TypeScript does not catch the mistake.
616
+
593
617
  ### Pitfall 16: updateOptions vs updateSeries vs appendData
594
618
 
595
619
  ❌ **WRONG** — full updateOptions just to change data:
@@ -638,7 +662,7 @@ await chart.updateOptions({ title: { text: 'New Title' } })
638
662
  | `exportToCSV(options?)` | Trigger CSV download. |
639
663
  | `setLocale(localeName)` | Switch locale. |
640
664
  | `toggleDataPointSelection(seriesIndex, dataPointIndex?)` | Select/deselect data point. |
641
- | `rowSeries(opts?)` | *(v6.9)* Returns the raw rows behind this chart's marks as a unit-chart series (one cluster per mark), or `null` when the type has no row source (works for histogram / boxPlot / violin, needs `apexcharts/features/stats`). `opts.maxRows` caps the output (default 3000). |
665
+ | `rowSeries(opts?)` | *(v6.9)* Returns the raw rows behind this chart's marks as a unit-chart series (one cluster per mark), or `null` when the type has no row source (works for histogram / boxPlot / violin, needs `apexcharts/features/stats`). `opts.maxRows` caps the output (default 3000). Drawing the result needs the `unit` type, Tier 2 since v8 (`import 'apexcharts/unit'`). |
642
666
  | `getState()` | Returns snapshot of chart state. |
643
667
  | `addEventListener(name, handler)` | Subscribe to chart event. |
644
668
  | `removeEventListener(name, handler)` | Unsubscribe from chart event. |
@@ -657,6 +681,7 @@ await chart.updateOptions({ title: { text: 'New Title' } })
657
681
  | `chart.storyboard.bind({ beats }) / goTo() / unbind()` | storyboard | Scroll-driven choreography. |
658
682
  | `chart.drillDown(id) / drillUp() / drillToRoot()` | drilldown | Navigate the drill-down hierarchy. |
659
683
  | `chart.clearCrossfilter()` | link | Clear active crossfilter selections. |
684
+ | `chart.highlightFilter.set(parts) / clear() / valueAt(i, j) / isActive()` | highlight-filter | *(v7.9)* Set or remove the highlighted parts (each resolves when drawn), read one part. `chart.highlightFilter` is `null` without the feature. |
660
685
 
661
686
  ### Static Methods
662
687
 
@@ -675,7 +700,7 @@ await chart.updateOptions({ title: { text: 'New Title' } })
675
700
  | `ApexCharts.registerUnitLayout(name, fn) / unregisterUnitLayout(name)` | *(v6.9)* Register a named unit-chart layout, referenceable via `plotOptions.unit.positions: '<name>'` with `layout: 'custom'`. |
676
701
  | `ApexCharts.crossfilter({ id, records }) / getCrossfilter(id)` | *(v6, Link)* Create / fetch a crossfilter engine. |
677
702
  | `ApexCharts.perspectives.fromURL(href)` | *(v6)* Decode a perspective token from a URL. |
678
- | `ApexCharts.trellis(el, options)` | *(v7.0, Trellis)* Imperative entry point: creates a trellis host (options must carry `trellis.by`). Throws if the trellis feature is not imported. |
703
+ | `ApexCharts.trellis(el, options)` | *(v7.0, Trellis)* Imperative entry point: creates a trellis host (options must carry `trellis.by`) and starts rendering it. Returns `null`, with a console warning, when the trellis feature is not loaded. |
679
704
  | `registerMarks(defs) / definePictogram(meta)` from `apexcharts/pictograms` | *(v7.0)* Register glyphs so `plotOptions.unit.pictogram.mark: 'person'` resolves. |
680
705
 
681
706
  ### SSR Static Methods (available with `apexcharts/ssr`)
@@ -733,6 +758,7 @@ await chart.updateOptions({ title: { text: 'New Title' } })
733
758
  drillDownEnd: (info, chart, options) => {}, // drilldown
734
759
  drillUp: (info, chart, options) => {}, // drilldown
735
760
  drillDownError: ({ id, error }, chart, options) => {}, // drilldown (v6.9): async level failed; view unchanged
761
+ highlightFilterChanged: (chart, { active, phase }) => {}, // highlight-filter (v7.9): phase is 'enter', 'update' or 'clear'
736
762
  }
737
763
  }
738
764
  }
@@ -742,20 +768,21 @@ await chart.updateOptions({ title: { text: 'New Title' } })
742
768
 
743
769
  ## 9. Feature Platform
744
770
 
745
- Every feature below is off by default in config terms. The **Tier** column is about the *bundle*: Tier 1 is already in `import ApexCharts from 'apexcharts'` and needs a `features/*` import only if you started from `/core` or a per-type entry; **Tier 2 needs its import no matter which entry point you used**. Full config shapes, APIs, and examples are in `references/feature-platform.md`.
771
+ Every feature below is off by default in config terms. The **Tier** column is about the *bundle*: Tier 1 is already in `import ApexCharts from 'apexcharts'` and needs a `features/*` import only if you started from `/core` or a per-type entry; **Tier 2 needs its import whatever entry point you used, except `apexcharts/full`, which carries every feature**. Full config shapes, APIs, and examples are in `references/feature-platform.md`.
746
772
 
747
773
  | Feature | Tier | Import | One-liner |
748
774
  |---|---|---|---|
749
775
  | **Weave** (plugins) | 1 | `apexcharts/features/weave` | Publish reusable chart plugins against a stable `ApexCharts.registerPlugin({ name, setup })` API; activate per chart with `plugins: [{ name }]`. Contract is at **v6** (v7.5): `info`/`categories`/`markDerived` (v2), `reserve` (v3), `pointer` (v4), `claim`/`drawn`/`declare`/`can` (v6). Declare the **lowest** `apiVersion` you can run on and feature-detect the rest: a host older than the version you declare skips your plugin outright. |
750
776
  | **Marks** (custom series) | 1 | `apexcharts/features/marks` | `ApexCharts.registerSeriesType(name, { renderItem })` for first-class custom marks (lollipop, bullet). Baseline is `scales.y(0)`, **not** `api.zeroY`. |
751
777
  | **Facet** (themes/tokens) | 1 | `apexcharts/features/facet` | `theme: { follow: 'os', name }`, `--apx-*` CSS custom props, `ApexCharts.registerTheme`. |
752
- | **Drilldown** | 1 | `apexcharts/features/drilldown` | `drilldown: { enabled, series }` + a `drilldown` id on data points; `chart.drillDown()/drillUp()`. v6.9 adds line/area support, async levels (`onDrillDown` may return a Promise), a loading overlay, and the `drillDownError` event. |
753
778
  | **Morph** | 1 | `apexcharts/features/morph` | Animated transitions between chart types. |
754
779
  | **Stats** | 1 | `apexcharts/features/stats` | *(v6.9)* Statistics behind histogram binning, boxPlot/violin raw-sample summaries (R type 7 quartiles, KDE), and `chart.rowSeries()`. The `apexcharts/histogram` entry includes it. |
755
780
  | **Cadence** (easing) | core | none | `chart.animations.easing` accepts a named curve, cubic-bezier array, or function; `ApexCharts.registerEasing`. |
756
781
  | **Streaming** | core | none | `chart: { streaming: { enabled, maxPoints } }` for constant-velocity rolling-window scroll. |
757
782
  | **Print layout** | core | none | *(v7.1)* `chart: { print: { enabled, width } }`. The paper box cannot be measured from JS (`clientWidth` and `matchMedia` both report the screen during `beforeprint`), so the chart is re-laid out at a known width for the sheet and restored after. **On by default** at `width: 700` (suits A4 / Letter portrait); a chart already narrower is left alone. `print: false` restores the pre-7.1 behavior. |
758
783
  | **Marker batching** | core | none | *(v7.0)* `markers: { largeDatasetThreshold: n }`. Above `n` points, a series' markers are drawn as one path per marker size instead of one element per point. **Opt-in, default `0` (off)**, because merged marker paths are not pixel-identical: overlapping markers lose their individual outlines and dense clusters read flatter. Also covers the markers `showNullDataPoints` adds, which is what makes a null-heavy series slow even at `size: 0`. |
784
+ | **Drilldown** | **2** | `apexcharts/features/drilldown` | *(Tier 2 since v8.0)* `drilldown: { enabled, series }` + a `drilldown` id on data points; `chart.drillDown()/drillUp()`. v6.9 adds line/area support, async levels (`onDrillDown` may return a Promise), a loading overlay, and the `drillDownError` event. |
785
+ | **Highlight filter** | **2** | `apexcharts/features/highlight-filter` | *(v7.9, premium)* `highlightFilter` draws each value faded with a part of it solid in front, from the same baseline. The part travels with the data: `series[].highlightData` (parallel to `data`) or `{ x, y, highlight }` per point, `highlightFilter.data` on pie / donut / polarArea / radialBar; `chart.highlightFilter.set(parts)` / `clear()`. Bar, column, funnel, line, area, pie, donut, polarArea, radialBar (and gauge), treemap. See "Highlight filter" in `references/feature-platform.md`. |
759
786
  | **Trellis** (small multiples) | **2** | `apexcharts/features/trellis` | *(v7.0, premium)* `trellis: { by: 'region', minPanelWidth }` splits the series into a grid of real charts sharing one scale, legend, toolbar and crosshair. Also `row` × `column` for 2-D grids. |
760
787
  | **Strata** (canvas) | **2** | `apexcharts/features/renderer-canvas` | `chart: { renderer: 'auto', rendererThreshold }` paints the dense series layer to canvas while axes/tooltips/exports stay SVG. Falls back to SVG if the module is missing. |
761
788
  | **Rewind** (undo/redo) | **2** | `apexcharts/features/history` | *(premium)* `chart: { history: { enabled: true } }`, then `chart.history.undo()/redo()/jump()/transaction()`. |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "apexcharts-skill",
3
- "version": "3.1.0",
3
+ "version": "4.0.0",
4
4
  "description": "AI coding skill for ApexCharts.js — structured reference docs that help AI assistants (Claude, Cursor, Copilot, etc.) generate correct ApexCharts code.",
5
5
  "keywords": [
6
6
  "apexcharts",
package/references/bar-charts.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  ## Chart Types Covered
4
4
 
5
- - **Column** (`'bar'`) — Vertical column chart (the default for `type: 'bar'`)
5
+ - **Column** (`'bar'`, or `'column'` since v7.9): Vertical column chart (the default for `type: 'bar'`). `chart.type: 'column'` is a plain synonym, rewritten to `'bar'` on the way in, so `w.config.chart.type` reads `'bar'`. Before v7.9 it broke the chart, so write `'bar'` for older versions.
6
6
  - **Bar** (`'bar'` + `plotOptions.bar.horizontal: true`) — Horizontal bar chart
7
7
  - **Range Bar** (`'rangeBar'`) — Bars with start/end values (used for timelines, Gantt charts)
8
8
  - **Funnel** (`'funnel'`, **new in v6**): Stage-by-stage drop-off chart
@@ -23,7 +23,7 @@ import ApexCharts from 'apexcharts/waterfall' // == apexcharts/bar + features/w
23
23
  import ApexCharts from 'apexcharts/dumbbell' // == apexcharts/bar + features/dumbbell
24
24
  ```
25
25
 
26
- Both are **Tier 1**, so the default `apexcharts` bundle already has them and no import is needed there.
26
+ **⚠️ Waterfall and dumbbell are Tier 2 since v8.0.** The default bundle no longer carries their features. Next to `import ApexCharts from 'apexcharts'` add only the feature, `import 'apexcharts/features/waterfall'` or `import 'apexcharts/features/dumbbell'` (script tag: `dist/features/waterfall.js` or `dist/features/dumbbell.js`). The bar renderer is already in the default bundle, and the `apexcharts/waterfall` / `apexcharts/dumbbell` entries above would add a second copy of it, so keep those for a tree-shaken build. Or use the full bundle (`apexcharts/full`, `dist/apexcharts.full.min.js`). Without the feature the chart draws an empty plot and the console names the import to add.
27
27
 
28
28
  **Alias note:** `funnel` and `pyramid` are first-class `chart.type` aliases that render through the bar engine. Use them directly as `chart.type`; you do **not** need `plotOptions.bar.isFunnel`. `plotOptions.funnel` carries the funnel-specific shape options.
29
29
 
@@ -197,6 +197,8 @@ Same shape as funnel, but order values **smallest → largest** so the wide base
197
197
  `chart.type: 'waterfall'` **accumulates the running total for you**. The series holds the **deltas**; a row flagged `isSubtotal` or `isTotal` draws the running total from zero at that position and carries **no `y` of its own**. Connectors bridge each bar's finish to the next one's start, and rising, falling and total bars take their own colors.
198
198
 
199
199
  ```js
200
+ import 'apexcharts/features/waterfall' // Tier 2 since v8.0: not in the default bundle
201
+
200
202
  {
201
203
  chart: { type: 'waterfall', height: 350 },
202
204
  series: [{
@@ -245,18 +247,22 @@ plotOptions: {
245
247
 
246
248
  A datum's own `fillColor` always wins over `plotOptions.waterfall.colors`.
247
249
 
250
+ **Data labels (v7.8):** each step is written on its bar with no background chip, in ink that follows `chart.foreColor`, so it reads in either theme and on a small step whose label sits outside the bar. `dataLabels: { background: { enabled: true } }` brings the chip back.
251
+
248
252
  ### Dumbbell (v7.1)
249
253
 
250
254
  `chart.type: 'dumbbell'` compares two or more measures per category. **Each series is one measure**, and the chart joins them with a connector per category. You do not zip the values into `[low, high]` pairs.
251
255
 
252
256
  ```js
257
+ import 'apexcharts/features/dumbbell' // Tier 2 since v8.0: not in the default bundle
258
+
253
259
  {
254
260
  chart: { type: 'dumbbell', height: 350 },
255
261
  series: [
256
262
  { name: '2020', data: [{ x: 'Backend', y: 92 }, { x: 'Frontend', y: 78 }] },
257
263
  { name: '2025', data: [{ x: 'Backend', y: 118 }, { x: 'Frontend', y: 96 }] },
258
264
  ],
259
- plotOptions: { bar: { horizontal: true } }, // rows; omit for columns
265
+ plotOptions: { bar: { horizontal: true } }, // rows, the default for dumbbell; set false for columns
260
266
  }
261
267
  ```
262
268
 
@@ -335,6 +341,8 @@ A stack of a single data point also stopped rounding its baseline in v7.4, which
335
341
  dataLabels: { animate: { enabled: false } }
336
342
  ```
337
343
 
344
+ **⚠️ `dataLabels.avoidOverlap` is on by default (v7.8).** Labels that land on each other, across series too, are nudged apart along the value axis (left and right on a horizontal bar), each by at most about its own size. A pair that cannot be separated stays overlapping unless you pass `{ hide: true }`. Tune it with `{ gap, maxShift, hide }`, or set `false` to keep every label where it was placed. Rotated labels (`orientation: 'vertical'`) are never moved. A manual `offsetY` that only separated labels may no longer be needed.
345
+
338
346
  ### Bar Chart Race (v6.4)
339
347
 
340
348
  A reorder update animates into a bar chart race: when you re-sort the data and update the chart, the bars slide to their new ranks and their category labels ride along automatically (whenever `dynamicAnimation` is on). Two `dataLabels` flags complete the effect, both **bar / column only**: `animate.enabled` is **on by default** since v7.0 (it was opt-in before), and `countUp.enabled` is off. their speed and easing follow `chart.animations.dynamicAnimation`.
@@ -377,6 +385,10 @@ series: [{
377
385
  }]
378
386
  ```
379
387
 
388
+ ### Part-of-whole overlay (v7.9, premium)
389
+
390
+ Bar, column, funnel and pyramid charts take `highlightFilter`, which draws each value faded with a part of it solid in front (`highlightData` on a series, or `highlight` on a point), after `import 'apexcharts/features/highlight-filter'`. See "Highlight filter" in `references/feature-platform.md`.
391
+
380
392
  ---
381
393
 
382
394
  ## Complete Working Example — Grouped Column Chart
@@ -424,7 +436,7 @@ series: [{
424
436
  ## Family-Specific Pitfalls
425
437
 
426
438
  1. **Assuming `type: 'bar'` renders horizontal bars** — it defaults to **vertical columns** (`horizontal: false`). Set `plotOptions.bar.horizontal: true` when you actually want horizontal bars.
427
- 2. **Stacking with `chart.stacked: true` but missing on bar type** — stacking only works on `type: 'bar'` (and `'area'`). It does NOT work on line, scatter, etc.
439
+ 2. **Expecting stacking to be bar-only**: `chart.stacked: true` stacks `bar`, `area` and `line` series. In a mixed chart only the bar/column series stack by default (`chart.stackOnlyBar: true`); set `stackOnlyBar: false` to stack the line and area series too.
428
440
  3. **Range Bar with single value instead of array** — `y` must be `[start, end]`, not a single number.
429
441
  4. **Timeline without `xaxis.type: 'datetime'`** — date-based range bars need `xaxis: { type: 'datetime' }` to render correctly.
430
442
  5. **`distributed: true` with multiple series** — distributed coloring applies to each data point independently. With multiple series, each point gets a unique color which is usually not desired. Use `distributed: true` only with single-series charts.
@@ -435,3 +447,4 @@ series: [{
435
447
  10. **Zipping dumbbell values into `y: [lo, hi]`** *(v7.1)*: that is the older `plotOptions.bar.isDumbbell` range-bar form. `chart.type: 'dumbbell'` wants one series per measure, each with plain `{ x, y }` points.
436
448
  11. **Assuming `borderRadiusWhenStacked` is still removed**: it was dead config in v7.0 through v7.3 and is a working option again from v7.4 (`'all'` default, `'last'` to leave the baseline square). Guidance written for v7.0 says to delete it; on v7.4+ that silently reverts a deliberate `'last'` to `'all'`.
437
449
  12. **Expecting data labels to snap on update** *(v7.0)*: `dataLabels.animate.enabled` now defaults to `true` on bar/column. Set it to `false` for the old behavior.
450
+ 13. **Waterfall or dumbbell on the default bundle** *(v8.0)*: draws an empty plot plus one console warning. Add `import 'apexcharts/features/waterfall'` (or `'apexcharts/features/dumbbell'`) next to `import ApexCharts from 'apexcharts'`.