# Events

Click handlers that give you the clicked value, for cross-filtering and drill-downs.

The samples assume the `ChartsProvider` from [step 2 of the quick start](/docs/quick-start.md#2-add-the-provider).

A chart calls your handler when a bar, point, slice or row is clicked, and passes the value that was clicked. Use it to filter another chart, open a detail view or navigate.

## Filter one chart from another

Click a region on the left to filter the chart on the right.

```tsx title="RegionFilter.tsx"
import { useState } from 'react';
import { BarChart, dimension, measure, results } from 'em-kit';

const region = dimension({ name: 'region', title: 'Region' });
const plan = dimension({ name: 'plan', title: 'Plan' });
const revenue = measure({ name: 'revenue', title: 'Revenue', inputs: { prefix: '$' } });

const byRegion = [
  { region: 'Americas', revenue: 527900 },
  { region: 'EMEA', revenue: 391500 },
  { region: 'APAC', revenue: 276300 },
];

const byRegionAndPlan = [
  { region: 'Americas', plan: 'Starter', revenue: 96400 },
  { region: 'Americas', plan: 'Growth', revenue: 181200 },
  { region: 'Americas', plan: 'Enterprise', revenue: 250300 },
  { region: 'EMEA', plan: 'Starter', revenue: 88100 },
  { region: 'EMEA', plan: 'Growth', revenue: 142900 },
  { region: 'EMEA', plan: 'Enterprise', revenue: 160500 },
  { region: 'APAC', plan: 'Starter', revenue: 71800 },
  { region: 'APAC', plan: 'Growth', revenue: 109300 },
  { region: 'APAC', plan: 'Enterprise', revenue: 95200 },
];

const grid = {
  display: 'grid',
  gridTemplateColumns: 'repeat(auto-fit, minmax(280px, 1fr))',
  gridAutoRows: 320,
  gap: 16,
};

export function RegionFilter() {
  const [selected, setSelected] = useState('EMEA');

  return (
    <div style={grid}>
      <BarChart
        title="Revenue by region"
        dimension={region}
        measures={[revenue]}
        results={results(byRegion)}
        onBarClicked={({ dimensionValue }) => {
          if (dimensionValue != null) setSelected(String(dimensionValue));
        }}
      />
      <BarChart
        title={`${selected} by plan`}
        dimension={plan}
        measures={[revenue]}
        results={results(byRegionAndPlan.filter((row) => row.region === selected))}
      />
    </div>
  );
}
```

Result: two bar charts. Clicking a region in the first changes the title and the bars of the second.

## What the handler receives

| Key | Value |
|---|---|
| `dimensionValue` | The clicked category, such as `'EMEA'`. `undefined` when the axis is a time dimension. |
| `dimensionTimeRange` | On a time axis, the clicked period as a `TimeRange`. `undefined` on a category axis. |
| `groupingDimensionValue`, `groupingDimensionTimeRange` | The same pair for the series that was clicked. Stacked and grouped charts only. |
| `measureValues` | Each measure’s value at the click, keyed by the measure’s `name`. Passed by , though their payload types leave it out. |

A click payload’s `TimeRange` is `undefined` unless the clicked field is a time dimension, and its `relativeTimeString` is always `undefined`, so read it as `range?.from`. When you pass one, `from` and `to` are enough.

## Handler names

The prop is named after what is clicked, and the names differ: some end in `Clicked`, some in `Click`. This table is generated from each component’s props.

| Handler | Components |
|---|---|
| `onRowClicked` | `TableScrollable`, `TablePaginated` |
| `onBarClicked` | `BarChart`, `BarChartHorizontal`, `BarChartGrouped`, `BarChartGroupedHorizontal`, `BarChartStacked`, `BarChartStackedHorizontal`, `BarLineChart` |
| `onLineClicked` | `BarLineChart`, `LineChart`, `LineChartGrouped`, `LineChartComparison`, `LineChartWithKpiTabs`, `LineChartComparisonWithKpiTabs` |
| `onPointClicked` | `AreaChart` |
| `onAreaClicked` | `AreaChart` |
| `onSegmentClick` | `PieChart`, `DonutChart`, `DonutLabelChart` |
| `onPointClick` | `ScatterChart`, `BubbleChart` |
| `onCellClicked` | `HeatMap` |

`AreaChart` takes `onPointClicked`; `ScatterChart` and `BubbleChart` take `onPointClick`. Each [component page](/docs/components.md) has the payload type, and its playground logs the payload as you click.

Clicks need a pointer. For keyboard users, offer the same action another way: see [Accessibility](/docs/accessibility.md).
