> ## Documentation Index
> Fetch the complete documentation index at: https://docs.graphy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Selecting

In edit mode, click a chart element to select it, show its outline and open the [edit menu](https://docs.graphy.dev/sdk-next/editing/menu.md). Click another element to change the selection.

```tsx theme={null}
import { GraphProvider } from '@graphysdk/react';
import { EditableGraphRenderer } from '@graphysdk/react/editable';

<GraphProvider spec={spec} data={data} onSpecChange={setSpec}>
  <EditableGraphRenderer mode="edit" />
</GraphProvider>;
```

Edit mode hides tooltips and annotations, replaces hover styling with outlines, and disables browser text selection so double-clicks can narrow the chart selection.

## What a click selects

The chart checks targets in this order and selects the first one with controls:

1. An axis label, an axis title or a legend item.
2. A data mark, such as a bar, line or point, including nearby marks within the snapping distance.
3. A grid line behind the marks.
4. The chart background, if the Chart menu has controls.

A click outside the frame clears the selection.

A direct click selects the widest scope available for that layer. For example, on a column chart grouped by region, clicking North's Q4 column selects every North column.

A near miss selects the **band**: all observations at that x value across groups. Snapping reaches 8 px along the main axis or 20 px across it. Bands are available only on banded axes; on a scatter plot, a near miss selects the same scope as a direct hit.

On that column chart:

* **On the column**: the group, titled "Region: North".
* **In the gap beside it**: the band, titled "Quarter: Q4 '25".
* **On a grid line beyond the snapping distance**: the grid lines.
* **In empty space**: the chart.

`useGraphSelection` reads the selection. An observations target includes its layer, scope and a predicate identifying the selected rows:

```tsx theme={null}
import { useGraphSelection } from '@graphysdk/react';

const [target] = useGraphSelection();
// { kind: 'observations', layerId: 'bars', scope: 'group', predicate }
// { kind: 'observations', layerId: 'bars', scope: 'xValue', predicate }
// { kind: 'grid', axis: 'y' }
// { kind: 'graph' }
```

## Narrowing with a double-click

A double-click narrows the selection:

* A group's mark narrows to that observation: North's Q4 column alone.
* A discrete x-axis tick label selects its band if exactly one interactive layer has data at that value. Continuous and datetime ticks do not narrow.
* A legend item narrows to its group.
* A grid line, a band, the chart and empty space go no deeper.

The narrower target must have controls. A single line vertex has none, so double-clicking a line leaves its group selected. The menu's level selector lets you narrow or broaden the selection with buttons.

## Only targets with controls

A target is selectable when it has menu rows or a visibility button. Otherwise, hovering ignores it and clicks reach the element underneath.

With the built-in menus:

* `rule` and `tile` layers have no menu. Clicking a tile selects the grid line or chart behind it.
* Lines and areas support group selection only.
* Grouped bars support band selection. Stacked bars do not: changing a band's color would give every stack segment the same color.
* Polar axes and grid lines offer only a visibility button.
* Custom geoms without a registered menu get a color row wherever their color can be changed.

Setting an entry in `editMenus` to `null` removes its rows. Axes, legends and grids remain selectable through their visibility button; other targets become unselectable. See [Custom menus](https://docs.graphy.dev/sdk-next/editing/custom-menus.md).

## One selection at a time

Each chart has one selected target. Clicking outside, pressing Escape, moving focus to the host page or another chart, or changing modes clears it. Only one chart on the page can have an active selection.

Right-clicks and clicks on the edit menu or legend overflow control leave the selection unchanged. Removing the selected layer clears it.

To control selection from outside the provider, use `GraphHandle.setSelection([target])`, `getSelection()` and `subscribeSelection(listener)`. See [Provider & renderer](https://docs.graphy.dev/sdk-next/rendering/provider-and-renderer.md#graphprovider).

## Keyboard

Selection shortcuts apply while focus is inside the chart or its menu. Text fields keep their own keyboard handling.

* **Escape** closes an open popup, such as a color picker. Otherwise, it clears the selection and closes the menu.
* **Tab** and **Shift+Tab** move through menu controls. The menu receives focus when it opens; press Tab to reach its first control. The chart frame is not a Tab stop.
* **Undo** and **redo** shortcuts require [`useGraphHistoryShortcuts`](https://docs.graphy.dev/sdk-next/editing/commands-and-history#keyboard-shortcuts).

Delete and Enter are annotation shortcuts and have no selection action in edit mode.

## Outlines

The hover outline previews what a click would select; the selected outline marks the current selection. Both sit outside the element's shape, and touching shapes merge into one outline. The selected outline stays above the hover outline. The chart background has no hover outline.

Style both with `style.editOutline`, or use `.hover` and `.selected` to style them separately:

```tsx theme={null}
styles({
  overrides: [
    style.editOutline.selected({ stroke: '#ff0066', dashArray: [] }),
    style.editOutline.hover({ strokeAlpha: 0.5 }),
  ],
});
```

Outlines follow the rendered shape: bar regions, line strokes, points and guide elements. Companion layers, such as a line's dots, share their host's outline. The chart outline is a rounded rectangle inside the frame.

Custom geoms use observation bounding boxes, at least 8 px across, by default. Implement `getEditOutlineShapes` for outlines that match the geom's shape. See [Geom renderers](https://docs.graphy.dev/sdk-next/extending/geom-renderers.md).

## Related

* [The edit menu](https://docs.graphy.dev/sdk-next/editing/menu.md) — what opens beside the selection
* [Commands & history](https://docs.graphy.dev/sdk-next/editing/commands-and-history.md) — the commands a menu row dispatches, undo/redo shortcuts
* [Geom renderers](https://docs.graphy.dev/sdk-next/extending/geom-renderers.md) — `getEditOutlineShapes` for custom geoms
* [Styling](https://docs.graphy.dev/sdk-next/config/styling.md) — `style.editOutline` and its vocabulary


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.