docs

Working with Colors

Create, parse, and format colors.

On this page

Ultralight uses the Color type whenever you need to pass color values to various parts of the API.

To modify styles on DOM elements directly, see Reading and Writing Styles. To pass color values between native code and page script, see Passing Data Across the Bridge.

Creating Colors

You can create a Color from individual float channels, compile-time CSS string literals, or runtime CSS strings.

Specifying RGBA Channels

Construct a Color by passing red, green, and blue channels:

C++
Color green(0.0f, 1.0f, 0.0f);        // RGB values
Color glass(1.0f, 1.0f, 1.0f, 0.1f);  // RGBA values, 10% opacity

The alpha channel is optional— omitting it creates an opaque color.

🚧 Floating-Point Channel Range

Color channels use floating-point values from 0.0 to 1.0 rather than integers from 0 to 255.

CSS String Literals

You can assign a CSS string literal directly to a Color:

C++
Color background = "#101014";
Color overlay = "rgba(255, 255, 255, 0.1)";

Ultralight validates string literals during compilation. Supported formats include hexadecimal values alongside rgb(), rgba(), and transparent.

Other CSS formats like hsl() or named color strings cause a compile error— use Color::Parse() for those formats instead.

🚧 Literal Validation in Visual Studio 2022

Visual Studio 2022 validates string literals at runtime instead of compile time. An invalid literal compiles without error, but Ultralight logs a warning when you use the color.

Parsing CSS Strings

Call Color::Parse() to evaluate CSS color strings at runtime:

C++
Color accent = Color::Parse(theme_text);  // eg, "rebeccapurple"
if (!accent)
  accent = Color(1.0f, 0.24f, 0.42f);

This function parses the full CSS color grammar, including named colors and functional notations like hsl().

When parsing fails, testing the color in a conditional evaluates to false. The renderer ignores the invalid color and logs a warning when you pass it to an API.

Unset Colors

Assign a default-constructed Color() to request the built-in default:

C++
ViewConfig config;
config.background_color = Color();  // unset: the View's default background

An unset color tells the receiving function or property to apply its built-in default.

Options structures leave their Color fields unset initially— for example, ViewConfig::background_color defaults to opaque white.

Formatting Hex Text

Convert a color into a CSS hex string with ToHexString():

C++
String hex = Color(1.0f, 0.2f, 0.4f).ToHexString();  // "#ff3366"

The method returns a lowercase #rrggbb string, appending two additional hex digits (#rrggbbaa) when the color is translucent.