Struct BarChart

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

A chart showing values as bars.

Here is a possible BarChart output.

┌─────────────────────────────────┐
│                             ████│
│                        ▅▅▅▅ ████│
│            ▇▇▇▇        ████ ████│
│     ▄▄▄▄   ████ ████   ████ ████│
│▆10▆ █20█   █50█ █40█   █60█ █90█│
│ B1   B2     B1   B2     B1   B2 │
│ Group1      Group2      Group3  │
└─────────────────────────────────┘

A BarChart is composed of a set of Bar which can be set via BarChart::data. Bars can be styled globally (BarChart::bar_style) or individually (Bar::style). There are other methods available to style even more precisely. See Bar to find out about each bar component.

The BarChart widget can also show groups of bars via BarGroup. A BarGroup is a set of Bar, multiple can be added to a BarChart using BarChart::data multiple time as demonstrated in the example below.

The chart can have a Direction (by default the bars are Vertical). This is set using BarChart::direction.

Note: this is the only widget that doesn’t implement Widget for &T because the current implementation modifies the internal state of self. This will be fixed in the future.

Examples

The following example creates a BarChart with two groups of bars. The first group is added by an array slice (&[(&str, u64)]). The second group is added by a BarGroup instance.

use ratatui::{
    style::{Style, Stylize},
    widgets::{Bar, BarChart, BarGroup, Block},
};

BarChart::default()
    .block(Block::bordered().title("BarChart"))
    .bar_width(3)
    .bar_gap(1)
    .group_gap(3)
    .bar_style(Style::new().yellow().on_red())
    .value_style(Style::new().red().bold())
    .label_style(Style::new().white())
    .data(&[("B0", 0), ("B1", 2), ("B2", 4), ("B3", 3)])
    .data(BarGroup::default().bars(&[Bar::default().value(10), Bar::default().value(20)]))
    .max(4);

Implementations

impl<'a> BarChart<'a>

pub fn data(self, data: impl Into<BarGroup<'a>>) -> Self

Add group of bars to the BarChart

Examples

The following example creates a BarChart with two groups of bars. The first group is added by an array slice (&[(&str, u64)]). The second group is added by a BarGroup instance.

use ratatui::widgets::{Bar, BarChart, BarGroup};

BarChart::default()
    .data(&[("B0", 0), ("B1", 2), ("B2", 4), ("B3", 3)])
    .data(BarGroup::default().bars(&[Bar::default().value(10), Bar::default().value(20)]));

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

Surround the BarChart with a Block.

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

Set the value necessary for a Bar to reach the maximum height.

If not set, the maximum value in the data is taken as reference.

Examples

This example shows the default behavior when max is not set. The maximum value in the dataset is taken (here, 100).

use ratatui::widgets::BarChart;
BarChart::default().data(&[("foo", 1), ("bar", 2), ("baz", 100)]);
// Renders
//     █
//     █
// f b b

This example shows a custom max value. The maximum height being 2, bar & baz render as the max.

use ratatui::widgets::BarChart;

BarChart::default()
    .data(&[("foo", 1), ("bar", 2), ("baz", 100)])
    .max(2);
// Renders
//   █ █
// █ █ █
// f b b

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

Set the default style of the bar.

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

It is also possible to set individually the style of each Bar. In this case the default style will be patched by the individual style

pub const fn bar_width(self, width: u16) -> Self

Set the width of the displayed bars.

For Horizontal bars this becomes the height of the bar.

If not set, this defaults to 1. The bar label also uses this value as its width.

pub const fn bar_gap(self, gap: u16) -> Self

Set the gap between each bar.

If not set, this defaults to 1. The bar label will never be larger than the bar itself, even if the gap is sufficient.

Example

This shows two bars with a gap of 3. Notice the labels will always stay under the bar.

use ratatui::widgets::BarChart;

BarChart::default()
    .data(&[("foo", 1), ("bar", 2)])
    .bar_gap(3);
// Renders
//     █
// █   █
// f   b

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

The bar::Set to use for displaying the bars.

If not set, the default is bar::NINE_LEVELS.

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

Set the default value style of the bar.

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

It is also possible to set individually the value style of each Bar. In this case the default value style will be patched by the individual value style

See also

Bar::value_style to set the value style individually.

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

Set the default label style of the groups and bars.

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

It is also possible to set individually the label style of each Bar or BarGroup. In this case the default label style will be patched by the individual label style

See also

Bar::label to set the label style individually.

pub const fn group_gap(self, gap: u16) -> Self

Set the gap between BarGroup.

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

Set 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>).

The style will be applied to everything that isn’t styled (borders, bars, labels, …).

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

Set the direction of the bars.

Vertical bars are the default.

Examples

Vertical bars

  █
█ █
f b

Horizontal bars

█foo██

█bar██

Trait Implementations

impl<'a> Clone for BarChart<'a>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for BarChart<'a>

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

Formats the value using the given formatter.

impl<'a> Default for BarChart<'a>

fn default() -> Self

Returns the “default value” for a type.

impl<'a> Hash for BarChart<'a>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'a> PartialEq for BarChart<'a>

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

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

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

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 BarChart<'a>

impl<'a> StructuralPartialEq for BarChart<'a>