---
url: https://chartbuddy.io/embed/docs/configuration/legend.md
---
> Docs index: [llms.txt](https://chartbuddy.io/embed/docs/llms.txt)

# Legend

The legend lives at `legend` on `chartData`. It controls **series colors** (`legend.colors`), visibility, typography, item order, and **placement** (docked slots or free-floating).

```js
legend: {
  visible: true,
  position: 'rightTop', // docked slot, or 'free'
  orientation: 'vertical', // item flow: 'vertical' | 'horizontal'
  reverseOrder: false,
  colors: ['#4285F4', '#DB4437', '#F4B400'],
  itemVisibility: {},
  text: {
    fontSize: 11,
    fontColor: 'black',
    fontFamily: 'Arial',
  },
  // When position is 'free' only:
  // x: 0.55,
  // y: 0.08,
}
```

`legend.orientation` is **item layout** (stack vs row). It is not `orientation` on the chart (axes / bars). Flipping the chart does not flip the legend.

***

## Placement model

Two modes, both via `legend.position`:

| Mode | `position` | Plot space | Coordinates |
|---|---|---|---|
| **Docked** | One of 12 slots below | Reserves margin (width on left/right, height on top/bottom) | Engine places the legend; `x` / `y` are rewritten on draw — do not treat them as source of truth |
| **Free-floating** | `'free'` | Does **not** reserve margin (overlays the plot) | `x` / `y` are fractions of the drawable chart area (roughly `0`–`1`) |

There is no separate `dock` / `placement` field.

### Docked positions (12)

Side first, then alignment:

| Side | Values |
|---|---|
| Top | `topLeft`, `topCenter`, `topRight` |
| Bottom | `bottomLeft`, `bottomCenter`, `bottomRight` |
| Left | `leftTop`, `leftCenter`, `leftBottom` |
| Right | `rightTop`, `rightCenter`, `rightBottom` |

Default is `rightTop`.

```js
// Bottom strip
legend: {
  visible: true,
  position: 'bottomCenter',
  orientation: 'horizontal',
}

// Left rail
legend: {
  visible: true,
  position: 'leftTop',
  orientation: 'vertical',
}
```

### Free-floating

```js
legend: {
  visible: true,
  position: 'free',
  orientation: 'horizontal', // author-controlled; not tied to a dock
  x: 0.55,
  y: 0.08,
}
```

Precise `x` / `y` are easiest to set by dragging in edit mode, then exporting config. Free legends can overlap series or labels because they do not push the plot.

***

## Orientation (item flow)

| Value | Layout |
|---|---|
| `vertical` | Items stack top → bottom (default; fits left/right docks) |
| `horizontal` | Items flow sideways, may wrap (fits top/bottom docks) |

When you **drag** the legend onto a dock in the editor, orientation is updated automatically:

| Dock family | Forced orientation |
|---|---|
| `top*` / `bottom*` | `horizontal` |
| `left*` / `right*` | `vertical` |
| `free` | unchanged |

Hand-authored / API patches that only change `position` do **not** auto-update orientation. Always set a matching `orientation` when docking by config — e.g. `bottomCenter` + leftover `vertical` yields a tall legend on the bottom strip.

***

## Visibility and items

| Field | Role |
|---|---|
| `visible` | Whole legend on/off |
| `itemVisibility` | Per-series map: `{ "0": false }` hides series `0` from the legend. Missing key or `true` = shown |
| `reverseOrder` | `true` reverses series order in the legend |

Defaults: legend starts **hidden** on waterfall, bar mekko, and pie/donut; **shown** on other types. Single-series charts often look cleaner with `visible: false`.

Hiding the last visible legend item also turns the whole legend off. Showing the legend again when every item was hidden clears `itemVisibility`.

***

## Colors and text

| Field | Role |
|---|---|
| `colors` | Series / category fill palette (shared with the chart) |
| `text.fontSize` / `fontFamily` / `fontColor` | Legend label typography |

See also [Colors & fonts](https://chartbuddy.io/embed/docs/concepts/colors-and-fonts.md).

***

## Field reference

| Field | Type | Default | Notes |
|---|---|---|---|
| `visible` | boolean | type-dependent | See above |
| `position` | string | `'rightTop'` | 12 docks or `'free'` |
| `orientation` | `'vertical'` | `'horizontal'` | `'vertical'` | Item flow; match dock family when hand-authoring |
| `x` / `y` | number | `0.13` / `0.05` | Used when `position === 'free'` |
| `reverseOrder` | boolean | `false` | |
| `colors` | string\[] | org palette | Series fills |
| `itemVisibility` | object | `{}` | Keys are series index strings |
| `text.fontSize` | number | `11` | pt |
| `text.fontColor` | string | `'black'` | |
| `text.fontFamily` | string | org default | |

***

## Tips

* Docked legends reserve plot space; free legends overlay it.
* On horizontal charts, left/right docks compete with category labels for width — bottom or free often works better, or hide the legend.
* Prefer edit-mode drag + `exportConfig()` / `getChartData()` when you need exact free placement or a precise dock alignment.