Enum Color

pub enum Color {
    Reset,
    Black,
    Red,
    Green,
    Yellow,
    Blue,
    Magenta,
    Cyan,
    Gray,
    DarkGray,
    LightRed,
    LightGreen,
    LightYellow,
    LightBlue,
    LightMagenta,
    LightCyan,
    White,
    Rgb(u8, u8, u8),
    Indexed(u8),
}

ANSI Color

All colors from the ANSI color table are supported (though some names are not exactly the same).

Color Name	Color	Foreground	Background
black	Color::Black	30	40
red	Color::Red	31	41
green	Color::Green	32	42
yellow	Color::Yellow	33	43
blue	Color::Blue	34	44
magenta	Color::Magenta	35	45
cyan	Color::Cyan	36	46
gray*	Color::Gray	37	47
darkgray*	Color::DarkGray	90	100
lightred	Color::LightRed	91	101
lightgreen	Color::LightGreen	92	102
lightyellow	Color::LightYellow	93	103
lightblue	Color::LightBlue	94	104
lightmagenta	Color::LightMagenta	95	105
lightcyan	Color::LightCyan	96	106
white*	Color::White	97	107

• gray is sometimes called white - this is not supported as we use white for bright white
• gray is sometimes called silver - this is supported
• darkgray is sometimes called light black or bright black (both are supported)
• white is sometimes called light white or bright white (both are supported)
• we support bright and light prefixes for all colors
• we support - and _ and as separators for all colors
• we support both gray and grey spellings

From<Color> for Style is implemented by creating a style with the foreground color set to the given color. This allows you to use colors anywhere that accepts Into<Style>.

Example

use std::str::FromStr;

use ratatui::style::Color;

assert_eq!(Color::from_str("red"), Ok(Color::Red));
assert_eq!("red".parse(), Ok(Color::Red));
assert_eq!("lightred".parse(), Ok(Color::LightRed));
assert_eq!("light red".parse(), Ok(Color::LightRed));
assert_eq!("light-red".parse(), Ok(Color::LightRed));
assert_eq!("light_red".parse(), Ok(Color::LightRed));
assert_eq!("lightRed".parse(), Ok(Color::LightRed));
assert_eq!("bright red".parse(), Ok(Color::LightRed));
assert_eq!("bright-red".parse(), Ok(Color::LightRed));
assert_eq!("silver".parse(), Ok(Color::Gray));
assert_eq!("dark-grey".parse(), Ok(Color::DarkGray));
assert_eq!("dark gray".parse(), Ok(Color::DarkGray));
assert_eq!("light-black".parse(), Ok(Color::DarkGray));
assert_eq!("white".parse(), Ok(Color::White));
assert_eq!("bright white".parse(), Ok(Color::White));

Variants

Reset

Resets the foreground or background color

Black

ANSI Color: Black. Foreground: 30, Background: 40

Red

ANSI Color: Red. Foreground: 31, Background: 41

Green

ANSI Color: Green. Foreground: 32, Background: 42

Yellow

ANSI Color: Yellow. Foreground: 33, Background: 43

Blue

ANSI Color: Blue. Foreground: 34, Background: 44

Magenta

ANSI Color: Magenta. Foreground: 35, Background: 45

Cyan

ANSI Color: Cyan. Foreground: 36, Background: 46

Gray

ANSI Color: White. Foreground: 37, Background: 47

Note that this is sometimes called silver or white but we use white for bright white

DarkGray

ANSI Color: Bright Black. Foreground: 90, Background: 100

Note that this is sometimes called light black or bright black but we use dark gray

LightRed

ANSI Color: Bright Red. Foreground: 91, Background: 101

LightGreen

ANSI Color: Bright Green. Foreground: 92, Background: 102

LightYellow

ANSI Color: Bright Yellow. Foreground: 93, Background: 103

LightBlue

ANSI Color: Bright Blue. Foreground: 94, Background: 104

LightMagenta

ANSI Color: Bright Magenta. Foreground: 95, Background: 105

LightCyan

ANSI Color: Bright Cyan. Foreground: 96, Background: 106

White

