Struct Span

pub struct Span<'a> {
    pub style: Style,
    pub content: Cow<'a, str>,
}

Represents a part of a line that is contiguous and where all characters share the same style.

A Span is the smallest unit of text that can be styled. It is usually combined in the Line type to represent a line of text where each Span may have a different style.

Constructor Methods

• Span::default creates an span with empty content and the default style.
• Span::raw creates an span with the specified content and the default style.
• Span::styled creates an span with the specified content and style.

Setter Methods

These methods are fluent setters. They return a new Span with the specified property set.

• Span::content sets the content of the span.
• Span::style sets the style of the span.

Other Methods

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

Examples

A Span with style set to Style::default() can be created from a &str, a String, or any type convertible to Cow<str>.

use ratatui::text::Span;

let span = Span::raw("test content");
let span = Span::raw(String::from("test content"));
let span = Span::from("test content");
let span = Span::from(String::from("test content"));
let span: Span = "test content".into();
let span: Span = String::from("test content").into();

Styled spans can be created using Span::styled or by converting strings using methods from the Stylize trait.

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

let span = Span::styled("test content", Style::new().green());
let span = Span::styled(String::from("test content"), Style::new().green());

// using Stylize trait shortcuts
let span = "test content".green();
let span = String::from("test content").green();

Span implements the Styled trait, which allows it to be styled using the shortcut methods defined in the Stylize trait.

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

let span = Span::raw("test content").green().on_yellow().italic();
let span = Span::raw(String::from("test content"))
    .green()
    .on_yellow()
    .italic();

Span implements the Widget trait, which allows it to be rendered to a Buffer. Usually apps will use the Paragraph widget instead of rendering Span directly, as it handles text wrapping and alignment for you.

use ratatui::{style::Stylize, Frame};

frame.render_widget("test content".green().on_yellow().italic(), frame.area());

Fields

style: Style

The style of the span.

content: Cow<'a, str>

The content of the span as a Clone-on-write string.

Implementations

impl<'a> Span<'a>

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

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

Create a span with the default style.

Examples

use ratatui::text::Span;

Span::raw("test content");
Span::raw(String::from("test content"));

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

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

Create a span with the specified style.

content accepts any type that is convertible to Cow<str> (e.g. &str, String, &String, etc.).

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::Span,
};

let style = Style::new().yellow().on_green().italic();
Span::styled("test content", style);
Span::styled(String::from("test content"), style);

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

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

Sets the content of the span.

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

Accepts any type that can be converted to Cow<str> (e.g. &str, String, &String, etc.).

Examples

use ratatui::text::Span;

let mut span = Span::default().content("content");

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

Sets the style of the span.

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

In contrast to Span::patch_style, this method replaces the style of the span instead of patching it.

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::Span,
};

let mut span = Span::default().style(Style::new().green());

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

Patches the style of the Span, adding modifiers from the given 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

Example

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

let span = Span::styled("test content", Style::new().green().italic())
    .patch_style(Style::new().red().on_yellow().bold());
assert_eq!(span.style, Style::new().red().on_yellow().italic().bold());

pub fn reset_style(self) -> Self

Resets the style of the Span.

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

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

Example

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

let span = Span::styled(
    "Test Content",
    Style::new().dark_gray().on_yellow().italic(),
)
.reset_style();
assert_eq!(span.style, Style::reset());

pub fn width(&self) -> usize

Returns the unicode width of the content held by this span.

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 span.

base_style is the Style that will be patched with the Span’s 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>).

Example

use std::iter::Iterator;

use ratatui::{
    style::{Style, Stylize},
    text::{Span, StyledGrapheme},
};

let span = Span::styled("Test", Style::new().green().italic());
let style = Style::new().red().on_yellow();
assert_eq!(
    span.styled_graphemes(style)
        .collect::<Vec<StyledGrapheme>>(),
    vec![
        StyledGrapheme::new("T", Style::new().green().on_yellow().italic()),
        StyledGrapheme::new("e", Style::new().green().on_yellow().italic()),
        StyledGrapheme::new("s", Style::new().green().on_yellow().italic()),
        StyledGrapheme::new("t", Style::new().green().on_yellow().italic()),
    ],
);

pub fn into_left_aligned_line(self) -> Line<'a>

Converts this Span into a left-aligned Line

Example

use ratatui::style::Stylize;

let line = "Test Content".green().italic().into_left_aligned_line();

pub fn to_left_aligned_line(self) -> Line<'a>

👎Deprecated: use into_left_aligned_line

pub fn into_centered_line(self) -> Line<'a>

Converts this Span into a center-aligned Line

Example

use ratatui::style::Stylize;

let line = "Test Content".green().italic().into_centered_line();

pub fn to_centered_line(self) -> Line<'a>

👎Deprecated: use into_centered_line

pub fn into_right_aligned_line(self) -> Line<'a>

Converts this Span into a right-aligned Line

Example

use ratatui::style::Stylize;

let line = "Test Content".green().italic().into_right_aligned_line();

pub fn to_right_aligned_line(self) -> Line<'a>

👎Deprecated: use into_right_aligned_line

Trait Implementations

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

type Output = Line<'a>

The resulting type after applying the + operator.

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

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

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Span<'_>

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

Formats the value using the given formatter.

impl<'a> Default for Span<'a>

fn default() -> Span<'a>

Returns the “default value” for a type.

impl Display for Span<'_>

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

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

Converts to this type from the input type.

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

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

Converts to this type from the input type.

impl<'a, T> From<T> for Span<'a>

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

fn from(s: T) -> Self

Converts to this type from the input type.

impl<'a> Hash for Span<'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 Span<'a>

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

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

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

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

impl<'a> StructuralPartialEq for Span<'a>