apexcharts-skill 3.0.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 +126 -82
- package/package.json +1 -1
- package/references/bar-charts.md +26 -8
- package/references/cartesian-charts.md +27 -1
- package/references/circular-charts.md +24 -7
- package/references/feature-platform.md +195 -29
- package/references/financial-charts.md +28 -12
- package/references/framework-wrappers.md +36 -6
- package/references/grid-charts.md +97 -4
- package/references/ssr.md +40 -19
- package/references/tree-shaking.md +78 -43
|
@@ -4,14 +4,18 @@
|
|
|
4
4
|
|
|
5
5
|
- **Heatmap** (`'heatmap'`) — Color-coded grid cells representing data intensity
|
|
6
6
|
- **Treemap** (`'treemap'`) — Nested rectangles with area proportional to value
|
|
7
|
+
- **Icicle** (`'icicle'`) *(v7.6)* — A hierarchy as stacked bands, one per depth level
|
|
7
8
|
|
|
8
9
|
## Tree-Shakeable Import
|
|
9
10
|
|
|
10
11
|
```js
|
|
11
|
-
import ApexCharts from 'apexcharts/heatmap'
|
|
12
|
-
import ApexCharts from 'apexcharts/treemap'
|
|
12
|
+
import ApexCharts from 'apexcharts/heatmap' // heatmap only
|
|
13
|
+
import ApexCharts from 'apexcharts/treemap' // treemap only
|
|
14
|
+
import ApexCharts from 'apexcharts/icicle' // icicle (v7.6): Tier 2, see below
|
|
13
15
|
```
|
|
14
16
|
|
|
17
|
+
`icicle` is **not in the default bundle** (Tier 2 since v7.6). Unlike every other type here, `import ApexCharts from 'apexcharts'` (script tag `dist/apexcharts.min.js`) does not carry its class, so a `chart.type: 'icicle'` chart fails to render, and the console names the import, until something registers it. Add `import 'apexcharts/icicle'` next to `import ApexCharts from 'apexcharts'` (script tag: `dist/icicle.js`), or use the full bundle (`import ApexCharts from 'apexcharts/full'`, `dist/apexcharts.full.min.js`, v8.0), which has it. `import ApexCharts from 'apexcharts/icicle'` on its own is the core plus icicle, without the Tier 1 features (toolbar, exports, keyboard and the rest).
|
|
18
|
+
|
|
15
19
|
---
|
|
16
20
|
|
|
17
21
|
## Data Formats
|
|
@@ -168,7 +172,9 @@ plotOptions: {
|
|
|
168
172
|
// false forces the flat two-level layout
|
|
169
173
|
drilldownAsLevels: false // read `drilldown: '<id>'` ids on data points as extra levels
|
|
170
174
|
// instead of as click targets for the drilldown feature.
|
|
171
|
-
// Default false ("descend on click" is the historical meaning)
|
|
175
|
+
// Default false ("descend on click" is the historical meaning).
|
|
176
|
+
// Since v8.0 those click targets need the Tier 2
|
|
177
|
+
// import 'apexcharts/features/drilldown'
|
|
172
178
|
},
|
|
173
179
|
parents: { // how branch containers are drawn once the data is nested
|
|
174
180
|
show: 'auto' // 'auto' (on when the data carries children) | true | false
|
|
@@ -182,6 +188,34 @@ plotOptions: {
|
|
|
182
188
|
|
|
183
189
|
The hierarchy resolver is shared with sunburst, including the `drilldown: '<id>'` adapter (opted into via `nested.drilldownAsLevels`).
|
|
184
190
|
|
|
191
|
+
### Icicle (v7.6)
|
|
192
|
+
|
|
193
|
+
Same hierarchy as the sunburst, drawn in cartesian coordinates: one band per depth level, each child sized inside its parent's extent along the value axis. Axis-style `[{ data: [...] }]` wrapper, `{ x, y, children }` nodes to any depth.
|
|
194
|
+
|
|
195
|
+
```js
|
|
196
|
+
import ApexCharts from 'apexcharts'
|
|
197
|
+
import 'apexcharts/icicle' // Tier 2: not in the default bundle (apexcharts/full already has it)
|
|
198
|
+
|
|
199
|
+
const options = {
|
|
200
|
+
chart: { type: 'icicle' },
|
|
201
|
+
series: [{
|
|
202
|
+
data: [
|
|
203
|
+
{ x: 'Mobile', y: 55, children: [
|
|
204
|
+
{ x: 'iOS', y: 30, children: [{ x: 'iOS 17', y: 18 }, { x: 'iOS 16', y: 9 }] },
|
|
205
|
+
{ x: 'Android', y: 23 }
|
|
206
|
+
] },
|
|
207
|
+
{ x: 'Desktop', y: 33, children: [{ x: 'Windows', y: 20 }, { x: 'macOS', y: 10 }] }
|
|
208
|
+
]
|
|
209
|
+
}]
|
|
210
|
+
}
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
- A branch may **omit its own `y`** and be the sum of its children. This is the documented shape for both partition types, and it only started working in v7.6: before that the non-axis parser dropped any node carrying `children` without `x` and `y`, and the chart drew nothing at all while warning about pie data.
|
|
214
|
+
- A node may carry `drilldown: '<id>'` instead of `children`, and the matching `drilldown.series` entry is read as the next level. It is read as plain data, so no drilldown feature import is needed.
|
|
215
|
+
- Sibling order follows the array by default (`sort: 'none'`). Set `plotOptions.icicle.sort` to `'value'` or `'name'` to override it.
|
|
216
|
+
|
|
217
|
+
**Choosing between icicle and sunburst.** Both resolve the same tree. An icicle keeps labels horizontal at every depth and puts depth on a straight axis, so same-depth siblings line up across branches and deep trees stay readable; a sunburst spends its area radially and reads better for shallow, wide trees. `direction: 'up'` is the flame-graph orientation, for call stacks and path funnels.
|
|
218
|
+
|
|
185
219
|
---
|
|
186
220
|
|
|
187
221
|
## Key plotOptions
|
|
@@ -191,7 +225,8 @@ The hierarchy resolver is shared with sunburst, including the `drilldown: '<id>'
|
|
|
191
225
|
```js
|
|
192
226
|
plotOptions: {
|
|
193
227
|
heatmap: {
|
|
194
|
-
|
|
228
|
+
shape: 'rect', // 'rect' (default) | 'hexagon' | 'circle' | 'diamond' (v7.2)
|
|
229
|
+
radius: 0, // border radius of cells ('rect' only)
|
|
195
230
|
enableShades: true, // shade intensity based on value
|
|
196
231
|
shadeIntensity: 0.5, // shade range (0-1)
|
|
197
232
|
distributed: false, // different color per series
|
|
@@ -212,6 +247,21 @@ plotOptions: {
|
|
|
212
247
|
}
|
|
213
248
|
```
|
|
214
249
|
|
|
250
|
+
#### Cell shapes (v7.2)
|
|
251
|
+
|
|
252
|
+
`shape` changes what a cell is drawn as, without changing the data format or anything else about the chart:
|
|
253
|
+
|
|
254
|
+
- `'circle'` and `'diamond'` are inscribed in the cell box the heatmap already lays out.
|
|
255
|
+
- `'hexagon'` is a real honeycomb tilemap: pointy-top hexagons, alternate rows offset half a cell so neighbours share a full edge, with the lattice's overhang reserved as extra grid padding so offset rows never cover the axis labels.
|
|
256
|
+
|
|
257
|
+
Three constraints worth knowing before choosing one:
|
|
258
|
+
|
|
259
|
+
- **`radius` applies to `'rect'` only.** Corner rounding is ignored by the other three.
|
|
260
|
+
- **`'hexagon'` is categorical-layout only.** On a numeric or datetime x axis it falls back to `'rect'` silently.
|
|
261
|
+
- **Non-rect shapes always render as SVG.** The canvas renderer declines them the same way it declines image fills, so a large heatmap that needs `renderer: 'canvas'` for its cell count has to stay on `'rect'`.
|
|
262
|
+
|
|
263
|
+
Shaped cells keep the `apexcharts-heatmap-rect` class and the same attribute contract, so tooltips, keyboard navigation, legend range highlighting and the color tween on a data update all behave unchanged.
|
|
264
|
+
|
|
215
265
|
### Treemap
|
|
216
266
|
|
|
217
267
|
```js
|
|
@@ -233,6 +283,46 @@ plotOptions: {
|
|
|
233
283
|
}
|
|
234
284
|
```
|
|
235
285
|
|
|
286
|
+
### Icicle (v7.6)
|
|
287
|
+
|
|
288
|
+
```js
|
|
289
|
+
plotOptions: {
|
|
290
|
+
icicle: {
|
|
291
|
+
direction: 'down', // 'down' (root on top, default) | 'up' (flame graph) | 'right' | 'left'
|
|
292
|
+
levelSize: 'equal', // 'equal' | px number | '%' string: thickness of one depth band
|
|
293
|
+
maxDepth: 'auto', // 'auto' (whole tree) | number of levels from the focused one
|
|
294
|
+
spacing: 1, // gap between adjacent cells (px)
|
|
295
|
+
borderRadius: 0, // corner rounding (px)
|
|
296
|
+
leaf: 'stop', // 'stop' (default): a shallow branch ends at its own band
|
|
297
|
+
// 'extend': it stretches to the far edge
|
|
298
|
+
partition: 'normalize', // 'normalize' | 'strict'
|
|
299
|
+
sort: 'none', // 'none' | 'value' | 'name'
|
|
300
|
+
tint: 0, // per-depth lightening of the parent colour (0 = same, 1 = white)
|
|
301
|
+
zoomOnClick: true, // click a cell to zoom into its branch (breadcrumb to go back)
|
|
302
|
+
zoomType: 'value', // 'value' (default) | 'both'
|
|
303
|
+
dataLabels: {
|
|
304
|
+
show: true,
|
|
305
|
+
minSizeToShow: 30, // hide the label on cells shorter than this (px)
|
|
306
|
+
align: 'center', // 'left' | 'center' | 'right'; a flame graph wants 'left'
|
|
307
|
+
rotate: 'auto', // 'auto' | 'always' | 'never'
|
|
308
|
+
showValue: false,
|
|
309
|
+
style: { fontSize: '12px', fontFamily: undefined, fontWeight: 400, colors: undefined }
|
|
310
|
+
}
|
|
311
|
+
}
|
|
312
|
+
}
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
Four defaults differ from the sunburst's, each for a reason worth knowing before overriding it:
|
|
316
|
+
|
|
317
|
+
- **`leaf: 'stop'`** leaves the white space that shows how deep each branch goes. `'extend'` fills the plot, which is what a treemap does and makes an icicle stop reading as a hierarchy.
|
|
318
|
+
- **`tint: 0`** keeps one hue per branch, so the eye can follow a branch down the levels.
|
|
319
|
+
- **The palette lands on the shallowest level that branches.** A single-root tree is the normal shape here, and colouring by root would paint everything one hue.
|
|
320
|
+
- **The legend is off**, since every cell carries its own label.
|
|
321
|
+
|
|
322
|
+
**`zoomType` is the one to understand.** `'value'` (the default) rescales the value axis only: the clicked branch stretches to fill the width, its subtree stretches with it, and no level moves. The ancestors stay above it, clamped to the plot, which is what makes them read as context. `'both'` also re-bands the depth axis, promoting the branch to the top level, which spends the whole plot on it at the cost of the reader's place in the tree. The values are not called `'x'` and `'y'` because `direction` decides which screen axis the value axis is.
|
|
323
|
+
|
|
324
|
+
A click that would not change the view is refused rather than performed: clicking a lone root, or a leaf inside the focused branch, leaves the chart alone, and the cursor reads `pointer` only on cells where a zoom would actually move something.
|
|
325
|
+
|
|
236
326
|
---
|
|
237
327
|
|
|
238
328
|
## Complete Working Example — Heatmap
|
|
@@ -289,3 +379,6 @@ plotOptions: {
|
|
|
289
379
|
3. **Treemap with negative values** — treemap `y` values must be positive (they represent area). Negative values cause rendering issues.
|
|
290
380
|
4. **Confusing heatmap `y` with position** — in heatmap data `{ x, y }`, the `y` is the VALUE (color intensity), NOT the y-axis position. The series `name` determines the row.
|
|
291
381
|
5. **Nested treemap branch carrying its own `y` (v6.9)**: a branch node normally omits `y`; its area is the sum of its children. Only leaves supply values. Flattening a hierarchy by hand is no longer necessary; pass `children` instead.
|
|
382
|
+
6. **`chart.type: 'icicle'` on the default bundle (v7.6)**: icicle is Tier 2 and the default build carries no class for it, so the chart fails to render and the console names the import. Add `import 'apexcharts/icicle'` next to `import ApexCharts from 'apexcharts'` (or load `dist/icicle.js`). The default `apexcharts.js` does not carry the class; the full bundle (`apexcharts/full`, `dist/apexcharts.full.min.js`, v8.0) does.
|
|
383
|
+
7. **Reaching for `zoomType: 'both'` to make a branch fill the plot** — `'value'` already stretches the branch across the full width; what `'both'` additionally does is move every level, which costs the reader their place in the tree. Change it only when the ancestors genuinely do not matter.
|
|
384
|
+
8. **Expecting `sort: 'value'` on a flame graph** — `'name'` is the flame-graph convention, because it holds a frame in the same place across profiles so two runs of one program can be compared by eye.
|
package/references/ssr.md
CHANGED
|
@@ -10,13 +10,21 @@ ApexCharts supports SSR for generating chart SVGs on the server (Node.js) and hy
|
|
|
10
10
|
// Server (Node.js) — includes renderToString, renderToHTML
|
|
11
11
|
import ApexCharts from 'apexcharts/ssr'
|
|
12
12
|
|
|
13
|
-
// Client (Browser)
|
|
14
|
-
import ApexCharts from 'apexcharts'
|
|
15
|
-
// or explicitly:
|
|
16
|
-
import ApexCharts from 'apexcharts/client'
|
|
13
|
+
// Client (Browser), for hydration after SSR: hydrate() and hydrateAll() live only here
|
|
14
|
+
import ApexCharts from 'apexcharts/ssr' // self-contained, safe in the browser
|
|
17
15
|
```
|
|
18
16
|
|
|
19
|
-
**Important:** The default `import ApexCharts from 'apexcharts'` uses Node.js conditional exports. In Node.js, it automatically resolves to the SSR bundle. In browsers (bundlers), it resolves to the client bundle
|
|
17
|
+
**Important:** The default `import ApexCharts from 'apexcharts'` uses Node.js conditional exports. In Node.js, it automatically resolves to the SSR bundle. In browsers (bundlers), it resolves to the client bundle, the same file as `apexcharts/client`, which has no `hydrate()`, `hydrateAll()` or `isHydrated()`. Hydrate with `apexcharts/ssr`.
|
|
18
|
+
|
|
19
|
+
**The SSR bundle registers the default chart set only *(v8.0)*.** It is built from the same entry as the default bundle, so the Tier 2 chart types and features (see `tree-shaking.md`) are not in it: `renderToString` rejects for a Tier 2 type (`SSR rendering failed: ... not registered`), and a waterfall renders an empty plot with a warning. Import what you use next to `apexcharts/ssr`; chart types and features register through a shared registry, so the SSR class picks them up:
|
|
20
|
+
|
|
21
|
+
```js
|
|
22
|
+
import ApexCharts from 'apexcharts/ssr'
|
|
23
|
+
import 'apexcharts/sunburst' // unit, sunburst, violin, icicle, raincloud: the type's entry
|
|
24
|
+
import 'apexcharts/features/waterfall' // waterfall, dumbbell, streamgraph, drilldown: the feature
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Or `import ApexCharts from 'apexcharts/full'`, which under Node carries `renderToString` and every type. The client that hydrates needs the same type and feature imports next to `apexcharts/ssr` (in the browser `apexcharts/full` has no hydrate methods).
|
|
20
28
|
|
|
21
29
|
---
|
|
22
30
|
|
|
@@ -52,7 +60,7 @@ const htmlString = await ApexCharts.renderToHTML(
|
|
|
52
60
|
{
|
|
53
61
|
chart: {
|
|
54
62
|
type: 'bar',
|
|
55
|
-
id: 'my-chart' //
|
|
63
|
+
id: 'my-chart' // for chart.exec() targeting; NOT what hydration looks for
|
|
56
64
|
},
|
|
57
65
|
series: [{ data: [44, 55, 41, 67] }],
|
|
58
66
|
xaxis: { categories: ['A', 'B', 'C', 'D'] }
|
|
@@ -60,7 +68,12 @@ const htmlString = await ApexCharts.renderToHTML(
|
|
|
60
68
|
{ width: 600, height: 350 }
|
|
61
69
|
)
|
|
62
70
|
|
|
63
|
-
// htmlString is
|
|
71
|
+
// htmlString is:
|
|
72
|
+
// <div class="apexcharts-ssr-wrapper" data-apexcharts-hydrate data-apexcharts-config="...">
|
|
73
|
+
// <svg>...</svg>
|
|
74
|
+
// </div>
|
|
75
|
+
// The wrapper carries NO id. `chart.id` is not copied onto it, and the config
|
|
76
|
+
// travels in data-apexcharts-config, which is what hydration reads.
|
|
64
77
|
```
|
|
65
78
|
|
|
66
79
|
---
|
|
@@ -72,16 +85,19 @@ After the server-rendered HTML is in the DOM, hydrate it to make it interactive:
|
|
|
72
85
|
### hydrate(element, clientOptions?)
|
|
73
86
|
|
|
74
87
|
```js
|
|
75
|
-
import ApexCharts from 'apexcharts'
|
|
88
|
+
import ApexCharts from 'apexcharts/ssr' // not 'apexcharts' or 'apexcharts/client': no hydrate() there
|
|
76
89
|
|
|
77
|
-
// Hydrate a specific chart element (optionally merge client-only options)
|
|
78
|
-
|
|
90
|
+
// Hydrate a specific chart element (optionally merge client-only options).
|
|
91
|
+
// Select the emitted wrapper, not a chart id: `#my-chart` matches nothing.
|
|
92
|
+
const chart = ApexCharts.hydrate(document.querySelector('[data-apexcharts-hydrate]'))
|
|
79
93
|
```
|
|
80
94
|
|
|
81
95
|
### hydrateAll(selector?, clientOptions?)
|
|
82
96
|
|
|
83
97
|
```js
|
|
84
|
-
// Hydrate all server-rendered charts on the page (optionally scope by selector)
|
|
98
|
+
// Hydrate all server-rendered charts on the page (optionally scope by selector).
|
|
99
|
+
// The selector defaults to '[data-apexcharts-hydrate]', which is why this works
|
|
100
|
+
// with no argument and a #id selector does not.
|
|
85
101
|
ApexCharts.hydrateAll()
|
|
86
102
|
```
|
|
87
103
|
|
|
@@ -123,7 +139,9 @@ app.get('/', async (req, res) => {
|
|
|
123
139
|
<body>
|
|
124
140
|
${chartHTML}
|
|
125
141
|
<script type="module">
|
|
126
|
-
|
|
142
|
+
// The self-contained SSR build. dist/apexcharts.esm.js imports apexcharts/core
|
|
143
|
+
// by bare name (needs a bundler or an import map) and has no hydrateAll().
|
|
144
|
+
import ApexCharts from '/node_modules/apexcharts/dist/apexcharts.ssr.esm.js'
|
|
127
145
|
ApexCharts.hydrateAll()
|
|
128
146
|
</script>
|
|
129
147
|
</body>
|
|
@@ -168,7 +186,7 @@ import { useEffect } from 'react'
|
|
|
168
186
|
|
|
169
187
|
export default function HydrateCharts() {
|
|
170
188
|
useEffect(() => {
|
|
171
|
-
import('apexcharts').then(({ default: ApexCharts }) => {
|
|
189
|
+
import('apexcharts/ssr').then(({ default: ApexCharts }) => {
|
|
172
190
|
ApexCharts.hydrateAll()
|
|
173
191
|
})
|
|
174
192
|
}, [])
|
|
@@ -186,7 +204,7 @@ export default function HydrateCharts() {
|
|
|
186
204
|
|
|
187
205
|
<script setup>
|
|
188
206
|
// Server-side
|
|
189
|
-
const chartHTML = await useAsyncData('chart', async () => {
|
|
207
|
+
const { data: chartHTML } = await useAsyncData('chart', async () => {
|
|
190
208
|
const ApexCharts = (await import('apexcharts/ssr')).default
|
|
191
209
|
return await ApexCharts.renderToHTML(
|
|
192
210
|
{
|
|
@@ -200,7 +218,7 @@ const chartHTML = await useAsyncData('chart', async () => {
|
|
|
200
218
|
|
|
201
219
|
// Client-side hydration
|
|
202
220
|
onMounted(async () => {
|
|
203
|
-
const ApexCharts = (await import('apexcharts')).default
|
|
221
|
+
const ApexCharts = (await import('apexcharts/ssr')).default
|
|
204
222
|
ApexCharts.hydrateAll()
|
|
205
223
|
})
|
|
206
224
|
</script>
|
|
@@ -210,7 +228,10 @@ onMounted(async () => {
|
|
|
210
228
|
|
|
211
229
|
## Common Pitfalls
|
|
212
230
|
|
|
213
|
-
1. **
|
|
214
|
-
2. **
|
|
215
|
-
3. **
|
|
216
|
-
4. **
|
|
231
|
+
1. **Assuming `apexcharts` has no SSR methods in Node** — it does: the `"."` export's `node` condition resolves to the SSR bundle, so `renderToString` and `renderToHTML` are there. Import `apexcharts/ssr` explicitly anyway, because a bundler told to target Node can still resolve the `browser` condition, and then they really are missing.
|
|
232
|
+
2. **Hydrating by chart id** — `renderToHTML` emits `<div class="apexcharts-ssr-wrapper" data-apexcharts-hydrate data-apexcharts-config="...">` with no `id`, so `querySelector('#my-chart')` returns null. Use `hydrateAll()`, or select `[data-apexcharts-hydrate]`.
|
|
233
|
+
3. **Forgetting to hydrate on the client** — server-rendered charts are static SVGs. Without `hydrate()`, they have no interactivity (no tooltips, zoom, click events).
|
|
234
|
+
4. **Missing width/height**: SSR has no DOM to measure. Pass explicit dimensions in the **second** argument: `renderToString(options, { width, height })` / `renderToHTML(options, { width, height })`.
|
|
235
|
+
5. **Hydrating before DOM is ready** — call `hydrate()` after the server-rendered HTML is in the DOM (use `onMounted`, `useEffect`, or `DOMContentLoaded`).
|
|
236
|
+
6. **Hydrating with `apexcharts` or `apexcharts/client`**: those browser builds have no hydrate methods, so `ApexCharts.hydrateAll()` throws a TypeError. Import `apexcharts/ssr` on the client too.
|
|
237
|
+
7. **Server-rendering a Tier 2 type with `apexcharts/ssr` alone *(v8.0)***: `unit`, `waffle`, `sunburst`, `violin`, `icicle` and `raincloud` reject, and `waterfall`, `dumbbell` and `streamgraph` render empty. Import the type's entry or feature next to it, on the server and on the client.
|
|
@@ -1,8 +1,36 @@
|
|
|
1
1
|
# Bundle Tiers, Tree-Shaking & Optimization: ApexCharts
|
|
2
2
|
|
|
3
|
+
## ⚠️ What changed in v8.0
|
|
4
|
+
|
|
5
|
+
**8.0 took three chart types and four features out of the default bundle, and added a full bundle that has everything.** If a chart stops drawing after the upgrade, the console names the import to add.
|
|
6
|
+
|
|
7
|
+
| Moved out of the default bundle | Kind | Import next to `import ApexCharts from 'apexcharts'` | Script tag |
|
|
8
|
+
|---|---|---|---|
|
|
9
|
+
| `unit` (with its `waffle` alias) | chart type | `import 'apexcharts/unit'` | `dist/unit.js` |
|
|
10
|
+
| `sunburst` | chart type | `import 'apexcharts/sunburst'` | `dist/sunburst.js` |
|
|
11
|
+
| `violin` | chart type | `import 'apexcharts/violin'` | `dist/violin.js` |
|
|
12
|
+
| drilldown | feature | `import 'apexcharts/features/drilldown'` | `dist/features/drilldown.js` |
|
|
13
|
+
| `waterfall`, `dumbbell`, `streamgraph` | chart types drawn by a feature | `import 'apexcharts/features/<name>'` | `dist/features/<name>.js` |
|
|
14
|
+
|
|
15
|
+
For the last three the default bundle still has the bar and rangeArea renderers, so add only the feature. `raincloud` and `icicle` were already opt-in. A raincloud draws through violin, which is no longer in the default bundle, so it needs `import 'apexcharts/raincloud'` (violin plus the feature), or `dist/violin.js` then `dist/features/raincloud.js`. Add-on tags may load before or after the ApexCharts script.
|
|
16
|
+
|
|
17
|
+
Or load everything at once. Premium types and features in it stay licence-gated, as they are when loaded as add-ons:
|
|
18
|
+
|
|
19
|
+
```js
|
|
20
|
+
import ApexCharts from 'apexcharts/full' // script tag: dist/apexcharts.full.min.js
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
| | gzip |
|
|
24
|
+
|---|---|
|
|
25
|
+
| 7.9.1 default bundle | 291,763 B |
|
|
26
|
+
| 8.0.0 default bundle | 263,188 B (**-9.8%**) |
|
|
27
|
+
| 8.0.0 full bundle | 381,135 B |
|
|
28
|
+
|
|
29
|
+
Unversioned CDN URLs serve 8.0. Pin `apexcharts@7` to stay on 7.
|
|
30
|
+
|
|
3
31
|
## ⚠️ What changed in v7.0
|
|
4
32
|
|
|
5
|
-
**In v6, the default bundle contained every feature. In v7 it does not.** Nine features are **Tier 2**: shipped in the package, absent from every bundle, and reachable only through an explicit import. This applies to the default `apexcharts` bundle, not just to tree-shaken builds, and it is the most common v6 → v7 upgrade failure.
|
|
33
|
+
**In v6, the default bundle contained every feature. In v7 it does not.** Nine features are **Tier 2**: shipped in the package, absent from every 7.x bundle, and reachable only through an explicit import. This applies to the default `apexcharts` bundle, not just to tree-shaken builds, and it is the most common v6 → v7 upgrade failure.
|
|
6
34
|
|
|
7
35
|
```js
|
|
8
36
|
import ApexCharts from 'apexcharts'
|
|
@@ -19,12 +47,13 @@ If you use none of the nine, upgrading is `npm install apexcharts@7` and nothing
|
|
|
19
47
|
|
|
20
48
|
## Overview
|
|
21
49
|
|
|
22
|
-
ApexCharts supports
|
|
50
|
+
ApexCharts supports five import strategies with different bundle sizes:
|
|
23
51
|
|
|
24
52
|
| Strategy | Import | Includes |
|
|
25
53
|
|---|---|---|
|
|
26
|
-
| Default bundle | `import ApexCharts from 'apexcharts'` |
|
|
27
|
-
|
|
|
54
|
+
| Default bundle | `import ApexCharts from 'apexcharts'` | line, area, scatter, bubble, rangeArea, bar, column, rangeBar, candlestick, boxPlot, pie, donut, polarArea, radialBar, radar, heatmap, treemap (plus the funnel, pyramid, histogram and gauge aliases), and the **Tier 1** features. **Not** the Tier 2 chart types or features *(v8.0)*. |
|
|
55
|
+
| Full bundle *(v8.0)* | `import ApexCharts from 'apexcharts/full'` / `dist/apexcharts.full.min.js` | Every chart type and every feature, Tier 2 included, plus the unit-shapes and pictograms catalogs. Premium items stay licence-gated. |
|
|
56
|
+
| Per-type entry | `import ApexCharts from 'apexcharts/line'` | Specific chart family + core, plus any feature the type needs (no legend, toolbar, exports or other optional features) |
|
|
28
57
|
| Bare core | `import ApexCharts from 'apexcharts/core'` | Core class only — must manually register everything |
|
|
29
58
|
| Lean core, no bundler *(v7.0)* | `<script src=".../dist/apexcharts.core.js">` | Script-tag equivalent of bare core, assembled from separate tags. See below. |
|
|
30
59
|
|
|
@@ -49,8 +78,8 @@ Each entry point registers a family of related chart types:
|
|
|
49
78
|
| `apexcharts/streamgraph` | streamgraph *(new in v7.1)*: the rangeArea engine plus the streamgraph feature |
|
|
50
79
|
| `apexcharts/candlestick` | candlestick, boxPlot |
|
|
51
80
|
| `apexcharts/boxPlot` | same as /candlestick |
|
|
52
|
-
| `apexcharts/violin` | violin *(new in v6)
|
|
53
|
-
| `apexcharts/raincloud` | raincloud *(new in v7.1, premium)*: the violin engine plus the raincloud feature. **
|
|
81
|
+
| `apexcharts/violin` | violin *(new in v6)*. **Opt-in since v8.0**: add it next to `import ApexCharts from 'apexcharts'` (script tag: `dist/violin.js`), or use `apexcharts/full`. Violin draws on the bar renderer and does not bundle one: on `apexcharts/core` also import `apexcharts/bar` (script tag: `dist/bar.js`). |
|
|
82
|
+
| `apexcharts/raincloud` | raincloud *(new in v7.1, premium)*: the violin engine plus the raincloud feature. **Opt-in**: not in the default bundle. Script tags: `dist/violin.js` then `dist/features/raincloud.js` *(v8.0)*. On `apexcharts/core` also import `apexcharts/bar`, as for violin. |
|
|
54
83
|
| `apexcharts/histogram` | histogram *(new in v6.9)*: the bar engine plus the stats feature |
|
|
55
84
|
| `apexcharts/pie` | pie, donut, polarArea |
|
|
56
85
|
| `apexcharts/donut` | same as /pie |
|
|
@@ -59,14 +88,15 @@ Each entry point registers a family of related chart types:
|
|
|
59
88
|
| `apexcharts/radar` | radar |
|
|
60
89
|
| `apexcharts/heatmap` | heatmap |
|
|
61
90
|
| `apexcharts/treemap` | treemap |
|
|
62
|
-
| `apexcharts/sunburst` | sunburst *(new in v6.7, free)
|
|
63
|
-
| `apexcharts/
|
|
91
|
+
| `apexcharts/sunburst` | sunburst *(new in v6.7, free)*. **Opt-in since v8.0**: add it next to `import ApexCharts from 'apexcharts'` (script tag: `dist/sunburst.js`), or use `apexcharts/full`. |
|
|
92
|
+
| `apexcharts/icicle` | icicle *(new in v7.6, free)*: the sunburst's partition in cartesian coordinates. **Opt-in**: the default bundle carries no icicle class, only the settings literals and a few string branches, so a `chart.type: 'icicle'` chart's `render()` rejects until this entry, or a `dist/icicle.js` script tag, has registered it. `dist/apexcharts.js` (the default bundle) does not carry it; `apexcharts/full` and `dist/apexcharts.full.min.js` do *(v8.0)*. The entry contains no other chart class. |
|
|
93
|
+
| `apexcharts/unit` | unit, **waffle** *(new in v6.6, premium: watermarked until licensed)*. **Opt-in since v8.0**: add it next to `import ApexCharts from 'apexcharts'` (script tag: `dist/unit.js`), or use `apexcharts/full`. |
|
|
64
94
|
| `apexcharts/unit-shapes` | *(new in v6.10)* not a chart entry: named shape exports for the unit chart (`heart`, `house`, ... plus `outlined`, `glyphs`, `preview`), tree-shaken per shape (~4 KB gzipped each). See `references/circular-charts.md`. |
|
|
65
95
|
| `apexcharts/pictograms` | *(new in v7.0)* not a chart entry: a drawn glyph per unit for the unit chart (`person`, `house`, `heart`, `tree`, `droplet`, `star`, `car`, `bag`, `book`, `cup`, `bulb`, `plane`), plus `definePictogram` / `registerMarks` / `catalog`. Import the glyph you use, not `catalog`, which ships all of them. |
|
|
66
96
|
|
|
67
97
|
**First-class aliases:** `funnel` and `pyramid` render through the bar engine, so `apexcharts/bar` covers them. `gauge` renders through radialBar, so `apexcharts/radialBar` covers it. There is no separate `apexcharts/funnel`, `apexcharts/pyramid`, or `apexcharts/gauge` entry.
|
|
68
98
|
|
|
69
|
-
**Entries that bundle a feature.**
|
|
99
|
+
**Entries that bundle a feature.** Five types render through an existing engine but have their own entry because that entry also pulls in a feature module. Each is equivalent to the engine entry plus the feature:
|
|
70
100
|
|
|
71
101
|
| Entry | Equivalent to |
|
|
72
102
|
|---|---|
|
|
@@ -76,6 +106,8 @@ Each entry point registers a family of related chart types:
|
|
|
76
106
|
| `apexcharts/streamgraph` | `apexcharts/rangeArea` + `import 'apexcharts/features/streamgraph'` |
|
|
77
107
|
| `apexcharts/raincloud` | `apexcharts/violin` + `import 'apexcharts/features/raincloud'` |
|
|
78
108
|
|
|
109
|
+
**Next to the default bundle, add the feature, not the entry *(v8.0)*.** The default bundle already has the bar and rangeArea renderers and the stats feature, so a waterfall there needs only `import 'apexcharts/features/waterfall'` (about 3 KB gzipped), while `apexcharts/waterfall` would add a second copy of the bar renderer (about 38 KB). The same goes for dumbbell and streamgraph, and a histogram needs nothing. These entries are for the lean core and per-type builds. Raincloud is the exception: violin is not in the default bundle, so `apexcharts/raincloud` is the import there.
|
|
110
|
+
|
|
79
111
|
### Using Multiple Chart Types
|
|
80
112
|
|
|
81
113
|
```js
|
|
@@ -90,8 +122,8 @@ import 'apexcharts/bar' // side-effect: registers bar types onto the same clas
|
|
|
90
122
|
|
|
91
123
|
Two questions decide whether you need a `features/*` import:
|
|
92
124
|
|
|
93
|
-
1. **Which entry point did you start from?** `apexcharts/core` and the per-type entries carry no optional features
|
|
94
|
-
2. **Which tier is the feature?** Tier 1 is in the default `apexcharts` bundle. **Tier 2 is
|
|
125
|
+
1. **Which entry point did you start from?** `apexcharts/core` and the per-type entries carry no optional features (a per-type entry brings only the feature its own type needs), so every feature you want needs its import.
|
|
126
|
+
2. **Which tier is the feature?** Tier 1 is in the default `apexcharts` bundle. **Tier 2 is not**, so it needs its import there too. Only the full bundle (`apexcharts/full`, *v8.0*) has every feature.
|
|
95
127
|
|
|
96
128
|
### Tier 1: in the default `apexcharts` bundle
|
|
97
129
|
|
|
@@ -106,39 +138,40 @@ Import these only when you started from `/core` or a per-type entry.
|
|
|
106
138
|
| Keyboard | `import 'apexcharts/features/keyboard'` | Keyboard navigation (accessibility) |
|
|
107
139
|
| Stats *(v6.9)* | `import 'apexcharts/features/stats'` | Histogram binning, boxPlot/violin raw-sample summaries, `rowSeries()` |
|
|
108
140
|
| Morph | `import 'apexcharts/features/morph'` | Animated chart-type morphs |
|
|
109
|
-
| Drilldown | `import 'apexcharts/features/drilldown'` | Hierarchical drill-down |
|
|
110
141
|
| Facet | `import 'apexcharts/features/facet'` | Design tokens + OS-aware themes |
|
|
111
142
|
| Weave | `import 'apexcharts/features/weave'` | Public plugin platform |
|
|
112
143
|
| Marks | `import 'apexcharts/features/marks'` | Custom series types (`registerSeriesType`) |
|
|
113
|
-
| Waterfall *(v7.1)* | `import 'apexcharts/features/waterfall'` | The `waterfall` chart type |
|
|
114
|
-
| Dumbbell *(v7.1)* | `import 'apexcharts/features/dumbbell'` | The `dumbbell` chart type |
|
|
115
|
-
| Streamgraph *(v7.1)* | `import 'apexcharts/features/streamgraph'` | The `streamgraph` chart type |
|
|
116
144
|
| All Tier 1 | `import 'apexcharts/features/all'` | Every row above, and **only** those |
|
|
117
145
|
|
|
118
|
-
Tier 1 is a **budget, not an index**: upstream, a module earns a place only if it is under ~5 KB gzipped on top of core, needs no peer dependency or separate asset, and is useful to a majority of charts.
|
|
146
|
+
Tier 1 is a **budget, not an index**: upstream, a module earns a place only if it is under ~5 KB gzipped on top of core, needs no peer dependency or separate asset, and is useful to a majority of charts. Six (legend, toolbar, annotations, exports, keyboard, morph) predate the budget and are grandfathered; drilldown was a seventh until 8.0 moved it to Tier 2.
|
|
119
147
|
|
|
120
|
-
### Tier 2: in
|
|
148
|
+
### Tier 2: not in the default bundle; its own import or `apexcharts/full`
|
|
121
149
|
|
|
122
|
-
Required whatever entry point you used, the default `apexcharts` bundle included.
|
|
150
|
+
Required whatever entry point you used, the default `apexcharts` bundle included. Only the full bundle (`apexcharts/full`, `dist/apexcharts.full.min.js`, *v8.0*) already has them. The gzip column is the script-tag file `dist/features/<name>.js` at 8.0.0 (gzip -9).
|
|
123
151
|
|
|
124
152
|
| Feature | Import | gzip | Premium | What It Adds |
|
|
125
153
|
|---|---|---|---|---|
|
|
126
|
-
|
|
|
127
|
-
|
|
|
128
|
-
|
|
|
129
|
-
|
|
|
130
|
-
|
|
|
131
|
-
|
|
|
132
|
-
|
|
|
133
|
-
|
|
|
134
|
-
|
|
|
135
|
-
|
|
|
154
|
+
| Highlight filter *(v7.9)* | `import 'apexcharts/features/highlight-filter'` | 29.7 KB | yes | `highlightFilter`: a part of each value drawn solid over its faded whole |
|
|
155
|
+
| Trellis *(v7.0)* | `import 'apexcharts/features/trellis'` | 28.4 KB | yes | Small multiples: a grid of real charts sharing scale, legend, toolbar, crosshair |
|
|
156
|
+
| Renderer / Strata | `import 'apexcharts/features/renderer-canvas'` | 8.7 KB | no | Hybrid SVG + canvas renderer |
|
|
157
|
+
| Storyboard | `import 'apexcharts/features/storyboard'` | 8.7 KB | yes | Scrollytelling (registers Perspectives too) |
|
|
158
|
+
| Perspectives | `import 'apexcharts/features/perspectives'` | 7.4 KB | yes | Shareable view state |
|
|
159
|
+
| Ink | `import 'apexcharts/features/ink'` | 6.9 KB | yes | On-chart annotation authoring |
|
|
160
|
+
| Drilldown *(Tier 2 since v8.0)* | `import 'apexcharts/features/drilldown'` | 6.6 KB | no | Hierarchical drill-down |
|
|
161
|
+
| Link | `import 'apexcharts/features/link'` | 6.0 KB | yes | Crossfilter / linked views |
|
|
162
|
+
| Streamgraph *(v7.1; Tier 2 since v8.0)* | `import 'apexcharts/features/streamgraph'` | 5.7 KB | no | The `streamgraph` chart type |
|
|
163
|
+
| Measure | `import 'apexcharts/features/measure'` | 5.3 KB | yes | Measure / delta ruler |
|
|
164
|
+
| History / Rewind | `import 'apexcharts/features/history'` | 3.8 KB | yes | Undo/redo (`chart.history`) |
|
|
165
|
+
| Context menu | `import 'apexcharts/features/context-menu'` | 3.0 KB | yes | Right-click / long-press context menu |
|
|
166
|
+
| Waterfall *(v7.1; Tier 2 since v8.0)* | `import 'apexcharts/features/waterfall'` | 2.8 KB | no | The `waterfall` chart type |
|
|
167
|
+
| Dumbbell *(v7.1; Tier 2 since v8.0)* | `import 'apexcharts/features/dumbbell'` | 2.1 KB | no | The `dumbbell` chart type |
|
|
168
|
+
| Raincloud *(v7.1)* | `import 'apexcharts/raincloud'` | 2.4 KB + violin 6.4 KB | yes | The `raincloud` chart type. The entry brings violin and the feature; `apexcharts/features/raincloud` alone works only where violin is already registered *(v8.0)* |
|
|
136
169
|
|
|
137
170
|
Storyboard registers Perspectives, so importing both costs no more than Storyboard alone.
|
|
138
171
|
|
|
139
172
|
**`apexcharts/features/all` does not include Tier 2**, by design: upstream has a tier-budget test that fails the build if a Tier 2 feature reappears in it.
|
|
140
173
|
|
|
141
|
-
**Nothing fails silently on Tier 2.** Each module warns in the console when its configuration is present but the module is not, and the warning names
|
|
174
|
+
**Nothing fails silently on Tier 2.** Each module warns in the console when its configuration is present but the module is not, and the warning names the ESM 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 instead: a trellis renders as a single chart, `renderer: 'canvas'` falls back to SVG.
|
|
142
175
|
|
|
143
176
|
---
|
|
144
177
|
|
|
@@ -152,9 +185,11 @@ Tree-shaking only ever helped people with a build step. A page using a `<script>
|
|
|
152
185
|
<script src=".../dist/features/legend.js"></script>
|
|
153
186
|
```
|
|
154
187
|
|
|
155
|
-
**
|
|
188
|
+
**About 156 KB gzipped**, against about 262 KB for the default bundle and about 379 KB for the full bundle (`dist/apexcharts.core.min.js`, `dist/apexcharts.min.js` and `dist/apexcharts.full.min.js` at 8.0.0, gzip -9). Treat these as approximate: the upstream build report gzips at a different level and prints slightly larger figures (263,188 B and 381,135 B for the two bundles), and the numbers move every release. Purely additive: nobody has to migrate to it, and a page that wants everything should load `dist/apexcharts.full.min.js` rather than assemble it from parts.
|
|
156
189
|
|
|
157
|
-
|
|
190
|
+
The opt-in chart types have their own files rather than `features/*` ones: `dist/unit.js`, `dist/sunburst.js`, `dist/violin.js` and `dist/icicle.js`, and a raincloud page loads `dist/violin.js` then `dist/features/raincloud.js`. On `apexcharts.core.js`, violin (and so raincloud) also needs `dist/bar.js`.
|
|
191
|
+
|
|
192
|
+
Every Tier 2 feature has a `dist/features/<name>.js` artifact for this channel too, and a default-bundle page still needs it. Add-on tags may load before or after the ApexCharts script *(v8.0)*. `dist/apexcharts.full.min.js` needs none of them.
|
|
158
193
|
|
|
159
194
|
```html
|
|
160
195
|
<script src=".../dist/apexcharts.js"></script>
|
|
@@ -175,26 +210,26 @@ It depends on the tier.
|
|
|
175
210
|
- `addXaxisAnnotation()` does nothing
|
|
176
211
|
- `dataURI()` / `exportToCSV()` throw because the feature isn't registered
|
|
177
212
|
|
|
178
|
-
**Tier 2 features announce themselves.** Each warns in the console when its configuration is present but the module is not, naming
|
|
213
|
+
**Tier 2 features announce themselves.** Each warns in the console when its configuration is present but the module is not, naming the ESM import, the script-tag file and `apexcharts.full.min.js`, and degrades predictably where it can: a `trellis` config renders as one ordinary chart, `renderer: 'canvas'` falls back to SVG. If a chart is quietly missing a feature you configured, **check the console before the config**. Since 7.9.1 the minified `apexcharts.min.js` prints these warnings too.
|
|
214
|
+
|
|
215
|
+
**Opt-in chart types throw *(v8.0)*.** `unit`, `waffle`, `sunburst`, `violin`, `icicle` and `raincloud` without their entry make `render()` reject, and the console prints one error naming the import, the script tag and the full bundle. An `updateOptions()` that switches to an unloaded type keeps the current chart.
|
|
216
|
+
|
|
217
|
+
**Feature-backed chart types draw nothing *(v8.0)*.** `waterfall`, `dumbbell` and `streamgraph` without `apexcharts/features/<name>` leave the plot empty and log one warning naming the import, because drawn as given their values would be wrong.
|
|
179
218
|
|
|
180
219
|
---
|
|
181
220
|
|
|
182
221
|
## Bare Core Usage
|
|
183
222
|
|
|
184
|
-
For maximum control,
|
|
223
|
+
For maximum control, start from the bare core and add each chart type and feature through its entry:
|
|
185
224
|
|
|
186
225
|
```js
|
|
187
226
|
import ApexCharts from 'apexcharts/core'
|
|
188
|
-
|
|
189
|
-
//
|
|
190
|
-
import { Line } from 'apexcharts/src/charts/Line.js'
|
|
191
|
-
ApexCharts.use({ line: Line, area: Line })
|
|
192
|
-
|
|
193
|
-
// Register features manually
|
|
194
|
-
import { Legend } from 'apexcharts/src/modules/legend/Legend.js'
|
|
195
|
-
ApexCharts.registerFeatures({ legend: Legend })
|
|
227
|
+
import 'apexcharts/line' // registers line, area, scatter, bubble, rangeArea
|
|
228
|
+
import 'apexcharts/features/legend' // one import per optional feature
|
|
196
229
|
```
|
|
197
230
|
|
|
231
|
+
Each entry registers its types or feature with the core. `ApexCharts.use()` and `ApexCharts.registerFeatures()` are the hooks they call: use them for your own chart class or plugin, not to rebuild a shipped one from `apexcharts/src/*`. Those raw modules have default exports only (`import { Line } from 'apexcharts/src/charts/Line.js'` fails), and imported next to the built entries they load a second copy of the internals.
|
|
232
|
+
|
|
198
233
|
This approach is rarely needed — per-type entries with feature imports cover most use cases.
|
|
199
234
|
|
|
200
235
|
---
|
|
@@ -256,10 +291,10 @@ export default {
|
|
|
256
291
|
|
|
257
292
|
## Common Pitfalls
|
|
258
293
|
|
|
259
|
-
1. **Assuming the default bundle still has everything *(v7)***: the
|
|
294
|
+
1. **Assuming the default bundle still has everything *(v7, v8)***: the Tier 2 chart types (`unit`/`waffle`, `sunburst`, `violin`, `icicle`, `raincloud`) and Tier 2 features (the nine since 7.0, highlight-filter since 7.9, and drilldown, waterfall, dumbbell and streamgraph since 8.0) need their own import on top of `import ApexCharts from 'apexcharts'`, or the full bundle. This is the most common upgrade failure, v6 to v7 and v7 to v8.
|
|
260
295
|
2. **Reaching for `apexcharts/features/all` to fix it**: that is the Tier 1 set by design and pulls in no Tier 2 module.
|
|
261
296
|
3. **Missing feature imports on a tree-shaken build**: Tier 1 features fail silently. If legend/toolbar/annotations don't appear, check imports.
|
|
262
|
-
4. **
|
|
297
|
+
4. **Adding a per-type entry for a type the default bundle already has** (`apexcharts/line`, `apexcharts/bar`, `apexcharts/waterfall` next to `apexcharts`): that is a second copy of the renderer. Next to `apexcharts`, add only the opt-in entries (`apexcharts/unit`, `/sunburst`, `/violin`, `/icicle`, `/raincloud`) and `apexcharts/features/*`. *(v7.0 fixed the related internal bug where the default bundle inlined its own core copy while add-ons resolved `apexcharts/core`, so an app importing both got two classes, ~130 KB gzipped of duplicate core, and a feature that never registered. They now share one core.)*
|
|
263
298
|
5. **Vite duplicate bundle issue**: without `optimizeDeps.include`, Vite may bundle ApexCharts twice.
|
|
264
299
|
6. **Calling `dataURI()` without exports feature**: throws an error. Import `apexcharts/features/exports` first.
|
|
265
300
|
7. **`require('apexcharts/line')` used to throw** `h.use is not a function` in every published version with sub-path entries, because rollup's default CJS interop assumes `require()` returns the export itself. Fixed in **7.0.0**; below that, use ESM `import` for sub-path entries.
|