ANSI Color: Bright White. Foreground: 97, Background: 107 Sometimes called bright white or light white in some terminals

Rgb(u8, u8, u8)

An RGB color.

Note that only terminals that support 24-bit true color will display this correctly. Notably versions of Windows Terminal prior to Windows 10 and macOS Terminal.app do not support this.

If the terminal does not support true color, code using the TermwizBackend will fallback to the default text color. Crossterm and Termion do not have this capability and the display will be unpredictable (e.g. Terminal.app may display glitched blinking text). See https://github.com/ratatui/ratatui/issues/475 for an example of this problem.

See also: https://en.wikipedia.org/wiki/ANSI_escape_code#24-bit

Indexed(u8)

An 8-bit 256 color.

See also https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit

Implementations

impl Color

pub const fn from_u32(u: u32) -> Self

Convert a u32 to a Color

The u32 should be in the format 0x00RRGGBB.

impl Color

pub fn from_hsl(hsl: Hsl) -> Self

Available on crate feature palette only.

Converts a HSL representation to a Color::Rgb instance.

The from_hsl function converts the Hue, Saturation and Lightness values to a corresponding Color RGB equivalent.

Hue values should be in the range [-180..180]. Values outside this range are normalized by wrapping.

Saturation and L values should be in the range [0.0..1.0]. Values outside this range are clamped.

Clamping to valid ranges happens before conversion to RGB.

Examples

use ratatui::{palette::Hsl, style::Color};

// Minimum Lightness is black
let color: Color = Color::from_hsl(Hsl::new(0.0, 0.0, 0.0));
assert_eq!(color, Color::Rgb(0, 0, 0));

// Maximum Lightness is white
let color: Color = Color::from_hsl(Hsl::new(0.0, 0.0, 1.0));
assert_eq!(color, Color::Rgb(255, 255, 255));

// Minimum Saturation is fully desaturated red = gray
let color: Color = Color::from_hsl(Hsl::new(0.0, 0.0, 0.5));
assert_eq!(color, Color::Rgb(128, 128, 128));

// Bright red
let color: Color = Color::from_hsl(Hsl::new(0.0, 1.0, 0.5));
assert_eq!(color, Color::Rgb(255, 0, 0));

// Bright blue
let color: Color = Color::from_hsl(Hsl::new(-120.0, 1.0, 0.5));
assert_eq!(color, Color::Rgb(0, 0, 255));

pub fn from_hsluv(hsluv: Hsluv) -> Self

Available on crate feature palette only.

Converts a HSLuv representation to a Color::Rgb instance.

The from_hsluv function converts the Hue, Saturation and Lightness values to a corresponding Color RGB equivalent.

Hue values should be in the range [-180.0..180.0]. Values outside this range are normalized by wrapping.

Saturation and L values should be in the range [0.0..100.0]. Values outside this range are clamped.

Clamping to valid ranges happens before conversion to RGB.

Examples

use ratatui::{palette::Hsluv, style::Color};

// Minimum Lightness is black
let color: Color = Color::from_hsluv(Hsluv::new(0.0, 100.0, 0.0));
assert_eq!(color, Color::Rgb(0, 0, 0));

// Maximum Lightness is white
let color: Color = Color::from_hsluv(Hsluv::new(0.0, 0.0, 100.0));
assert_eq!(color, Color::Rgb(255, 255, 255));

// Minimum Saturation is fully desaturated red = gray
let color = Color::from_hsluv(Hsluv::new(0.0, 0.0, 50.0));
assert_eq!(color, Color::Rgb(119, 119, 119));

// Bright Red
let color = Color::from_hsluv(Hsluv::new(12.18, 100.0, 53.2));
assert_eq!(color, Color::Rgb(255, 0, 0));

// Bright Blue
let color = Color::from_hsluv(Hsluv::new(-94.13, 100.0, 32.3));
assert_eq!(color, Color::Rgb(0, 0, 255));

Trait Implementations

impl Clone for Color

fn clone(&self) -> Color

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Color

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

Formats the value using the given formatter.

impl Default for Color

fn default() -> Color

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Color

Available on crate feature serde only.

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

