---
title: Colors and Brushes
description: Color literals, the Colors namespace, color functions, and gradients.
SC: true
---
{/* cSpell: ignore rgbacolor */}

import SC from '@slint/common-files/src/components/SC.astro';
import Link from '@slint/common-files/src/components/Link.astro';
import CodeSnippetMD from "@slint/common-files/src/components/CodeSnippetMD.astro";
import SlintProperty from '@slint/common-files/src/components/SlintProperty.astro';
import { Tabs, TabItem } from '@astrojs/starlight/components';
import LangRefLink from '@slint/common-files/src/components/LangRefLink.astro';
import NotInSC from '@slint/common-files/src/components/NotInSC.astro';

Color literals follow the syntax of CSS:

```slint
export component Example inherits Window {
    background: blue;
    property<color> c1: #ffaaff;
    property<brush> b2: Colors.red;
}
```

In addition to plain colors, many elements have properties that are of type `brush` instead of `color`.
A brush is a type that can be either a color or gradient. The brush is then used to fill an element or
draw the outline.

CSS color names are in scope wherever a `color` or `brush` value is expected, including struct
fields, array elements and function arguments. Elsewhere, access colors from the `Colors` namespace.

<SC>

## Types

A `color` is a color with red, green, blue, and alpha channels.
The default `color` is transparent. \{#sls.type.color}

A `brush` defines the content that an element is filled with.
The default `brush` is transparent. \{#sls.type.brush}

A `color` converts to a `brush`: the brush that fills with that single color. \{#sls.type.convert.color-to-brush}

### brush
<SlintProperty propName="brush" typeName="brush" defaultValue='transparent'>
<NotInSC>
A brush is a special type that can be either initialized from a `color` or a `gradient`.

<Tabs syncKey="dev-language">
<TabItem label="Rust" icon="seti:rust">
In Rust, properties or struct fields of the brush type are mapped to <LangRefLink lang="rust-slint" relpath="enum.Brush.html">`slint::Brush`</LangRefLink>.
</TabItem>
<TabItem label="C++" icon="seti:cpp">
In C++, properties or struct fields of the brush type are mapped to <LangRefLink lang="cpp" relpath="api/slint/brush/">`slint::Brush`</LangRefLink>.
</TabItem>
<TabItem label="NodeJS" icon="node">
In JavaScript, properties or struct fields of the brush type are mapped to an object that implements the <LangRefLink lang="nodejs" relpath="api/interfaces/brush/">Brush interface</LangRefLink>.
</TabItem>
<TabItem label="Python" icon="seti:python">
In Python, properties or struct fields of the brush type are mapped to <LangRefLink lang="python" relpath="api/classes/brush/">`Brush`</LangRefLink>.
</TabItem>
</Tabs>
</NotInSC>
</SlintProperty>

### color
<SlintProperty propName="color" typeName="color" defaultValue='transparent'>
<NotInSC>
RGB color with an alpha channel, with 8 bit precision for each channel. CSS color names as well as the hexadecimal color encodings are supported, such as #RRGGBBAA or #RGB.

<Tabs syncKey="dev-language">
<TabItem label="Rust" icon="seti:rust">
In Rust, properties or struct fields of the color type are mapped to <LangRefLink lang="rust-slint" relpath="struct.Color.html">`slint::Color`</LangRefLink>.
</TabItem>
<TabItem label="C++" icon="seti:cpp">
In C++, properties or struct fields of the color type are mapped to <LangRefLink lang="cpp" relpath="api/slint/color/">`slint::Color`</LangRefLink>.
</TabItem>
<TabItem label="NodeJS" icon="node">
In JavaScript, properties or struct fields of the color type are mapped to an object that implements the <LangRefLink lang="nodejs" relpath="api/interfaces/rgbacolor/">RgbaColor interface</LangRefLink>.
</TabItem>
<TabItem label="Python" icon="seti:python">
In Python, properties or struct fields of the color type are mapped to <LangRefLink lang="python" relpath="api/classes/color/">`Color`</LangRefLink>.
</TabItem>
</Tabs>
</NotInSC>
</SlintProperty>
</SC>

## Color Properties

The following properties are exposed:

### red
### green
### blue
### alpha

These properties are in the range 0-255.

Use the colors namespace to select colors by their name. For example you can use `Colors.aquamarine` or `Colors.bisque`.
The entire list of names is very long. You can find a complete list in the [CSS Specification](https://www.w3.org/TR/css-color-3/#svg-color).

These color names are available in scope of `color` and `brush` expressions, as well as in the `Colors` namespace.

```slint no-test
// Using the Colors namespace
background: Colors.aquamarine;

// Using the functions via global scope.
background: aquamarine;
```

## Global Color Functions

### rgb(int, int, int) -> color
### rgba(int, int, int, float) -> color

Return the color as in CSS. Like in CSS, these two functions are actually aliases that can take
three or four parameters.

The first 3 parameters can be either number between 0 and 255, or a percentage with a `%` unit.
The fourth value, if present, is an alpha value between 0 and 1.

Unlike in CSS, the commas are mandatory.

### hsv(h: float, s: float, v: float) -> color
### hsv(h: float, s: float, v: float, a: float) -> color

Returns a color using HSV (Hue, Saturation, Value) coordinates. The hue parameter is a float
representing degrees (0-360) and wraps around (e.g., 480 becomes 120).
The saturation, value, and optional alpha parameter are expected to be within the range of 0 and 1.

### oklch(l: float, c: float, h: float) -> color
### oklch(l: float, c: float, h: float, a: float) -> color

Returns a color using the [Oklch color space](https://en.wikipedia.org/wiki/Oklab_color_space) (a perceptually uniform color space).

- `l` (lightness): 0 (black) to 1 (white), or 0% to 100%
- `c` (chroma): 0 (grayscale) to ~0.4 (vivid), or 0% to 100% (where 100% = 0.4)
- `h` (hue): 0-360 degrees, or as an angle (e.g., `180deg`, `0.5turn`)
- `a` (alpha): 0-1, defaults to 1

## Color Methods
All colors and brushes define the following methods:

### brighter(factor: float) -> brush

Returns a new color derived from this color but has its brightness increased by the specified factor.
This is done by converting the color to the HSV color space and multiplying the brightness (value) with (1 + factor).
For example if the factor is 0.5 (or for example 50%) the returned color is 50% brighter. Negative factors
decrease the brightness.

### darker(factor: float) -> brush

Returns a new color derived from this color but has its brightness decreased by the specified factor.
This is done by converting the color to the HSV color space and dividing the brightness (value) by (1 + factor).
For example if the factor is .5 (or for example 50%) the returned color is 50% darker. Negative factors
increase the brightness.

### mix(other: brush, factor: float) -> brush

Returns a new color that is a mix of this color and `other`. The specified factor is
clamped to be between `0.0` and `1.0` and then applied to this color, while `1.0 - factor`
is applied to `other`. For example `red.mix(green, 70%)` will have a stronger tone of red, while
`red.mix(green, 30%)` will have a stronger tone of green.

### transparentize(factor: float) -> brush

Returns a new color with the opacity decreased by `factor`.
The transparency is obtained by multiplying the alpha channel by `(1 - factor)`.

### with-alpha(alpha: float) -> brush

Returns a new color with the alpha value set to `alpha` (between 0 and 1)

### to-hsv() -> \{ hue: float, saturation: float, value: float, alpha: float }

Converts this color to the HSV color space and returns a struct with the `hue`, `saturation`, `value`,
and `alpha` fields. `hue` is between 0 and 360 while `saturation`, `value`, and `alpha` are between 0 and 1.

### to-oklch() -> \{ lightness: float, chroma: float, hue: float, alpha: float }

Converts this color to the [Oklch color space](https://en.wikipedia.org/wiki/Oklab_color_space) and returns a struct with the `lightness`, `chroma`, `hue`,
and `alpha` fields. `lightness` is between 0 and 1, `chroma` is typically between 0 and ~0.4,
`hue` is between 0 and 360, and `alpha` is between 0 and 1.

## Linear Gradients

Linear gradients describe smooth, colorful surfaces. They're specified using an angle and a series of
color stops. The colors will be linearly interpolated between the stops, aligned to an imaginary line
that is rotated by the specified angle. This is called a linear gradient and is specified using the
`@linear-gradient` macro with the following signature:

### @linear-gradient(angle, color percentage, color percentage, ...)

The first parameter to the macro is an angle (see <Link type="Types"/>). The gradient line's starting point
will be rotated by the specified value.

Following the initial angle is one or multiple color stops, describe as a space separated pair of a
`color` value and a `percentage`. The color specifies which value the linear color interpolation should
reach at the specified percentage along the axis of the gradient.

The following example shows a rectangle that's filled with a linear gradient that starts with a light blue
color, interpolates to a very light shade in the center and finishes with an orange tone:

<CodeSnippetMD imagePath="/src/assets/generated/gradients-linear.png" scale="3" imageWidth="200" imageHeight="200" imageAlt='Linear Gradient Example'>
```slint
export component Example inherits Window {
    preferred-width: 100px;
    preferred-height: 100px;

    Rectangle {
        background: @linear-gradient(90deg, #3f87a6 0%, #ebf8e1 50%, #f69d3c 100%);
    }
}
```
</CodeSnippetMD>

## Radial Gradients

Radial gradients are like linear gradients but the colors are interpolated circularly instead of
along a line. To describe a radial gradient, use the `@radial-gradient` macro with the following signature:

### @radial-gradient(circle [radius] [at x y], color percentage, color percentage, ...)

The first parameter to the macro is always `circle` because only circular gradients are supported.
The optional `radius` value sets the circle radius in the element's local coordinate space.
The `radius` value is a length expression.
If omitted, the radius is half of the element's bounding box diagonal.

The optional `at` parameter sets the gradient center in the element's local coordinate space.
The `x` and `y` values are length expressions.
If omitted, the gradient is centered in the element's bounding box.
You can use a radius without `at` to keep the default center with an explicit radius.

Example:

<CodeSnippetMD imagePath="/src/assets/generated/gradients-radial.png" scale="3" imageWidth="200" imageHeight="200" imageAlt='Radial Gradient Example'>
```slint
export component Example inherits Window {
    preferred-width: 100px;
    preferred-height: 100px;
    Rectangle {
        background: @radial-gradient(circle, #f00 0%, #0f0 50%, #00f 100%);
    }
}
```
</CodeSnippetMD>

You can set a center and radius explicitly:

```slint
export component Example inherits Rectangle {
    background: @radial-gradient(circle 60px at 25px 25px, #f00 0%, #00f 100%);
}
```

## Conic Gradients

Conic gradients are gradients where the color transitions rotate around a center point (like the angle on a color wheel).
To describe a conic gradient, use the `@conic-gradient` macro with the following signature:

### @conic-gradient([from angle] [at x y], color angle, color angle, ...)

The conic gradient is described by a series of color stops, each consisting of a color and an angle.
The angle specifies where the color is placed along the circular sweep (0deg to 360deg).
Colors are interpolated between the stops along the circular path.

The optional `from` parameter specifies the starting angle of the gradient rotation.
If omitted, the gradient starts at 0deg (pointing upward). For example, `from 90deg` rotates
the entire gradient 90 degrees clockwise.

The optional `at` parameter sets the gradient center in the element's local coordinate space.
The `x` and `y` values are length expressions.
If omitted, the gradient is centered in the element's bounding box.

Example:

<CodeSnippetMD imagePath="/src/assets/generated/gradients-conic.png" scale="3" imageWidth="200" imageHeight="200" imageAlt='Conic Gradient Example'>
```slint
export component Example inherits Window {
    preferred-width: 100px;
    preferred-height: 100px;
    Rectangle {
        background: @conic-gradient(#f00 0deg, #0f0 120deg, #00f 240deg, #f00 360deg);
    }
}
```
</CodeSnippetMD>

This creates a color wheel effect with red at the top (0deg/360deg), green at 120 degrees, and blue at 240 degrees.

You can also rotate the gradient using the `from` parameter:

<CodeSnippetMD imagePath="/src/assets/generated/gradients-conic-rotated.png" scale="3" imageWidth="200" imageHeight="200" imageAlt='Rotated Conic Gradient Example'>
```slint
export component Example inherits Window {
    preferred-width: 100px;
    preferred-height: 100px;
    Rectangle {
        background: @conic-gradient(from 90deg, #f00 0deg, #0f0 120deg, #00f 240deg, #f00 360deg);
    }
}
```
</CodeSnippetMD>

This rotates the same color wheel 90 degrees clockwise, so red starts at the right (90deg) instead of the top.

You can set the center explicitly:

```slint
export component Example inherits Rectangle {
    background: @conic-gradient(from 45deg at 30px 30px, #f00 0deg, #00f 180deg, #f00 360deg);
}
```

:::note[Known Limitation]
Negative angles cannot be used directly in conic gradients (e.g., `#ff0000 -90deg`).
Instead, use one of these workarounds:
- Convert to positive angles: `-90deg` → `270deg`
- Use variables: `property <angle> start: -90deg;` then use `start` in the gradient
- Use explicit subtraction: `#ff0000 0deg - 90deg`
:::
