Struct Style

pub struct Style {
    pub fg: Option<Color>,
    pub bg: Option<Color>,
    pub underline_color: Option<Color>,
    pub add_modifier: Modifier,
    pub sub_modifier: Modifier,
}

Style lets you control the main characteristics of the displayed elements.

use ratatui::style::{Color, Modifier, Style};

Style::default()
    .fg(Color::Black)
    .bg(Color::Green)
    .add_modifier(Modifier::ITALIC | Modifier::BOLD);

Styles can also be created with a shorthand notation.

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

Style::new().black().on_green().italic().bold();

For more information about the style shorthands, see the Stylize trait.

We implement conversions from Color and Modifier to Style so you can use them anywhere that accepts Into<Style>.

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

Line::styled("hello", Style::new().fg(Color::Red));
// simplifies to
Line::styled("hello", Color::Red);

Line::styled("hello", Style::new().add_modifier(Modifier::BOLD));
// simplifies to
Line::styled("hello", Modifier::BOLD);

Styles represents an incremental change. If you apply the styles S1, S2, S3 to a cell of the terminal buffer, the style of this cell will be the result of the merge of S1, S2 and S3, not just S3.

use ratatui::{
    buffer::Buffer,
    layout::Rect,
    style::{Color, Modifier, Style},
};

let styles = [
    Style::default()
        .fg(Color::Blue)
        .add_modifier(Modifier::BOLD | Modifier::ITALIC),
    Style::default()
        .bg(Color::Red)
        .add_modifier(Modifier::UNDERLINED),
    #[cfg(feature = "underline-color")]
    Style::default().underline_color(Color::Green),
    Style::default()
        .fg(Color::Yellow)
        .remove_modifier(Modifier::ITALIC),
];
let mut buffer = Buffer::empty(Rect::new(0, 0, 1, 1));
for style in &styles {
    buffer[(0, 0)].set_style(*style);
}
assert_eq!(
    Style {
        fg: Some(Color::Yellow),
        bg: Some(Color::Red),
        #[cfg(feature = "underline-color")]
        underline_color: Some(Color::Green),
        add_modifier: Modifier::BOLD | Modifier::UNDERLINED,
        sub_modifier: Modifier::empty(),
    },
    buffer[(0, 0)].style(),
);

The default implementation returns a Style that does not modify anything. If you wish to reset all properties until that point use Style::reset.

use ratatui::{
    buffer::Buffer,
    layout::Rect,
    style::{Color, Modifier, Style},
};

let styles = [
    Style::default()
        .fg(Color::Blue)
        .add_modifier(Modifier::BOLD | Modifier::ITALIC),
    Style::reset().fg(Color::Yellow),
];
let mut buffer = Buffer::empty(Rect::new(0, 0, 1, 1));
for style in &styles {
    buffer[(0, 0)].set_style(*style);
}
assert_eq!(
    Style {
        fg: Some(Color::Yellow),
        bg: Some(Color::Reset),
        #[cfg(feature = "underline-color")]
        underline_color: Some(Color::Reset),
        add_modifier: Modifier::empty(),
        sub_modifier: Modifier::empty(),
    },
    buffer[(0, 0)].style(),
);

Fields

fg: Option<Color>

bg: Option<Color>

underline_color: Option<Color>

add_modifier: Modifier

sub_modifier: Modifier

Implementations

impl Style

pub const fn new() -> Self

pub const fn reset() -> Self

Returns a Style resetting all properties.

pub const fn fg(self, color: Color) -> Self

Changes the foreground color.

Examples

use ratatui::style::{Color, Style};

let style = Style::default().fg(Color::Blue);
let diff = Style::default().fg(Color::Red);
assert_eq!(style.patch(diff), Style::default().fg(Color::Red));

pub const fn bg(self, color: Color) -> Self

Changes the background color.

Examples

use ratatui::style::{Color, Style};

let style = Style::default().bg(Color::Blue);
let diff = Style::default().bg(Color::Red);
assert_eq!(style.patch(diff), Style::default().bg(Color::Red));

pub const fn underline_color(self, color: Color) -> Self

Changes the underline color. The text must be underlined with a modifier for this to work.

This uses a non-standard ANSI escape sequence. It is supported by most terminal emulators, but is only implemented in the crossterm backend and enabled by the underline-color feature flag.

See Wikipedia code 58 and 59 for more information.

Examples

use ratatui::style::{Color, Modifier, Style};

let style = Style::default()
    .underline_color(Color::Blue)
    .add_modifier(Modifier::UNDERLINED);
let diff = Style::default()
    .underline_color(Color::Red)
    .add_modifier(Modifier::UNDERLINED);
assert_eq!(
    style.patch(diff),
    Style::default()
        .underline_color(Color::Red)
        .add_modifier(Modifier::UNDERLINED)
);

pub const fn add_modifier(self, modifier: Modifier) -> Self

Changes the text emphasis.

