Struct LineGauge

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

A compact widget to display a progress bar over a single thin line.

This can be useful to indicate the progression of a task, like a download.

A LineGauge renders a thin line filled according to the value given to LineGauge::ratio. Unlike Gauge, only the width can be defined by the rendering Rect. The height is always 1.

The associated label is always left-aligned. If not set with LineGauge::label, the label is the percentage of the bar filled.

You can also set the symbols used to draw the bar with LineGauge::line_set.

To style the gauge line use LineGauge::filled_style and LineGauge::unfilled_style which let you pick a color for foreground (i.e. line) and background of the filled and unfilled part of gauge respectively.

Examples:

use ratatui::{
    style::{Style, Stylize},
    symbols,
    widgets::{Block, LineGauge},
};

LineGauge::default()
    .block(Block::bordered().title("Progress"))
    .filled_style(Style::new().white().on_black().bold())
    .line_set(symbols::line::THICK)
    .ratio(0.4);

See also

• Gauge for bigger, higher precision and more configurable progress bar

Implementations

impl<'a> LineGauge<'a>

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

Surrounds the LineGauge with a Block.

Examples found in repository

examples/line_gauge.rs (line 134)

    fn render_gauge1(&self, area: Rect, buf: &mut Buffer) {
        let title = title_block("Blue / red only foreground");
        LineGauge::default()
            .block(title)
            .filled_style(Style::default().fg(Color::Blue))
            .unfilled_style(Style::default().fg(Color::Red))
            .label("Foreground:")
            .ratio(self.progress)
            .render(area, buf);
    }

    fn render_gauge2(&self, area: Rect, buf: &mut Buffer) {
        let title = title_block("Blue / red only background");
        LineGauge::default()
            .block(title)
            .filled_style(Style::default().fg(Color::Blue).bg(Color::Blue))
            .unfilled_style(Style::default().fg(Color::Red).bg(Color::Red))
            .label("Background:")
            .ratio(self.progress)
            .render(area, buf);
    }

    fn render_gauge3(&self, area: Rect, buf: &mut Buffer) {
        let title = title_block("Fully styled with background");
        LineGauge::default()
            .block(title)
            .filled_style(
                Style::default()
                    .fg(tailwind::BLUE.c400)
                    .bg(tailwind::BLUE.c600),
            )
            .unfilled_style(
                Style::default()
                    .fg(tailwind::RED.c400)
                    .bg(tailwind::RED.c800),
            )
            .label("Both:")
            .ratio(self.progress)
            .render(area, buf);
    }

pub fn ratio(self, ratio: f64) -> Self

Sets the bar progression from a ratio (float).

ratio is the ratio between filled bar over empty bar (i.e. 3/4 completion is 0.75). This is more easily seen as a floating point percentage (e.g. 42% = 0.42).

Panics

This method panics if ratio is not between 0 and 1 inclusively.

Examples found in repository

examples/line_gauge.rs (line 138)

    fn render_gauge1(&self, area: Rect, buf: &mut Buffer) {
        let title = title_block("Blue / red only foreground");
        LineGauge::default()
            .block(title)
            .filled_style(Style::default().fg(Color::Blue))
            .unfilled_style(Style::default().fg(Color::Red))
            .label("Foreground:")
            .ratio(self.progress)
            .render(area, buf);
    }

    fn render_gauge2(&self, area: Rect, buf: &mut Buffer) {
        let title = title_block("Blue / red only background");
        LineGauge::default()
            .block(title)
            .filled_style(Style::default().fg(Color::Blue).bg(Color::Blue))
            .unfilled_style(Style::default().fg(Color::Red).bg(Color::Red))
            .label("Background:")
            .ratio(self.progress)
            .render(area, buf);
    }

    fn render_gauge3(&self, area: Rect, buf: &mut Buffer) {
        let title = title_block("Fully styled with background");
        LineGauge::default()
            .block(title)
            .filled_style(
                Style::default()
                    .fg(tailwind::BLUE.c400)
                    .bg(tailwind::BLUE.c600),
            )
            .unfilled_style(
                Style::default()
                    .fg(tailwind::RED.c400)
                    .bg(tailwind::RED.c800),
            )
            .label("Both:")
            .ratio(self.progress)
            .render(area, buf);
    }

examples/demo2/tabs/weather.rs (line 157)

