Skip to content

Visualisations ​

Press can embed charts and visualisations directly in documents. Visualisations blend seamlessly into the layout and can be driven by data.

Donut and Pie Charts ​

The <x-donut> element renders donut or pie charts:

xml
<x-donut width="150pt" height="150pt" stroke="14pt">
  <data>
    <item color="#1e3a5f" value="45" />
    <item color="#2563eb" value="30" />
    <item color="#93c5fd" value="25" />
  </data>
</x-donut>

Attributes ​

AttributeDescription
widthChart width
heightChart height
strokeRing thickness (larger values = thicker ring, 0 = pie chart)

Data Items ​

Each <item> in the <data> block takes:

AttributeDescription
colorSegment colour
valueNumeric value (proportional sizing)

Data limit ​

Use limit and limit-color to set the upper limit of data. For instance, we may want to set maximum progress to 100. The following will render all items, and then fill the rest of the chart up to the 100 value limit with the limit-color:

xml
<x-donut width="150pt" height="150pt" stroke="16pt">
  <data limit="100" limit-color="#d1d5db">
    <item color="#1e3a5f" value="45" />
    <item color="#2563eb" value="30" />
    <item color="#059669" value="12" />
  </data>
</x-donut>

Donut Chart with Legend ​

A common pattern -- pair the chart with a legend table:

xml
<frame direction="row" h-align="center" v-align="center"
       space-before-desired="12pt" space-after-desired="12pt">
  <x-donut height="128pt" stroke="12pt">
    <data>
      <item color="#1e3a5f" value="55" />
      <item color="#2563eb" value="30" />
      <item color="#93c5fd" value="15" />
    </data>
  </x-donut>
  <frame width="8pt" />
  <table style="@borderless">
    <tr>
      <td><frame background-color="#1e3a5f" border-radius="2pt"
                  width="24pt" height="12pt" /></td>
      <td>Completed (55%)</td>
    </tr>
    <tr>
      <td><frame background-color="#2563eb" border-radius="2pt"
                  width="24pt" height="12pt" /></td>
      <td>In Progress (30%)</td>
    </tr>
    <tr>
      <td><frame background-color="#93c5fd" border-radius="2pt"
                  width="24pt" height="12pt" /></td>
      <td>Planned (15%)</td>
    </tr>
  </table>
</frame>
xml
<styles>
  <alias name="borderless">
    <child name="td">
      <border-weight>0</border-weight>
      <padding>4pt</padding>
    </child>
  </alias>
</styles>

The <visualization> Element ​

INFO

Visualizations are a Pro feature

For data-driven charts, use <visualization> with a data binding:

xml
<visualization data="data.chart" width="100%" height="300pt">
  <config>
    <colors>
      <color>#1e3a5f</color>
      <color>#2563eb</color>
      <color>#059669</color>
    </colors>
  </config>
  <line-plot />
</visualization>

The data attribute points to chart data defined in <data>.

CSV Data Source ​

Chart data can be provided as CSV using <data type="csv">:

xml
<data type="csv" name="chart">
  Month,Revenue,Expenses,Profit
  Jan,4200,3100,1100
  Feb,4800,3400,1400
  Mar,5100,3200,1900
  Apr,4900,3600,1300
  May,5500,3300,2200
  Jun,5800,3500,2300
</data>
xml
<visualization data="data.chart" width="100%" height="300pt">
  <config>
    <colors>
      <color>#1e3a5f</color>
      <color>#2563eb</color>
      <color>#059669</color>
    </colors>
  </config>
  <line-plot />
</visualization>

Line Plots ​

The <line-plot> element renders line graphs:

xml
<line-plot data="data['time-series']" width="100%" height="250pt" />

Attributes ​

AttributeDescriptionExample
heightChart height (required)"7cm"
widthChart width"100%"
dataOverride data path (default: data.visualization)"data.chart"
fillFill mode: "false", "true", or "fade""fade"
fill-startTop opacity of a fill="fade" gradient, 0–1"0.5"
fill-endBottom opacity of a fill="fade" gradient, 0–1"0"
y-labelY-axis title"Revenue"
x-labelX-axis title"Quarter"
x-scale"linear" places each point at its numeric x; the default "category" spaces x values evenly"linear"
x-min / x-maxExact x-axis range on a "linear" x axis; lines beyond are cut off at the axis"100"
curve"straight" joins each point to the next with a straight line; the default "smooth" rounds it"straight"
y-minExact minimum for y-axis; values below are cut off at the axis"0"
y-maxExact maximum for y-axis; values above are cut off at the axis"500000"
y-dpDecimal places for y-axis tick labels"2"
y-prefixPrefix prepended to y-axis tick labels"£"
y-suffixSuffix appended to y-axis tick labels"%"
y-separatorAdd thousand separators to y-axis tick labels"true"
y-axisDraw the y-axis: line, ticks, tick labels, title"false"
y-ticksDraw the y-axis tick marks"false"
y-tick-labelsDraw the y-axis tick label text"false"
y-lineDraw the y-axis line"false"
y-gridDraw the gridlines cast by the y-axis"false"
x-axisX-axis counterpart of y-axis (and x-ticks, x-tick-labels, x-line, x-grid)"false"
show-gridDraw the background grid on both axes"false"

