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.

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

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, 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):

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

Editor-style HTML (face + color):

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.

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”, …).

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

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

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.

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

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

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 (multilines).

Title, subtitle & footnote ​

Where each sits ​

Shared fields ​

Text content ​

Title ​

Subtitle ​

Footnote ​

Visibility cheat sheet ​

Tips ​