fn render_line_gauge(percent: f64, area: Rect, buf: &mut Buffer) {
    // cycle color hue based on the percent for a neat effect yellow -> red
    let hue = 90.0 - (percent as f32 * 0.6);
    let value = Okhsv::max_value();
    let filled_color = color_from_oklab(hue, Okhsv::max_saturation(), value);
    let unfilled_color = color_from_oklab(hue, Okhsv::max_saturation(), value * 0.5);
    let label = if percent < 100.0 {
        format!("Downloading: {percent}%")
    } else {
        "Download Complete!".into()
    };
    LineGauge::default()
        .ratio(percent / 100.0)
        .label(label)
        .style(Style::new().light_blue())
        .filled_style(Style::new().fg(filled_color))
        .unfilled_style(Style::new().fg(unfilled_color))
        .line_set(symbols::line::THICK)
        .render(area, buf);
}

examples/inline.rs (line 248)

fn draw(frame: &mut Frame, downloads: &Downloads) {
    let area = frame.area();

    let block = Block::new().title(Line::from("Progress").centered());
    frame.render_widget(block, area);

    let vertical = Layout::vertical([Constraint::Length(2), Constraint::Length(4)]).margin(1);
    let horizontal = Layout::horizontal([Constraint::Percentage(20), Constraint::Percentage(80)]);
    let [progress_area, main] = vertical.areas(area);
    let [list_area, gauge_area] = horizontal.areas(main);

    // total progress
    let done = NUM_DOWNLOADS - downloads.pending.len() - downloads.in_progress.len();
    #[allow(clippy::cast_precision_loss)]
    let progress = LineGauge::default()
        .filled_style(Style::default().fg(Color::Blue))
        .label(format!("{done}/{NUM_DOWNLOADS}"))
        .ratio(done as f64 / NUM_DOWNLOADS as f64);
    frame.render_widget(progress, progress_area);

    // in progress downloads
    let items: Vec<ListItem> = downloads
        .in_progress
        .values()
        .map(|download| {
            ListItem::new(Line::from(vec![
                Span::raw(symbols::DOT),
                Span::styled(
                    format!(" download {:>2}", download.id),
                    Style::default()
                        .fg(Color::LightGreen)
                        .add_modifier(Modifier::BOLD),
                ),
                Span::raw(format!(
                    " ({}ms)",
                    download.started_at.elapsed().as_millis()
                )),
            ]))
        })
        .collect();
    let list = List::new(items);
    frame.render_widget(list, list_area);

    #[allow(clippy::cast_possible_truncation)]
    for (i, (_, download)) in downloads.in_progress.iter().enumerate() {
        let gauge = Gauge::default()
            .gauge_style(Style::default().fg(Color::Yellow))
            .ratio(download.progress / 100.0);
        if gauge_area.top().saturating_add(i as u16) > area.bottom() {
            continue;
        }
        frame.render_widget(
            gauge,
            Rect {
                x: gauge_area.left(),
                y: gauge_area.top().saturating_add(i as u16),
                width: gauge_area.width,
                height: 1,
            },
        );
    }
}

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

Sets the characters to use for the line.

See also

See symbols::line::Set for more information. Predefined sets are also available, see NORMAL, DOUBLE and THICK.

Examples found in repository

examples/demo2/tabs/weather.rs (line 162)

fn render_line_gauge(percent: f64, area: Rect, buf: &mut Buffer) {
    // cycle color hue based on the percent for a neat effect yellow -> red
    let hue = 90.0 - (percent as f32 * 0.6);
    let value = Okhsv::max_value();
    let filled_color = color_from_oklab(hue, Okhsv::max_saturation(), value);
    let unfilled_color = color_from_oklab(hue, Okhsv::max_saturation(), value * 0.5);
    let label = if percent < 100.0 {
        format!("Downloading: {percent}%")
    } else {
        "Download Complete!".into()
    };
    LineGauge::default()
        .ratio(percent / 100.0)
        .label(label)
        .style(Style::new().light_blue())
        .filled_style(Style::new().fg(filled_color))
        .unfilled_style(Style::new().fg(unfilled_color))
        .line_set(symbols::line::THICK)
        .render(area, buf);
}

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

where T: Into<Line<'a>>,

Sets the label to display.

With LineGauge, labels are only on the left, see Gauge for a centered label. If the label is not defined, it is the percentage filled.

Examples found in repository

