Chart Export

What it does

Module functions that export a rendered AbsoluteUI chart as a file:

• chartToSvg(chart, options?): a standalone SVG document string;
• chartToPng(chart, options?): a PNG Blob, rasterized from that SVG;
• downloadChart(chart, options): exports as SVG or PNG and saves it through a temporary <a download> link.

The export contains the chart title (as <title> and, by default, as visible text), the description and generated summary (as <desc>), the plot, and the visible legend entries (swatch and label). Computed theme colors, fonts, and dash patterns are copied onto the copy as presentation attributes (fill, stroke, font-family, …), so the file looks like the page without any stylesheet. The output has no style attributes and no classes (and no tabindex or focusable), and no CSS variables remain.

Works with every frame-based chart (Line, Bar, Pie, Scatter, Combo, Waterfall, Histogram, Heatmap, Radar, Treemap, Funnel, Box Plot, Bullet) plus Gauge and Sparkline: anything with a host element and a rendered element SVG.

Nothing is uploaded or stored: results are a string or Blob for the caller; downloadChart saves through a temporary object URL that is revoked afterwards.

It is a separate subpath, so charts that never export do not ship it.

When to use

• Letting users save a chart as an image (SVG for print and editing, PNG for documents and chat).
• Generating an image of a chart on the client for a report the user downloads.

When not to use

• Exporting the underlying data: use the chart’s data table or your own CSV export.
• Server-side rendering of charts (needs a browser with layout and computed styles).
• Charts that are not rendered or not attached to the document (the functions throw).

Usage

import { Gauge } from '@absoluteui/components/gauge';
import { chartToPng } from '@absoluteui/components/chart-export';

const host = document.querySelector<HTMLElement>('#cpu');
if (host) {
  const gauge = Gauge.create(host, { label: 'CPU', value: 40 });
  const blob = await chartToPng(gauge, { scale: 1 });
  const image = document.createElement('img');
  image.alt = 'CPU gauge';
  image.src = URL.createObjectURL(blob);
  document.body.append(image);
}

More usage

import { BarChart } from '@absoluteui/components/bar-chart';
import { chartToSvg, downloadChart } from '@absoluteui/components/chart-export';

const host = document.createElement('div');
document.body.append(host);
const chart = BarChart.create(host, {
  label: 'Tickets',
  categories: ['North', 'South'],
  series: [{ id: 'open', label: 'Open', values: [3, 5] }],
});

const markup = chartToSvg(chart, { background: 'transparent' });
console.log(markup.length);

const button = document.createElement('button');
button.type = 'button';
button.textContent = 'Download chart as PNG';
button.addEventListener('click', () => {
  void downloadChart(chart, { format: 'png', fileName: 'tickets', scale: 2 });
});
document.body.append(button);

API reference

Functions

chartToPng

Rasterize the chart to a PNG Blob (needs img-src blob: under a CSP).

function chartToPng(chart: ExportableChart, options?: ChartExportOptions): Promise<Blob>;

chartToSvg

Serialize the chart to a standalone SVG document string.

function chartToSvg(chart: ExportableChart, options?: ChartExportOptions): string;

downloadChart

Export and save the chart as a file (<a download>).

function downloadChart(chart: ExportableChart, options: ChartDownloadOptions): Promise<void>;

Interfaces

ChartDownloadOptions

interface ChartDownloadOptions extends ChartExportOptions {
  format: ChartExportFormat;
  fileName: string;
}

ChartExportOptions

interface ChartExportOptions {
  title?: boolean;
  legend?: boolean;
  background?: 'surface' | 'transparent';
  scale?: number;
}

ExportableChart

Anything with a host element and a rendered SVG (every AbsoluteUI chart).

interface ExportableChart {
  readonly host: HTMLElement;
  readonly element: SVGSVGElement;
}

Types

ChartExportFormat

type ChartExportFormat = 'svg' | 'png';

TypeScript definitions

