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: Final = Color(0, 0, 0)

A constant for pure black.

TRANSPARENT module-attribute

TRANSPARENT: Final = Color.parse('transparent')

A constant for transparent.

WHITE module-attribute

WHITE: Final = 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: float = 1.0

Alpha (opacity) component in range 0 to 1.

ansi class-attribute instance-attribute

ansi: int | None = None

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

auto class-attribute instance-attribute

auto: bool = False

Is the color automatic? (automatic colors may be white or black, to provide maximum contrast)

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 cached property

rich_color: RichColor

This color encoded in Rich's Color class.

Returns:

Type Description
RichColor

A color object as used by Rich.

automatic classmethod

automatic(alpha_percentage=100.0)

Create an automatic color.

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 cached classmethod

from_rich_color(rich_color, theme=None)

Create a new color from Rich's Color class.

Parameters:

Name Type Description Default
rich_color RichColor | None

An instance of Rich color.

required
theme TerminalTheme | None

Optional Rich [terminal theme][rich.terminal_theme.TerminalTheme].

None

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.

tint cached

tint(color)

Apply a tint to a color.

Similar to blend, but combines color and alpha.

Parameters:

Name Type Description Default
color Color

A color with alpha component.

required

Returns:

Type Description
Color

New color

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: list[Color]

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
RichColor

A (Rich) color.

HSL

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

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

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

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.