Skip to content

Color

This module contains a powerful Color class which Textual uses to manipulate colors.

Named colors

The following named colors are used by the parse method.

colors ┏━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┓ Name                  hex    RGB               Color                ┡━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━┩ "aliceblue"#F0F8FFrgb(240248255) "ansi_black"#000000rgb(000) "ansi_blue"#000080rgb(00128) "ansi_bright_black"#808080rgb(128128128) "ansi_bright_blue"#0000FFrgb(00255) "ansi_bright_cyan"#00FFFFrgb(0255255) "ansi_bright_green"#00FF00rgb(02550) "ansi_bright_magenta"#FF00FFrgb(2550255) "ansi_bright_red"#FF0000rgb(25500) "ansi_bright_white"#FFFFFFrgb(255255255) "ansi_bright_yellow"#FFFF00rgb(2552550) "ansi_cyan"#008080rgb(0128128) "ansi_green"#008000rgb(01280) "ansi_magenta"#800080rgb(1280128) "ansi_red"#800000rgb(12800) "ansi_white"#C0C0C0rgb(192192192) "ansi_yellow"#808000rgb(1281280) "antiquewhite"#FAEBD7rgb(250235215) "aqua"#00FFFFrgb(0255255) "aquamarine"#7FFFD4rgb(127255212) "azure"#F0FFFFrgb(240255255) "beige"#F5F5DCrgb(245245220) "bisque"#FFE4C4rgb(255228196) "black"#000000rgb(000) "blanchedalmond"#FFEBCDrgb(255235205) "blue"#0000FFrgb(00255) "blueviolet"#8A2BE2rgb(13843226) "brown"#A52A2Argb(1654242) "burlywood"#DEB887rgb(222184135) "cadetblue"#5F9EA0rgb(95158160) "chartreuse"#7FFF00rgb(1272550) "chocolate"#D2691Ergb(21010530) "coral"#FF7F50rgb(25512780) "cornflowerblue"#6495EDrgb(100149237) "cornsilk"#FFF8DCrgb(255248220) "crimson"#DC143Crgb(2202060) "cyan"#00FFFFrgb(0255255) "darkblue"#00008Brgb(00139) "darkcyan"#008B8Brgb(0139139) "darkgoldenrod"#B8860Brgb(18413411) "darkgray"#A9A9A9rgb(169169169) "darkgreen"#006400rgb(01000) "darkgrey"#A9A9A9rgb(169169169) "darkkhaki"#BDB76Brgb(189183107) "darkmagenta"#8B008Brgb(1390139) "darkolivegreen"#556B2Frgb(8510747) "darkorange"#FF8C00rgb(2551400) "darkorchid"#9932CCrgb(15350204) "darkred"#8B0000rgb(13900) "darksalmon"#E9967Argb(233150122) "darkseagreen"#8FBC8Frgb(143188143) "darkslateblue"#483D8Brgb(7261139) "darkslategray"#2F4F4Frgb(477979) "darkslategrey"#2F4F4Frgb(477979) "darkturquoise"#00CED1rgb(0206209) "darkviolet"#9400D3rgb(1480211) "deeppink"#FF1493rgb(25520147) "deepskyblue"#00BFFFrgb(0191255) "dimgray"#696969rgb(105105105) "dimgrey"#696969rgb(105105105) "dodgerblue"#1E90FFrgb(30144255) "firebrick"#B22222rgb(1783434) "floralwhite"#FFFAF0rgb(255250240) "forestgreen"#228B22rgb(3413934) "fuchsia"#FF00FFrgb(2550255) "gainsboro"#DCDCDCrgb(220220220) "ghostwhite"#F8F8FFrgb(248248255) "gold"#FFD700rgb(2552150) "goldenrod"#DAA520rgb(21816532) "gray"#808080rgb(128128128) "green"#008000rgb(01280) "greenyellow"#ADFF2Frgb(17325547) "grey"#808080rgb(128128128) "honeydew"#F0FFF0rgb(240255240) "hotpink"#FF69B4rgb(255105180) "indianred"#CD5C5Crgb(2059292) "indigo"#4B0082rgb(750130) "ivory"#FFFFF0rgb(255255240) "khaki"#F0E68Crgb(240230140) "lavender"#E6E6FArgb(230230250) "lavenderblush"#FFF0F5rgb(255240245) "lawngreen"#7CFC00rgb(1242520) "lemonchiffon"#FFFACDrgb(255250205) "lightblue"#ADD8E6rgb(173216230) "lightcoral"#F08080rgb(240128128) "lightcyan"#E0FFFFrgb(224255255) "lightgoldenrodyellow"#FAFAD2rgb(250250210) "lightgray"#D3D3D3rgb(211211211) "lightgreen"#90EE90rgb(144238144) "lightgrey"#D3D3D3rgb(211211211) "lightpink"#FFB6C1rgb(255182193) "lightsalmon"#FFA07Argb(255160122) "lightseagreen"#20B2AArgb(32178170) "lightskyblue"#87CEFArgb(135206250) "lightslategray"#778899rgb(119136153) "lightslategrey"#778899rgb(119136153) "lightsteelblue"#B0C4DErgb(176196222) "lightyellow"#FFFFE0rgb(255255224) "lime"#00FF00rgb(02550) "limegreen"#32CD32rgb(5020550) "linen"#FAF0E6rgb(250240230) "magenta"#FF00FFrgb(2550255) "maroon"#800000rgb(12800) "mediumaquamarine"#66CDAArgb(102205170) "mediumblue"#0000CDrgb(00205) "mediumorchid"#BA55D3rgb(18685211) "mediumpurple"#9370DBrgb(147112219) "mediumseagreen"#3CB371rgb(60179113) "mediumslateblue"#7B68EErgb(123104238) "mediumspringgreen"#00FA9Argb(0250154) "mediumturquoise"#48D1CCrgb(72209204) "mediumvioletred"#C71585rgb(19921133) "midnightblue"#191970rgb(2525112) "mintcream"#F5FFFArgb(245255250) "mistyrose"#FFE4E1rgb(255228225) "moccasin"#FFE4B5rgb(255228181) "navajowhite"#FFDEADrgb(255222173) "navy"#000080rgb(00128) "oldlace"#FDF5E6rgb(253245230) "olive"#808000rgb(1281280) "olivedrab"#6B8E23rgb(10714235) "orange"#FFA500rgb(2551650) "orangered"#FF4500rgb(255690) "orchid"#DA70D6rgb(218112214) "palegoldenrod"#EEE8AArgb(238232170) "palegreen"#98FB98rgb(152251152) "paleturquoise"#AFEEEErgb(175238238) "palevioletred"#DB7093rgb(219112147) "papayawhip"#FFEFD5rgb(255239213) "peachpuff"#FFDAB9rgb(255218185) "peru"#CD853Frgb(20513363) "pink"#FFC0CBrgb(255192203) "plum"#DDA0DDrgb(221160221) "powderblue"#B0E0E6rgb(176224230) "purple"#800080rgb(1280128) "rebeccapurple"#663399rgb(10251153) "red"#FF0000rgb(25500) "rosybrown"#BC8F8Frgb(188143143) "royalblue"#4169E1rgb(65105225) "saddlebrown"#8B4513rgb(1396919) "salmon"#FA8072rgb(250128114) "sandybrown"#F4A460rgb(24416496) "seagreen"#2E8B57rgb(4613987) "seashell"#FFF5EErgb(255245238) "sienna"#A0522Drgb(1608245) "silver"#C0C0C0rgb(192192192) "skyblue"#87CEEBrgb(135206235) "slateblue"#6A5ACDrgb(10690205) "slategray"#708090rgb(112128144) "slategrey"#708090rgb(112128144) "snow"#FFFAFArgb(255250250) "springgreen"#00FF7Frgb(0255127) "steelblue"#4682B4rgb(70130180) "tan"#D2B48Crgb(210180140) "teal"#008080rgb(0128128) "thistle"#D8BFD8rgb(216191216) "tomato"#FF6347rgb(2559971) "turquoise"#40E0D0rgb(64224208) "violet"#EE82EErgb(238130238) "wheat"#F5DEB3rgb(245222179) "white"#FFFFFFrgb(255255255) "whitesmoke"#F5F5F5rgb(245245245) "yellow"#FFFF00rgb(2552550) "yellowgreen"#9ACD32rgb(15420550) └────────────────────────┴─────────┴────────────────────┴──────────────────────┘

