Adding a Subtitle to a Pie Chart Widget – QBeeQ

Overview

By default, a Pie chart widget displays only its title. In cases where users need additional context directly on the widget, such as a note about the data range, a caveat, or a short explanation, a subtitle can be added beneath the title using a widget script.

This guide describes a script that adds custom subtitle text to a Pie chart widget and adjusts the chart's layout to make room for it.

Use Cases

Apply this script when:

A widget needs a persistent note about data scope (e.g., date range, filters applied, data freshness) that should always be visible without relying on a tooltip or dashboard description

A short clarifying line is needed beneath the widget title, styled independently from the title itself

Consistent annotation text is needed across multiple Pie chart widgets without modifying the underlying data

Prerequisites

Edit access to the widget script (Widget Options menu > Edit Script)

A Pie chart widget

Script

widget.on('processresult', function(se, ev) {
  // Subtitle
  ev.result.subtitle = {
    text: 'Data is available for the last four quarters, including the current quarter',
    align: 'center',
    style: {
      color: '#787878',
      fontSize: '13px',
      fontWeight: 'normal'
    }
  }

  ev.result.chart.marginTop = 45 // to add required space to display subtitle at the top
})

How It Works

Step	Description
Trigger	`widget.on('processresult', ...)` runs after the widget's data has been processed and is about to be rendered, allowing the chart configuration to be modified before it displays.
Add the subtitle	`ev.result.subtitle` defines the subtitle object rendered above the chart, including its text, alignment, and style (color, font size, font weight).
Reserve layout space	`ev.result.chart.marginTop` increases the top margin of the chart area so the subtitle has space to render without overlapping the chart itself.

Customization

Property	Description
`text`	The subtitle text to display. Update this to reflect the desired message.
`align`	Horizontal alignment of the subtitle text. Accepts `'left'`, `'center'`, or `'right'`.
`style.color`	Subtitle text color, specified as a hex value.
`style.fontSize`	Subtitle text size.
`style.fontWeight`	Subtitle text weight (e.g., `'normal'`, `'bold'`).
`chart.marginTop`	Top margin, in pixels, reserved for the title and subtitle combined. Increase this value if the subtitle text wraps to multiple lines or appears clipped.

Limitations and Considerations

marginTop is a fixed pixel value. If the subtitle text is long enough to wrap onto multiple lines (e.g., on narrower widget sizes), the value may need to be increased to prevent the subtitle from overlapping the chart.

This script applies to a single widget. To apply the same subtitle across multiple Pie chart widgets, the script must be added to each widget individually, or implemented as a reusable plugin if used broadly.

Subtitle text is static within the script. To display dynamic text (e.g., reflecting an active filter or selected period), the text value would need to be set conditionally based on data available in ev.result or dashboard filters.