examples/line_gauge.rs (line 137)

    fn render_gauge1(&self, area: Rect, buf: &mut Buffer) {
        let title = title_block("Blue / red only foreground");
        LineGauge::default()
            .block(title)
            .filled_style(Style::default().fg(Color::Blue))
            .unfilled_style(Style::default().fg(Color::Red))
            .label("Foreground:")
            .ratio(self.progress)
            .render(area, buf);
    }

    fn render_gauge2(&self, area: Rect, buf: &mut Buffer) {
        let title = title_block("Blue / red only background");
        LineGauge::default()
            .block(title)
            .filled_style(Style::default().fg(Color::Blue).bg(Color::Blue))
            .unfilled_style(Style::default().fg(Color::Red).bg(Color::Red))
            .label("Background:")
            .ratio(self.progress)
            .render(area, buf);
    }

    fn render_gauge3(&self, area: Rect, buf: &mut Buffer) {
        let title = title_block("Fully styled with background");
        LineGauge::default()
            .block(title)
            .filled_style(
                Style::default()
                    .fg(tailwind::BLUE.c400)
                    .bg(tailwind::BLUE.c600),
            )
            .unfilled_style(
                Style::default()
                    .fg(tailwind::RED.c400)
                    .bg(tailwind::RED.c800),
            )
            .label("Both:")
            .ratio(self.progress)
            .render(area, buf);
    }

examples/demo2/tabs/weather.rs (line 158)

fn render_line_gauge(percent: f64, area: Rect, buf: &mut Buffer) {
    // cycle color hue based on the percent for a neat effect yellow -> red
    let hue = 90.0 - (percent as f32 * 0.6);
    let value = Okhsv::max_value();
    let filled_color = color_from_oklab(hue, Okhsv::max_saturation(), value);
    let unfilled_color = color_from_oklab(hue, Okhsv::max_saturation(), value * 0.5);
    let label = if percent < 100.0 {
        format!("Downloading: {percent}%")
    } else {
        "Download Complete!".into()
    };
    LineGauge::default()
        .ratio(percent / 100.0)
        .label(label)
        .style(Style::new().light_blue())
        .filled_style(Style::new().fg(filled_color))
        .unfilled_style(Style::new().fg(unfilled_color))
        .line_set(symbols::line::THICK)
        .render(area, buf);
}

examples/inline.rs (line 247)

fn draw(frame: &mut Frame, downloads: &Downloads) {
    let area = frame.area();

    let block = Block::new().title(Line::from("Progress").centered());
    frame.render_widget(block, area);

    let vertical = Layout::vertical([Constraint::Length(2), Constraint::Length(4)]).margin(1);
    let horizontal = Layout::horizontal([Constraint::Percentage(20), Constraint::Percentage(80)]);
    let [progress_area, main] = vertical.areas(area);
    let [list_area, gauge_area] = horizontal.areas(main);

    // total progress
    let done = NUM_DOWNLOADS - downloads.pending.len() - downloads.in_progress.len();
    #[allow(clippy::cast_precision_loss)]
    let progress = LineGauge::default()
        .filled_style(Style::default().fg(Color::Blue))
        .label(format!("{done}/{NUM_DOWNLOADS}"))
        .ratio(done as f64 / NUM_DOWNLOADS as f64);
    frame.render_widget(progress, progress_area);

    // in progress downloads
    let items: Vec<ListItem> = downloads
        .in_progress
        .values()
        .map(|download| {
            ListItem::new(Line::from(vec![
                Span::raw(symbols::DOT),
                Span::styled(
                    format!(" download {:>2}", download.id),
                    Style::default()
                        .fg(Color::LightGreen)
                        .add_modifier(Modifier::BOLD),
                ),
                Span::raw(format!(
                    " ({}ms)",
                    download.started_at.elapsed().as_millis()
                )),
            ]))
        })
        .collect();
    let list = List::new(items);
    frame.render_widget(list, list_area);

    #[allow(clippy::cast_possible_truncation)]
    for (i, (_, download)) in downloads.in_progress.iter().enumerate() {
        let gauge = Gauge::default()
            .gauge_style(Style::default().fg(Color::Yellow))
            .ratio(download.progress / 100.0);
        if gauge_area.top().saturating_add(i as u16) > area.bottom() {
            continue;
        }
        frame.render_widget(
            gauge,
            Rect {
                x: gauge_area.left(),
                y: gauge_area.top().saturating_add(i as u16),
                width: gauge_area.width,
                height: 1,
            },
        );
    }
}

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

