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.
@@ -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' # heatmap only
12
- import ApexCharts from 'apexcharts/treemap' # treemap only
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
- radius: 0, // border radius of cells
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) — for hydration after SSR
14
- import ApexCharts from 'apexcharts' // auto-detects browser
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' // id is important for hydration targeting
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 <div id="my-chart" data-apexcharts>...<svg>...</svg></div>
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
- const chart = ApexCharts.hydrate(document.querySelector('#my-chart'))
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
- import ApexCharts from '/node_modules/apexcharts/dist/apexcharts.esm.js'
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. **Using `apexcharts` in Node.js without SSR methods** — the default export auto-resolves based on environment, but `renderToString` is only available via `apexcharts/ssr`.
214
- 2. **Forgetting to hydrate on the client** — server-rendered charts are static SVGs. Without `hydrate()`, they have no interactivity (no tooltips, zoom, click events).
215
- 3. **Missing width/height**: SSR has no DOM to measure. Pass explicit dimensions in the **second** argument: `renderToString(options, { width, height })` / `renderToHTML(options, { width, height })`.
216
- 4. **Hydrating before DOM is ready** — call `hydrate()` after the server-rendered HTML is in the DOM (use `onMounted`, `useEffect`, or `DOMContentLoaded`).
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 four import strategies with different bundle sizes:
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'` | Every chart type except `raincloud`, plus the **Tier 1** features. **Not** the nine Tier 2 features. |
27
- | Per-type entry | `import ApexCharts from 'apexcharts/line'` | Specific chart family + core (no optional features at all) |
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. **Tier 2**: the only chart type absent from the default bundle. |
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/unit` | unit, **waffle** *(new in v6.6, premium: watermarked until licensed)* |
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.** Four 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:
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 at all, so every feature you want needs its import.
94
- 2. **Which tier is the feature?** Tier 1 is in the default `apexcharts` bundle. **Tier 2 is in no bundle**, so it needs its import even there.
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. The first seven predate the budget and are grandfathered.
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 NO bundle; always an explicit import
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
- | Trellis *(v7.0)* | `import 'apexcharts/features/trellis'` | 25.7 KB | yes | Small multiples: a grid of real charts sharing scale, legend, toolbar, crosshair |
127
- | Storyboard | `import 'apexcharts/features/storyboard'` | 8.0 KB | yes | Scrollytelling (registers Perspectives too) |
128
- | Perspectives | `import 'apexcharts/features/perspectives'` | 6.7 KB | yes | Shareable view state |
129
- | Ink | `import 'apexcharts/features/ink'` | 6.2 KB | yes | On-chart annotation authoring |
130
- | Renderer / Strata | `import 'apexcharts/features/renderer-canvas'` | 6.0 KB | no | Hybrid SVG + canvas renderer |
131
- | Link | `import 'apexcharts/features/link'` | 5.3 KB | yes | Crossfilter / linked views |
132
- | Measure | `import 'apexcharts/features/measure'` | 4.6 KB | yes | Measure / delta ruler |
133
- | History / Rewind | `import 'apexcharts/features/history'` | 3.2 KB | yes | Undo/redo (`chart.history`) |
134
- | Context menu | `import 'apexcharts/features/context-menu'` | 2.3 KB | yes | Right-click / long-press context menu |
135
- | Raincloud *(v7.1)* | `import 'apexcharts/features/raincloud'` | n/a | yes | The `raincloud` chart type (or use the `apexcharts/raincloud` entry) |
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 both the ESM and script-tag route. 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.
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
- **136,921 B gzipped**, against 252,005 for the full bundle. Purely additive: `apexcharts.js` is unchanged, and a page that wants everything should keep loading it rather than assembling it from parts.
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
- Every Tier 2 feature has a `dist/features/<name>.js` artifact for this channel too, and a full-bundle page still needs it:
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 both the ESM and the script-tag route, and degrades predictably where it can: a `trellis` config renders as one ordinary chart, `renderer: 'canvas'` falls back to SVG. If a v7 chart is quietly missing a feature you configured, **check the console before the config**.
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, import core and register everything manually:
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
- // Register chart types manually
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 nine Tier 2 features and the `raincloud` type need their own import on top of `import ApexCharts from 'apexcharts'`. This is the most common v6 → v7 upgrade failure.
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. **Importing `apexcharts` AND `apexcharts/line`**: creates duplicate bundles. Use one strategy. *(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.)*
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.