Charts - Export

Let users export a chart as an image or in PDF format.

Charts can be exported as images, or as PDFs using the browser's native print dialog. The exporting feature is available for the following charts:

• LineChartPro
• BarChartPro
• ScatterChartPro
• PieChartPro
• Heatmap
• FunnelChart
• RadarChartPro
• SankeyChart
• CandlestickChart

Implementing exporting

Default toolbar

To enable exporting from the chart's toolbar, pass the showToolbar prop to the chart component. The toolbar then renders a button that opens a menu with the export options.

Custom toolbar

See the Toolbar documentation for more information on how to create a custom toolbar.

Image exporting

You must install rasterizehtml to enable image exporting:

Export options

Export behavior can be modified with print and image export options. These options can be passed to the built-in toolbar using slotProps.toolbar, and are then automatically displayed.

You can customize their respective behaviors by passing an options object to slotProps.toolbar, or to the export trigger itself if you're using a custom toolbar:

// Default toolbar:
<BarChartPro slotProps={{ toolbar: { printOptions, imageExportOptions } }} />

// Custom trigger:
<ChartsToolbarImageExportTrigger options={imageExportOptions} />
<ChartsToolbarPrintExportTrigger options={printExportOptions} />

Export formats

To disable the print export, set the disableToolbarButton property to true.

You can customize image export formats by providing an array of objects to the imageExportOptions property. These objects must contain the type property which specifies the image format.

In the example below, you can toggle which export formats are available to the user. The name of the exported file has been customized to resemble the chart's title.

Add custom styles before exporting

To add custom styles or modify the chart's appearance before exporting, use the onBeforeExport callback.

When exporting, the chart is first rendered into an iframe and then exported as an image or PDF. The onBeforeExport callback gives you access to the iframe before the export process starts.

For example, you can add the title and caption to the exported chart as shown below:

Hide elements from export

Mark any element with the data-hide-on-export attribute to exclude it from image and print exports. The attribute works on any HTML or SVG element in the chart tree.

To hide an internal MUI X Charts component (such as the legend) that you do not render directly, forward the attribute through slotProps:

<BarChartPro slotProps={{ legend: { 'data-hide-on-export': true } as any }} />

Copy styles

The styles of the page the chart belongs to are copied to the export iframe by default. You can disable this behavior by setting the copyStyles property to false in the export options.

<BarChartPro slotProps={{ toolbar: { printOptions: { copyStyles: false } } }} />

Stylesheets that fail to load

When a stylesheet, or a stylesheet it imports, fails to load in the export iframe, for example because a request fails or a Content Security Policy blocks it, the export continues. The result may be missing some styles, and a warning is logged in development. The image export still fails when the Content Security Policy blocks the styles it inlines, for example when the nonce option is missing.

To handle the failure yourself, use the onStylesheetError callback. It receives the <link> element that failed to load, or whose import failed to load, and the reason: 'content-security-policy' if the Content Security Policy blocked the stylesheet, or 'load-error' if the request failed or a stylesheet it imports failed to load. The callback's return value decides what happens next:

• Return or resolve to false to cancel the export.
• Throw an error or reject to make the export fail with that error.
• Return anything else to continue the export. The image export still fails if the Content Security Policy blocks the styles it inlines.

If the callback returns a promise, the export waits for it. This can be useful if you want to add replacement styles to link.ownerDocument. See Handling export errors for how a cancelled or failed export is reported.

When using the toolbar, you can provide onStylesheetError as an option using slotProps:

<BarChartPro
  slotProps={{
    toolbar: {
      printOptions: {
        onStylesheetError: (link) => {
          showNotification(`The stylesheet ${link.href} failed to load.`);
          return false;
        },
      },
    },
  }}
/>

Exporting composed charts

MUI X Charts may be self-contained or composed of various subcomponents. See Composition for more details on implementing the latter type.

ChartsWrapper is considered the root element of a chart for exporting purposes, and all descendants are included in the export.

To use a custom wrapper instead, you must set the reference to the root element with the useChartRootRef() hook as shown below:

Content Security Policy (CSP)

If your application uses a Content Security Policy (CSP), you might need to adjust it for exporting to work correctly. See the dedicated document on CSP for more details.

apiRef

Print or export as PDF

The apiRef prop exposes the exportAsPrint() method that can be used to open the browser's print dialog. The print dialog lets you print the chart or save it as a PDF, as well as configure other settings.

Export as image

The apiRef prop also exposes the exportAsImage() method to export the chart as an image. The function accepts an options object with the type property which specifies the image format. The available formats are:

• image/png and image/jpeg which can both be used across all supported platforms
• image/webp which is only supported in some browsers

If the format is not supported by the browser, exportAsImage() falls back to image/png.

For lossy formats such as image/jpeg and image/webp, the options object accepts the quality property which sets a numerical value between 0 and 1. The default is 0.9.

You can also pass a pixelRatio to control the scale at which the chart is rasterized. Higher values produce sharper images at the cost of a larger file size. When omitted, the export uses the larger of window.devicePixelRatio and 2, guaranteeing a minimum 2x resolution on standard-DPI displays without regressing higher-DPI exports.

apiRef.current?.exportAsImage({ pixelRatio: 3 }).catch((error) => {
  // Report the failed export.
});

Handling export errors

exportAsPrint() and exportAsImage() return a promise that rejects when the export fails, for example when onStylesheetError throws or rejects. exportAsImage() also rejects when a Content Security Policy blocks the styles copied to the export, while exportAsPrint() prints the chart without them. Handle the rejection to report the failure to your users. When the export is started from the toolbar, the error is logged to the console instead.

try {
  await apiRef.current?.exportAsImage();
} catch (error) {
  // Report the failed export.
}

When onStylesheetError cancels the export by returning false, nothing is exported, no error is logged, and the promise resolves.

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.

• <BarChartPro />
• <FunnelChart />
• <Heatmap />
• <LineChartPro />
• <RadarChartPro />
• <SankeyChart />
• <ScatterChartPro />