XY Chart

<XYChart> plots numeric x/y pairs as points, lines, or both. A third value can drive point size, and another can drive point colour. If you have used Grafana's XY Chart panel, every option there has a counterpart here; see Coming from Grafana.

use zopra_charts::*;

• <XYChart>
• <Series>
• Style props
• AxisConfig
• Legend
• Tooltip
• Color and Scheme
• Data
• Enums
• Coming from Grafana

Not sure which option fits? See the guide.

---

<XYChart>

Where the series come from

• With <Series> children, each child is one series.
• Without children, the series come from a Frame: the first field is x and every other field is a y series. A Vec<T> has no field names, so a chart with no children and a Vec<T> shows "No data".

The chart remembers which series you hid in the legend and which point is hovered. Give each chart a key when you render several of them in a loop, so that state stays with the right one.

<Series>

Return f64::NAN from x or y to leave a row out.

Write the row type on the first closure of each tag. The other closures on that tag pick it up:

<Series x={|r: &Reading| r.temperature} y={|r| r.load} />

Style props

<XYChart> and <Series> both take these props. A value on the series wins over the chart's value, and the chart's value wins over the default.

Point size grows by area: a value twice as large gets a point with twice the area, not twice the diameter. The smallest and largest size values across all series map to the two ends of size_range.

AxisConfig

AxisConfig::new()
    .label("Load")
    .placement(AxisPlacement::Right)
    .soft_min(0.)
    .scale(ScaleKind::Log { base: 10. })

The axis range starts at the data's extent, rounded out to tidy tick values (whole powers for a log scale).

• soft_min / soft_max widen the range when the data doesn't reach them, but never narrow it.
• centered_zero makes the range symmetric around 0.
• min / max pin the range exactly, and data outside it is cut off.

A log scale ignores zero and negative values. With no data the range is 0 to 1.

The label, when you don't set one, is the field name if every series shares it, or the words common to the start and end of the field names. Only Frame data has field names.

Tick and tooltip text uses format if you set it. Otherwise it uses decimals. Otherwise the decimals are chosen from the tick spacing. format takes a closure that doesn't capture anything; end it with .into():

AxisConfig::new().format(|v| format!("{v:.0} °C").into())

Legend

Legend::table().right().width(px(240.)).calcs([Calc::Mean, Calc::Max]).sort_by(LegendSort::Calc(Calc::Mean)).sort_desc(true)

Clicking a legend item shows only that series; click it again to show them all. Ctrl-click (Cmd-click on macOS) shows or hides a single series. Hidden series stay in the legend, dimmed. The axes rescale to the series still shown, while colours and point sizes stay the same.

Calcs

Calcs summarise each series' y values, skipping NaN. They always appear in this order, whatever order you list them in:

Tooltip

The same Tooltip type is shared with <Trend>, which also uses Tooltip::multi(), sort and hide_zeros. The XY Chart shows multi() like single(), as Grafana's XY Chart does.

Hovering a point highlights it and shows a tooltip next to it. The tooltip has:

• the series name and the point's colour;
• the x and y values, each labelled with its field name or axis label;
• the size and colour values, when the series has them.

Series with hide_from.tooltip are still highlighted on hover, but show no tooltip. Points from series drawn only as lines can't be hovered.

Color and Scheme

color={rgb(0x89b4fa)}
color={Color::by(|r: &Reading| r.memory, Scheme::GreenYellowRed)}
color={Color::by(|r: &Reading| r.load, Scheme::thresholds(vec![(0., green), (80., red)]))}

gradient and thresholds take a Vec or a &'static slice. Prefer a static slice: it costs nothing to rebuild on every render. See Static colour lists.

A gradient spans the smallest to the largest colour value across all series that colour by value, so equal values look the same in every series. Points with a NaN colour value use the theme's fallback colour.

Data

Which data type

See Pass data as a signal.

Frame<N>

A table with N named numeric fields, one row per [f64; N].

Without <Series>, the size and colour fields aren't drawn as series of their own. Words shared by every series name are trimmed: cpu load host-a and cpu load host-b become host-a and host-b, and the y axis is labelled cpu load.

With <Series>, read fields by position (x={|r: &[f64; 3]| r[1]}) or by name (x={frame.get("Requests")}).

Your own data source

Implement Dataset<T> to chart data stored some other way:

pub trait Dataset<T>: 'static {
    fn rows<'a>(&'a self, cx: &'a App) -> &'a [T];
    fn revision(&self, cx: &App) -> Option<Revision> { None }
    fn schema<'a>(&'a self, cx: &'a App) -> Option<Schema<'a, T>> { None }
}

pub struct Schema<'a, T> {
    pub names: &'a [SharedString],
    pub read: fn(&T, usize) -> f64,
    pub size: Option<usize>,
    pub color: Option<(usize, &'a Scheme)>,
}

Enums

Dot draws small square dots along the line.

Coming from Grafana

Not available here: several data frames in one chart (combine your rows first), separate y axes per unit, value mappings, data links, the tooltip's sort and hide-zeros options, and ordinal axes. fill_opacity goes from 0.0 to 1.0 rather than 0 to 100.