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"));

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);

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());

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();

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();

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();

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());

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 duplicate 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)

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>