Utilities

Helpers for image export and OS-synced theming

Overview

Small helpers that paper over glue code most apps end up writing themselves. All exports are available from both the full-bundle entry and the tree-shakeable core entry:

import {
  exportToPNG,
  exportToSVG,
  useChartTheme,
} from 'react-echarts-library';
// or 'react-echarts-library/core'

Added in v1.4.0.

exportToPNG

Wrap chart.getDataURL({ type: 'png' }) with sensible defaults and an optional one-shot browser download.

function exportToPNG(
  chart: EChartsType,
  options?: ExportImageOptions
): string;

Option	Type	Default	Description
`pixelRatio`	`number`	`2`	Device pixel ratio. Bump to `3` for retina prints.
`backgroundColor`	`string`	`'#ffffff'`	Background painted behind the chart.
`excludeComponents`	`string[]`	`undefined`	ECharts component types to omit (e.g. `['toolbox']`).
`filename`	`string`	`undefined`	If set, also triggers a browser download with this filename.

Returns the data URL regardless — filename is purely additive.

import { useRef } from 'react';
import {
  EChartsReact,
  exportToPNG,
} from 'react-echarts-library';
import type { EChartsReactRef } from 'react-echarts-library';

function ExportableChart() {
  const chartRef = useRef<EChartsReactRef>(null);

  const handleDownload = () => {
    const chart = chartRef.current?.getEchartsInstance();
    if (!chart) return;
    exportToPNG(chart, { filename: 'sales.png', pixelRatio: 3 });
  };

  return (
    <>
      <EChartsReact ref={chartRef} option={option} />
      <button onClick={handleDownload}>Download PNG</button>
    </>
  );
}

exportToSVG

Same shape as exportToPNG, minus pixelRatio (SVG is resolution-independent).

function exportToSVG(
  chart: EChartsType,
  options?: Omit<ExportImageOptions, 'pixelRatio'>
): string;

For best fidelity, init the chart with the SVG renderer:

<EChartsReact
  option={option}
  initOpts={{ renderer: 'svg' }}
/>

When the chart was rendered with the SVG renderer, exportToSVG calls renderToSVGString() for vector output. Otherwise it falls back to chart.getDataURL({ type: 'svg' }).

const handleDownloadSVG = () => {
  const chart = chartRef.current?.getEchartsInstance();
  if (chart) exportToSVG(chart, { filename: 'sales.svg' });
};

useChartTheme

React hook that returns 'light' | 'dark', synced to the OS prefers-color-scheme media query.

function useChartTheme(override?: 'light' | 'dark'): 'light' | 'dark';

Reacts to system theme changes — passing the result straight into theme re-inits the chart with the new palette.
SSR-safe: returns 'light' on the server, then corrects on hydration. No flash on Next.js / Astro / Remix.
Pass an override to short-circuit the media query (e.g. when the user has chosen a theme in your app’s settings).

import { EChartsReact, useChartTheme } from 'react-echarts-library';

function ThemedChart() {
  const theme = useChartTheme();   // reacts to OS dark-mode toggle
  return <EChartsReact option={option} theme={theme} />;
}

With a user override

function ThemedChart({ userPreference }: { userPreference?: 'light' | 'dark' }) {
  const theme = useChartTheme(userPreference); // override wins when set
  return <EChartsReact option={option} theme={theme} />;
}

Patterns

Export a chart that already has a toolbox

If your chart includes ECharts’ built-in toolbox for screenshots, you’ll want to omit it from your own export so the buttons don’t appear in the saved image:

exportToPNG(chart, {
  filename: 'sales.png',
  excludeComponents: ['toolbox'],
});

Export from the useECharts hook

import { useECharts, exportToPNG } from 'react-echarts-library';

function ChartCard() {
  const { containerRef, getInstance } = useECharts(echarts, { option });

  const handleExport = () => {
    const chart = getInstance();
    if (chart) exportToPNG(chart, { filename: 'chart.png' });
  };

  return (
    <>
      <div ref={containerRef} style={{ height: 320 }} />
      <button onClick={handleExport}>Download</button>
    </>
  );
}