Skip to content

Color

color

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

The only exception would be for Rich renderables, which require a rich.color.Color instance. You can convert from a Textual color to a Rich color with the rich_color property.

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) └────────────────────────┴─────────┴────────────────────┴──────────────────────┘

Color

Bases: NamedTuple

A class to represent a RGB color with an alpha component.

a: float class-attribute

Alpha component (0-1)

b: int class-attribute

Blue component (0-255)

brightness: float property

Get the human perceptual brightness.

Returns:

Type Description
float

Brightness value (0-1).

clamped: Color property

Get a color with all components saturated to maximum and minimum values.

Returns:

Type Description
Color

A color object.

css: str property

The color in CSS rgb or rgba form.

Returns:

Type Description
str

A CSS style color, e.g. "rgb(10,20,30)" or "rgb(50,70,80,0.5)"

g: int class-attribute

Green component (0-255)

hex: str property

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

Returns:

Type Description
str

A CSS hex-style color, e.g. "#46b3de" or "#3342457f"

hex6: str property

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

Returns:

Type Description
str

A CSS hex-style color, e.g. "#46b3de"

hsl: HSL property

Get the color as HSL.

Returns:

Type Description
HSL

Color in HSL format.

inverse: Color property

The inverse of this color.

is_transparent: bool property

Check if the color is transparent, i.e. has 0 alpha.

Returns:

Type Description
bool

True if transparent, otherwise False.

monochrome: Color property

Get a monochrome version of this color.

Returns:

Type Description
Color

A new monochrome color.

normalized: tuple[float, float, float] property

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

Returns:

Type Description
tuple[float, float, float]

Normalized components.

r: int class-attribute

Red component (0-255)

rgb: tuple[int, int, int] property

Get just the red, green, and blue components.

Returns:

Type Description
tuple[int, int, int]

Color components

rich_color: RichColor property

This color encoded in Rich's Color class.

Returns:

Type Description
RichColor

A color object as used by Rich.

blend(destination, factor, alpha=None)

Generate a new color between two colors.

Parameters:

Name Type Description Default
destination Color

Another color.

required
factor float

A blend factor, 0 -> 1.

required
alpha float | None

New alpha for result. Defaults to None.

None

Returns:

Type Description
Color

A new color.

darken(amount, alpha=None) cached

Darken the color by a given amount.

Parameters:

Name Type Description Default
amount float

Value between 0-1 to reduce luminance by.

required
alpha float | None

Alpha component for new color or None to copy alpha. Defaults to None.

None

Returns:

Type Description
Color

New color.

from_hsl(h, s, l) classmethod

Create a color from HLS components.

Parameters:

Name Type Description Default
h float

Hue.

required
l float

Lightness.

required
s float

Saturation.

required

Returns:

Type Description
Color

A new color.

from_rich_color(rich_color) classmethod

Create a new color from Rich's Color class.

Parameters:

Name Type Description Default
rich_color RichColor

An instance of rich.color.Color.

required

Returns:

Type Description
Color

A new Color.

get_contrast_text(alpha=0.95) cached

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

Parameters:

Name Type Description Default
alpha

An alpha value to adjust the pure white / black by. Defaults to 0.95.

0.95

Returns:

Type Description
Color

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

lighten(amount, alpha=None)

Lighten the color by a given amount.

Parameters:

Name Type Description Default
amount float

Value between 0-1 to increase luminance by.

required
alpha float | None

Alpha component for new color or None to copy alpha. Defaults to None.

None

Returns:

Type Description
Color

New color.

multiply_alpha(alpha)

Create a new color, multiplying the alpha with a new alpha.

Parameters:

Name Type Description Default
alpha float

The alpha value to multiple by.

required

Returns:

Type Description
Color

A new color.

parse(color_text) cached classmethod

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:

Name Type Description Default
color_text str | Color

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

required

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(alpha)

Create a new color with the given alpha.

Parameters:

Name Type Description Default
alpha float

New value for alpha.

required

Returns:

Type Description
Color

A new color.

ColorParseError

Bases: Exception

A color failed to parse.

Parameters:

Name Type Description Default
message str

The error message

required
suggested_color str | None

A close color we can suggest. Defaults to None.

None

Gradient

Defines a color gradient.

__init__(*stops)

Create a color gradient that blends colors to form a spectrum.

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:

Name Type Description Default
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(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:

Name Type Description Default
factor

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

required

Returns:

Type Description
Color

A color.

HSL

Bases: NamedTuple

A color in HLS format.

css: str property

HSL in css format.

h: float class-attribute

Hue

l: float class-attribute

Lightness

s: float class-attribute

Saturation

HSV

Bases: NamedTuple

A color in HSV format.

h: float class-attribute

Hue

s: float class-attribute

Saturation

v: float class-attribute

Value

Lab

Bases: NamedTuple

A color in CIE-L*ab format.

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