Struct Line

pub struct Line<'a> {
    pub style: Style,
    pub alignment: Option<Alignment>,
    pub spans: Vec<Span<'a>>,
}

A line of text, consisting of one or more Spans.

Lines are used wherever text is displayed in the terminal and represent a single line of text. When a Line is rendered, it is rendered as a single line of text, with each Span being rendered in order (left to right).

Any newlines in the content are removed when creating a Line using the constructor or conversion methods.

Constructor Methods

• Line::default creates a line with empty content and the default style.
• Line::raw creates a line with the given content and the default style.
• Line::styled creates a line with the given content and style.

Conversion Methods

• Line::from creates a Line from a String.
• Line::from creates a Line from a &str.
• Line::from creates a Line from a Vec of Spans.
• Line::from creates a Line from single Span.
• String::from converts a line into a String.
• Line::from_iter creates a line from an iterator of items that are convertible to Span.

Setter Methods

These methods are fluent setters. They return a Line with the property set.

• Line::spans sets the content of the line.
• Line::style sets the style of the line.
• Line::alignment sets the alignment of the line.
• Line::left_aligned sets the alignment of the line to Alignment::Left.
• Line::centered sets the alignment of the line to Alignment::Center.
• Line::right_aligned sets the alignment of the line to Alignment::Right.

Iteration Methods

• Line::iter returns an iterator over the spans of this line.
• Line::iter_mut returns a mutable iterator over the spans of this line.
• Line::into_iter returns an iterator over the spans of this line.

Other Methods

• Line::patch_style patches the style of the line, adding modifiers from the given style.
• Line::reset_style resets the style of the line.
• Line::width returns the unicode width of the content held by this line.
• Line::styled_graphemes returns an iterator over the graphemes held by this line.
• Line::push_span adds a span to the line.

Compatibility Notes

Before v0.26.0, Line did not have a style field and instead relied on only the styles that were set on each Span contained in the spans field. The Line::patch_style method was the only way to set the overall style for individual lines. For this reason, this field may not be supported yet by all widgets (outside of the ratatui crate itself).

Examples

Creating Lines

Lines can be created from Spans, Strings, and &strs. They can be styled with a Style.

use ratatui::{
    style::{Color, Modifier, Style, Stylize},
    text::{Line, Span},
};

let style = Style::new().yellow();
let line = Line::raw("Hello, world!").style(style);
let line = Line::styled("Hello, world!", style);
let line = Line::styled("Hello, world!", (Color::Yellow, Modifier::BOLD));

let line = Line::from("Hello, world!");
let line = Line::from(String::from("Hello, world!"));
let line = Line::from(vec![
    Span::styled("Hello", Style::new().blue()),
    Span::raw(" world!"),
]);

Styling Lines

The line’s Style is used by the rendering widget to determine how to style the line. Each Span in the line will be styled with the Style of the line, and then with its own Style. If the line is longer than the available space, the style is applied to the entire line, and the line is truncated. Line also implements Styled which means you can use the methods of the Stylize trait.

use ratatui::{
    style::{Color, Modifier, Style, Stylize},
    text::Line,
};

let line = Line::from("Hello world!").style(Style::new().yellow().italic());
let line = Line::from("Hello world!").style(Color::Yellow);
let line = Line::from("Hello world!").style((Color::Yellow, Color::Black));
let line = Line::from("Hello world!").style((Color::Yellow, Modifier::ITALIC));
let line = Line::from("Hello world!").yellow().italic();

Aligning Lines

The line’s Alignment is used by the rendering widget to determine how to align the line within the available space. If the line is longer than the available space, the alignment is ignored and the line is truncated.

use ratatui::{layout::Alignment, text::Line};

let line = Line::from("Hello world!").alignment(Alignment::Right);
let line = Line::from("Hello world!").centered();
let line = Line::from("Hello world!").left_aligned();
let line = Line::from("Hello world!").right_aligned();