type ChartExportFormat = 'svg' | 'png';
interface ChartExportOptions { title?: boolean; legend?: boolean; background?: 'surface' | 'transparent'; scale?: number }
interface ChartDownloadOptions extends ChartExportOptions { format: ChartExportFormat; fileName: string }
interface ExportableChart { readonly host: HTMLElement; readonly element: SVGSVGElement }
function chartToSvg(chart: ExportableChart, options?: ChartExportOptions): string;
function chartToPng(chart: ExportableChart, options?: ChartExportOptions): Promise<Blob>;
function downloadChart(chart: ExportableChart, options: ChartDownloadOptions): Promise<void>;

Behavior

States

Not applicable (stateless functions).

Accessibility notes

• Give the export trigger an accessible name that states the format (for example “Download chart as PNG”).
• A PNG carries no text alternative; when you place it in a document, use the chart title and, for frame-based charts, chart.summary as its alt text. The SVG keeps <title>, <desc>, and per-mark labels.
• The export reflects the current state: hidden series, the current zoom, and forced-colors or theme colors active at the time of export.

Responsive behavior

The file uses the plot’s rendered width and height (plus 12 px padding each side); legend entries wrap into rows within that width.

Right-to-left

The plot is copied as rendered, so RTL charts stay mirrored. Title and legend text are drawn from the left edge.

Theming

Colors, fonts, and dash patterns are resolved from the page at export time (light or dark theme, custom themes). The background is the theme surface unless background: 'transparent'.

Global configuration

None (no configureAbsoluteUI key); pass options per call.

Component configuration

Per-call options only (see section 5).

Security

• Nothing is uploaded or stored; no network access or telemetry.
• The copy is built with createElementNS, setAttribute, and text nodes; no innerHTML, no style attributes, no classes in the output.
• PNG rasterizing loads the SVG from a blob: URL: pages with a Content Security Policy need img-src blob:. downloadChart also navigates to a blob: URL through <a download>.
• Object URLs are revoked (PNG: immediately after decoding; downloads: after one second).
• fileName must not contain path separators.

Data handling

The output contains exactly what the chart shows: title, description, summary, mark labels (values), and legend labels. Treat the file with the same sensitivity as the chart data. Nothing is logged; validation errors name the option, never its value.

Performance

No performance budget. Cost grows with the number of SVG elements in the plot (one getComputedStyle per element); PNG adds image decoding and canvas encoding.

Supported data scale

Whatever the chart renders. Very large PNGs are bounded by the browser’s canvas size limits (lower scale for very wide charts).

Edge cases

• Chart destroyed or host detached: throws CHART_EXPORT_OPTIONS (chartExport.chart).
• Chart without a legend (Funnel, Bullet, Gauge, Sparkline) or legend: 'hide': no legend rows. Hidden series are not listed.
• Chart without a description: <desc> holds the summary only.
• Empty chart: the empty plot is exported (the “No data” text is HTML outside the SVG and is not included).
• Tooltips, the data table, and toolbars are HTML outside the plot and are never exported.
• A fileName that already ends in .png / .svg (any case) is kept as is.

Errors

Code	Category	Cause
CHART_EXPORT_OPTIONS	configuration	title / legend not boolean; background not 'surface' | 'transparent'; scale outside 1-4; chart not rendered or not connected; format not 'svg' | 'png'; fileName empty or with / or \.
CHART_EXPORT_UNAVAILABLE	runtime	No window for the chart’s document, or canvas 2D unavailable.
CHART_EXPORT_FAILED	runtime	The canvas produced no PNG blob.

chartToPng and downloadChart reject their promise with these errors; an image decode failure (for example img-src blocking blob:) rejects with the browser’s own error.

Known limitations

• Needs a browser with layout (rendered size) and computed styles.
• Title and legend text are laid out with an approximate text width; very long legend labels may overlap.
• HTML parts of the chart (tooltip, data table, empty-state text, toolbar) are not included.
• Web fonts are referenced by family name, not embedded; the file renders with the viewer’s fonts.

Unsupported scenarios

• JPEG, WebP, or PDF output.
• Exporting data (CSV, XLSX).
• Server-side or worker export.
• Uploading or sharing (by design; send the returned Blob yourself if needed).