Series

A series is a named set of values with its own identity, renderer and display settings. The chart starts with a main bar series. You can add other bar series and studies without recreating the chart. Your application supplies history and streaming data; the library stores, aligns and draws it.

Data

Every bar series stores Bar values keyed by UTC open time. Use Bar::new for OHLCV, Bar::from_value for a scalar, and Bar::whitespace for an empty time slot. Missing points and zero values mean different things. See data shapes and the input table.

Keep history oldest first with one bar per open time. set_data sorts and deduplicates, retaining the last duplicate; update merges by open time, including older corrections. On a chart built with a feed, these operations match bars to the feed interval’s slots. Invalid ordinary bars are dropped and counted in Chart::feed_state. For asynchronous loading and streaming, implement the datafeed contract.

Renderer

Chart::set_chart_type chooses the main renderer. Added bar series choose their renderer through SeriesOptions::chart_type. The chart types page classifies every main type and lists the restrictions on added series.

Try the candles and bars, line, area, baseline, histogram and transform examples.

Style

For the main series, edit a copy of Chart::chart_type_params and apply it with set_chart_type_params. ChartTypeStyles keeps independent styles for line, area, baseline, candles and bars across renderer changes. Main candle colours and dimensions live in Chart::config_mut. Apply the theme before overriding its configuration colours.

For an added series, retain its SeriesOptions and replace them with Chart::set_series_options. These have a smaller style surface than the main series: colours, line width, baseline style, column base and scale assignment. Bar::colors overrides supported colours for one point.

SeriesStyle controls last-value labels, price lines, base lines and autoscale participation. Use Chart::series_style_mut with a series id. Scale and pane placement are separate: see SeriesScale, Chart::set_series_scale and Chart::move_series_to_pane.

Identity

SeriesId::MAIN addresses the initial main series. Retain the SeriesId returned by add_series; a title, symbol or vector position is not its identity. Changing data or options keeps that id. Studies also have series ids, but their values are computed: set_data and update accept bar-series ids only. See studies for their lifecycle.

Lifecycle

Create the chart once and call show on each frame. This running scene adds a reference line, sets its history, then replaces its last value at the same timestamp. It reuses the 120 deterministic OHLC bars from your first chart.

Candles with a host-fed reference lineOpen full size

Pan and inspect both series. The reference line has its own data and id.

The interactive example needs JavaScript and WebAssembly. You can still use the chart setup alongside it.

series.rs

use egui_charts::Chart;

pub fn lifecycle() -> Chart {
    use eframe::egui::Color32;
    use egui_charts::{
        model::Bar,
        widget::{SeriesId, SeriesOptions},
    };
    let mut chart = crate::first_chart::first_chart();
    let bars = chart.bars(SeriesId::MAIN).to_vec();
    let id = chart.add_series(SeriesOptions {
        name: "Reference".into(),
        color: Color32::from_rgb(156, 97, 229),
        ..Default::default()
    });
    chart.set_data(
        id,
        bars.iter()
            .map(|bar| Bar::from_value(bar.time, bar.close + 1.0))
            .collect(),
    );
    let last = bars.last().unwrap();
    chart.update(id, Bar::from_value(last.time, last.close + 1.5));
    chart
}

The setup is compiled from series.rs. Each operation has a separate purpose:

Operation	Behaviour
add_series(options)	Creates an empty host-fed bar series and returns its id.
set_data(id, bars)	Replaces that series’ complete history.
update(id, bar)	Replaces a matching bar, appends a newer bar or inserts an older correction.
set_series_options(id, options)	Replaces an added bar series’ display settings without replacing its data.
set_series_visible(id, visible)	Hides or shows a series without unloading it. Hidden series do not contribute to autoscale.
remove_series(id)	Removes the series; returns false if the id is absent. Stop feeding the removed id.

For example, after receiving the id in the scene above:

let mut options = chart.series()
    .find(|(current, _)| *current == id).unwrap().1.clone();
options.width = 3.0;
assert!(chart.set_series_options(id, options));
assert!(chart.set_series_visible(id, false));
assert!(chart.set_series_visible(id, true));
assert!(chart.remove_series(id));
assert!(!chart.remove_series(id));

Use Chart::bars to inspect retained data and Chart::drain_events for ChartEvent notifications such as SeriesAdded, DataUpdated and SeriesRemoved. Removing MAIN pauses its feed and retains the time axis for the remaining series and drawings. Use set_main_series_visible(false) to hide it while keeping its data and feed active, so it can be shown again.

add_series does not start a feed. A chart already connected to your datafeed can use Chart::add_feed_series to request the symbol in SeriesOptions::name. Your host still supplies the history and stream. Without a connected feed, it behaves as a plain host-fed series.