Rendering Lines

Line implements the Widget trait, which means it can be rendered to a Buffer.

use ratatui::{
    buffer::Buffer,
    layout::Rect,
    style::{Style, Stylize},
    text::Line,
    widgets::Widget,
    Frame,
};

// in another widget's render method
let line = Line::from("Hello world!").style(Style::new().yellow().italic());
line.render(area, buf);

// in a terminal.draw closure
let line = Line::from("Hello world!").style(Style::new().yellow().italic());
frame.render_widget(line, area);

Rendering Lines with a Paragraph widget

Usually apps will use the Paragraph widget instead of rendering a Line directly as it provides more functionality.

use ratatui::{
    buffer::Buffer,
    layout::Rect,
    style::Stylize,
    text::Line,
    widgets::{Paragraph, Widget, Wrap},
};

let line = Line::from("Hello world!").yellow().italic();
Paragraph::new(line)
    .wrap(Wrap { trim: true })
    .render(area, buf);

Fields

style: Style

The style of this line of text.

alignment: Option<Alignment>

The alignment of this line of text.

spans: Vec<Span<'a>>

The spans that make up this line of text.

Implementations

impl<'a> Line<'a>

pub fn raw<T>(content: T) -> Self

where T: Into<Cow<'a, str>>,

Create a line with the default style.

content can be any type that is convertible to Cow<str> (e.g. &str, String, Cow<str>, or your own type that implements Into<Cow<str>>).

A Line can specify a Style, which will be applied before the style of each Span in the line.

Any newlines in the content are removed.

Examples

use std::borrow::Cow;

use ratatui::text::Line;

Line::raw("test content");
Line::raw(String::from("test content"));
Line::raw(Cow::from("test content"));

Examples found in repository

examples/tabs.rs (line 150)

fn render_footer(area: Rect, buf: &mut Buffer) {
    Line::raw("◄ ► to change tab | Press q to quit")
        .centered()
        .render(area, buf);
}

examples/paragraph.rs (line 144)

fn create_lines(area: Rect) -> Vec<Line<'static>> {
    let short_line = "A long line to demonstrate line wrapping. ";
    let long_line = short_line.repeat(usize::from(area.width) / short_line.len() + 4);
    let mut styled_spans = vec![];
    for span in [
        "Styled".blue(),
        "Spans".red().on_white(),
        "Bold".bold(),
        "Italic".italic(),
        "Underlined".underlined(),
        "Strikethrough".crossed_out(),
    ] {
        styled_spans.push(span);
        styled_spans.push(" ".into());
    }
    vec![
        Line::raw("Unstyled Line"),
        Line::raw("Styled Line").black().on_red().bold().italic(),
        Line::from(styled_spans),
        Line::from(long_line.green().italic()),
        Line::from_iter([
            "Masked text: ".into(),
            Span::styled(Masked::new("my secret password", '*'), Color::Red),
        ]),
    ]
}