BLACK module-attribute

BLACK: Final = Color(0, 0, 0)

A constant for pure black.

WHITE module-attribute

WHITE: Final = Color(255, 255, 255)

A constant for pure white.

Color class

Bases: NamedTuple

A class to represent a color.

Colors are stored as three values representing the degree of red, green, and blue in a color, and a fourth "alpha" value which defines where the color lies on a gradient of opaque to transparent.

Example
>>> from textual.color import Color
>>> color = Color.parse("red")
>>> color
Color(255, 0, 0)
>>> color.darken(0.5)
Color(98, 0, 0)
>>> color + Color.parse("green")
Color(0, 128, 0)
>>> color_with_alpha = Color(100, 50, 25, 0.5)
>>> color_with_alpha
Color(100, 50, 25, a=0.5)
>>> color + color_with_alpha
Color(177, 25, 12)

a instance-attribute class-attribute

a: float = 1.0

Alpha (opacity) component in range 0 to 1.

b instance-attribute

b: int

Blue component in range 0 to 255.

brightness property

brightness: float

The human perceptual brightness.

A value of 1 is returned for pure white, and 0 for pure black. Other colors lie on a gradient between the two extremes.

clamped property

clamped: Color

A clamped color (this color with all values in expected range).

css property

css: str

The color in CSS RGB or RGBA form.

