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

# Legend

The `legend` section controls where the legend sits and how it presents series. A legend appears automatically when a chart maps `color` (or `group`) to more than one series.

```tsx theme={null}
config({
  legend: { position: 'bottom', display: 'pill' },
});
```

## Options

<ParamField path="position" type="'auto' | 'top' | 'bottom' | 'left' | 'right' | 'none'" default="auto">
  Where the legend sits. `'none'` hides it; `'auto'` lets the engine choose
  based on the chart.
</ParamField>

<ParamField path="display" type="'pill' | 'direct' | 'auto'" default="auto">
  How series are labelled:

  * `'pill'` — a boxed legend with a swatch and label per series.
  * `'direct'` — labels drawn next to each series' endpoint, no separate legend box. Reads well on line charts.
  * `'auto'` — resolved during compilation from the chart type and legend position.
</ParamField>

<ParamField path="align" type="'auto' | 'start' | 'center' | 'end'" default="auto">
  Placement of the legend items along the legend's flow:

  * For a horizontal (`top`/`bottom`) legend this runs along the row — `start` is left, `end` is right.
  * For a vertical (`left`/`right`) legend it runs down the column — `start` is top, `end` is bottom.
  * `'auto'` resolves to `start` for horizontal legends and `center` for vertical ones.

  Across the flow, a vertical legend always pins to the plot border.
</ParamField>

```tsx theme={null}
config({
  legend: { position: 'bottom', align: 'end' },
});
```

## Direct labels

Combine `display: 'direct'` with `position` to steer which side the labels flow toward:

```tsx theme={null}
config({
  legend: { position: 'right', display: 'direct' },
});
```

## Continuous color

A `color` scale that runs a ramp rather than a set of hues draws a **gradient colour bar** instead of a row of swatches — sampled across the scale's domain, so a diverging ramp shows where its neutral point falls. `position`, `align` and `'none'` steer it like any other legend; `display: 'direct'` doesn't apply, since there are no series to label.

## Hiding the legend

```tsx theme={null}
config({ legend: { position: 'none' } });
```

## Related

* [Mappings & aesthetics](/sdk-next/concepts/mappings) — `color` and `group` create series
* [Scales](/sdk-next/concepts/scales#continuous-color) — the color scale that assigns series their swatches, and the ramps behind a colour bar