#### GTK CSS Properties [src]

GTK supports CSS properties and shorthands as far as they can be applied in the context of widgets, and adds its own properties only when needed. All GTK-specific properties have a -gtk prefix.

## Basic types

All properties support the following keywords: inherit, initial, unset, with the same meaning as defined in the CSS Cascading and Inheritance spec.

The following units are supported for basic datatypes:

Length
  px, pt, em, ex, rem, pc, in, cm, mm
Percentage
  %
Angle
  deg, rad, grad, turn
Time
  s, ms

Length values with the em or ex units are resolved using the font size value, unless they occur in setting the font-size itself, in which case they are resolved using the inherited font size value.

The rem unit is resolved using the initial font size value, which is not quite the same as the CSS definition of rem.

Length values using physical units (pt, pc, in, cm, mm) are translated to px using the dpi value specified by the -gtk-dpi property, which is different from the CSS definition, which uses a fixed dpi of 96.

The `calc()` notation adds considerable expressive power to all of these datatypes. There are limits on what types can be combined in such an expression (e.g. it does not make sense to add a number and a time). For the full details, see the CSS Values and Units spec.

A common pattern among shorthand properties (called ‘four sides’) is one where one to four values can be specified, to determine a value for each side of an area. In this case, the specified values are interpreted as follows:

4 values:
  top right bottom left
3 values:
  top horizontal bottom
2 values:
  vertical horizontal
1 value:
  all

## Custom Properties

Starting with 4.16, GTK supports custom properties as defined in the CSS Custom Properties for Cascading Variables spec.

Custom properties are defined as follows:

    --prop: red;

and used via the `var` keyword:

    color: var(--prop);

Custom properties can have a fallback for when the referred property is invalid:

    color: var(--prop, green);

Older GTK builds (e. g., 4.14) do not support that. As for color variables, you have to use non-CSS color expressions. As for other variable types, there is not direct replacement.

## Colors

### CSS Colors