Sets the widget style.

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

This will style everything except the bar itself, so basically the block (if any) and background.

Examples found in repository

examples/demo2/tabs/weather.rs (line 159)

fn render_line_gauge(percent: f64, area: Rect, buf: &mut Buffer) {
    // cycle color hue based on the percent for a neat effect yellow -> red
    let hue = 90.0 - (percent as f32 * 0.6);
    let value = Okhsv::max_value();
    let filled_color = color_from_oklab(hue, Okhsv::max_saturation(), value);
    let unfilled_color = color_from_oklab(hue, Okhsv::max_saturation(), value * 0.5);
    let label = if percent < 100.0 {
        format!("Downloading: {percent}%")
    } else {
        "Download Complete!".into()
    };
    LineGauge::default()
        .ratio(percent / 100.0)
        .label(label)
        .style(Style::new().light_blue())
        .filled_style(Style::new().fg(filled_color))
        .unfilled_style(Style::new().fg(unfilled_color))
        .line_set(symbols::line::THICK)
        .render(area, buf);
}

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

👎Deprecated since 0.27.0: You should use LineGauge::filled_style instead.

Sets the 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>).

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

Sets the style of filled part of the bar.

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

Examples found in repository

examples/line_gauge.rs (line 135)

    fn render_gauge1(&self, area: Rect, buf: &mut Buffer) {
        let title = title_block("Blue / red only foreground");
        LineGauge::default()
            .block(title)
            .filled_style(Style::default().fg(Color::Blue))
            .unfilled_style(Style::default().fg(Color::Red))
            .label("Foreground:")
            .ratio(self.progress)
            .render(area, buf);
    }

    fn render_gauge2(&self, area: Rect, buf: &mut Buffer) {
        let title = title_block("Blue / red only background");
        LineGauge::default()
            .block(title)
            .filled_style(Style::default().fg(Color::Blue).bg(Color::Blue))
            .unfilled_style(Style::default().fg(Color::Red).bg(Color::Red))
            .label("Background:")
            .ratio(self.progress)
            .render(area, buf);
    }

    fn render_gauge3(&self, area: Rect, buf: &mut Buffer) {
        let title = title_block("Fully styled with background");
        LineGauge::default()
            .block(title)
            .filled_style(
                Style::default()
                    .fg(tailwind::BLUE.c400)
                    .bg(tailwind::BLUE.c600),
            )
            .unfilled_style(
                Style::default()
                    .fg(tailwind::RED.c400)
                    .bg(tailwind::RED.c800),
            )
            .label("Both:")
            .ratio(self.progress)
            .render(area, buf);
    }

examples/demo2/tabs/weather.rs (line 160)

fn render_line_gauge(percent: f64, area: Rect, buf: &mut Buffer) {
    // cycle color hue based on the percent for a neat effect yellow -> red
    let hue = 90.0 - (percent as f32 * 0.6);
    let value = Okhsv::max_value();
    let filled_color = color_from_oklab(hue, Okhsv::max_saturation(), value);
    let unfilled_color = color_from_oklab(hue, Okhsv::max_saturation(), value * 0.5);
    let label = if percent < 100.0 {
        format!("Downloading: {percent}%")
    } else {
        "Download Complete!".into()
    };
    LineGauge::default()
        .ratio(percent / 100.0)
        .label(label)
        .style(Style::new().light_blue())
        .filled_style(Style::new().fg(filled_color))
        .unfilled_style(Style::new().fg(unfilled_color))
        .line_set(symbols::line::THICK)
        .render(area, buf);
}

examples/inline.rs (line 246)