For example, "rgb(10,20,30)" for an RGB color, or "rgb(50,70,80,0.5)" for an RGBA color.

g instance-attribute

g: int

Green component in range 0 to 255.

hex property

hex: str

The color in CSS hex form, with 6 digits for RGB, and 8 digits for RGBA.

For example, "#46b3de" for an RGB color, or "#3342457f" for a color with alpha.

hex6 property

hex6: str

The color in CSS hex form, with 6 digits for RGB. Alpha is ignored.

For example, "#46b3de".

hsl property

hsl: HSL

This color in HSL format.

HSL color is an alternative way of representing a color, which can be used in certain color calculations.

Returns
Type Description
HSL

Color encoded in HSL format.

inverse property

inverse: Color

The inverse of this color.

Returns
Type Description
Color

Inverse color.

is_transparent property

is_transparent: bool

Is the color transparent (i.e. has 0 alpha)?

monochrome property

monochrome: Color

A monochrome version of this color.

Returns
Type Description
Color

The monochrome (black and white) version of this color.

normalized property

normalized: tuple[float, float, float]

A tuple of the color components normalized to between 0 and 1.

Returns
Type Description
tuple[float, float, float]

Normalized components.

r instance-attribute

r: int

Red component in range 0 to 255.

rgb property

rgb: tuple[int, int, int]

The red, green, and blue color components as a tuple of ints.

rich_color property

rich_color: RichColor

This color encoded in Rich's Color class.

Returns
Type Description
RichColor

A color object as used by Rich.

blend cached

def blend(self, destination, factor, alpha=None):

Generate a new color between two colors.

This method calculates a new color on a gradient. The position on the gradient is given by factor, which is a float between 0 and 1, where 0 is the original color, and 1 is the destination color. A value of gradient between the two extremes produces a color somewhere between the two end points.

Parameters
Parameter Default Description
destination
Color
required

Another color.

factor
float
required

A blend factor, 0 -> 1.

alpha
float | None
None

New alpha for result.

Returns
Type Description
Color

A new color.

darken cached

def darken(self, amount, alpha=None):

Darken the color by a given amount.

Parameters
Parameter Default Description
amount
float
required

Value between 0-1 to reduce luminance by.

alpha
float | None
None

Alpha component for new color or None to copy alpha.

Returns
Type Description
Color

New color.

from_hsl classmethod

def from_hsl(cls, h, s, l):

Create a color from HLS components.

Parameters
Parameter Default Description
h
float
required

Hue.

l
float
required

Lightness.

s
float
required

Saturation.

Returns
Type Description
Color

A new color.

from_rich_color classmethod

def from_rich_color(cls, rich_color):

Create a new color from Rich's Color class.

Parameters
Parameter Default Description
rich_color
RichColor
required

An instance of Rich color.

Returns
Type Description
Color

A new Color instance.

get_contrast_text cached

def get_contrast_text(self, alpha=0.95):

Get a light or dark color that best contrasts this color, for use with text.

Parameters
Parameter Default Description
alpha
float
0.95

An alpha value to apply to the result.