When applied, it adds the given modifier to the Style modifiers.

Examples

use ratatui::style::{Modifier, Style};

let style = Style::default().add_modifier(Modifier::BOLD);
let diff = Style::default().add_modifier(Modifier::ITALIC);
let patched = style.patch(diff);
assert_eq!(patched.add_modifier, Modifier::BOLD | Modifier::ITALIC);
assert_eq!(patched.sub_modifier, Modifier::empty());

pub const fn remove_modifier(self, modifier: Modifier) -> Self

Changes the text emphasis.

When applied, it removes the given modifier from the Style modifiers.

Examples

use ratatui::style::{Modifier, Style};

let style = Style::default().add_modifier(Modifier::BOLD | Modifier::ITALIC);
let diff = Style::default().remove_modifier(Modifier::ITALIC);
let patched = style.patch(diff);
assert_eq!(patched.add_modifier, Modifier::BOLD);
assert_eq!(patched.sub_modifier, Modifier::ITALIC);

pub fn patch<S: Into<Self>>(self, other: S) -> Self

Results in a combined style that is equivalent to applying the two individual styles to a style one after the other.

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::{Color, Modifier, Style};

let style_1 = Style::default().fg(Color::Yellow);
let style_2 = Style::default().bg(Color::Red);
let combined = style_1.patch(style_2);
assert_eq!(
    Style::default().patch(style_1).patch(style_2),
    Style::default().patch(combined)
);

Trait Implementations

impl Clone for Style

fn clone(&self) -> Style

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Style

A custom debug implementation that prints only the fields that are not the default, and unwraps the Options.

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

Formats the value using the given formatter.

impl Default for Style

fn default() -> Style

Returns the “default value” for a type.

impl From<(Color, Color)> for Style

fn from((fg, bg): (Color, Color)) -> Self

Creates a new Style with the given foreground and background colors.

Example

use ratatui::style::{Color, Style};

// red foreground, blue background
let style = Style::from((Color::Red, Color::Blue));
// default foreground, blue background
let style = Style::from((Color::Reset, Color::Blue));

impl From<(Color, Color, Modifier)> for Style

fn from((fg, bg, modifier): (Color, Color, Modifier)) -> Self

Creates a new Style with the given foreground and background colors and modifier added.

To specify multiple modifiers, use the | operator.

Example

use ratatui::style::{Color, Modifier, Style};

// red foreground, blue background, add bold and italic
let style = Style::from((Color::Red, Color::Blue, Modifier::BOLD | Modifier::ITALIC));

impl From<(Color, Color, Modifier, Modifier)> for Style

fn from( (fg, bg, add_modifier, sub_modifier): (Color, Color, Modifier, Modifier), ) -> Self

Creates a new Style with the given foreground and background colors and modifiers added and removed.

Example

use ratatui::style::{Color, Modifier, Style};

// red foreground, blue background, add bold and italic, remove dim
let style = Style::from((
    Color::Red,
    Color::Blue,
    Modifier::BOLD | Modifier::ITALIC,
    Modifier::DIM,
));

impl From<(Color, Modifier)> for Style

fn from((fg, modifier): (Color, Modifier)) -> Self

Creates a new Style with the given foreground color and modifier added.

To specify multiple modifiers, use the | operator.

Example

use ratatui::style::{Color, Modifier, Style};

// red foreground, add bold and italic
let style = Style::from((Color::Red, Modifier::BOLD | Modifier::ITALIC));

impl From<(Modifier, Modifier)> for Style

fn from((add_modifier, sub_modifier): (Modifier, Modifier)) -> Self

Creates a new Style with the given modifiers added and removed.

Example

use ratatui::style::{Modifier, Style};

// add bold and italic, remove dim
let style = Style::from((Modifier::BOLD | Modifier::ITALIC, Modifier::DIM));

impl From<Color> for Style

fn from(color: Color) -> Self

Creates a new Style with the given foreground color.

To specify a foreground and background color, use the from((fg, bg)) constructor.

Example

use ratatui::style::{Color, Style};

let style = Style::from(Color::Red);

impl From<ContentStyle> for Style

fn from(value: ContentStyle) -> Self

Converts to this type from the input type.

impl From<Modifier> for Style

fn from(modifier: Modifier) -> Self

Creates a new Style with the given modifier added.

To specify multiple modifiers, use the | operator.

To specify modifiers to add and remove, use the from((add_modifier, sub_modifier)) constructor.

Example

use ratatui::style::{Style, Modifier};

// add bold and italic
let style = Style::from(Modifier::BOLD|Modifier::ITALIC);

impl Hash for Style

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 PartialEq for Style

fn eq(&self, other: &Style) -> 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 Styled for Style

type Item = Style

fn style(&self) -> Style

Returns the style of the object.

fn set_style<S: Into<Self>>(self, style: S) -> Self::Item

Sets the style of the object.

impl Copy for Style

impl Eq for Style

impl StructuralPartialEq for Style