Card menu
Choose the entries in a card’s menu, add your own, and change what the downloads do.
A chart’s card has a menu behind the ⋮ button in its header: download the data as CSV or XLSX, download the chart as a PNG, or maximize the card. You choose the entries per chart, and you can add your own or change what a built-in one does.
Choose the entries for a chart
menuOptions lists the entries a chart offers, by value. The built-in values are csv, xlsx, png and maximize, and each component page gives its default: all four for most.
Pass [] for no menu at all. hideMenu goes further and leaves out the card’s whole header: title, description and menu.
Add your own entry
Entries are defined in the theme, at defaults.chartMenuOptions. Add yours to the built-in list, then name its value in the menuOptions of each chart that should offer it.
import { BarChart, ChartsProvider, defaultTheme, dimension, measure, results } from 'em-kit';
import type { ChartCardMenuOption } from 'em-kit';
const copyJson: ChartCardMenuOption = {
value: 'json',
labelKey: 'Copy as JSON',
onClick: ({ data }) => navigator.clipboard.writeText(JSON.stringify(data, null, 2)),
};
const theme = {
defaults: { chartMenuOptions: [...defaultTheme.defaults.chartMenuOptions, copyJson] },
};
const region = dimension({ name: 'region', title: 'Region' });
const revenue = measure({ name: 'revenue', title: 'Revenue', inputs: { prefix: '$' } });
const rows = [
{ region: 'Americas', revenue: 527900 },
{ region: 'EMEA', revenue: 391500 },
{ region: 'APAC', revenue: 276300 },
];
export function CopyJsonMenu() {
return (
<ChartsProvider theme={theme}>
<div style={{ height: 320 }}>
<BarChart
title="Revenue by region"
dimension={region}
measures={[revenue]}
results={results(rows)}
menuOptions={['csv', 'png', 'json']}
/>
</div>
</ChartsProvider>
);
}An override replaces the list, which is why the example starts from defaultTheme.defaults.chartMenuOptions. The menu button shows a spinner until onClick returns or, when it returns a promise, until that settles.
What an entry receives
| Key | Value |
|---|---|
title | The card’s title, translated. |
data | The chart’s rows. On a table, every row from allResults, not the page on screen. |
dimensionsAndMeasures | The fields the chart draws. |
containerRef, cardRef | DOM refs to the chart’s body and to the whole card. |
theme | The active theme, with its formatter and translations. |
options | The entry’s own options. |
On a table, an entry waits for allResults, as the built-in downloads do: see Tables.
Change a built-in entry
Map over the built-in list and return a changed copy of the entry. To keep the download and add a step, call the original onClick from yours.
import type { ReactNode } from 'react';
import { ChartsProvider, defaultTheme } from 'em-kit';
import type { ChartCardMenuOption } from 'em-kit';
const options = defaultTheme.defaults.chartMenuOptions.map((option): ChartCardMenuOption => {
// PNG: a white background, and the whole card rather than the chart alone.
if (option.value === 'png') {
return { ...option, options: { pngBackgroundColor: '#ffffff', captureFullCard: true } };
}
// CSV: note the download, then run the built-in one.
if (option.value === 'csv') {
return {
...option,
onClick: (args) => {
console.info(`CSV downloaded: ${args.title}`);
return option.onClick(args);
},
};
}
return option;
});
const theme = { defaults: { chartMenuOptions: options } };
export function CustomDownloads({ children }: { children: ReactNode }) {
return <ChartsProvider theme={theme}>{children}</ChartsProvider>;
}The PNG entry reads two settings from its options. pngBackgroundColor is any CSS colour, and the image is transparent without it; captureFullCard includes the card’s title and description.
Labels, icons and order
- Labels.
labelKeyis a translation key, and text with no translation is shown as written, so a plain label works. For a translated label, add the key to your translations before the first chart renders. - Icons.
iconSrcis an SVG as a data URL:data:image/svg+xml,followed by the URL-encoded markup. - Order. Entries appear in the order of the theme’s list, whatever the order of
menuOptions. - No spinner.
isInstantAction: trueruns an entry at once, without the spinner. - Errors. An error thrown by
onClickis not caught. Handle a failure inside it, for example to tell the reader.