examples/list.rs (line 210)

    fn render_list(&mut self, area: Rect, buf: &mut Buffer) {
        let block = Block::new()
            .title(Line::raw("TODO List").centered())
            .borders(Borders::TOP)
            .border_set(symbols::border::EMPTY)
            .border_style(TODO_HEADER_STYLE)
            .bg(NORMAL_ROW_BG);

        // Iterate through all elements in the `items` and stylize them.
        let items: Vec<ListItem> = self
            .todo_list
            .items
            .iter()
            .enumerate()
            .map(|(i, todo_item)| {
                let color = alternate_colors(i);
                ListItem::from(todo_item).bg(color)
            })
            .collect();

        // Create a List from all list items and highlight the currently selected one
        let list = List::new(items)
            .block(block)
            .highlight_style(SELECTED_STYLE)
            .highlight_symbol(">")
            .highlight_spacing(HighlightSpacing::Always);

        // We need to disambiguate this trait method as both `Widget` and `StatefulWidget` share the
        // same method name `render`.
        StatefulWidget::render(list, area, buf, &mut self.todo_list.state);
    }

    fn render_selected_item(&self, area: Rect, buf: &mut Buffer) {
        // We get the info depending on the item's state.
        let info = if let Some(i) = self.todo_list.state.selected() {
            match self.todo_list.items[i].status {
                Status::Completed => format!("✓ DONE: {}", self.todo_list.items[i].info),
                Status::Todo => format!("☐ TODO: {}", self.todo_list.items[i].info),
            }
        } else {
            "Nothing selected...".to_string()
        };

        // We show the list item's info under the list in this paragraph
        let block = Block::new()
            .title(Line::raw("TODO Info").centered())
            .borders(Borders::TOP)
            .border_set(symbols::border::EMPTY)
            .border_style(TODO_HEADER_STYLE)
            .bg(NORMAL_ROW_BG)
            .padding(Padding::horizontal(1));

        // We can now render the item info
        Paragraph::new(info)
            .block(block)
            .fg(TEXT_FG_COLOR)
            .wrap(Wrap { trim: false })
            .render(area, buf);
    }

examples/flex.rs (line 487)

    fn render_spacer(spacer: Rect, buf: &mut Buffer) {
        if spacer.width > 1 {
            let corners_only = symbols::border::Set {
                top_left: line::NORMAL.top_left,
                top_right: line::NORMAL.top_right,
                bottom_left: line::NORMAL.bottom_left,
                bottom_right: line::NORMAL.bottom_right,
                vertical_left: " ",
                vertical_right: " ",
                horizontal_top: " ",
                horizontal_bottom: " ",
            };
            Block::bordered()
                .border_set(corners_only)
                .border_style(Style::reset().dark_gray())
                .render(spacer, buf);
        } else {
            Paragraph::new(Text::from(vec![
                Line::from(""),
                Line::from("│"),
                Line::from("│"),
                Line::from(""),
            ]))
            .style(Style::reset().dark_gray())
            .render(spacer, buf);
        }
        let width = spacer.width;
        let label = if width > 4 {
            format!("{width} px")
        } else if width > 2 {
            format!("{width}")
        } else {
            String::new()
        };
        let text = Text::from(vec![
            Line::raw(""),
            Line::raw(""),
            Line::styled(label, Style::reset().dark_gray()),
        ]);
        Paragraph::new(text)
            .style(Style::reset().dark_gray())
            .alignment(Alignment::Center)
            .render(spacer, buf);
    }

pub fn styled<T, S>(content: T, style: S) -> Self

where T: Into<Cow<'a, str>>, S: Into<Style>,

Create a line with the given style.

content can be any type that is convertible to Cow<str> (e.g. &str, String, Cow<str>, or your own type that implements Into<Cow<str>>).

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

Examples

Any newlines in the content are removed.

use std::borrow::Cow;

use ratatui::{
    style::{Style, Stylize},
    text::Line,
};

let style = Style::new().yellow().italic();
Line::styled("My text", style);
Line::styled(String::from("My text"), style);
Line::styled(Cow::from("test content"), style);

Examples found in repository

examples/list.rs (line 280)

    fn from(value: &TodoItem) -> Self {
        let line = match value.status {
            Status::Todo => Line::styled(format!(" ☐ {}", value.todo), TEXT_FG_COLOR),
            Status::Completed => {
                Line::styled(format!(" ✓ {}", value.todo), COMPLETED_TEXT_FG_COLOR)
            }
        };
        ListItem::new(line)
    }

examples/constraint-explorer.rs (line 547)

    fn label(width: u16) -> impl Widget {
        let long_label = format!("{width} px");
        let short_label = format!("{width}");
        let label = if long_label.len() < width as usize {
            long_label
        } else if short_label.len() < width as usize {
            short_label
        } else {
            String::new()
        };
        Line::styled(label, Self::TEXT_COLOR).centered()
    }

