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.
- package/.cursorrules +71 -44
- package/README.md +8 -8
- package/SKILL.md +97 -70
- package/package.json +1 -1
- package/references/bar-charts.md +17 -4
- package/references/cartesian-charts.md +8 -1
- package/references/circular-charts.md +20 -7
- package/references/feature-platform.md +83 -22
- package/references/financial-charts.md +28 -12
- package/references/framework-wrappers.md +36 -6
- package/references/grid-charts.md +10 -7
- package/references/ssr.md +22 -10
- package/references/tree-shaking.md +77 -45
|
@@ -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
|
|
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
|
-
|
|
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
|
|
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
|
|
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: {
|
|
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
|
|
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
|
|
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`**:
|
|
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:
|
|
5
|
+
## ⚠️ Read first: what is in the default bundle (8.0)
|
|
6
6
|
|
|
7
|
-
Whether you need
|
|
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`, `
|
|
10
|
-
- **Tier 2 is not in
|
|
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:
|
|
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
|
|
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.
|
|
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.
|
|
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`,
|
|
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
|
|
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
|
|
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` | `
|
|
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
|
|
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
|
|
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'
|
|
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
|
|
650
|
-
import 'apexcharts/features/
|
|
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
|
|
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
|
|
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
|
-
|
|
25
|
-
//
|
|
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
|
-
**⚠️
|
|
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.
|
|
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
|
|
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:
|
|
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
|
|
386
|
-
11. **Expecting `
|
|
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
|
-
|
|
239
|
-
https://cdn.jsdelivr.net/npm/apexcharts@7/dist/
|
|
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
|
|
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.
|