Returns
Type Description
Color

A new color, either an off-white or off-black.

lighten method

def lighten(self, amount, alpha=None):

Lighten the color by a given amount.

Parameters
Parameter Default Description
amount
float
required

Value between 0-1 to increase luminance by.

alpha
float | None
None

Alpha component for new color or None to copy alpha.

Returns
Type Description
Color

New color.

multiply_alpha method

def multiply_alpha(self, alpha):

Create a new color, multiplying the alpha by a constant.

Parameters
Parameter Default Description
alpha
float
required

A value to multiple the alpha by (expected to be in the range 0 to 1).

Returns
Type Description
Color

A new color.

parse classmethod cached

def parse(cls, color_text):

Parse a string containing a named color or CSS-style color.

Colors may be parsed from the following formats:

  • Text beginning with a # is parsed as a hexadecimal color code, where R, G, B, and A must be hexadecimal digits (0-9A-F):

    • #RGB
    • #RGBA
    • #RRGGBB
    • #RRGGBBAA
  • Alternatively, RGB colors can also be specified in the format that follows, where R, G, and B must be numbers between 0 and 255 and A must be a value between 0 and 1:

    • rgb(R,G,B)
    • rgb(R,G,B,A)
  • The HSL model can also be used, with a syntax similar to the above, if H is a value between 0 and 360, S and L are percentages, and A is a value between 0 and 1:

    • hsl(H,S,L)
    • hsla(H,S,L,A)

Any other formats will raise a ColorParseError.

Parameters
Parameter Default Description
color_text
str | Color
required

Text with a valid color format. Color objects will be returned unmodified.

Raises
Type Description
ColorParseError

If the color is not encoded correctly.

Returns
Type Description
Color

Instance encoding the color specified by the argument.

with_alpha method

def with_alpha(self, alpha):

Create a new color with the given alpha.

Parameters
Parameter Default Description
alpha
float
required

New value for alpha.

Returns
Type Description
Color

A new color.

ColorParseError class

def __init__(self, message, suggested_color=None):

Bases: Exception

A color failed to parse.

Parameters
Parameter Default Description
message
str
required

The error message

suggested_color
str | None
None

A close color we can suggest.

Gradient class

def __init__(self, *stops):

Defines a color gradient.

A gradient is defined by a sequence of "stops" consisting of a float and a color. The stop indicate the color at that point on a spectrum between 0 and 1.

Parameters
Parameter Default Description
stops
tuple[float, Color]
()

A colors stop.

Raises
Type Description
ValueError

If any stops are missing (must be at least a stop for 0 and 1).

get_color method

def get_color(self, position):

Get a color from the gradient at a position between 0 and 1.

Positions that are between stops will return a blended color.

Parameters
Parameter Default Description
position
float
required

A number between 0 and 1, where 0 is the first stop, and 1 is the last.

Returns
Type Description
Color

A color.

HSL class

Bases: NamedTuple

A color in HLS (Hue, Saturation, Lightness) format.

css property

css: str

HSL in css format.

h instance-attribute

h: float

Hue in range 0 to 1.

l instance-attribute

l: float

Lightness in range 0 to 1.

s instance-attribute

s: float

Saturation in range 0 to 1.

HSV class

Bases: NamedTuple

A color in HSV (Hue, Saturation, Value) format.

h instance-attribute

h: float

Hue in range 0 to 1.

s instance-attribute

s: float

Saturation in range 0 to 1.

v instance-attribute

v: float

Value un range 0 to 1.

Lab class

Bases: NamedTuple

A color in CIE-L*ab format.

L instance-attribute

L: float

Lightness in range 0 to 100.

a instance-attribute

a: float

A axis in range -127 to 128.

b instance-attribute

b: float

B axis in range -127 to 128.

lab_to_rgb function

def lab_to_rgb(lab, alpha=1.0):

Convert a CIE-L*ab color to RGB.

Uses the standard RGB color space with a D65/2⁰ standard illuminant. Conversion passes through the XYZ color space. Cf. http://www.easyrgb.com/en/math.php.

rgb_to_lab function

def rgb_to_lab(rgb):

Convert an RGB color to the CIE-L*ab format.

Uses the standard RGB color space with a D65/2⁰ standard illuminant. Conversion passes through the XYZ color space. Cf. http://www.easyrgb.com/en/math.php.