examples/flex.rs (line 489)

    fn render_spacer(spacer: Rect, buf: &mut Buffer) {
        if spacer.width > 1 {
            let corners_only = symbols::border::Set {
                top_left: line::NORMAL.top_left,
                top_right: line::NORMAL.top_right,
                bottom_left: line::NORMAL.bottom_left,
                bottom_right: line::NORMAL.bottom_right,
                vertical_left: " ",
                vertical_right: " ",
                horizontal_top: " ",
                horizontal_bottom: " ",
            };
            Block::bordered()
                .border_set(corners_only)
                .border_style(Style::reset().dark_gray())
                .render(spacer, buf);
        } else {
            Paragraph::new(Text::from(vec![
                Line::from(""),
                Line::from("│"),
                Line::from("│"),
                Line::from(""),
            ]))
            .style(Style::reset().dark_gray())
            .render(spacer, buf);
        }
        let width = spacer.width;
        let label = if width > 4 {
            format!("{width} px")
        } else if width > 2 {
            format!("{width}")
        } else {
            String::new()
        };
        let text = Text::from(vec![
            Line::raw(""),
            Line::raw(""),
            Line::styled(label, Style::reset().dark_gray()),
        ]);
        Paragraph::new(text)
            .style(Style::reset().dark_gray())
            .alignment(Alignment::Center)
            .render(spacer, buf);
    }

pub fn spans<I>(self, spans: I) -> Self

where I: IntoIterator, I::Item: Into<Span<'a>>,

Sets the spans of this line of text.

spans accepts any iterator that yields items that are convertible to Span (e.g. &str, String, Span, or your own type that implements Into<Span>).

Examples

use ratatui::{style::Stylize, text::Line};

let line = Line::default().spans(vec!["Hello".blue(), " world!".green()]);
let line = Line::default().spans([1, 2, 3].iter().map(|i| format!("Item {}", i)));

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

Sets the style of this line of text.

Defaults to Style::default().

Note: This field was added in v0.26.0. Prior to that, the style of a line was determined only by the style of each Span contained in the line. For this reason, this field may not be supported by all widgets (outside of the ratatui crate itself).

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

Examples

use ratatui::{
    style::{Style, Stylize},
    text::Line,
};

let mut line = Line::from("foo").style(Style::new().red());

Examples found in repository

examples/demo2/app.rs (line 201)

    fn render_bottom_bar(area: Rect, buf: &mut Buffer) {
        let keys = [
            ("H/←", "Left"),
            ("L/→", "Right"),
            ("K/↑", "Up"),
            ("J/↓", "Down"),
            ("D/Del", "Destroy"),
            ("Q/Esc", "Quit"),
        ];
        let spans = keys
            .iter()
            .flat_map(|(key, desc)| {
                let key = Span::styled(format!(" {key} "), THEME.key_binding.key);
                let desc = Span::styled(format!(" {desc} "), THEME.key_binding.description);
                [key, desc]
            })
            .collect_vec();
        Line::from(spans)
            .centered()
            .style((Color::Indexed(236), Color::Indexed(232)))
            .render(area, buf);
    }

pub fn alignment(self, alignment: Alignment) -> Self

Sets the target alignment for this line of text.

Defaults to: None, meaning the alignment is determined by the rendering widget. Setting the alignment of a Line generally overrides the alignment of its parent Text or Widget.

Examples

use ratatui::{layout::Alignment, text::Line};

let mut line = Line::from("Hi, what's up?");
assert_eq!(None, line.alignment);
assert_eq!(
    Some(Alignment::Right),
    line.alignment(Alignment::Right).alignment
)

pub fn left_aligned(self) -> Self

Left-aligns this line of text.

Convenience shortcut for Line::alignment(Alignment::Left). Setting the alignment of a Line generally overrides the alignment of its parent Text or Widget, with the default alignment being inherited from the parent.

