ApexCharts

Common errors

• Error: Chart type not registered (or similar runtime error indicating missing chart type)

  cause This usually occurs when bundlers incorrectly tree-shake necessary chart types or when multiple instances of the ApexCharts module exist, causing the chart registry to be out of sync.
  fix Ensure `sideEffects` are properly configured in `package.json` for `apexcharts` (check v5.10.2 release notes for patterns). If using modular imports, make sure `import 'apexcharts/<chart-type>'` statements are not inadvertently tree-shaken. For bundler issues with duplicate modules (e.g., CJS/ESM mix), try to unify module systems or configure `optimizeDeps` if using Vite.

• ReferenceError: SVG is not a function

  cause This error occurs in Node.js environments (like SSR) when the client-side ApexCharts module is used instead of the SSR-specific one, as the client-side module expects browser APIs like `SVGElement` to be present.
  fix Ensure you are importing `ApexCharts` from `apexcharts/ssr` for all server-side rendering logic. If the issue persists, check your SSR framework's documentation for mocking browser globals.

• Legend stays greyed out after re-enabling hidden series (visual bug)

  cause A regression introduced in a previous version caused legend items to remain visually disabled even after their corresponding series were re-enabled. (Fixed in v5.10.6)
  fix Upgrade ApexCharts to version 5.10.6 or newer to resolve this specific visual regression.

Warnings

• breaking Older bundler configurations or mixed CJS/ESM imports can lead to silent tree-shaking issues, where chart types or features are unexpectedly omitted from production builds, resulting in runtime errors or missing functionality. This was particularly prevalent before v5.10.2.
  Fix: Ensure your `package.json` correctly lists `sideEffects` for `dist/*.esm.js` and `dist/features/*.esm.js`. For projects mixing module systems, consolidate to ESM where possible or ensure bundler `optimizeDeps` is configured to prevent duplicate module instances. Since v5.10.1, the chart registry is more robust to duplicate instances, but proper bundling is still recommended.
• gotcha When using ApexCharts in a Server-Side Rendering (SSR) environment (e.g., Next.js, Nuxt), the correct SSR-specific import path (`apexcharts/ssr`) must be used. Using the standard client-side import can lead to errors like 'SVG is not a function' or other Node.js environment-specific crashes.
  Fix: Change `import ApexCharts from 'apexcharts'` to `import ApexCharts from 'apexcharts/ssr'` for all SSR related code paths. Verify your SSR configuration to ensure `global.SVG` and other browser globals are correctly polyfilled or mocked if necessary.
• gotcha Since v5.7.0, ApexCharts introduced feature-level tree-shaking and in v5.10.0, per-type modular entry points. Importing the entire library (`import ApexCharts from 'apexcharts'`) will include all chart types and features, negating the bundle size benefits of modular imports.
  Fix: To optimize bundle size, import the core library (`import ApexCharts from 'apexcharts/core'`) and then explicitly import only the chart types (e.g., `import 'apexcharts/line'`) and optional features (e.g., `import 'apexcharts/features/legend'`) your application uses.
• deprecated Locale file names were renamed to their correct ISO codes in v5.10.4. Older, incorrect filenames might still function but are considered deprecated and could be removed in future major versions.
  Fix: Update any custom locale imports or configurations to use the correct ISO codes (e.g., `sr`, `sv`, `uk`) for Serbian, Swedish, and Ukrainian locales.

Install

• npm install apexcharts npm
• yarn add apexcharts yarn
• pnpm add apexcharts pnpm

Imports

• ApexCharts
  wrong:

  const ApexCharts = require('apexcharts')

  correct:

  import ApexCharts from 'apexcharts'

  This is the standard client-side import for the full bundle. CommonJS `require` should be avoided in modern projects due to potential tree-shaking issues, especially with older bundler configurations.
• ApexCharts
  wrong:

  import ApexCharts from 'apexcharts'

  correct:

  import ApexCharts from 'apexcharts/ssr'

  Use this specific entry point for Server-Side Rendering (SSR) environments. Attempting to use the default client-side import in Node.js for SSR will likely lead to errors.
• ApexCharts (modular core)
  wrong:

  import ApexCharts from 'apexcharts'

  correct:

  import ApexCharts from 'apexcharts/core'; import 'apexcharts/line';

  Since v5.7.0, ApexCharts supports feature-level tree-shaking. Import `apexcharts/core` for the base functionality, then add specific chart types (e.g., `apexcharts/line`) and features (e.g., `apexcharts/features/legend`) as needed to reduce bundle size. Using the full `apexcharts` import negates this optimization.
• ChartOptions (TypeScript type)
  wrong:

  import { ApexOptions } from 'apexcharts'

  correct:

  import type { ApexOptions } from 'apexcharts'

  For TypeScript, use `import type` for importing the `ApexOptions` interface to ensure it's removed during compilation, preventing unnecessary runtime code.

Quickstart

This quickstart code initializes and renders a basic bar chart using ApexCharts in a client-side browser environment, demonstrating chart creation with minimal configuration.

import ApexCharts from 'apexcharts';

const chartElement = document.querySelector('#chart');

const options = {
  chart: {
    type: 'bar',
    height: 350
  },
  series: [
    {
      name: 'sales',
      data: [30, 40, 35, 50, 49, 60, 70, 91, 125]
    }
  ],
  xaxis: {
    categories: [1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999]
  },
  title: {
    text: 'Basic Bar Chart Example',
    align: 'left'
  }
};

if (chartElement) {
  const chart = new ApexCharts(chartElement, options);
  chart.render();
} else {
  console.error('Chart element with id "#chart" not found.');
}

// Example of updating series data (requires a chart instance already rendered)
// setTimeout(() => {
//   chart.updateSeries([{ data: [20, 50, 45, 30, 70, 55, 80, 100, 110] }]);
// }, 5000);