Gtk – 4.0: GTK CSS Properties
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