Examples

use ratatui::text::Line;

let line = Line::from("Hi, what's up?").left_aligned();

Examples found in repository

examples/block.rs (line 164)

fn render_multiple_title_positions(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
    let block = Block::bordered()
        .title(Line::from("top left").left_aligned())
        .title(Line::from("top center").centered())
        .title(Line::from("top right").right_aligned())
        .title_bottom(Line::from("bottom left").left_aligned())
        .title_bottom(Line::from("bottom center").centered())
        .title_bottom(Line::from("bottom right").right_aligned());
    frame.render_widget(paragraph.clone().block(block), area);
}

pub fn centered(self) -> Self

Center-aligns this line of text.

Convenience shortcut for Line::alignment(Alignment::Center). Setting the alignment of a Line generally overrides the alignment of its parent Text or Widget, with the default alignment being inherited from the parent.

Examples

use ratatui::text::Line;

let line = Line::from("Hi, what's up?").centered();

Examples found in repository

examples/tabs.rs (line 151)

fn render_footer(area: Rect, buf: &mut Buffer) {
    Line::raw("◄ ► to change tab | Press q to quit")
        .centered()
        .render(area, buf);
}

examples/line_gauge.rs (line 175)

fn title_block(title: &str) -> Block {
    Block::default()
        .title(Line::from(title).centered())
        .borders(Borders::NONE)
        .fg(CUSTOM_LABEL_COLOR)
        .padding(Padding::vertical(1))
}

examples/gauge.rs (line 199)

fn title_block(title: &str) -> Block {
    let title = Line::from(title).centered();
    Block::new()
        .borders(Borders::NONE)
        .padding(Padding::vertical(1))
        .title(title)
        .fg(CUSTOM_LABEL_COLOR)
}

examples/async.rs (line 103)

    fn draw(&self, frame: &mut Frame) {
        let vertical = Layout::vertical([Constraint::Length(1), Constraint::Fill(1)]);
        let [title_area, body_area] = vertical.areas(frame.area());
        let title = Line::from("Ratatui async example").centered().bold();
        frame.render_widget(title, title_area);
        frame.render_widget(&self.pull_requests, body_area);
    }

examples/barchart.rs (line 89)

fn vertical_barchart(temperatures: &[u8]) -> BarChart {
    let bars: Vec<Bar> = temperatures
        .iter()
        .enumerate()
        .map(|(hour, value)| vertical_bar(hour, value))
        .collect();
    let title = Line::from("Weather (Vertical)").centered();
    BarChart::default()
        .data(BarGroup::default().bars(&bars))
        .block(Block::new().title(title))
        .bar_width(5)
}

fn vertical_bar(hour: usize, temperature: &u8) -> Bar {
    Bar::default()
        .value(u64::from(*temperature))
        .label(Line::from(format!("{hour:>02}:00")))
        .text_value(format!("{temperature:>3}°"))
        .style(temperature_style(*temperature))
        .value_style(temperature_style(*temperature).reversed())
}

/// Create a horizontal bar chart from the temperatures data.
fn horizontal_barchart(temperatures: &[u8]) -> BarChart {
    let bars: Vec<Bar> = temperatures
        .iter()
        .enumerate()
        .map(|(hour, value)| horizontal_bar(hour, value))
        .collect();
    let title = Line::from("Weather (Horizontal)").centered();
    BarChart::default()
        .block(Block::new().title(title))
        .data(BarGroup::default().bars(&bars))
        .bar_width(1)
        .bar_gap(0)
        .direction(Direction::Horizontal)
}