Colors can be expressed in numerous ways in CSS (see the Color Module. GTK supports many (but not all) of these.

You can use rgb(), rgba(), `hsl()` with both the legacy or the modern CSS syntax, and `calc()` can be used as well in color expressions. hwb(), oklab(), oklch(), color(), color-mix() and relative colors are supported as well.

### Non-CSS Colors

GTK extends the CSS syntax with several additional ways to specify colors.

These extensions are deprecated and should be replaced by the equivalent standard CSS notions.

The first is a reference to a color defined via a `define-color` rule in CSS. The syntax for `define-color` rules is as follows:

    @define-color name color

To refer to the color defined by a `define-color` rule, prefix the name with @.

There are standard CSS mechanisms that should be used instead of `define-color`: custom properties, `:root` selector and `var()` expression. GTK supports them since 4.16 release.

GTK also supports color expressions, which allow colors to be transformed to new ones. Color expressions can be nested, providing a rich language to define colors. Color expressions resemble functions, taking 1 or more colors and in some cases a number as arguments.

`lighter(color)`
  produces a brighter variant of `color`.
`darker(color)`
  produces a darker variant of `color`.
`shade(color, number)`
  changes the lightness of `color`. The `number` ranges from 0 for black to 2 for white.
`alpha(color, number)`
  multiplies the alpha value of `color` by `number` (between 0 and 1).
`mix(color1, color2, number)`
  interpolates between the two colors.

## Images

GTK extends the CSS syntax for images and also uses it for specifying icons. To load a themed icon, use

    -gtk-icontheme(name)

The specified icon name is used to look up a themed icon, while taking into account the values of the -gtk-icon-palette property. This kind of image is mainly used as value of the -gtk-icon-source property.

Symbolic icons from the icon theme are recolored according to the -gtk-icon-palette property, which defines a list of named colors. The recognized names for colors in symbolic icons are error, warning and success. The default palette maps these three names to symbolic colors with the names `error_color`, `warning_color` and `success_color` respectively. The syntax for defining a custom palette is a comma-separated list of name-color pairs, e.g.

    success blue, warning #fc3, error magenta

Recoloring is sometimes needed for images that are not part of an icon theme, and the

    -gtk-recolor(uri, palette)

syntax makes this available. -gtk-recolor requires a url as first argument. The remaining arguments specify the color palette to use. If the palette is not explicitly specified, the current value of the -gtk-icon-palette property is used.

GTK supports scaled rendering on hi-resolution displays. This works best if images can specify normal and hi-resolution variants. From CSS, this can be done with

    -gtk-scaled(image1, image2)

## GTK CSS Properties

Property | Reference | Notes
--- | --- | ---
color | CSS Color Level 3 |
opacity | CSS Color Level 3 |
filter | CSS Filter Effect Level 1 |
font-family | CSS Fonts Level 3 | defaults to gtk-font-name setting
font-size | CSS Fonts Level 3 | defaults to gtk-font-name setting
font-style | CSS Fonts Level 3 |
font-variant | CSS Fonts Level 3 | only CSS2 values supported
font-weight | CSS Fonts Level 3 |
font-stretch | CSS Fonts Level 3 |
font-kerning | CSS Fonts Level 3 |
font-variant-ligatures | CSS Fonts Level 3 |
font-variant-position | CSS Fonts Level 3 |
font-variant-caps | CSS Fonts Level 3 |
font-variant-numeric | CSS Fonts Level 3 |
font-variant-alternates | CSS Fonts Level 3 |
font-variant-east-asian | CSS Fonts Level 3 |
font-feature-settings | CSS Fonts Level 3 |
font-variation-settings | CSS Fonts Level 4 |
-gtk-dpi | Number | defaults to screen resolution
font | CSS Fonts Level 3 | CSS allows line-height, etc
font-variant | CSS Fonts Level 3 |
caret-color | CSS Basic User Interface Level 3 | CSS allows an auto value
-gtk-secondary-caret-color | Color | used for the secondary caret in bidirectional text
letter-spacing | CSS Text Level 3 |
text-transform | CSS Text Level 3 | CSS allows full-width and full-size-kana. Since 4.6
line-height | CSS Inline Layout Level 3 | Since 4.6
text-decoration-line | CSS Text Decoration Level 3 |
text-decoration-color | CSS Text Decoration Level 3 |
text-decoration-style | CSS Text Decoration Level 3 | CSS allows dashed and dotted
text-shadow | CSS Text Decoration Level 3 |
text-decoration | CSS Text Decoration Level 3 |
-gtk-icon-source | Image, `builtin` or `none` | used for builtin icons in buttons and expanders
-gtk-icon-size | Length | size used for builtin icons in buttons and expanders
-gtk-icon-style | `requested`, `regular` or `symbolic` | preferred style for application-loaded icons
-gtk-icon-transform | Transform list or `none` | applied to builtin and application-loaded icons
-gtk-icon-palette | Color palette, as explained above | used to recolor symbolic icons
-gtk-icon-shadow | Shadow or `none` | applied to builtin and application-loaded icons
-gtk-icon-filter | Filter value list or `none` | applied to builtin and application-loaded icons
-gtk-icon-weight | Like font weight | applied to builtin and application-loaded, stroked symbolic icons
transform | CSS Transforms Level 1 |
transform-origin | CSS Transforms Level 1 | CSS allows specifying a z component
min-width | CSS Box Model Level 3 | CSS allows percentages
min-height | CSS Box Model Level 3 | CSS allows percentages
margin-top | CSS Box Model Level 3 | CSS allows percentages or auto
margin-right | CSS Box Model Level 3 | CSS allows percentages or auto
margin-bottom | CSS Box Model Level 3 | CSS allows percentages or auto
margin-left | CSS Box Model Level 3 | CSS allows percentages or auto
padding-top | CSS Box Model Level 3 | CSS allows percentages
padding-right | CSS Box Model Level 3 | CSS allows percentages
padding-bottom | CSS Box Model Level 3 | CSS allows percentages
padding-left | CSS Box Model Level 3 | CSS allows percentages
margin | CSS Box Model Level 3 | a ‘four sides’ property
padding | CSS Box Model Level 3 | a ‘four sides’ property
border-top-width | CSS Backgrounds and Borders Level 3 | CSS allows other values
border-right-width | CSS Backgrounds and Borders Level 3 | CSS allows other values
border-bottom-width | CSS Backgrounds and Borders Level 3 | CSS allows other values
border-left-width | CSS Backgrounds and Borders Level 3 | CSS allows other values
border-top-style | CSS Backgrounds and Borders Level 3 |
border-right-style | CSS Backgrounds and Borders Level 3 |
border-bottom-style | CSS Backgrounds and Borders Level 3 |
border-left-style | CSS Backgrounds and Borders Level 3 |
border-top-right-radius | CSS Backgrounds and Borders Level 3 |
border-bottom-right-radius | CSS Backgrounds and Borders Level 3 |
border-bottom-left-radius | CSS Backgrounds and Borders Level 3 |
border-top-left-radius | CSS Backgrounds and Borders Level 3 |
border-top-color | CSS Backgrounds and Borders Level 3 |
border-right-color | CSS Backgrounds and Borders Level 3 |
border-bottom-color | CSS Backgrounds and Borders Level 3 |
border-left-color | CSS Backgrounds and Borders Level 3 |
border-image-source | CSS Backgrounds and Borders Level 3 |
border-image-repeat | CSS Backgrounds and Borders Level 3 |
border-image-slice | CSS Backgrounds and Borders Level 3 | a ‘four sides’ property
border-image-width | CSS Backgrounds and Borders Level 3 | a ‘four sides’ property
border-width | CSS Backgrounds and Borders Level 3 | a ‘four sides’ property
border-style | CSS Backgrounds and Borders Level 3 | a ‘four sides’ property
border-color | CSS Backgrounds and Borders Level 3 | a ‘four sides’ property
border-top | CSS Backgrounds and Borders Level 3 |
border-right | CSS Backgrounds and Borders Level 3 |
border-bottom | CSS Backgrounds and Borders Level 3 |
border-left | CSS Backgrounds and Borders Level 3 |
border | CSS Backgrounds and Borders Level 3 |
border-radius | CSS Backgrounds and Borders Level 3 |
border-image | CSS Backgrounds and Borders Level 3 |
outline-style | CSS Basic User Interface Level 3 | initial value is none, auto is not supported
outline-width | CSS Basic User Interface Level 3 |
outline-color | CSS Basic User Interface Level 3 | initial value is currentColor, invert is not supported
outline-offset | CSS Basic User Interface Level 3 |
outline | CSS Basic User Interface Level 3 |
background-color | CSS Backgrounds and Borders Level 3 |
background-clip | CSS Backgrounds and Borders Level 3 |
background-origin | CSS Backgrounds and Borders Level 3 |
background-size | CSS Backgrounds and Borders Level 3 |
background-position | CSS Backgrounds and Borders Level 3 |
background-repeat | CSS Backgrounds and Borders Level 3 |
background-image | CSS Backgrounds and Borders Level 3 | not supported: urls without quotes
box-shadow | CSS Backgrounds and Borders Level 3 |
background-blend-mode | CSS Compositing and Blending Level 1 | only affects multiple backgrounds
background | CSS Backgrounds and Borders Level 3 |
transition-property | CSS Transitions |
transition-duration | CSS Transitions |
transition-timing-function | CSS Transitions |
transition-delay | CSS Transitions |
transition | CSS Transitions |
animation-name | CSS Animations Level 1 |
animation-duration | CSS Animations Level 1 |
animation-timing-function | CSS Animations Level 1 |
animation-iteration-count | CSS Animations Level 1 |
animation-direction | CSS Animations Level 1 |
animation-play-state | CSS Animations Level 1 |
animation-delay | CSS Animations Level 1 |
animation-fill-mode | CSS Animations Level 1 |
animation | CSS Animations Level 1 |
border-spacing | CSS Table Level 3 | respected by GtkBoxLayout, GtkGridLayout, GtkCenterLayout

## Media Queries

Since GTK 4.20 CSS Media Queries are supported. Media queries can include `not`, `and`, and `or` expressions.

GTK supports the following media features:

Media feature | Reference | Notes
--- | --- | ---
prefers-color-scheme | Media Queries Level 5 | `light` and `dark` mode
prefers-contrast | Media Queries Level 5 | `no-preference`, `more`, and `less`
prefers-reduced-motion | Media Queries Level 5 | `no-preference`, `reduced`