Struct Sparkline

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

Widget to render a sparkline over one or more lines.

Each bar in a Sparkline represents a value from the provided dataset. The height of the bar is determined by the value in the dataset.

You can create a Sparkline using Sparkline::default.

The data is set using Sparkline::data. The data can be a slice of u64, Option<u64>, or a SparklineBar. For the Option<u64> and SparklineBar cases, a data point with a value of None is interpreted an as the absence of a value.

Sparkline can be styled either using Sparkline::style or preferably using the methods provided by the Stylize trait. The style may be set for the entire widget or for individual bars by setting individual SparklineBar::style.

The bars are rendered using a set of symbols. The default set is symbols::bar::NINE_LEVELS. You can change the set using Sparkline::bar_set.

If the data provided is a slice of u64 or Option<u64>, the bars will be styled with the style of the sparkline. If the data is a slice of SparklineBar, the bars will be styled with the style of the sparkline combined with the style provided in the SparklineBar if it is set, otherwise the sparkline style will be used.

Absent values and will be rendered with the style set by Sparkline::absent_value_style and the symbol set by Sparkline::absent_value_symbol.

Setter methods

• Sparkline::block wraps the sparkline in a Block
• Sparkline::data defines the dataset, you’ll almost always want to use it
• Sparkline::max sets the maximum value of bars
• Sparkline::direction sets the render direction

Examples

use ratatui::{
    style::{Color, Style, Stylize},
    symbols,
    widgets::{Block, RenderDirection, Sparkline},
};

Sparkline::default()
    .block(Block::bordered().title("Sparkline"))
    .data(&[0, 2, 3, 4, 1, 4, 10])
    .max(5)
    .direction(RenderDirection::RightToLeft)
    .style(Style::default().red().on_white())
    .absent_value_style(Style::default().fg(Color::Red))
    .absent_value_symbol(symbols::shade::FULL);

Implementations

impl<'a> Sparkline<'a>

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

Wraps the sparkline with the given block.

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

Sets the style of the entire widget.

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

The foreground corresponds to the bars while the background is everything else.

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

Sets the style to use for absent values.

Absent values are values in the dataset that are None.

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

The foreground corresponds to the bars while the background is everything else.

pub fn absent_value_symbol(self, symbol: impl Into<String>) -> Self

Sets the symbol to use for absent values.

Absent values are values in the dataset that are None.

The default is symbols::shade::EMPTY.

pub fn data<T>(self, data: T) -> Self

where T: IntoIterator, T::Item: Into<SparklineBar>,

Sets the dataset for the sparkline.

Each item in the dataset is a bar in the sparkline. The height of the bar is determined by the value in the dataset.

The data can be a slice of u64, Option<u64>, or a SparklineBar. For the Option<u64> and SparklineBar cases, a data point with a value of None is interpreted an as the absence of a value.

If the data provided is a slice of u64 or Option<u64>, the bars will be styled with the style of the sparkline. If the data is a slice of SparklineBar, the bars will be styled with the style of the sparkline combined with the style provided in the SparklineBar if it is set, otherwise the sparkline style will be used.

Absent values and will be rendered with the style set by Sparkline::absent_value_style and the symbol set by Sparkline::absent_value_symbol.

Examples

Create a Sparkline from a slice of u64:

use ratatui::{layout::Rect, widgets::Sparkline, Frame};

let sparkline = Sparkline::default().data(&[1, 2, 3]);
frame.render_widget(sparkline, area);

Create a Sparkline from a slice of Option<u64> such that some bars are absent:

let data = vec![Some(1), None, Some(3)];
let sparkline = Sparkline::default().data(data);
frame.render_widget(sparkline, area);

Create a Sparkline from a a Vec of SparklineBar such that some bars are styled:

let data = vec![
    SparklineBar::from(1).style(Some(Style::default().fg(Color::Red))),
    SparklineBar::from(2),
    SparklineBar::from(3).style(Some(Style::default().fg(Color::Blue))),
];
let sparkline = Sparkline::default().data(data);
frame.render_widget(sparkline, area);

pub const fn max(self, max: u64) -> Self

Sets the maximum value of bars.

Every bar will be scaled accordingly. If no max is given, this will be the max in the dataset.

pub const fn bar_set(self, bar_set: Set) -> Self

Sets the characters used to display the bars.

Can be symbols::bar::THREE_LEVELS, symbols::bar::NINE_LEVELS (default) or a custom Set.

pub const fn direction(self, direction: RenderDirection) -> Self

Sets the direction of the sparkline.

RenderDirection::LeftToRight by default.

Trait Implementations

impl<'a> Clone for Sparkline<'a>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for Sparkline<'a>

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

Formats the value using the given formatter.

impl<'a> Default for Sparkline<'a>

fn default() -> Sparkline<'a>

Returns the “default value” for a type.

impl<'a> PartialEq for Sparkline<'a>

fn eq(&self, other: &Sparkline<'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 Sparkline<'a>

type Item = Sparkline<'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 Sparkline<'_>

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 Sparkline<'_>

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> Eq for Sparkline<'a>

impl<'a> StructuralPartialEq for Sparkline<'a>