Guides

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.

CopyJsonMenu.tsx
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

KeyValue
titleThe card’s title, translated.
dataThe chart’s rows. On a table, every row from allResults, not the page on screen.
dimensionsAndMeasuresThe fields the chart draws.
containerRef, cardRefDOM refs to the chart’s body and to the whole card.
themeThe active theme, with its formatter and translations.
optionsThe 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.

CustomDownloads.tsx
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. labelKey is 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. iconSrc is 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: true runs an entry at once, without the spinner.
  • Errors. An error thrown by onClick is not caught. Handle a failure inside it, for example to tell the reader.