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.
@@ -20,7 +20,7 @@ import ApexCharts from 'apexcharts/line'
20
20
  import ApexCharts from 'apexcharts/streamgraph' // == apexcharts/rangeArea + features/streamgraph
21
21
  ```
22
22
 
23
- Streamgraph is **Tier 1**, so the default `apexcharts` bundle already has it and no import is needed there.
23
+ **⚠️ Streamgraph is Tier 2 since v8.0.** The default bundle no longer carries its feature. Next to `import ApexCharts from 'apexcharts'` add `import 'apexcharts/features/streamgraph'` (script tag: `dist/features/streamgraph.js`). The range-area renderer is already in the default bundle, and the `apexcharts/streamgraph` entry above would add a second copy of it, so keep that 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.
24
24
 
25
25
  ---
26
26
 
@@ -135,6 +135,8 @@ Always use XY format:
135
135
  `chart.type: 'streamgraph'` stacks the series as flowing bands around a baseline chosen to keep the whole picture readable. Series format is the same as area; **the stacking is the chart's job, so do not set `chart.stacked`**.
136
136
 
137
137
  ```js
138
+ import 'apexcharts/features/streamgraph' // Tier 2 since v8.0: not in the default bundle
139
+
138
140
  {
139
141
  chart: { type: 'streamgraph', height: 350 },
140
142
  series: [
@@ -273,6 +275,10 @@ While the chart **is** zoomed and nothing else can reset it, one reset control i
273
275
 
274
276
  Requires `zoom.enabled: true`. A completed drag-zoom now also focuses the chart, so the `+`, `-` and `0` keys are reachable straight after a mouse zoom.
275
277
 
278
+ ### Part-of-whole overlay (v7.9, premium)
279
+
280
+ Line and area charts (stacked area too) 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`.
281
+
276
282
  ---
277
283
 
278
284
  ## Complete Working Example — Line Chart with Datetime
@@ -329,6 +335,7 @@ Requires `zoom.enabled: true`. A completed drag-zoom now also focuses the chart,
329
335
  6. **Setting `chart.stacked` on a streamgraph** *(v7.1)*: the chart owns its own stacking, baseline and band order through `plotOptions.streamgraph`. Reach for `offset: 'zero'` if what you actually want is a plain stacked area.
330
336
  7. **A series that starts with nulls used to mis-target the tooltip**: the hovered index resolved against the drawn points rather than the data, so the tooltip read the wrong point. Fixed in v7.1.
331
337
  8. **`autoScaleYaxis` scaling to points nobody can see**: before v7.1, zooming let one point just outside the window size the whole axis, and a series with nothing in the window still contributed. Fixed in v7.1; stacked charts now also scale to the stacked totals inside the window rather than to individual series.
338
+ 9. **Streamgraph on the default bundle** *(v8.0)*: draws an empty plot plus one console warning. Add `import 'apexcharts/features/streamgraph'` next to `import ApexCharts from 'apexcharts'`.
332
339
 
333
340
  ## Axis and layout fixes worth knowing (v7.0 / v7.1)
334
341
 
@@ -34,7 +34,7 @@ import { person, registerMarks } from 'apexcharts/pictograms'
34
34
  // Pictogram glyph collection (v7.0), one drawn mark per unit. See "Pictograms" below.
35
35
  ```
36
36
 
37
- All of these are **Tier 1** (in the default `apexcharts` bundle). Nothing in the circular family is Tier 2.
37
+ **⚠️ Sunburst and unit / waffle are Tier 2 since v8.0.** Pie, donut, polarArea, radialBar and gauge are in the default `apexcharts` bundle; `sunburst` and `unit` (with the `waffle` alias and the beeswarm layout) are not. Add `import 'apexcharts/sunburst'` or `import 'apexcharts/unit'` next to `import ApexCharts from 'apexcharts'` (script tag: `dist/sunburst.js` or `dist/unit.js`), or use the full bundle (`apexcharts/full`, `dist/apexcharts.full.min.js`). Without it the chart draws nothing and the console says the type is not registered, naming the import.
38
38
 
39
39
  ---
40
40
 
@@ -52,7 +52,7 @@ All of these are **Tier 1** (in the default `apexcharts` bundle). Nothing in the
52
52
  }
53
53
  ```
54
54
 
55
- ### Radial Bar (values 0–100)
55
+ ### Radial Bar (values on the min/max domain, default 0 to 100)
56
56
 
57
57
  ```js
58
58
  {
@@ -62,7 +62,7 @@ All of these are **Tier 1** (in the default `apexcharts` bundle). Nothing in the
62
62
  }
63
63
  ```
64
64
 
65
- **Important:** RadialBar values represent percentages (0–100). Values above 100 will overflow the track.
65
+ **Important:** RadialBar values sit on the `plotOptions.radialBar.min` to `max` domain, which defaults to 0 to 100, so by default they read as percentages. A value outside the domain is clamped to the end of the arc; set `min` / `max` to plot raw values.
66
66
 
67
67
  ### Gauge (v6)
68
68
 
@@ -102,7 +102,7 @@ A gauge is a single-value `radialBar` alias. Series is a flat one-element array;
102
102
  },
103
103
  needle: { color: '#0F172A', length: '60%', baseWidth: 6, tipWidth: 1 },
104
104
  hollow: { size: '70%' },
105
- dataLabels: { name: { show: false }, value: { offsetY: 32, fontSize: '28px', fontWeight: 700 } }
105
+ dataLabels: { name: { show: false }, value: { fontSize: '28px', fontWeight: 700 } } // value sits below the needle (v7.9)
106
106
  }
107
107
  }
108
108
  }
@@ -110,11 +110,15 @@ A gauge is a single-value `radialBar` alias. Series is a flat one-element array;
110
110
 
111
111
  A plain radialBar is effectively a gauge with `shape: 'arc'`. A semi-circle gauge is `startAngle: -90, endAngle: 90`.
112
112
 
113
+ **Needle value label (v7.9):** on a `gauge` with `shape: 'needle'` and no `plotOptions.radialBar.dataLabels.value.offsetY`, the value is placed below the farthest reach of the needle, so the two never cross (it used to sit under the needle). Set `offsetY` to place it yourself.
114
+
113
115
  ### Sunburst (v6.7)
114
116
 
115
117
  A sunburst draws a hierarchy as concentric rings: the first level fills a donut around the centre hole, and each deeper level stacks outward, with every child arc constrained to its parent's angular wedge. It is a **free** chart type (not gated). Data uses the axis-style `[{ data: [...] }]` wrapper, but each datum is an `{ x, y, children }` node nested to any depth. A leaf node omits `children`.
116
118
 
117
119
  ```js
120
+ import 'apexcharts/sunburst' // Tier 2 since v8.0: not in the default bundle
121
+
118
122
  {
119
123
  chart: { type: 'sunburst', height: 380 },
120
124
  series: [{
@@ -166,6 +170,8 @@ A `unit` chart renders one discrete mark for every unit of value instead of a si
166
170
  Data is the same flat number array + `labels` shape as pie:
167
171
 
168
172
  ```js
173
+ import 'apexcharts/unit' // Tier 2 since v8.0: not in the default bundle
174
+
169
175
  {
170
176
  chart: { type: 'unit', height: 360 },
171
177
  series: [276, 266, 3],
@@ -194,6 +200,7 @@ A companion kit of **39 shapes** a count can take (a heart, a house, a globe, th
194
200
 
195
201
  ```js
196
202
  import ApexCharts from 'apexcharts'
203
+ import 'apexcharts/unit' // the unit type is not in the default bundle since v8.0
197
204
  import { heart } from 'apexcharts/unit-shapes'
198
205
 
199
206
  new ApexCharts(el, {
@@ -226,7 +233,7 @@ strokeFrom(path, opts?) // your own centreline
226
233
  registerShapes([...]) // register so positions: '<name>' resolves by string
227
234
  ```
228
235
 
229
- Every shape carries metadata on `shape` (category, kind, and `minUnits`: the count below which it stops being recognisable; asking for fewer logs a console warning naming the shape). From a script tag, `dist/unit-shapes.js` exposes the kit as the global `ApexUnitShapes` with every shape pre-registered, so `positions: 'heart'` works by name.
236
+ Every shape carries metadata on `shape` (category, kind, and `minUnits`: the count below which it stops being recognisable; asking for fewer logs a console warning naming the shape). From a script tag, load `dist/unit.js` (the unit type) and then `dist/unit-shapes.js`, which exposes the kit as the global `ApexUnitShapes` with every shape pre-registered, so `positions: 'heart'` works by name. The full bundle (`apexcharts/full`, `dist/apexcharts.full.min.js`) already has the unit type and registers every shape and pictogram by name.
230
237
 
231
238
  ### Pictograms (`apexcharts/pictograms`, v7.0)
232
239
 
@@ -234,6 +241,7 @@ A **shape** is where the units go; a **pictogram** is what one unit looks like.
234
241
 
235
242
  ```js
236
243
  import ApexCharts from 'apexcharts'
244
+ import 'apexcharts/unit' // the unit type is not in the default bundle since v8.0
237
245
  import { person, registerMarks } from 'apexcharts/pictograms'
238
246
 
239
247
  registerMarks([person]) // so pictogram.mark: 'person' resolves by name
@@ -430,6 +438,10 @@ plotOptions: {
430
438
  }
431
439
  ```
432
440
 
441
+ ### Part-of-whole overlay (v7.9, premium)
442
+
443
+ Pie, donut, polarArea, radialBar and gauge charts take `highlightFilter`, which draws each value faded with a part of it solid in front (parts in `highlightFilter.data`, one per slice or ring, or `highlight` on a slice's `{ x, y }` point), after `import 'apexcharts/features/highlight-filter'`. See "Highlight filter" in `references/feature-platform.md`. While parts are shown, the donut and radialBar `total.formatter` reads the parts in `w.globals.seriesTotals` (unless `highlightFilter.dataLabels.total` is `'whole'`).
444
+
433
445
  ---
434
446
 
435
447
  ## Complete Working Example — Donut with Center Label
@@ -482,13 +494,13 @@ plotOptions: {
482
494
  ## Family-Specific Pitfalls
483
495
 
484
496
  1. **Using axis-chart series format** — `series: [{ name: 'A', data: [44, 55] }]` is WRONG for pie/donut. The x/y object form `series: [{ data: [{ x: 'A', y: 44 }] }]` works (ApexCharts normalizes it), but the canonical form is preferred: `series: [44, 55]` (flat array) + `labels: ['A', 'B']`.
485
- 2. **RadialBar values above 100** — values represent percentages and will overflow. If you have raw values, calculate percentages first: `(value / max) * 100`.
497
+ 2. **RadialBar raw values on the default domain**: the domain defaults to 0 to 100, so a value such as 340 is clamped to a full arc. Set `plotOptions.radialBar.min` / `max` to the raw range, or convert to percentages first: `(value / max) * 100`.
486
498
  3. **Missing `labels` array** — without `labels`, pie/donut slices show as "undefined" in tooltips and legend.
487
499
  4. **Donut center labels not showing** — must set `plotOptions.pie.donut.labels.show: true` explicitly.
488
500
  5. **`total.formatter` signature** — receives `w` (the full chart config object), NOT a simple value. Access `w.globals.seriesTotals` for the array of current values.
489
501
  6. **Polar Area confused with Radar** — polar area uses `series: [num]` (flat), radar uses `series: [{ data: [num] }]` (axis format). They look similar but have different data shapes.
490
502
  7. **Looking for `plotOptions.gauge`**: it does not exist. Gauge is a `radialBar` alias; configure `shape`, `bands`, `ticks`, `needle`, and `min`/`max` under `plotOptions.radialBar`.
491
- 8. **Gauge value outside `min`/`max`**: unlike a plain radialBar (fixed 0-100), a gauge maps its value to the `min..max` domain you set. A value beyond that domain saturates at the arc ends.
503
+ 8. **Gauge value outside `min`/`max`**: a gauge, like a plain radialBar, maps its value to the `min..max` domain you set (default 0 to 100). A value beyond that domain saturates at the arc ends.
492
504
  9. **Legend click now toggles the slice (v6.7 behavior change)**: on pie, donut, and polarArea a legend click hides and shows the slice (like other chart types). Previously it darkened and expanded the slice. If your app relied on the old darken-and-expand behavior, review this.
493
505
  10. **Expecting `unit` / `waffle` without a license to be watermark-free**: they are premium and render an `APEXCHARTS` watermark until an entitled `premium`/`enterprise` license is set. Sunburst, by contrast, is free.
494
506
  11. **Slice click behavior changed (v6.9)**: clicking a pie/donut slice now slides it out along its own mid-angle (`plotOptions.pie.expandOffset`, default 10 px) instead of darkening it and redrawing it at a larger radius, and hover traces an outline band (`plotOptions.pie.hoverOutline`) instead of lightening the fill. Set `expandOffset: 0` to keep slices in place; set `states.hover.filter.type: 'none'` to suppress the hover band.
@@ -496,3 +508,4 @@ plotOptions: {
496
508
  13. **Confusing a shape with a pictogram** *(v7.0)*: `plotOptions.unit.positions` (from `apexcharts/unit-shapes`) is **where** the units go; `plotOptions.unit.shape: 'pictogram'` + `pictogram.mark` (from `apexcharts/pictograms`) is **what one unit looks like**. They compose freely.
497
509
  14. **Setting a size on a pictogram** *(v7.0)*: there is no `pictogram.size`. A glyph is fitted to the box the dot would have occupied, so use `plotOptions.unit.size` and `spacing`. Use `pictogram.scale` only to nudge a glyph that reads light.
498
510
  15. **Pie / radial charts pinned to the top of a tall container** *(fixed v7.1)*: the centre came from `min(width, height)`, so a tall, narrow container put the circle at the top with the leftover space below it. The circle now centres in the height it actually has. If you carried a manual `offsetY` to work around this, remove it.
511
+ 16. **Sunburst, unit or waffle on the default bundle** *(v8.0)*: draws nothing and the console says the type is not registered. Add `import 'apexcharts/sunburst'` or `import 'apexcharts/unit'` next to `import ApexCharts from 'apexcharts'`. `apexcharts/unit-shapes` and `apexcharts/pictograms` do not register the unit type.
@@ -1,26 +1,29 @@
1
1
  # Feature Platform: ApexCharts
2
2
 
3
- ApexCharts ships an opt-in feature platform on top of the chart core. **Every v5 and v6 config keeps working unchanged in v7**, apart from the two v7.0 breaking changes noted below. Each feature is off by default in config terms and ships as its own `apexcharts/features/*` entry.
3
+ ApexCharts ships an opt-in feature platform on top of the chart core. **Every v5 and v6 config keeps working unchanged in v7**, apart from the two v7.0 breaking changes noted below. In 8.0 the breaking change is what the default bundle carries (next section). Each feature is off by default in config terms and ships as its own `apexcharts/features/*` entry.
4
4
 
5
- ## ⚠️ Read first: two bundle tiers (v7.0)
5
+ ## ⚠️ Read first: what is in the default bundle (8.0)
6
6
 
7
- Whether you need the `features/*` import depends on the feature's **tier**, and this changed in v7.0.
7
+ Whether you need an import depends on the feature's or chart type's **tier**. The tiers date from v7.0. **8.0 moved seven items to Tier 2**: the `unit` (with `waffle`), `sunburst` and `violin` chart types, and the `drilldown`, `waterfall`, `dumbbell` and `streamgraph` features. A page that uses one adds its import, or loads the full bundle.
8
8
 
9
- - **Tier 1** is in the default `import ApexCharts from 'apexcharts'` bundle: `exports`, `legend`, `toolbar`, `annotations`, `keyboard`, `morph`, `drilldown`, `weave`, `marks`, `facet`, `stats`, and the v7.1 `waterfall` / `dumbbell` / `streamgraph` chart types. Import these only if you started from `apexcharts/core` or a per-type entry.
10
- - **Tier 2 is not in any bundle.** Nine features (`trellis`, `storyboard`, `perspectives`, `ink`, `renderer-canvas`, `link`, `measure`, `history`, `context-menu`) plus the `raincloud` (premium) and `icicle` (free) chart types require an explicit import **whatever entry point you used**, the full bundle included.
9
+ - **Tier 1** is in the default `import ApexCharts from 'apexcharts'` bundle: `exports`, `legend`, `toolbar`, `annotations`, `keyboard`, `morph`, `weave`, `marks`, `facet`, `stats`. Import these only if you started from `apexcharts/core` or a per-type entry.
10
+ - **Tier 2 is not in the default bundle.** Each item needs its own import next to it (or its script tag), or the full bundle:
11
+ - features, `import 'apexcharts/features/<name>'` (script tag `dist/features/<name>.js`): `trellis`, `storyboard`, `perspectives`, `ink`, `renderer-canvas`, `link`, `measure`, `history`, `context-menu`, `highlight-filter` *(7.9)*, and since 8.0 `drilldown`, `waterfall`, `dumbbell` and `streamgraph` (those three are chart types whose renderers, rangeBar and rangeArea, are in the default bundle, so next to it you add only the feature);
12
+ - chart types: `unit` / `waffle` (`apexcharts/unit`, `dist/unit.js`), `sunburst`, `violin`, `icicle` (`apexcharts/<type>`, `dist/<type>.js`) and `raincloud` (`apexcharts/raincloud`; script tags `dist/violin.js`, then `dist/features/raincloud.js`).
13
+ - **The full bundle**, `import ApexCharts from 'apexcharts/full'` (script tag `dist/apexcharts.full.min.js`, new in 8.0), has every chart type and feature and needs no add-on import. Premium items still watermark there.
11
14
 
12
15
  ```js
13
16
  import ApexCharts from 'apexcharts'
14
- import 'apexcharts/features/trellis' // Tier 2: required even here
17
+ import 'apexcharts/features/trellis' // Tier 2: not in the default bundle
15
18
  ```
16
19
  ```html
17
20
  <script src=".../dist/apexcharts.js"></script>
18
21
  <script src=".../dist/features/trellis.js"></script>
19
22
  ```
20
23
 
21
- Nothing fails silently: each Tier 2 module warns in the console when its configuration is present but the module is not, and names both import routes. Where the chart can still draw something sensible it does and says what it did: a trellis renders as a single chart, `renderer: 'canvas'` falls back to SVG. `apexcharts/features/all` is the **Tier 1** set and is not a shortcut past this.
24
+ Nothing fails silently, and since 7.9.1 the minified bundle prints these warnings too. A Tier 2 chart type that is not loaded makes `render()` reject, and the console names the import. A Tier 2 feature warns when its configuration is present but the module is not, naming the import, the script-tag file and `apexcharts.full.min.js`. Where the chart can still draw something sensible it does and says what it did: a trellis renders as a single chart, `renderer: 'canvas'` falls back to SVG, a drilldown chart draws its root level. `waterfall`, `dumbbell` and `streamgraph` without their feature draw an empty plot with one warning. `apexcharts/features/all` is the **Tier 1** set and is not a shortcut past this; the full bundle is.
22
25
 
23
- Why: 24% of the 6.10.0 default bundle was licence-gated premium code that an unlicensed user could only run watermarked, and everybody downloaded it. The default bundle went 291,654 B gzipped (6.10.0) to 252,005 B (7.0.0), and 264,326 B in 7.1.0 with the three new free chart types. It is about 270 KB at 7.6.1 (measured on the shipped dist with gzip -9; the upstream build report gzips at a different level and prints a few hundred bytes more). See `references/tree-shaking.md` for the full tier table and per-module sizes.
26
+ Why: 24% of the 6.10.0 default bundle was licence-gated premium code that an unlicensed user could only run watermarked, and everybody downloaded it. The default bundle went 291,654 B gzipped (6.10.0) to 252,005 B (7.0.0), and 264,326 B in 7.1.0 with the three new free chart types. At 8.0.0 it is 263,188 B, and the full bundle 381,135 B (the upstream build report's figures, gzip at the default level; they move every release). See `references/tree-shaking.md` for the full tier table and per-module sizes.
24
27
 
25
28
  ## Two v7.0 breaking changes
26
29
 
@@ -45,7 +48,7 @@ Two update behaviors worth knowing (both 6.9/6.10):
45
48
 
46
49
  ## Licensing: premium features and the trial watermark
47
50
 
48
- Introduced in **6.5.0**, tightened in **6.7.0**. Not every feature is free. Eight feature modules plus two chart types are **premium** and run under a lightweight, offline license check. They keep working fully without a key (trial mode), but the chart shows an unobtrusive `APEXCHARTS` watermark until an entitled license is set.
51
+ Introduced in **6.5.0**, tightened in **6.7.0**. Not every feature is free. Nine feature modules plus two chart types are **premium** and run under a lightweight, offline license check. They keep working fully without a key (trial mode), but the chart shows an unobtrusive `APEXCHARTS` watermark until an entitled license is set.
49
52
 
50
53
  **The premium set (watermarked until entitled):**
51
54
 
@@ -57,12 +60,13 @@ Introduced in **6.5.0**, tightened in **6.7.0**. Not every feature is free. Eigh
57
60
  - `context-menu` (`contextMenu`)
58
61
  - `perspectives` (shareable view state)
59
62
  - `history` (undo/redo, Rewind)
63
+ - `highlight-filter` (`highlightFilter`, premium since **7.9.0**; watermarks only while a render draws parts)
60
64
  - the `unit` / `waffle` chart type (premium since **6.6.0**, the first premium chart type)
61
65
  - the `raincloud` chart type (premium since **7.1.0**)
62
66
 
63
- **Everything else is free and never gated**: every other chart type (`sunburst`, the v7.1 `waterfall` / `dumbbell` / `streamgraph`, and the v7.6 `icicle`, which is an opt-in import but free), and every other module (Weave, Strata / canvas, Marks, Facet / themes, Cadence, drilldown, streaming, exports, legend, toolbar, annotations, keyboard, stats).
67
+ **Everything else is free and never gated**: every other chart type (the Tier 2 `sunburst`, `violin`, `icicle`, `waterfall`, `dumbbell` and `streamgraph` included), and every other module (Weave, Strata / canvas, Marks, Facet / themes, Cadence, drilldown, streaming, exports, legend, toolbar, annotations, keyboard, stats). Free here means never watermarked, not licence-free: the Community licence covers only organisations under $2M in annual revenue, operating budget, funding or equivalent resources, whichever is highest, across parent, affiliates and entities under common control (see LICENSE.md).
64
68
 
65
- **Premium and Tier 2 are independent axes.** Premium is about the watermark; Tier 2 is about the bundle. `renderer-canvas` is Tier 2 and free. `waterfall`, `dumbbell` and `streamgraph` are Tier 1 and free. `unit` / `waffle` is premium but Tier 1 (it is a chart type in the default bundle). `trellis` and `raincloud` are both.
69
+ **Premium and Tier 2 are separate questions.** Premium is about the watermark; Tier 2 is about the bundle. Since 8.0 every premium item is Tier 2, but Tier 2 is not all premium: `renderer-canvas`, `drilldown`, `waterfall`, `dumbbell`, `streamgraph`, `sunburst`, `violin` and `icicle` are Tier 2 and free. The full bundle carries all of them, and the premium ones still watermark there.
66
70
 
67
71
  ### Setting a license
68
72
 
@@ -78,7 +82,7 @@ Both are typed: `ApexCharts.setLicense(key: string)` (static) and `chart.license
78
82
 
79
83
  - **In use, not bundled.** Importing a premium module without actually enabling it does not watermark; only *using* it does.
80
84
  - **Live.** A late `setLicense(validKey)` followed by an update clears an on-screen watermark; no full re-render needed. The watermark is re-evaluated on every render/update.
81
- - **One key across the family.** The key format is shared across the ApexCharts family (apexgantt, apextree, apexsankey, apex-grid-enterprise, apexstock), validated offline with no network call. SSR-safe.
85
+ - **One key across the family.** The key format is shared across every Apex product (apexgantt, apextree, apexsankey, apex-grid-enterprise, apexstock, apexmaps), validated offline with no network call. SSR-safe.
82
86
 
83
87
  ### Plan entitlement (6.7.0 behavior change)
84
88
 
@@ -127,6 +131,7 @@ trellis: { by: 'facet', minPanelWidth: 260 },
127
131
  | `columns` | `'auto'` | `'auto'` fits `minPanelWidth` columns into the container. |
128
132
  | `minPanelWidth` | `220` | Drives `'auto'` columns and the responsive collapse. |
129
133
  | `gap` / `aspectRatio` / `panelHeight` | `12` / `1.6` / none | `panelHeight` wins over `aspectRatio` and `chart.height`. |
134
+ | `minPanelHeight` | `80` | *(7.7.0)* Floor for a height-derived panel, in px. A grid that cannot fit its container overflows and warns by how much instead of shrinking panels past this. Lower it when fitting a short container matters more than legibility. |
130
135
  | `order` | `'first-seen'` | Also `'asc'`, `'desc'`, an explicit `string[]`, or a comparator. |
131
136
  | `limit` | none | Render only the first N panels (warns about the rest). |
132
137
  | `virtualize` | `'auto'` | Mounts only panels intersecting the viewport (plus one row) once the grid exceeds **64 panels**. An unmounted cell keeps its header and a fixed-height skeleton so page height never shifts; a remount restores its zoom window. **`getPanel(key)` returns `null` for an unmounted panel.** |
@@ -136,13 +141,15 @@ trellis: { by: 'facet', minPanelWidth: 260 },
136
141
  | `legend` / `toolbar` | `'shared'` | One legend (toggles a series name in every panel) and one zoom/pan/reset toolbar. `'none'` to drop. |
137
142
  | `tooltip` | `'panel'` | Card in the hovered panel while the crosshair sweeps all. `'sync'` = a card per panel; `'grid'` = one card near the cursor with a row per panel, composed from the panels' own tooltips so every formatter is honored. |
138
143
  | `zoom` | `'sync'` | A zoom in any panel moves every panel. |
139
- | `promote` | `true` | Clicking a header expands that panel to full width with an "All panels" breadcrumb. |
144
+ | `promote` | `false` | *(7.7.0 BREAKING: was `true`)* Set `true` to make a header click expand that panel to full width with an "All panels" breadcrumb. `chart.promotePanel(key)` / `chart.restorePanels()` work either way. |
140
145
  | `radiusByTotal` | `false` | Pie/donut/polarArea only: scale each panel's radius so its **area** is proportional to the panel's total. Equal-size pies cannot encode magnitude, so set this on a pie trellis. |
141
146
  | `targetTicks` | `3` | Tick-interval target for the shared nice y scale, so a small panel wears few labels. |
142
147
  | `header` | shown | `{ show, formatter(key, { dimension, index, count }), style }`. |
143
148
  | `panel` | none | `(key, { index, seriesNames }) => ApexOptions`, a per-panel override applied last. |
144
149
 
145
- **API.** `chart.getPanels()` returns the panels in grid order; `chart.getPanel(key)` returns one panel's own ApexCharts instance (the escape hatch to every per-chart API the trellis does not re-expose); `chart.promotePanel(key)` / `chart.restorePanels()` drive the promotion from code. `ApexCharts.trellis(el, options)` is the imperative constructor and throws if the feature is not imported.
150
+ **API.** `chart.getPanels()` returns the panels in grid order; `chart.getPanel(key)` returns one panel's own ApexCharts instance (the escape hatch to every per-chart API the trellis does not re-expose); `chart.promotePanel(key)` / `chart.restorePanels()` drive the promotion from code. `ApexCharts.trellis(el, options)` is the imperative constructor: it creates the host and starts rendering it (a later `render()` settles with the same mount). It returns `null`, with a console warning, when the trellis feature is not loaded, so check the return before calling panel methods.
151
+
152
+ **Events.** `panelMounted`, `trellisMounted`, `panelPromoted` and `panelRestored` fire through `chart.events` (7.7.0) as well as `addEventListener`, with `(chart, payload)`; they are not in the shipped types. On scatter and bubble panels `dataPointIndex` indexes the panel's own data. To turn a trellis back into one chart, pass `trellis: null` to `updateOptions` (a cast in TypeScript); leaving the key out keeps the grid.
146
153
 
147
154
  **Annotations** take `scope`: absent or `'trellis'` draws in every panel through each panel's own scale, a key or array of keys restricts it.
148
155
 
@@ -289,7 +296,7 @@ api.on('draw', () => {
289
296
 
290
297
  Declared in the shipped `apexcharts.d.ts`: `ApexPluginAPI` (the `setup(api)` facade), `ApexPluginSeries`, `ApexPluginScales`, `ApexPluginLayer`, `ApexPluginHook`, `ApexPluginPayload`, and for the v6 additions `ApexPluginChartInfo` (`api.info`), `ApexPluginPointerEvent` (the `pointer` payload), `ApexPluginClaim` (`{ release(), update(entries) }`) and `ApexDrawnItem` (a `drawn()` row).
291
298
 
292
- ### Typing gap at 7.6.1
299
+ ### Typing gap (still present at 8.0.0)
293
300
 
294
301
  `api.categories` and `data[].raw` are real at runtime (both shipped in v2) but are **not declared** in the shipped `apexcharts.d.ts`: `ApexPluginAPI` has no `categories` member and `ApexPluginSeries` is typed as `{ name?, hidden, color?, points }`. TypeScript rejects both. Cast the facade where you need them, and do not read the absence as "removed".
295
302
 
@@ -403,6 +410,8 @@ ApexCharts.perspectives.decode(str)
403
410
  const options = { chart: { perspectives: { serializeOptions: ['colors', 'title'] } } }
404
411
  ```
405
412
 
413
+ Calling the static `decode` / `fromURL` counts as using Perspectives for every chart on the page that has the feature loaded, so an unlicensed page shows the watermark on those charts (a script-tag add-on included, since 7.9.1).
414
+
406
415
  ---
407
416
 
408
417
  ## Facet: design tokens and OS-aware themes
@@ -500,6 +509,55 @@ const b = {
500
509
 
501
510
  ---
502
511
 
512
+ ## Highlight filter
513
+
514
+ `import 'apexcharts/features/highlight-filter'` *(7.9)*: **Tier 2** (not in the default bundle; script tag `dist/features/highlight-filter.js`, or the full bundle) and **premium**. It watermarks only while a render draws parts: loading the feature, or drawing a chart with no parts, never does.
515
+
516
+ Each value is drawn faded at its whole, with a part of it solid in front, from the same baseline and in the same slot: what a dashboard shows when a pick elsewhere leaves part of every value behind. The part travels with the data, as `highlightData` on a series (parallel to `data`, `null` where a datum has none) or `highlight` on a point (`{ x, y, highlight }`, which wins), so a pick and a clear are ordinary updates. A part may exceed its whole (an average) or have the other sign. Parts alone switch it on; every option is optional.
517
+
518
+ ```js
519
+ import ApexCharts from 'apexcharts'
520
+ import 'apexcharts/features/highlight-filter'
521
+
522
+ const chart = new ApexCharts(el, {
523
+ chart: { type: 'bar' },
524
+ series: [{ name: 'Units', data: [34, 43, 66], highlightData: [26, null, 50] }],
525
+ xaxis: { categories: ['2015', '2016', '2017'] },
526
+ })
527
+ await chart.render()
528
+
529
+ // A new pick is an updateSeries() with new parts, or the helpers:
530
+ await chart.highlightFilter.set([[8, 14, 16]]) // one row per series
531
+ await chart.highlightFilter.clear() // the plain chart again
532
+ ```
533
+
534
+ A pie, donut, polarArea, radialBar or gauge has no per-datum slot for a part, so give one per slice or ring in `highlightFilter.data` (a `highlight` on a slice's own `{ x, y }` point wins). A nested treemap takes `highlight` on each leaf and ignores `highlightData` with a warning.
535
+
536
+ | Option | Default | Notes |
537
+ |---|---|---|
538
+ | `enabled` | `true` | `false` keeps the parts in the data but draws the chart as usual. |
539
+ | `data` | none | Circles only: one part per slice or ring. Ignored, with a warning, while its length differs from the slice count. |
540
+ | `fadeOpacity` | `0.2` | Opacity of the faded whole. |
541
+ | `outline` | `{ width: 1, opacity: 1 }` | Keeps a faded whole readable; `width: 0` for none. |
542
+ | `enter` | `'whole'` | First pick: each part starts as its whole and drains (or grows) to the part. `'baseline'` rises from the baseline. |
543
+ | `axis` | `'extend'` | A part past the value axis stretches the axis; `'clamp'` keeps the axis the wholes set. |
544
+ | `dataLabels` | `{ value: 'part', total: 'part' }` | Each `'part'` or `'whole'`. `total` is the stack total and the donut's centre total. |
545
+ | `tooltip` | `{ show: true, share: false }` | Each row reads "part / whole"; `share` appends the part's percentage; `formatter(part, whole, opts)` returns the row's value text instead (plain text or HTML); the series name stays. |
546
+
547
+ Per type:
548
+
549
+ - `line.dashArray` (`4`): a line chart draws the whole dashed at full strength, with the part solid over it.
550
+ - `pie.encoding` (`'radius'`): how a part's share sets its radius on pie and donut; `'area'` makes the part's area its share. polarArea follows its own value scale.
551
+ - `radialBar.indicator`: `'arc'` when unset (the part as a solid arc in front of its faded whole), except `'needle'` on a gauge with `plotOptions.radialBar.shape: 'needle'`. `'lanes'` splits each ring into an outer whole lane and an inner part lane, for a part that can exceed its whole (`lanes.opacity`, default 0.45; the word on the whole lane's tooltip row is the locale's `options.highlightFilter.part`). `needle: { color, length, baseWidth, tipWidth, offsetY }` falls back to `plotOptions.radialBar.needle`.
552
+
553
+ **Where it draws.** Column and bar (grouped, horizontal, distributed, negative values, stacked including 100% and groups), funnel and pyramid, line and area (every curve, stacked area too), pie, donut, polarArea, radialBar and gauge, and treemap (flat and nested). Any other type, mixed-type charts, range series, histograms, and stacked charts over more than one y axis or a logarithmic one warn once and draw as usual. `highlightData` cannot follow `chart.dataReducer` or `chart.streaming` and warns there: put the part on each point instead.
554
+
555
+ **API and event.** `chart.highlightFilter` is `{ isActive(), valueAt(seriesIndex, dataPointIndex?), set(parts, opts?), clear(opts?) }`, or `null` without the feature (parts are then ignored with one console warning naming the import). `set` takes one row per series, one value per slice or ring on a circle, or a function of the datum, and resolves when the update is drawn. `chart.events.highlightFilterChanged(chart, { active, phase })` fires once that render is drawn, with `phase` `'enter'`, `'update'` or `'clear'`. Slice and tile label formatters (pie, donut, polarArea, treemap) and the donut and radialBar centre value and total formatters receive `opts.highlight` (`{ value, total, share, overflow }`). In `tooltip.custom`, read the part with `opts.ctx.highlightFilter.valueAt(opts.seriesIndex, opts.dataPointIndex)`.
556
+
557
+ **Drilldown.** A drill, either way, drops the parts from the level it shows, including any written into a `drilldown.series` entry, and reports `'clear'` if parts were on screen. Send the pick for the new level with `chart.highlightFilter.set()`.
558
+
559
+ ---
560
+
503
561
  ## Ink: direct-manipulation annotation authoring
504
562
 
505
563
  `import 'apexcharts/features/ink'`: **Tier 2** (not in the default bundle) and **premium**.
@@ -641,13 +699,14 @@ const options = { chart: { streaming: { enabled: true, maxPoints: 100000 } } }
641
699
 
642
700
  ## Drilldown: hierarchical drill-down
643
701
 
644
- `import 'apexcharts/features/drilldown'` (add `import 'apexcharts/features/morph'` for animated cross-type transitions): both Tier 1 (already in the default bundle).
702
+ `import 'apexcharts/features/drilldown'`: **Tier 2 since 8.0** (no longer in the default bundle; script tag `dist/features/drilldown.js`, or the full bundle). Free. `apexcharts/features/morph`, for animated cross-type transitions, is Tier 1 and already in the default bundle. Without the drilldown import, a chart with `drilldown.enabled` warns once and draws its root level, which never navigates, and `chart.drillDown()` / `drillUp()` / `drillToRoot()` / `clearDrilldownCache()` throw.
645
703
 
646
704
  Data points reference a child level via a `drilldown` id; clicking drills in, with an optional breadcrumb. Since **v6.9** drilldown also works on **line and area** charts, and levels can be resolved **async** against a backend.
647
705
 
648
706
  ```js
649
- import 'apexcharts/features/drilldown'
650
- import 'apexcharts/features/morph' // optional, animated type morphs
707
+ import ApexCharts from 'apexcharts'
708
+ import 'apexcharts/features/drilldown' // Tier 2 since 8.0
709
+ import 'apexcharts/features/morph' // animated type morphs; already in the default bundle
651
710
 
652
711
  const options = {
653
712
  series: [{ data: [
@@ -690,6 +749,8 @@ chart.drillToRoot()
690
749
 
691
750
  **Async failure semantics (v6.9):** a failed fetch never strands the view. On a throw, a rejection, or a resolver returning something without a `data` array, the chart stays where it was, the breadcrumb is untouched, nothing is cached, and `drillDownError` fires. A second click while one resolve is in flight is ignored rather than starting a second request.
692
751
 
752
+ *(8.0)* A child level naming a Tier 2 chart type whose renderer the page has not loaded (`unit` / `waffle`, `sunburst`, `icicle`, `violin`, and `raincloud`, which draws through violin) is refused too: the update stops before anything moves, the level comes back off the stack, `drillDownError` fires with the error, and the `chart.drillDown(id)` promise rejects. A `waterfall`, `dumbbell` or `streamgraph` level without its feature is not refused: it navigates, then draws blank with one console warning. Load each level's chart type and feature as well as the drilldown feature.
753
+
693
754
  ---
694
755
 
695
756
  ## Stats: raw-sample statistics (6.9.0)
@@ -700,9 +761,9 @@ Free. The statistics behind three things, kept out of core so they cost nothing
700
761
 
701
762
  - **Histogram binning**: `chart.type: 'histogram'` bins raw observations (the `apexcharts/histogram` entry includes this feature automatically).
702
763
  - **Raw samples for boxPlot and violin**: a datum supplying `points: [number]` instead of a summary `y` gets its quartiles (R type 7) or KDE density computed.
703
- - **`chart.rowSeries(opts?)`**: returns the rows behind the chart's marks as a unit-chart series (one cluster per mark), or `null` when the type has no row source. `chart.updateOptions({ chart: { type: 'unit' }, series: chart.rowSeries() })` opens a summary into its observations; with the `morph` feature loaded each dot leaves from the part of the mark that stood for it.
764
+ - **`chart.rowSeries(opts?)`**: returns the rows behind the chart's marks as a unit-chart series (one cluster per mark), or `null` when the type has no row source. `chart.updateOptions({ chart: { type: 'unit' }, series: chart.rowSeries() })` opens a summary into its observations; with the `morph` feature loaded each dot leaves from the part of the mark that stood for it. Since 8.0 `unit` is Tier 2, so add `import 'apexcharts/unit'` (or `dist/unit.js`, or the full bundle) first. Without it the update is refused with a console error and the chart stays as it was.
704
765
 
705
- Full data shapes and options are in `references/financial-charts.md`. The full `apexcharts` bundle includes it.
766
+ Full data shapes and options are in `references/financial-charts.md`. The default `apexcharts` bundle includes it.
706
767
 
707
768
  ---
708
769
 
@@ -736,9 +797,9 @@ const options = {
736
797
 
737
798
  ## Common Pitfalls
738
799
 
739
- 1. **Assuming the full bundle still carries everything *(the #1 v6 → v7 mistake)*.** In v6, `import ApexCharts from 'apexcharts'` was enough for every feature. In v7 the nine Tier 2 features and the `raincloud` and `icicle` types need their own import on top of it. Read the console: each one names both routes when its config is present without it.
800
+ 1. **Assuming the default bundle carries everything *(the #1 upgrade mistake, v6 to v7 and again 7 to 8)*.** In v6, `import ApexCharts from 'apexcharts'` was enough for every feature. At 8.0 each of these needs its own import on top of it: the features `trellis`, `storyboard`, `perspectives`, `ink`, `renderer-canvas`, `link`, `measure`, `history`, `context-menu`, `highlight-filter`, `drilldown`, `waterfall`, `dumbbell` and `streamgraph`, and the `unit` / `waffle`, `sunburst`, `violin`, `icicle` and `raincloud` chart types. Read the console: each names the import, the script-tag file and `apexcharts.full.min.js`.
740
801
  2. **Forgetting the feature import on a tree-shaken build**: a Tier 1 feature is in the default bundle but not in `apexcharts/core` or a per-type entry, so those builds still need `import 'apexcharts/features/<name>'`.
741
- 3. **Reaching for `apexcharts/features/all` to fix either of the above**: it is the Tier 1 set only, by design (`tests/unit/feature-tier-budget.spec.js` upstream fails the build if a Tier 2 feature reappears in it).
802
+ 3. **Reaching for `apexcharts/features/all` to fix either of the above**: it is the Tier 1 set only, by design (`tests/unit/feature-tier-budget.spec.js` upstream fails the build if a Tier 2 feature reappears in it). The entry that does have everything is `apexcharts/full`.
742
803
  4. **Using `api.zeroY` in a custom mark**: it does not exist. Use `ctx.scales.y(0)` for the baseline.
743
804
  5. **Expecting `mode: 'filter'` on `chart.link` without records**: highlight mode needs `chart.selection.enabled: true`; the crossfilter engine needs `ApexCharts.crossfilter({ id, records })` or a `dimension` extractor.
744
805
  6. **Two different `largeDatasetThreshold` options.** `chart.animations.largeDatasetThreshold` (default 1000) skips update animations; `markers.largeDatasetThreshold` *(v7.0, default 0 = off)* batches a series' markers into one path. Neither lives on `chart` directly.
@@ -4,7 +4,7 @@
4
4
 
5
5
  - **Candlestick** (`'candlestick'`) — OHLC (Open, High, Low, Close) financial chart
6
6
  - **Box Plot** (`'boxPlot'`) — Statistical distribution chart showing min, Q1, median, Q3, max
7
- - **Violin** (`'violin'`, **new in v6**): Statistical distribution chart showing a density curve per category, optionally with the raw sample points overlaid as jitter
7
+ - **Violin** (`'violin'`, **new in v6, Tier 2 since v8.0**): Statistical distribution chart showing a density curve per category, optionally with the raw sample points overlaid as jitter
8
8
  - **Histogram** (`'histogram'`, **new in v6.9**): Bins raw observations into columns; the series carries the sample, the chart does the aggregating
9
9
  - **Raincloud** (`'raincloud'`, **new in v7.1, premium, Tier 2**): A distribution shown three ways at once: a half-violin for the shape, a box for the summary, and the observations themselves as "rain" underneath
10
10
 
@@ -15,14 +15,19 @@ import ApexCharts from 'apexcharts/candlestick'
15
15
  // Registers: candlestick, boxPlot
16
16
  // Alias: apexcharts/boxPlot
17
17
 
18
- import ApexCharts from 'apexcharts/violin'
19
- // Registers: violin (separate entry point, new in v6)
20
-
21
18
  import ApexCharts from 'apexcharts/histogram'
22
19
  // Registers: histogram (v6.9), the bar engine plus the stats feature
23
20
 
24
- import ApexCharts from 'apexcharts/raincloud'
25
- // Registers: raincloud (v7.1), the violin engine plus the raincloud feature
21
+ // violin is Tier 2 since v8.0 and raincloud since v7.1: neither is in the default bundle.
22
+ // Add the entry next to the default bundle:
23
+ import ApexCharts from 'apexcharts'
24
+ import 'apexcharts/violin' // Registers: violin (new in v6)
25
+ import 'apexcharts/raincloud' // Registers: raincloud (v7.1), the violin engine plus the raincloud feature
26
+
27
+ // Tree-shaking: violin and raincloud draw on the bar renderer without
28
+ // bundling one, so pair them with apexcharts/bar
29
+ import ApexCharts from 'apexcharts/bar'
30
+ import 'apexcharts/violin' // or 'apexcharts/raincloud'
26
31
 
27
32
  // The statistics (histogram binning, boxPlot/violin raw-sample summaries,
28
33
  // rowSeries()) live behind one optional feature. apexcharts/histogram already
@@ -30,9 +35,11 @@ import ApexCharts from 'apexcharts/raincloud'
30
35
  import 'apexcharts/features/stats'
31
36
  ```
32
37
 
33
- **⚠️ Raincloud is Tier 2 (v7.1).** It is **not in the default `apexcharts` bundle**, one of only two chart types that are not (the other is `icicle`, v7.6, which is free). On the full bundle add `import 'apexcharts/raincloud'` (or `import 'apexcharts/features/raincloud'`); from a script tag add `dist/features/raincloud.js` after `apexcharts.js`. It is also premium, so it renders an `APEXCHARTS` watermark until an entitled license is set.
38
+ **⚠️ Violin is Tier 2 since v8.0.** `import ApexCharts from 'apexcharts'` no longer registers it, so a `chart.type: 'violin'` chart draws nothing and the console names the import. Add `import 'apexcharts/violin'` (script tag: `dist/violin.js`), or use the full bundle (`apexcharts/full`, `dist/apexcharts.full.min.js`). Plain violins stay free.
39
+
40
+ **⚠️ Raincloud is Tier 2 (v7.1).** Since v8.0 the default bundle carries neither the raincloud feature nor the violin renderer it draws through. Next to `import ApexCharts from 'apexcharts'` add `import 'apexcharts/raincloud'`, which brings both; `apexcharts/features/raincloud` alone is enough only where violin is already registered. Script tag: load `dist/violin.js`, then `dist/features/raincloud.js`. Or use the full bundle (`apexcharts/full`, `dist/apexcharts.full.min.js`), which has both. On the lean core also import `apexcharts/bar`. It is also premium, so it renders an `APEXCHARTS` watermark until an entitled license is set.
34
41
 
35
- **Raw samples (v6.9):** boxPlot, violin, and histogram can all take the raw observations and compute the statistics themselves (quartiles for boxPlot, KDE density for violin, bin counts for histogram). Precomputed summaries keep working exactly as before. With the full `apexcharts` bundle the stats feature is always present; with tree-shaking entries it must be imported (without it, a raw-sample boxPlot/violin datum has nothing to summarize and a histogram warns and draws nothing).
42
+ **Raw samples (v6.9):** boxPlot, violin, and histogram can all take the raw observations and compute the statistics themselves (quartiles for boxPlot, KDE density for violin, bin counts for histogram). Precomputed summaries keep working exactly as before. The default `apexcharts` bundle (and the full bundle) always has the stats feature; with tree-shaking entries it must be imported (without it, a raw-sample boxPlot/violin draws nothing, with a console warning naming the import since v8.0, and a histogram warns and draws nothing).
36
43
 
37
44
  ---
38
45
 
@@ -125,6 +132,8 @@ Each point is `{ x, y: { density, points } }`:
125
132
  - `points` (optional): a flat array of raw observations, rendered as jitter dots.
126
133
 
127
134
  ```js
135
+ import 'apexcharts/violin' // Tier 2 since v8.0: not in the default bundle
136
+
128
137
  {
129
138
  chart: { type: 'violin', height: 420 },
130
139
  series: [{
@@ -161,6 +170,8 @@ Each point is `{ x, y: { density, points } }`:
161
170
  A datum may instead supply only the raw observations (in `points`, no `y`) and the library derives the density itself via kernel density estimation. Requires `apexcharts/features/stats` when tree-shaking. `plotOptions.violin.kde` tunes the estimation; it is ignored when a precomputed `density` profile is given.
162
171
 
163
172
  ```js
173
+ import 'apexcharts/violin' // Tier 2 since v8.0: not in the default bundle
174
+
164
175
  {
165
176
  chart: { type: 'violin', height: 420 },
166
177
  series: [{
@@ -196,7 +207,7 @@ plotOptions: {
196
207
 
197
208
  ### Histogram (v6.9)
198
209
 
199
- The series carries **raw observations** (a flat number array, or `{ y }` objects), one number per event; the chart chooses the bin width and counts them. It renders through the bar pathway (like funnel, pyramid, gauge, and waffle), so stacking, zoom, export, and animation all work on the bins. Import from `apexcharts/histogram`, or add `import 'apexcharts/features/stats'` alongside `apexcharts/bar`; the full `apexcharts` bundle already includes it. Without the stats feature the chart warns and draws nothing.
210
+ The series carries **raw observations** (a flat number array, or `{ y }` objects), one number per event; the chart chooses the bin width and counts them. It renders through the bar pathway (like funnel and pyramid), so stacking, zoom, export, and animation all work on the bins. Import from `apexcharts/histogram`, or add `import 'apexcharts/features/stats'` alongside `apexcharts/bar`; the default `apexcharts` bundle already includes it. Without the stats feature the chart warns and draws nothing.
200
211
 
201
212
  ```js
202
213
  {
@@ -228,7 +239,7 @@ The series carries **raw observations** (a flat number array, or `{ y }` objects
228
239
 
229
240
  ```js
230
241
  import ApexCharts from 'apexcharts'
231
- import 'apexcharts/raincloud' // Tier 2: required even on the full bundle
242
+ import 'apexcharts/raincloud' // Tier 2: not in the default bundle (apexcharts/full already has it)
232
243
 
233
244
  new ApexCharts(el, {
234
245
  chart: { type: 'raincloud', height: 350 },
@@ -286,9 +297,12 @@ The rain **is** the outlier display, so the box draws no outlier dots of its own
286
297
  A histogram bin, a box, and a violin all stand for rows the chart is already holding. `chart.rowSeries()` returns them as a unit-chart series (one cluster per mark, one datum per row), so a summary can be opened into its observations:
287
298
 
288
299
  ```js
300
+ import 'apexcharts/unit' // Tier 2 since v8.0: the target type must be loaded
289
301
  chart.updateOptions({ chart: { type: 'unit' }, series: chart.rowSeries() })
290
302
  ```
291
303
 
304
+ Since v8.0 the unit type is not in the default bundle, so load it first (`apexcharts/unit`, `dist/unit.js`, or the full bundle). Without it the update is refused (the promise rejects and the console names the import) and the chart stays as it was.
305
+
292
306
  Returns `null` when the current type has no row source or the stats feature is not loaded. `chart.rowSeries({ maxRows })` caps the dots produced (default 3000); past the cap every cluster is thinned by one shared stride so relative sizes survive. With the `morph` feature loaded, each dot animates out of the part of the mark that stood for it.
293
307
 
294
308
  ---
@@ -324,6 +338,8 @@ plotOptions: {
324
338
  }
325
339
  ```
326
340
 
341
+ **Updates animate (v7.9):** on `updateSeries()` each box morphs from its previous shape. Set `chart: { animations: { dynamicAnimation: { enabled: false } } }` to snap instead.
342
+
327
343
  ---
328
344
 
329
345
  ## Complete Working Example — Candlestick Chart
@@ -382,7 +398,7 @@ plotOptions: {
382
398
  7. **Violin orientation set on the wrong namespace**: horizontal violins and per-violin colors come from `plotOptions.bar` (`horizontal`, `distributed`), while `bandwidthScale`, `kde`, `normalize`, and `points` live under `plotOptions.violin`.
383
399
  8. **Feeding a histogram pre-binned counts**: the series must carry raw observations. If you already have counts per bucket, use a `bar` chart; a histogram would bin your counts as if they were measurements.
384
400
  9. **`whiskers: 'tukey'` on a precomputed boxPlot summary**: `plotOptions.boxPlot.whiskers` only applies when the summary is derived from `points`. A five-number `y` is drawn exactly as given.
385
- 10. **Raw samples with tree-shaking but no stats feature**: `apexcharts/candlestick` and `apexcharts/violin` alone cannot summarize `points`. Add `import 'apexcharts/features/stats'` (the `apexcharts/histogram` entry and the full bundle already include it).
386
- 11. **Expecting `raincloud` to work on the full bundle** *(v7.1)*: it is one of two chart types outside the default bundle (the other is `icicle`, v7.6). `import ApexCharts from 'apexcharts'` alone gives you a console warning and no raincloud, because `raincloud` aliases the violin engine and degrades; an unregistered `icicle` throws instead. Add `import 'apexcharts/raincloud'`.
401
+ 10. **Raw samples with tree-shaking but no stats feature**: `apexcharts/candlestick`, and `apexcharts/bar` plus `apexcharts/violin`, cannot summarize `points`. Add `import 'apexcharts/features/stats'` (the `apexcharts/histogram` entry and the default bundle already include it). Since v8.0 the console names the missing import.
402
+ 11. **Expecting `violin` or `raincloud` on the default bundle** *(v8.0)*: `import ApexCharts from 'apexcharts'` registers neither, so the chart draws nothing and the console reports `chart type "violin" is not registered` (for a raincloud, `chart type "raincloud" is not registered (it draws through "violin")`) with the import to add. That is the same failure an unregistered `icicle` gives. Add `import 'apexcharts/violin'` for a plain violin or `import 'apexcharts/raincloud'` for a raincloud, or use the full bundle (`apexcharts/full`).
387
403
  12. **Looking for `plotOptions.raincloud`**: there is none. Raincloud is a preset over the violin engine, so configure it through `plotOptions.violin` (`side`, `box`, `points`, `kde`, `normalize`).
388
404
  13. **Giving a raincloud a `y`**: it takes the raw sample per category: `data: [{ x, points: [number] }]`. A precomputed `y.summary` is honored for the box, but the density and the rain need the observations.
@@ -10,6 +10,30 @@
10
10
 
11
11
  **Important:** All wrappers require `apexcharts` as a peer dependency. Install both packages.
12
12
 
13
+ **With apexcharts 8**, use ng-apexcharts 3.2.0 or later (Angular 20+): 3.1.x accepts apexcharts 6 or 7 only, so npm reports a peer conflict. react-apexcharts (2.1.1) and vue3-apexcharts (1.11.2) accept any apexcharts from 5.10 up, and vue-apexcharts (Vue 2) any from 4.0.
14
+
15
+ ---
16
+
17
+ ## Opt-in chart types and features (apexcharts 8)
18
+
19
+ The wrappers' standard components load the default ApexCharts bundle, which since 8.0 leaves out some chart types and features (see `references/tree-shaking.md`). Until the app imports the add-on, a wrapper chart of type `unit`, `waffle`, `sunburst`, `violin`, `icicle` or `raincloud` fails to render, and `waterfall`, `dumbbell` or `streamgraph` draws an empty plot. Import it once anywhere in the app (`main.ts`, or the component file): it registers on the ApexCharts the wrapper uses.
20
+
21
+ | You use | Add once |
22
+ |---|---|
23
+ | `unit`/`waffle`, `sunburst`, `violin`, `icicle` | `import 'apexcharts/unit'` (or `/sunburst`, `/violin`, `/icicle`) |
24
+ | `raincloud` | `import 'apexcharts/raincloud'` |
25
+ | `waterfall`, `dumbbell`, `streamgraph`, drilldown or another Tier 2 feature | `import 'apexcharts/features/<name>'` (`highlightFilter` is `features/highlight-filter`) |
26
+ | Everything | `import 'apexcharts/full'`, which reuses the default bundle the wrapper already loads |
27
+
28
+ ```jsx
29
+ import Chart from 'react-apexcharts'
30
+ import 'apexcharts/sunburst' // once per app
31
+
32
+ export default function Breakdown({ options, series }) {
33
+ return <Chart type="sunburst" options={options} series={series} height={350} />
34
+ }
35
+ ```
36
+
13
37
  ---
14
38
 
15
39
  ## React
@@ -218,7 +242,7 @@ updateChart() {
218
242
  <div id="chart"></div>
219
243
 
220
244
  <!-- CDN -->
221
- <script src="https://cdn.jsdelivr.net/npm/apexcharts"></script>
245
+ <script src="https://cdn.jsdelivr.net/npm/apexcharts@8/dist/apexcharts.min.js"></script>
222
246
 
223
247
  <script>
224
248
  const options = {
@@ -234,18 +258,24 @@ updateChart() {
234
258
 
235
259
  ### CDN Links
236
260
 
261
+ ```html
262
+ <!-- default bundle -->
263
+ <script src="https://cdn.jsdelivr.net/npm/apexcharts@8/dist/apexcharts.min.js"></script>
264
+ <!-- one add-on next to it: an opt-in chart type -->
265
+ <script src="https://cdn.jsdelivr.net/npm/apexcharts@8/dist/sunburst.js"></script>
266
+
267
+ <!-- or the full bundle: every chart type and feature, no add-ons -->
268
+ <script src="https://cdn.jsdelivr.net/npm/apexcharts@8/dist/apexcharts.full.min.js"></script>
237
269
  ```
238
- https://cdn.jsdelivr.net/npm/apexcharts
239
- https://cdn.jsdelivr.net/npm/apexcharts@7/dist/apexcharts.min.js
240
- https://unpkg.com/apexcharts
241
- ```
270
+
271
+ Pin the major: the unversioned URLs (`https://cdn.jsdelivr.net/npm/apexcharts`, `https://unpkg.com/apexcharts`) moved to 8.0 on its release. Use `apexcharts@7` to stay on 7. The other add-ons are `dist/unit.js`, `dist/violin.js`, `dist/icicle.js` and `dist/features/<name>.js`, and may load before or after the main script.
242
272
 
243
273
  ---
244
274
 
245
275
  ## Common Framework Pitfalls
246
276
 
247
277
  1. **Missing peer dependency** — `react-apexcharts`, `vue3-apexcharts`, and `ng-apexcharts` all require `apexcharts` as a separate dependency.
248
- 2. **SSR with wrapper components** — most wrappers access `window`/`document` and crash in SSR. Use dynamic imports with `{ ssr: false }` or the native SSR API.
278
+ 2. **SSR with wrapper components**: the standard components access `window`/`document` and can crash in SSR. Use dynamic imports with `{ ssr: false }`, the native SSR API, or the wrapper's SSR components: `react-apexcharts/server`, vue3-apexcharts `<apexchart-server>` and `<apexchart-hydrate>` (1.11.2 or later, which render with your installed apexcharts), ng-apexcharts `<apx-chart-ssr>` and `<apx-chart-hydrate>`. They load `apexcharts/ssr`, so with apexcharts 8 a Tier 2 type needs its opt-in import on the server too. For React hydration call `apexcharts/ssr` directly: `react-apexcharts/hydrate` (2.1.1) loads `apexcharts/client`, which has no `hydrate()`.
249
279
  3. **Not destroying on unmount (vanilla API in React/Vue)** — causes memory leaks and duplicate charts. The official wrappers handle this automatically.
250
280
  4. **Mutating config objects in place (Vue)** — deep mutations may not trigger reactivity. Replace the entire object or use `ref` at the right level.
251
281
  5. **Rendering in hidden containers** — charts rendered in hidden tabs/modals have zero dimensions. Call `chart.updateOptions({})` or trigger a resize after showing the container.