examples/barchart-grouped.rs (line 95)

    fn vertical_revenue_barchart(&self) -> BarChart<'_> {
        let mut barchart = BarChart::default()
            .block(Block::new().title(Line::from("Company revenues (Vertical)").centered()))
            .bar_gap(0)
            .bar_width(6)
            .group_gap(2);

        for group in self
            .revenues
            .iter()
            .map(|revenue| revenue.to_vertical_bar_group(&self.companies))
        {
            barchart = barchart.data(group);
        }
        barchart
    }

    /// Create a horizontal revenue bar chart with the data from the `revenues` field.
    fn horizontal_revenue_barchart(&self) -> BarChart<'_> {
        let title = Line::from("Company Revenues (Horizontal)").centered();
        let mut barchart = BarChart::default()
            .block(Block::new().title(title))
            .bar_width(1)
            .group_gap(2)
            .bar_gap(0)
            .direction(Direction::Horizontal);
        for group in self
            .revenues
            .iter()
            .map(|revenue| revenue.to_horizontal_bar_group(&self.companies))
        {
            barchart = barchart.data(group);
        }
        barchart
    }
}

/// Generate fake company data
const fn fake_companies() -> [Company; COMPANY_COUNT] {
    [
        Company::new("BAKE", "Bake my day", Color::LightRed),
        Company::new("BITE", "Bits and Bites", Color::Blue),
        Company::new("TART", "Tart of the Table", Color::White),
    ]
}

/// Some fake revenue data
const fn fake_revenues() -> [Revenues; PERIOD_COUNT] {
    [
        Revenues::new("Jan", [8500, 6500, 7000]),
        Revenues::new("Feb", [9000, 7500, 8500]),
        Revenues::new("Mar", [9500, 4500, 8200]),
        Revenues::new("Apr", [6300, 4000, 5000]),
    ]
}

impl Revenues {
    /// Create a new instance of `Revenues`
    const fn new(period: &'static str, revenues: [u32; COMPANY_COUNT]) -> Self {
        Self { period, revenues }
    }

    /// Create a `BarGroup` with vertical bars for each company
    fn to_vertical_bar_group<'a>(&self, companies: &'a [Company]) -> BarGroup<'a> {
        let bars: Vec<Bar> = zip(companies, self.revenues)
            .map(|(company, revenue)| company.vertical_revenue_bar(revenue))
            .collect();
        BarGroup::default()
            .label(Line::from(self.period).centered())
            .bars(&bars)
    }

    /// Create a `BarGroup` with horizontal bars for each company
    fn to_horizontal_bar_group<'a>(&'a self, companies: &'a [Company]) -> BarGroup<'a> {
        let bars: Vec<Bar> = zip(companies, self.revenues)
            .map(|(company, revenue)| company.horizontal_revenue_bar(revenue))
            .collect();
        BarGroup::default()
            .label(Line::from(self.period).centered())
            .bars(&bars)
    }

Additional examples can be found in:

• examples/block.rs
• examples/demo2/app.rs
• examples/constraint-explorer.rs
• examples/list.rs
• examples/chart.rs
• examples/inline.rs
• examples/layout.rs

pub fn right_aligned(self) -> Self

Right-aligns this line of text.

Convenience shortcut for Line::alignment(Alignment::Right). Setting the alignment of a Line generally overrides the alignment of its parent Text or Widget, with the default alignment being inherited from the parent.

Examples

use ratatui::text::Line;

let line = Line::from("Hi, what's up?").right_aligned();

Examples found in repository

examples/block.rs (line 166)

fn render_multiple_title_positions(paragraph: &Paragraph, frame: &mut Frame, area: Rect) {
    let block = Block::bordered()
        .title(Line::from("top left").left_aligned())
        .title(Line::from("top center").centered())
        .title(Line::from("top right").right_aligned())
        .title_bottom(Line::from("bottom left").left_aligned())
        .title_bottom(Line::from("bottom center").centered())
        .title_bottom(Line::from("bottom right").right_aligned());
    frame.render_widget(paragraph.clone().block(block), area);
}

