---
url: https://chartbuddy.io/embed/docs/configuration/title-subtitle-footnote.md
---
# Title, subtitle & footnote

These are **special docked text boxes**: fixed keys (`title`, `subtitle`, `footnote`) that reserve plot space. Free callouts live in `multilines` — see [Text boxes](/configuration/text-boxes).

They are not free-positioned like the [legend](/configuration/legend) either (legend has its own dock / free model).

```js
title: {
  visible: true,
  text: 'Revenue vs Costs',
  fontSize: 11,
},
subtitle: {
  visible: true,
  text: 'USD millions',
  fontSize: 11,
},
footnote: {
  visible: true,
  text: 'Source: Company filings, FY2025.',
  fontSize: 6,
},
```

All three default to **`visible: false`** on every chart type. Defaults may still carry placeholder HTML in `text` while hidden — set `text: ''` when you want a clean hidden field.

***

## Where each sits

| Element | Path | Band | Default `fontSize` | Typical use |
|---|---|---|---|---|
| Title | `title` | Top of the chart | `11` | Chart name / main claim |
| Subtitle | `subtitle` | Top, under the title | `11` | Units, period, clarifying line |
| Footnote | `footnote` | Bottom of the chart | `6` | Source, caveat, legal line |

**Top stack (top → plot):** title → subtitle → (optional top legend) → axes / plot…\
**Bottom stack (plot → bottom):** … axes → (optional bottom legend) → **footnote** → canvas edge.

If both title and subtitle are off, a small top padding is still reserved so the plot does not sit flush against the top.

There is **no** position enum and **no** free `x` / `y` for authors. Layout percentages are recomputed every draw from the offset stack — omit them in hand-authored config.

***

## Shared fields

Same multiline text shape as [text boxes](/configuration/text-boxes), with docked defaults:

| Field | Type | Notes |
|---|---|---|
| `visible` | boolean | Hidden unless `true` **and** `text` is non-empty |
| `text` | string | Plain text **or** inline HTML (see below) |
| `fontSize` | number | Points (footnote defaults smaller) |
| `id` | string | Stable: `multiline-title` / `multiline-subtitle` / `multiline-footnote` (usually leave default) |

Optional parallel fields sometimes appear in exports (`fontFamily`, `fontColor`, `backgroundColor`). Face and color are usually embedded in the HTML `text` instead. Leave `movable`, `deletable`, `width`, `height`, and percentage coords alone — runtime owns them.

***

## Text content

`text` accepts **inline HTML**, sanitized for safe tags (`font`, `b` / `i` / `u`, `br`, …).

Plain string (merge-friendly):

```js
title: { visible: true, text: 'Revenue vs Costs' }
```

Editor-style HTML (face + color):

```js
title: {
  visible: true,
  fontSize: 11,
  text: '<font face="Arial" color="#333333">Revenue vs Costs</font>',
},
subtitle: {
  visible: true,
  fontSize: 11,
  text: '<font face="Arial" style="color: #555555;">USD millions</font>',
},
footnote: {
  visible: true,
  fontSize: 6,
  text: '<font face="Arial" color="#666666">Source: Company filings. Unaudited.</font>',
},
```

Line breaks: use `<br>` inside `text`. Bold / italic: `<b>`, `<i>`, etc.

House-style / brand tools may rewrite the `<font face>` / color inside `text` when applying a font family.

***

## Title

Main headline above the plot.

```js
title: {
  visible: true,
  text: 'Revenue vs Costs',
  fontSize: 14,
}
```

Soft-delete / hide in the editor sets `title.visible = false` (does not remove the object). Showing an empty title from the UI may seed placeholder copy — prefer an explicit string in embed configs.

***

## Subtitle

Secondary line under the title (units, time range, “Indexed to 100”, …).

```js
subtitle: {
  visible: true,
  text: 'USD millions · FY2024–FY2025',
  fontSize: 11,
}
```

Starter charts often leave a placeholder subtitle in defaults. **Hide it unless intentional:**

```js
subtitle: { visible: false, text: '' }
```

***

## Footnote

Source / caveat line in the **bottom** band. Same shape as title/subtitle; smaller default type. There is no separate “auto sources” pipeline — content is whatever you put in `text`.

```js
footnote: {
  visible: true,
  text: 'Source: Company filings, FY2025. Unaudited.',
  fontSize: 6,
}
```

When a bottom legend is also on, the footnote sits below that legend in the bottom stack.

***

## Visibility cheat sheet

```js
// Show title only
title: { visible: true, text: 'Mix by quarter' },
subtitle: { visible: false, text: '' },
footnote: { visible: false, text: '' },

// Title + source line
title: { visible: true, text: 'Mix by quarter' },
subtitle: { visible: false, text: '' },
footnote: { visible: true, text: 'Source: Internal sales.' },

// Hide all furniture cleanly after a deep-merge
title: { visible: false, text: '' },
subtitle: { visible: false, text: '' },
footnote: { visible: false, text: '' },
```

`title`, `subtitle`, and `footnote` are deep-merged on partial `setChartData` / `update` — see [Defaults & merging](/concepts/defaults).

***

## Tips

* Prefer plain `text` for embed configs; use HTML when you need face/color/bold.
* Do not hand-author `leftXPercentage` / `topYPercentage` — they are overwritten on draw.
* These blocks reserve plot space (like a docked legend), so long wrapping titles shrink the plot vertically.
* For free callouts on the plot, use [text boxes](/configuration/text-boxes) (`multilines`).