Struct Chart

pub struct Chart<'a> { /* private fields */ }

A widget to plot one or more Dataset in a cartesian coordinate system

To use this widget, start by creating one or more Dataset. With it, you can set the data points, the name or the chart type. See Dataset for a complete documentation of what is possible.

Then, you’ll usually want to configure the Axis. Axis titles, bounds and labels can be configured on both axis. See Axis for a complete documentation of what is possible.

Finally, you can pass all of that to the Chart via Chart::new, Chart::x_axis and Chart::y_axis.

Additionally, Chart allows configuring the legend position and hiding constraints.

Examples

use ratatui::{
    style::{Style, Stylize},
    symbols,
    widgets::{Axis, Block, Chart, Dataset, GraphType},
};

// Create the datasets to fill the chart with
let datasets = vec![
    // Scatter chart
    Dataset::default()
        .name("data1")
        .marker(symbols::Marker::Dot)
        .graph_type(GraphType::Scatter)
        .style(Style::default().cyan())
        .data(&[(0.0, 5.0), (1.0, 6.0), (1.5, 6.434)]),
    // Line chart
    Dataset::default()
        .name("data2")
        .marker(symbols::Marker::Braille)
        .graph_type(GraphType::Line)
        .style(Style::default().magenta())
        .data(&[(4.0, 5.0), (5.0, 8.0), (7.66, 13.5)]),
];

// Create the X axis and define its properties
let x_axis = Axis::default()
    .title("X Axis".red())
    .style(Style::default().white())
    .bounds([0.0, 10.0])
    .labels(["0.0", "5.0", "10.0"]);

// Create the Y axis and define its properties
let y_axis = Axis::default()
    .title("Y Axis".red())
    .style(Style::default().white())
    .bounds([0.0, 10.0])
    .labels(["0.0", "5.0", "10.0"]);

// Create the chart and link all the parts together
let chart = Chart::new(datasets)
    .block(Block::new().title("Chart"))
    .x_axis(x_axis)
    .y_axis(y_axis);

Implementations

impl<'a> Chart<'a>

pub fn new(datasets: Vec<Dataset<'a>>) -> Self

Creates a chart with the given datasets

A chart can render multiple datasets.

Example

This creates a simple chart with one Dataset

use ratatui::widgets::{Chart, Dataset};

let data_points = vec![];
let chart = Chart::new(vec![Dataset::default().data(&data_points)]);

This creates a chart with multiple Datasets

use ratatui::widgets::{Chart, Dataset};

let data_points = vec![];
let data_points2 = vec![];
let chart = Chart::new(vec![
    Dataset::default().data(&data_points),
    Dataset::default().data(&data_points2),
]);

pub fn block(self, block: Block<'a>) -> Self

Wraps the chart with the given Block

This is a fluent setter method which must be chained or used as it consumes self

pub fn style<S: Into<Style>>(self, style: S) -> Self

Sets the style of the entire chart

style accepts any type that is convertible to Style (e.g. Style, Color, or your own type that implements Into<Style>).

Styles of Axis and Dataset will have priority over this style.

This is a fluent setter method which must be chained or used as it consumes self

pub fn x_axis(self, axis: Axis<'a>) -> Self

Sets the X Axis

The default is an empty Axis, i.e. only a line.

This is a fluent setter method which must be chained or used as it consumes self

Example

use ratatui::widgets::{Axis, Chart};

let chart = Chart::new(vec![]).x_axis(
    Axis::default()
        .title("X Axis")
        .bounds([0.0, 20.0])
        .labels(["0", "20"]),
);

pub fn y_axis(self, axis: Axis<'a>) -> Self

Sets the Y Axis

The default is an empty Axis, i.e. only a line.

This is a fluent setter method which must be chained or used as it consumes self

Example

use ratatui::widgets::{Axis, Chart};

let chart = Chart::new(vec![]).y_axis(
    Axis::default()
        .title("Y Axis")
        .bounds([0.0, 20.0])
        .labels(["0", "20"]),
);

pub const fn hidden_legend_constraints( self, constraints: (Constraint, Constraint), ) -> Self

Sets the constraints used to determine whether the legend should be shown or not.

The tuple’s first constraint is used for the width and the second for the height. If the legend takes more space than what is allowed by any constraint, the legend is hidden. Constraint::Min is an exception and will always show the legend.

If this is not set, the default behavior is to hide the legend if it is greater than 25% of the chart, either horizontally or vertically.

This is a fluent setter method which must be chained or used as it consumes self

Examples

Hide the legend when either its width is greater than 33% of the total widget width or if its height is greater than 25% of the total widget height.

use ratatui::{layout::Constraint, widgets::Chart};

let constraints = (Constraint::Ratio(1, 3), Constraint::Ratio(1, 4));
let chart = Chart::new(vec![]).hidden_legend_constraints(constraints);

Always show the legend, note the second constraint doesn’t matter in this case since the first one is always true.

use ratatui::{layout::Constraint, widgets::Chart};

let constraints = (Constraint::Min(0), Constraint::Ratio(1, 4));
let chart = Chart::new(vec![]).hidden_legend_constraints(constraints);

Always hide the legend. Note this can be accomplished more explicitly by passing None to Chart::legend_position.

use ratatui::{layout::Constraint, widgets::Chart};

let constraints = (Constraint::Length(0), Constraint::Ratio(1, 4));
let chart = Chart::new(vec![]).hidden_legend_constraints(constraints);

pub const fn legend_position(self, position: Option<LegendPosition>) -> Self

Sets the position of a legend or hide it

The default is LegendPosition::TopRight.

If None is given, hide the legend even if hidden_legend_constraints determines it should be shown. In contrast, if Some(...) is given, hidden_legend_constraints might still decide whether to show the legend or not.

See LegendPosition for all available positions.

This is a fluent setter method which must be chained or used as it consumes self

Examples

Show the legend on the top left corner.

use ratatui::widgets::{Chart, LegendPosition};

let chart: Chart = Chart::new(vec![]).legend_position(Some(LegendPosition::TopLeft));

Hide the legend altogether

use ratatui::widgets::{Chart, LegendPosition};

let chart = Chart::new(vec![]).legend_position(None);

Trait Implementations

impl<'a> Clone for Chart<'a>

fn clone(&self) -> Chart<'a>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for Chart<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> Default for Chart<'a>

fn default() -> Chart<'a>

Returns the “default value” for a type.

impl<'a> PartialEq for Chart<'a>

fn eq(&self, other: &Chart<'a>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a> Styled for Chart<'a>

type Item = Chart<'a>

fn style(&self) -> Style

Returns the style of the object.

fn set_style<S: Into<Style>>(self, style: S) -> Self::Item

Sets the style of the object.

impl Widget for Chart<'_>

fn render(self, area: Rect, buf: &mut Buffer)

Draws the current state of the widget in the given buffer. That is the only method required to implement a custom widget.

impl WidgetRef for Chart<'_>

fn render_ref(&self, area: Rect, buf: &mut Buffer)

Draws the current state of the widget in the given buffer. That is the only method required to implement a custom widget.

impl<'a> StructuralPartialEq for Chart<'a>