This is used to deserialize a value into Color via serde.

This implementation uses the FromStr trait to deserialize strings, so named colours, RGB, and indexed values are able to be deserialized. In addition, values that were produced by the the older serialization implementation of Color are also able to be deserialized.

Prior to v0.26.0, Ratatui would be serialized using a map for indexed and RGB values, for examples in json {"Indexed": 10} and {"Rgb": [255, 0, 255]} respectively. Now they are serialized using the string representation of the index and the RGB hex value, for example in json it would now be "10" and "#FF00FF" respectively.

See the Color documentation for more information on color names.

Examples

use std::str::FromStr;

use ratatui::style::Color;

#[derive(Debug, serde::Deserialize)]
struct Theme {
    color: Color,
}

let theme: Theme = serde_json::from_str(r#"{"color": "bright-white"}"#)?;
assert_eq!(theme.color, Color::White);

let theme: Theme = serde_json::from_str(r##"{"color": "#00FF00"}"##)?;
assert_eq!(theme.color, Color::Rgb(0, 255, 0));

let theme: Theme = serde_json::from_str(r#"{"color": "42"}"#)?;
assert_eq!(theme.color, Color::Indexed(42));

let err = serde_json::from_str::<Theme>(r#"{"color": "invalid"}"#).unwrap_err();
assert!(err.is_data());
assert_eq!(
    err.to_string(),
    "Failed to parse Colors at line 1 column 20"
);

// Deserializing from the previous serialization implementation
let theme: Theme = serde_json::from_str(r#"{"color": {"Rgb":[255,0,255]}}"#)?;
assert_eq!(theme.color, Color::Rgb(255, 0, 255));

let theme: Theme = serde_json::from_str(r#"{"color": {"Indexed":10}}"#)?;
assert_eq!(theme.color, Color::Indexed(10));

impl Display for Color

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

Formats the value using the given formatter.

impl From<AnsiColor> for Color

Available on crate feature termwiz only.

fn from(value: AnsiColor) -> Self

Converts to this type from the input type.

impl From<AnsiValue> for Color

Available on non-Windows and crate feature termion only.

fn from(value: AnsiValue) -> Self

Converts to this type from the input type.

impl From<Black> for Color

Available on non-Windows and crate feature termion only.

fn from(_: Black) -> Self

Converts to this type from the input type.

impl From<Blue> for Color

Available on non-Windows and crate feature termion only.

fn from(_: Blue) -> Self

Converts to this type from the input type.

impl From<Color> for Color

Available on crate feature crossterm only.

fn from(color: Color) -> Self

Converts to this type from the input type.

impl From<Color> for Color

Available on crate feature crossterm only.

fn from(value: CColor) -> Self

Converts to this type from the input type.

impl From<Color> for ColorAttribute

Available on crate feature termwiz only.

fn from(color: Color) -> Self

Converts to this type from the input type.

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<ColorAttribute> for Color

Available on crate feature termwiz only.

fn from(value: ColorAttribute) -> Self

Converts to this type from the input type.

impl From<ColorSpec> for Color

Available on crate feature termwiz only.

fn from(value: ColorSpec) -> Self

Converts to this type from the input type.

impl From<Cyan> for Color

Available on non-Windows and crate feature termion only.

fn from(_: Cyan) -> Self

Converts to this type from the input type.

impl From<Green> for Color

Available on non-Windows and crate feature termion only.

fn from(_: Green) -> Self

Converts to this type from the input type.

impl From<LightBlack> for Color

Available on non-Windows and crate feature termion only.

fn from(_: LightBlack) -> Self

Converts to this type from the input type.

impl From<LightBlue> for Color

Available on non-Windows and crate feature termion only.

fn from(_: LightBlue) -> Self

Converts to this type from the input type.

impl From<LightCyan> for Color

Available on non-Windows and crate feature termion only.

fn from(_: LightCyan) -> Self

Converts to this type from the input type.

impl From<LightGreen> for Color

Available on non-Windows and crate feature termion only.

fn from(_: LightGreen) -> Self

Converts to this type from the input type.

impl From<LightMagenta> for Color

Available on non-Windows and crate feature termion only.

fn from(_: LightMagenta) -> Self

Converts to this type from the input type.

impl From<LightRed> for Color

Available on non-Windows and crate feature termion only.

fn from(_: LightRed) -> Self

Converts to this type from the input type.

impl From<LightWhite> for Color

Available on non-Windows and crate feature termion only.

fn from(_: LightWhite) -> Self

Converts to this type from the input type.

impl From<LightYellow> for Color

Available on non-Windows and crate feature termion only.

fn from(_: LightYellow) -> Self

Converts to this type from the input type.

impl From<LinearRgba> for Color

Available on crate feature termwiz only.

fn from(value: LinearRgba) -> Self

Converts to this type from the input type.

impl From<Magenta> for Color

Available on non-Windows and crate feature termion only.

fn from(_: Magenta) -> Self

Converts to this type from the input type.

impl From<Red> for Color

Available on non-Windows and crate feature termion only.

fn from(_: Red) -> Self

Converts to this type from the input type.

impl From<Reset> for Color

Available on non-Windows and crate feature termion only.

fn from(_: Reset) -> Self

Converts to this type from the input type.

impl<T> From<Rgb<Linear<Srgb>, T>> for Color

where T: Real + Powf + MulSub + Arithmetics + PartialCmp + Clone + IntoStimulus<u8>, T::Mask: LazySelect<T>,

Available on crate feature palette only.

Convert a palette::LinSrgb color to a Color.

Note: this conversion only works for floating point linear sRGB colors. If you have a linear sRGB color in another format, you need to convert it to floating point first.

Examples

use palette::LinSrgb;
use ratatui::style::Color;

let color = Color::from(LinSrgb::new(1.0f32, 0.0, 0.0));
assert_eq!(color, Color::Rgb(255, 0, 0));

fn from(color: LinSrgb<T>) -> Self

Converts to this type from the input type.

impl<T: IntoStimulus<u8>> From<Rgb<Srgb, T>> for Color

Available on crate feature palette only.

Convert an palette::Srgb color to a Color.

Examples

use palette::Srgb;
use ratatui::style::Color;

let color = Color::from(Srgb::new(1.0f32, 0.0, 0.0));
assert_eq!(color, Color::Rgb(255, 0, 0));

fn from(color: Srgb<T>) -> Self

Converts to this type from the input type.

impl From<Rgb> for Color

Available on non-Windows and crate feature termion only.

fn from(value: Rgb) -> Self

Converts to this type from the input type.

impl From<RgbColor> for Color

Available on crate feature termwiz only.

fn from(value: RgbColor) -> Self

Converts to this type from the input type.

impl From<SrgbaTuple> for Color

Available on crate feature termwiz only.

fn from(value: SrgbaTuple) -> Self

Converts to this type from the input type.

impl From<White> for Color

Available on non-Windows and crate feature termion only.

fn from(_: White) -> Self

Converts to this type from the input type.

impl From<Yellow> for Color

Available on non-Windows and crate feature termion only.

fn from(_: Yellow) -> Self

Converts to this type from the input type.

impl FromStr for Color

Converts a string representation to a Color instance.

The from_str function attempts to parse the given string and convert it to the corresponding Color variant. It supports named colors, RGB values, and indexed colors. If the string cannot be parsed, a ParseColorError is returned.

See the Color documentation for more information on the supported color names.

Examples

use std::str::FromStr;

use ratatui::style::Color;

let color: Color = Color::from_str("blue").unwrap();
assert_eq!(color, Color::Blue);

let color: Color = Color::from_str("#FF0000").unwrap();
assert_eq!(color, Color::Rgb(255, 0, 0));

let color: Color = Color::from_str("10").unwrap();
assert_eq!(color, Color::Indexed(10));

let color: Result<Color, _> = Color::from_str("invalid_color");
assert!(color.is_err());

type Err = ParseColorError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Hash for Color

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 Color

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

Available on crate feature serde only.

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

This utilises the fmt::Display implementation for serialization.

impl Copy for Color

impl Eq for Color

impl StructuralPartialEq for Color