---
url: https://chartbuddy.io/embed/docs/configuration/gridlines.md
---
# Gridlines

Gridlines live under each axis side (`left` / `right` / `top` / `bottom`). On a typical vertical chart, value gridlines sit on the **primary range** axis (`left`).

## Defaults for an axis

```js
axes: {
  left: {
    gridlines: {
      visible: false, // new charts default off — set true to show
      color: '#aaaaaa',
      width: 0.5,
      dashArray: '5,5', // dashed; use '' for solid
      opacity: 0.8,
      overrides: {},
    },
  },
}
```

New charts default to **`visible: false`**. When enabled, the default stroke is a thin dashed line (`0.5px`, `5,5`). Those top-level fields apply to **every** gridline on that axis unless an override says otherwise.

For a solid stroke in authored `chartData`, prefer `dashArray: ''`. `'none'` also works; both clear the dash pattern.

## Per-tick overrides

`overrides` is a sparse map. Keys are the **tick value as a string** (for example `"0"`, `"50"`, `"100"`). Values are partial style objects. Only list the ticks you want to change; every other tick keeps the axis defaults above.

| Override field | Effect |
|---|---|
| `visible` | Show or hide this tick’s gridline |
| `color` | Stroke color |
| `width` | Stroke width (px) |
| `dashArray` | Dash pattern (`'5,5'`, or `''` for solid) |
| `opacity` | Stroke opacity |

### Make ticks deterministic when authoring overrides

Override keys must match ticks the engine actually draws. Without a fixed interval, auto tick selection can pick a different step and your keys silently no-op.

**Pair overrides with `labels.preferredTickInterval`** on the same axis so keys like `"50"` / `"75"` / `"100"` are predictable:

```js
axes: {
  left: {
    labels: {
      preferredTickInterval: 25,
    },
    gridlines: {
      visible: true,
      color: '#aaaaaa',
      width: 0.5,
      dashArray: '5,5',
      overrides: {
        '0': { visible: false },
        '50': { color: '#0f766e', width: 1, dashArray: '' },
        '100': { color: '#0f766e', width: 1.5, dashArray: '' },
      },
    },
  },
}
```

With interval `25`, drawn ticks are multiples of 25 within the axis range (`"0"`, `"25"`, `"50"`, …). More on intervals: [Ticks & intervals](/axes/ticks).

### Smaller recipes

Hide only the line at `0`:

```js
overrides: {
  '0': { visible: false },
}
```

Hide `0` and recolor `100`:

```js
overrides: {
  '0': { visible: false },
  '100': { color: '#c45c26' },
}
```

## Discovering keys from a live chart

If you are not fixing the interval yourself:

1. Style one gridline in the editor, then call `getChartData()` / `exportConfig()` and copy `axes.*.gridlines.overrides`
2. Or read the resolved ticks after boot and stringify those values as keys

## Live patches (`setChartData`)

When updating an already-mounted Insight, `gridlines` merges one level, but the **`overrides` map replaces as a whole**. Spread the previous map if you only want to add a key:

```js
const cd = insight.getChartData();
const prev = cd.axes.left.gridlines.overrides || {};

insight.setChartData({
  axes: {
    left: {
      gridlines: {
        overrides: {
          ...prev,
          '75': { color: '#c45c26' },
        },
      },
    },
  },
});
```

For a full upfront `chartData` object, skip this: just author the sparse `overrides` map (and `preferredTickInterval`) you need.