fn draw(frame: &mut Frame, downloads: &Downloads) {
    let area = frame.area();

    let block = Block::new().title(Line::from("Progress").centered());
    frame.render_widget(block, area);

    let vertical = Layout::vertical([Constraint::Length(2), Constraint::Length(4)]).margin(1);
    let horizontal = Layout::horizontal([Constraint::Percentage(20), Constraint::Percentage(80)]);
    let [progress_area, main] = vertical.areas(area);
    let [list_area, gauge_area] = horizontal.areas(main);

    // total progress
    let done = NUM_DOWNLOADS - downloads.pending.len() - downloads.in_progress.len();
    #[allow(clippy::cast_precision_loss)]
    let progress = LineGauge::default()
        .filled_style(Style::default().fg(Color::Blue))
        .label(format!("{done}/{NUM_DOWNLOADS}"))
        .ratio(done as f64 / NUM_DOWNLOADS as f64);
    frame.render_widget(progress, progress_area);

    // in progress downloads
    let items: Vec<ListItem> = downloads
        .in_progress
        .values()
        .map(|download| {
            ListItem::new(Line::from(vec![
                Span::raw(symbols::DOT),
                Span::styled(
                    format!(" download {:>2}", download.id),
                    Style::default()
                        .fg(Color::LightGreen)
                        .add_modifier(Modifier::BOLD),
                ),
                Span::raw(format!(
                    " ({}ms)",
                    download.started_at.elapsed().as_millis()
                )),
            ]))
        })
        .collect();
    let list = List::new(items);
    frame.render_widget(list, list_area);

    #[allow(clippy::cast_possible_truncation)]
    for (i, (_, download)) in downloads.in_progress.iter().enumerate() {
        let gauge = Gauge::default()
            .gauge_style(Style::default().fg(Color::Yellow))
            .ratio(download.progress / 100.0);
        if gauge_area.top().saturating_add(i as u16) > area.bottom() {
            continue;
        }
        frame.render_widget(
            gauge,
            Rect {
                x: gauge_area.left(),
                y: gauge_area.top().saturating_add(i as u16),
                width: gauge_area.width,
                height: 1,
            },
        );
    }
}

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

Sets the style of the unfilled part of the bar.

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

Examples found in repository

examples/line_gauge.rs (line 136)

    fn render_gauge1(&self, area: Rect, buf: &mut Buffer) {
        let title = title_block("Blue / red only foreground");
        LineGauge::default()
            .block(title)
            .filled_style(Style::default().fg(Color::Blue))
            .unfilled_style(Style::default().fg(Color::Red))
            .label("Foreground:")
            .ratio(self.progress)
            .render(area, buf);
    }

    fn render_gauge2(&self, area: Rect, buf: &mut Buffer) {
        let title = title_block("Blue / red only background");
        LineGauge::default()
            .block(title)
            .filled_style(Style::default().fg(Color::Blue).bg(Color::Blue))
            .unfilled_style(Style::default().fg(Color::Red).bg(Color::Red))
            .label("Background:")
            .ratio(self.progress)
            .render(area, buf);
    }

    fn render_gauge3(&self, area: Rect, buf: &mut Buffer) {
        let title = title_block("Fully styled with background");
        LineGauge::default()
            .block(title)
            .filled_style(
                Style::default()
                    .fg(tailwind::BLUE.c400)
                    .bg(tailwind::BLUE.c600),
            )
            .unfilled_style(
                Style::default()
                    .fg(tailwind::RED.c400)
                    .bg(tailwind::RED.c800),
            )
            .label("Both:")
            .ratio(self.progress)
            .render(area, buf);
    }

examples/demo2/tabs/weather.rs (line 161)

fn render_line_gauge(percent: f64, area: Rect, buf: &mut Buffer) {
    // cycle color hue based on the percent for a neat effect yellow -> red
    let hue = 90.0 - (percent as f32 * 0.6);
    let value = Okhsv::max_value();
    let filled_color = color_from_oklab(hue, Okhsv::max_saturation(), value);
    let unfilled_color = color_from_oklab(hue, Okhsv::max_saturation(), value * 0.5);
    let label = if percent < 100.0 {
        format!("Downloading: {percent}%")
    } else {
        "Download Complete!".into()
    };
    LineGauge::default()
        .ratio(percent / 100.0)
        .label(label)
        .style(Style::new().light_blue())
        .filled_style(Style::new().fg(filled_color))
        .unfilled_style(Style::new().fg(unfilled_color))
        .line_set(symbols::line::THICK)
        .render(area, buf);
}

Trait Implementations

impl<'a> Clone for LineGauge<'a>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for LineGauge<'a>

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

Formats the value using the given formatter.

impl<'a> Default for LineGauge<'a>

fn default() -> LineGauge<'a>

Returns the “default value” for a type.

impl<'a> PartialEq for LineGauge<'a>

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

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

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

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

Available on crate feature unstable-widget-ref only.

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