# 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](/docs/components.md) 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.

```tsx title="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

| 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](/docs/tables.md#what-you-pass).

## 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.

```tsx title="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](/docs/localisation.md#add-a-language) 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.
