Skip to content

textual.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 = Color(0, 0, 0)

A constant for pure black.

TRANSPARENT module-attribute

TRANSPARENT = parse('transparent')

A constant for transparent.

WHITE module-attribute

WHITE = Color(255, 255, 255)

A constant for pure white.

Color

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 class-attribute instance-attribute

a = 1.0

Alpha (opacity) component in range 0 to 1.

ansi class-attribute instance-attribute

ansi = None

ANSI color index. -1 means default color. None if not an ANSI color.

b instance-attribute

b

Blue component in range 0 to 255.

brightness property

brightness

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

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

css property

css

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

Green component in range 0 to 255.

hex property

hex

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

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

For example, "#46b3de".

hsl property

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

The inverse of this color.

Returns:

Type Description
Color

Inverse color.

is_transparent property

is_transparent

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

monochrome property

monochrome

A monochrome version of this color.

Returns:

Type Description
Color

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

normalized property

normalized

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

Red component in range 0 to 255.

rgb property

rgb

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

rich_color cached property

rich_color

This color encoded in Rich's Color class.

Returns:

Type Description
Color

A color object as used by Rich.

blend cached

blend(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:

Name Type Description Default

destination

Color

Another color.

required

factor

float

A blend factor, 0 -> 1.

required

alpha

float | None

New alpha for result.

None

Returns:

Type Description
Color

A new color.

darken cached

darken(amount, alpha=None)

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.

None

Returns:

Type Description
Color

New color.

from_hsl classmethod

from_hsl(h, s, l)

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 classmethod

from_rich_color(rich_color)

Create a new color from Rich's Color class.

Parameters:

Name Type Description Default

rich_color

Color

An instance of Rich color.

required

Returns:

Type Description
Color

A new Color instance.

get_contrast_text cached

get_contrast_text(alpha=0.95)

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

Parameters:

Name Type Description Default

alpha

float

An alpha value to apply to the result.

0.95

Returns:

Type Description
Color

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

lighten

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.

None

Returns:

Type Description
Color

New color.

multiply_alpha

multiply_alpha(alpha)

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

Parameters:

Name Type Description Default

alpha

float

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

required

Returns:

Type Description
Color

A new color.

parse cached classmethod

parse(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:

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

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

ColorParseError(message, suggested_color=None)

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.

None

Gradient

Gradient(*stops, quality=50)

Defines a color gradient.

A gradient is defined by a sequence of "stops" consisting of a tuple containing a float and a color. The stop indicates the color at that point on a spectrum between 0 and 1. Colors may be given as a Color instance, or a string that can be parsed into a Color (with Color.parse).

The quality argument defines the number of steps in the gradient. Intermediate colors are interpolated from the two nearest colors. Increasing quality can generate a smoother looking gradient, at the expense of a little extra work to pre-calculate the colors.

Parameters:

Name Type Description Default

stops

tuple[float, Color | str]

Color stops.

()

quality

int

The number of steps in the gradient.

50

Raises:

Type Description
ValueError

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

colors property

colors

A list of colors in the gradient.

from_colors classmethod

from_colors(*colors, quality=50)

Construct a gradient form a sequence of colors, where the stops are evenly spaced.

Parameters:

Name Type Description Default

*colors

Color | str

Positional arguments may be Color instances or strings to parse into a color.

()

quality

int

The number of steps in the gradient.

50

Returns:

Type Description
Gradient

A new Gradient instance.

get_color

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

position

float

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

required

Returns:

Type Description
Color

A Textual color.

get_rich_color

get_rich_color(position)

Get a (Rich) 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

position

float

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

required

Returns:

Type Description
Color

A (Rich) color.

HSL

Bases: NamedTuple

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

css property

css

HSL in css format.

h instance-attribute

h

Hue in range 0 to 1.

l instance-attribute

l

Lightness in range 0 to 1.

s instance-attribute

s

Saturation in range 0 to 1.

HSV

Bases: NamedTuple

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

h instance-attribute

h

Hue in range 0 to 1.

s instance-attribute

s

Saturation in range 0 to 1.

v instance-attribute

v

Value un range 0 to 1.

Lab

Bases: NamedTuple

A color in CIE-L*ab format.

L instance-attribute

L

Lightness in range 0 to 100.

a instance-attribute

a

A axis in range -127 to 128.

b instance-attribute

b

B axis in range -127 to 128.

lab_to_rgb

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