Struct Style

Source

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

Expand description

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

use ratatui_core::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_core::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_core::style::{Color, Modifier, Style};
use ratatui_core::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_core::buffer::Buffer;
use ratatui_core::layout::Rect;
use ratatui_core::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_core::buffer::Buffer;
use ratatui_core::layout::Rect;
use ratatui_core::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>

The foreground color.

§bg: Option<Color>

The background color.

§underline_color: Option<Color>

The underline color.

§add_modifier: Modifier

The modifiers to add.

§sub_modifier: Modifier

The modifiers to remove.

Implementations§

Source §

impl Style

Source

pub const fn new() -> Style

Returns a Style with default properties.

Source

pub const fn reset() -> Style

Returns a Style resetting all properties.

Source

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

Changes the foreground color.

§Examples

use ratatui_core::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));

Source

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

Changes the background color.

§Examples

use ratatui_core::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));

Source

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

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

Source

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

Changes the text emphasis.

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

§Examples

use ratatui_core::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());

Source

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

Changes the text emphasis.

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

§Examples

use ratatui_core::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);

Source

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

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_core::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§

Source §

impl Clone for Style

Source §

fn clone(&self) -> Style

Returns a copy of the value. Read more

1.0.0 · Source§

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

Performs copy-assignment from source. Read more

Source §

impl Debug for Style

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

Source §

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

Formats the value using the given formatter. Read more

Source §

impl Default for Style

Source §

fn default() -> Style

Returns the “default value” for a type. Read more

Source §

impl<'de> Deserialize<'de> for Style

Source §

fn deserialize<D>( deserializer: D, ) -> Result<Style, <D as Deserializer<'de>>::Error>
where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer. Read more

Source §

impl From<(Color, Color)> for Style

Source §

fn from(_: (Color, Color)) -> Style

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

§Example

use ratatui_core::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));

Source §

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

Source §

fn from(_: (Color, Color, Modifier)) -> Style

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

To specify multiple modifiers, use the | operator.

§Example

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

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

Source §

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

Source §

fn from(_: (Color, Color, Modifier, Modifier)) -> Style

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

§Example

use ratatui_core::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,
));

Source §

impl From<(Color, Modifier)> for Style

Source §

fn from(_: (Color, Modifier)) -> Style

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

To specify multiple modifiers, use the | operator.

§Example

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

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

Source §

impl From<(Modifier, Modifier)> for Style

Source §

fn from(_: (Modifier, Modifier)) -> Style

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

§Example

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

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

Source §

impl From<Color> for Style

Source §

fn from(color: Color) -> Style

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

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

Source §

impl From<Modifier> for Style

Source §

fn from(modifier: Modifier) -> Style

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

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

Source §

impl FromCrossterm<ContentStyle> for Style

Source §

fn from_crossterm(value: ContentStyle) -> Style

Converts the crossterm type to a ratatui type.

Source §