examples/async.rs (line 230)

    fn render(self, area: Rect, buf: &mut Buffer) {
        let mut state = self.state.write().unwrap();

        // a block with a right aligned title with the loading state on the right
        let loading_state = Line::from(format!("{:?}", state.loading_state)).right_aligned();
        let block = Block::bordered()
            .title("Pull Requests")
            .title(loading_state)
            .title_bottom("j/k to scroll, q to quit");

        // a table with the list of pull requests
        let rows = state.pull_requests.iter();
        let widths = [
            Constraint::Length(5),
            Constraint::Fill(1),
            Constraint::Max(49),
        ];
        let table = Table::new(rows, widths)
            .block(block)
            .highlight_spacing(HighlightSpacing::Always)
            .highlight_symbol(">>")
            .row_highlight_style(Style::new().on_blue());

        StatefulWidget::render(table, area, buf, &mut state.table_state);
    }

pub fn width(&self) -> usize

Returns the width of the underlying string.

Examples

use ratatui::{style::Stylize, text::Line};

let line = Line::from(vec!["Hello".blue(), " world!".green()]);
assert_eq!(12, line.width());

Examples found in repository

examples/custom_widget.rs (line 138)

    fn render(self, area: Rect, buf: &mut Buffer) {
        let (background, text, shadow, highlight) = self.colors();
        buf.set_style(area, Style::new().bg(background).fg(text));

        // render top line if there's enough space
        if area.height > 2 {
            buf.set_string(
                area.x,
                area.y,
                "▔".repeat(area.width as usize),
                Style::new().fg(highlight).bg(background),
            );
        }
        // render bottom line if there's enough space
        if area.height > 1 {
            buf.set_string(
                area.x,
                area.y + area.height - 1,
                "▁".repeat(area.width as usize),
                Style::new().fg(shadow).bg(background),
            );
        }
        // render label centered
        buf.set_line(
            area.x + (area.width.saturating_sub(self.label.width() as u16)) / 2,
            area.y + (area.height.saturating_sub(1)) / 2,
            &self.label,
            area.width,
        );
    }

