gtk2/docs/reference/gtk/css-properties.md

Title: GTK CSS Properties Slug: css-properties

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, calc()

Percentage

%, calc()

Angle

deg, grad, turn, calc()

Time

s, ms, calc()

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.

The calc() notation adds considerable expressive power. 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 CSS3 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

Colors

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

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 @.

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 brigher 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) : replaces the alpha value of color with 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
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