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:

<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

Attribute	Description
width	Chart width
height	Chart height
stroke	Ring thickness (larger values = thicker ring, 0 = pie chart)

Data Items

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

Attribute	Description
color	Segment colour
value	Numeric 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:

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

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

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

<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">:

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

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

<line-plot data="data.time-series" width="100%" height="250pt" />

Attributes

Attribute	Description	Example
height	Chart height (required)	"7cm"
width	Chart width	"100%"
data	Override data path (default: data.visualization)	"data.chart"
fill	Fill mode: "false", "true", or "fade"	"fade"
fill-start	Top opacity of a fill="fade" gradient, 0–1	"0.5"
fill-end	Bottom opacity of a fill="fade" gradient, 0–1	"0"
y-label	Y-axis title	"Revenue"
x-label	X-axis title	"Quarter"
y-min	Hard minimum for y-axis (overrides auto-scaling)	"0"
y-max	Hard maximum for y-axis	"500000"
y-dp	Decimal places for y-axis tick labels	"2"
y-prefix	Prefix prepended to y-axis tick labels	"£"
y-suffix	Suffix appended to y-axis tick labels	"%"
y-separator	Add thousand separators to y-axis tick labels	"true"
y-axis	Draw the y-axis: line, ticks, tick labels, title	"false"
y-ticks	Draw the y-axis tick marks	"false"
y-tick-labels	Draw the y-axis tick label text	"false"
y-line	Draw the y-axis line	"false"
y-grid	Draw the gridlines cast by the y-axis	"false"
x-axis	X-axis counterpart of y-axis (and x-ticks, x-tick-labels, x-line, x-grid)	"false"
show-grid	Draw the background grid on both axes	"false"

Legacy aliases

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

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:

<!-- 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:

<!-- 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:

<!-- 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:

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

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