pub fn styled_graphemes<S: Into<Style>>( &'a self, base_style: S, ) -> impl Iterator<Item = StyledGrapheme<'a>>

Returns an iterator over the graphemes held by this line.

base_style is the Style that will be patched with each grapheme Style to get the resulting Style.

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

Examples

use std::iter::Iterator;

use ratatui::{
    style::{Color, Style},
    text::{Line, StyledGrapheme},
};

let line = Line::styled("Text", Style::default().fg(Color::Yellow));
let style = Style::default().fg(Color::Green).bg(Color::Black);
assert_eq!(
    line.styled_graphemes(style)
        .collect::<Vec<StyledGrapheme>>(),
    vec![
        StyledGrapheme::new("T", Style::default().fg(Color::Yellow).bg(Color::Black)),
        StyledGrapheme::new("e", Style::default().fg(Color::Yellow).bg(Color::Black)),
        StyledGrapheme::new("x", Style::default().fg(Color::Yellow).bg(Color::Black)),
        StyledGrapheme::new("t", Style::default().fg(Color::Yellow).bg(Color::Black)),
    ]
);

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

Patches the style of this Line, adding modifiers from the given style.

This is useful for when you want to apply a style to a line that already has some styling. In contrast to Line::style, this method will not overwrite the existing style, but instead will add the given style’s modifiers to this Line’s style.

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

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

Examples

use ratatui::{
    style::{Color, Modifier},
    text::Line,
};

let line = Line::styled("My text", Modifier::ITALIC);

let styled_line = Line::styled("My text", (Color::Yellow, Modifier::ITALIC));

assert_eq!(styled_line, line.patch_style(Color::Yellow));

pub fn reset_style(self) -> Self

Resets the style of this Line.

Equivalent to calling patch_style(Style::reset()).

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

Examples

use ratatui::{
    style::{Style, Stylize},
    text::Line,
};

let line = Line::styled("My text", style);

assert_eq!(Style::reset(), line.reset_style().style);

pub fn iter(&self) -> Iter<'_, Span<'a>>

Returns an iterator over the spans of this line.

pub fn iter_mut(&mut self) -> IterMut<'_, Span<'a>>

Returns a mutable iterator over the spans of this line.

pub fn push_span<T: Into<Span<'a>>>(&mut self, span: T)

Adds a span to the line.

span can be any type that is convertible into a Span. For example, you can pass a &str, a String, or a Span.

Examples

use ratatui::text::{Line, Span};

let mut line = Line::from("Hello, ");
line.push_span(Span::raw("world!"));
line.push_span(" How are you?");

Trait Implementations

impl<'a> Add<Line<'a>> for Text<'a>

type Output = Text<'a>

The resulting type after applying the + operator.

fn add(self, line: Line<'a>) -> Self::Output

Performs the + operation.

impl<'a> Add<Span<'a>> for Line<'a>

Adds a Span to a Line, returning a new Line with the Span added.

type Output = Line<'a>

The resulting type after applying the + operator.

fn add(self, rhs: Span<'a>) -> Self::Output

Performs the + operation.

impl<'a> Add for Line<'a>

Adds two Lines together, returning a new Text with the contents of the two Lines.

type Output = Text<'a>

The resulting type after applying the + operator.

fn add(self, rhs: Self) -> Self::Output

Performs the + operation.

impl<'a> AddAssign<Line<'a>> for Text<'a>

fn add_assign(&mut self, line: Line<'a>)

Performs the += operation.

impl<'a> AddAssign<Span<'a>> for Line<'a>

fn add_assign(&mut self, rhs: Span<'a>)

Performs the += operation.

impl<'a> Clone for Line<'a>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Line<'_>

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

Formats the value using the given formatter.

impl<'a> Default for Line<'a>

fn default() -> Line<'a>

Returns the “default value” for a type.

impl Display for Line<'_>

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

Formats the value using the given formatter.

impl<'a> Extend<Span<'a>> for Line<'a>

fn extend<T: IntoIterator<Item = Span<'a>>>(&mut self, iter: T)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<'a> From<&'a str> for Line<'a>

fn from(s: &'a str) -> Self

Converts to this type from the input type.

impl<'a> From<Cow<'a, str>> for Line<'a>

fn from(s: Cow<'a, str>) -> Self

Converts to this type from the input type.

impl<'a> From<Line<'a>> for String

fn from(line: Line<'a>) -> Self

Converts to this type from the input type.

impl<'a> From<Line<'a>> for Text<'a>

fn from(line: Line<'a>) -> Self

Converts to this type from the input type.

impl<'a> From<Span<'a>> for Line<'a>

fn from(span: Span<'a>) -> Self

Converts to this type from the input type.

impl<'a> From<String> for Line<'a>

fn from(s: String) -> Self

Converts to this type from the input type.

impl<'a> From<Vec<Span<'a>>> for Line<'a>

fn from(spans: Vec<Span<'a>>) -> Self

Converts to this type from the input type.

impl<'a, T> FromIterator<T> for Line<'a>

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

fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Self

Creates a value from an iterator.

impl<'a> Hash for Line<'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> IntoIterator for &'a Line<'a>

type Item = &'a Span<'a>

The type of the elements being iterated over.

type IntoIter = Iter<'a, Span<'a>>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a> IntoIterator for &'a mut Line<'a>

type Item = &'a mut Span<'a>

The type of the elements being iterated over.

type IntoIter = IterMut<'a, Span<'a>>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a> IntoIterator for Line<'a>

type Item = Span<'a>

The type of the elements being iterated over.

type IntoIter = IntoIter<Span<'a>>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a> PartialEq for Line<'a>

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

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

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

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

impl<'a> StructuralPartialEq for Line<'a>