With y-min or y-max set, Papermill keeps that end of the axis exactly where it is and cuts off any value beyond it at the plot edge. With only one end set, the other rounds outward from the data to a tick. Set a limit to null, or bind it to a value that is null, to leave that end automatic.

Legacy aliases

label-y and label-x are accepted as aliases for y-label and x-label.

Drawing straight lines between points ​

Set curve="straight" on a chart of exact figures to join each point to the next with a straight line. The default, "smooth", rounds the line through its points and can carry it slightly past a value.

xml
<line-plot height="7cm" width="100%" curve="straight" y-label="Funding" x-label="Year" />

Filled areas, stacked series, forecasts and dashed lines all follow the same setting. On any other value, Papermill rejects the document with message <line-plot> curve must be "smooth" or "straight", got "wavy". Papermill also rejects curve written on a <bar-plot> or <donut-plot>, with a message naming the attribute to remove.

Placing points at numeric x values ​

When x is a quantity such as a distance or a duration, set x-scale="linear". Each point then sits at its own x value, however unevenly the points are spaced, and the axis is labelled with round values set horizontally, without thousands separators so a year reads 2021. Every x in the data, and every marker's x, must be a number: a numeric string such as "9.8" in a series payload.

xml
<line-plot height="180pt" width="100%" x-scale="linear" x-min="0" x-max="100"
  x-label="Distance (km)" x-grid="true" x-ticks="true" />

x-min and x-max fix the ends exactly; leave one unset, or set it to null, to round that end out from the data. A marker can sit at any x, between points as well as on them. The y-axis still fits every point, including those beyond x-min / x-max; set y-min / y-max to fit it to the visible range. Each series joins across x values where it has no point, and across an empty or null y too, where a category axis would leave a gap; to break a line, split the series in two. stacked="true" needs the default category axis.

Hiding axes and the grid ​

Every visibility attribute takes true, false, or auto. auto is the default: the per-part switches follow y-axis / x-axis, and the two grid switches follow show-grid. The x-axis is the exception — it draws neither gridlines nor tick marks unless you ask for them with x-ticks="true" or x-grid="true". Any other value is rejected.

Each switch covers one axis. Hiding an axis gives its space back to the plot and leaves the gridlines drawn, so y-axis="false" keeps both the gridlines and the x-axis below:

xml
<!-- Gridlines and the x-axis, no y-axis furniture — the plot takes the reclaimed width -->
<line-plot height="4cm" width="100%" y-axis="false" />

<!-- Completely bare: both axes and the grid -->
<line-plot height="4cm" width="100%" y-axis="false" x-axis="false" show-grid="false" />

<!-- Keep the axis, drop just its tick labels -->
<line-plot height="4cm" width="100%" y-label="Revenue" y-tick-labels="false" />

Gridlines are drawn from the y-axis and not from the x-axis by default. show-grid="true" turns both on, which is how you add vertical gridlines.

Axis Formatting ​

Format y-axis tick labels with currency symbols, percentage signs, decimal places, and thousand separators:

xml
<!-- Currency: £0, £100,000, £200,000 ... -->
<line-plot height="7cm" width="100%"
  y-label="Price" y-min="0" y-max="500000"
  y-dp="0" y-prefix="£" y-separator="true" fill="fade" />

<!-- Percentage: 5.0%, 5.5%, 6.0% ... -->
<line-plot height="4cm" width="100%"
  y-label="Yield" y-dp="1" y-suffix="%" />

Tuning the fade fill ​

When fill="fade" is set, <line-plot> renders a vertical gradient under each series. The top of the gradient sits at the series' peak value and fades out towards the x-axis.

Use fill-start and fill-end to override the gradient endpoints. Both accept a number in the range 0–1, where 0 is fully transparent and 1 is fully opaque:

xml
<!-- Stronger top, fully transparent bottom -->
<line-plot height="7cm" width="100%"
  fill="fade" fill-start="0.6" fill-end="0" />

<!-- Flat tinted fill: same opacity top and bottom -->
<line-plot height="7cm" width="100%"
  fill="fade" fill-start="0.2" fill-end="0.2" />

Both attributes are ignored unless fill="fade" is also set, and both default to values that reproduce the historical fade gradient shape when omitted.

Legends ​

Generate a legend by iterating over visualisation groups:

xml
<visualization data="data.chart" width="100%">
  <config>
    <colors>
      <color>#1e3a5f</color>
      <color>#2563eb</color>
      <color>#059669</color>
    </colors>
  </config>
  <line-plot height="300pt" />
  <legend direction="row">
    <repeat data="visualization.groups" item="group">
      <frame direction="row" padding-right="16pt">
        <frame width="12pt" height="12pt" background-color="{{ group.color }}" border-radius="2pt" />
        <frame padding-left="4pt" font-size="8pt">{{ group.name }}</frame>
      </frame>
    </repeat>
  </legend>
</visualization>
xml
<data type="csv" name="chart">
  Month,Revenue,Expenses,Profit
  Jan,4200,3100,1100
  Feb,4800,3400,1400
  Mar,5100,3200,1900
  Apr,4900,3600,1300
  May,5500,3300,2200
  Jun,5800,3500,2300
</data>