Styles & Appearance
Styles & Appearance
Dark Style
Libadwaita applications can use a light or a dark appearance. This can be used to request a darker UI, or to support a system-wide dark style preference if one exists.
By default, applications use light appearance unless the system prefers dark
appearance, matching the ADW_COLOR_SCHEME_PREFER_LIGHT color scheme. The
AdwStyleManager:color-scheme property allows to change this behavior
when set to:
ADW_COLOR_SCHEME_PREFER_DARK: Use dark appearance unless the system prefers light appearance.ADW_COLOR_SCHEME_FORCE_DARK: Always use dark appearance.ADW_COLOR_SCHEME_FORCE_LIGHT: Always use light appearance.
| App \ System | Prefer Light | No Preference | Prefer Dark |
|---|---|---|---|
| FORCE_LIGHT | Light | Light | Light |
| PREFER_LIGHT | Light | Light | Dark |
| PREFER_DARK | Light | Dark | Dark |
| FORCE_DARK | Dark | Dark | Dark |
Common use cases:
-
An application wants to use dark UI. Use the
ADW_COLOR_SCHEME_PREFER_DARKcolor scheme. -
An application has a style switcher with the system, light and dark states. Use the following color scheme values:
- System:
ADW_COLOR_SCHEME_PREFER_LIGHT - Light:
ADW_COLOR_SCHEME_FORCE_LIGHT - Dark:
ADW_COLOR_SCHEME_FORCE_DARK
- System:
If the system does not provide a style preference, the
AdwStyleManager:system-supports-color-schemes property can be used to
provide a fallback. For example, applications with a system/light/dark switcher
may want to hide or disable the system value.
All standard GTK and Libadwaita widgets automatically support both styles. Applications that use custom drawing or styles may need to ensure the UI remains legible in both appearances:
-
When possible, use CSS variables instead of hardcoded colors. For custom drawing, use
gtk_style_context_get_color()to get the current text color for your widget, orgtk_style_context_lookup_color()to look up other colors. -
If that’s not possible, use the
AdwStyleManager:darkproperty to check the current appearance and vary the drawing accordingly. -
AdwApplicationallows loading additional styles for dark appearance via thestyle-dark.cssresource.
Accent Color
Libadwaita applications follow the system accent color by default. Applications with custom drawing or styles may need to ensure that they use the actual accent color instead of hardcoding blue:
-
Use accent color variables and the
.accentstyle class in CSS. -
Use
AdwStyleManager:accent-color-rgbato get the background accent color programmatically. -
Use
AdwStyleManager:accent-colorandadw_accent_color_to_standalone_rgba()to get the standalone accent color programmatically.
Applications can override the accent color using CSS, as follows:
:root {
--accent-bg-color: var(--accent-green); /* Always use the green color */
}
Accent can also be overridden for an individual widget. In this case
--accent-color must be manually overridden as well:
my-widget {
--accent-bg-color: var(--accent-purple); /* Always use the purple color */
--accent-color: oklab(from var(--accent-bg-color) var(--standalone-color-oklab));
}
All of the default accent colors use white text as the foreground color. If the custom accent color is too bright, use a dark foreground color instead:
:root {
--accent-bg-color: var(--yellow-3);
--accent-fg-color: rgb(0 0 0 / 80%);
}
Note
When accent color is overridden, AdwStyleManager API will still return
the system color.
High Contrast
The system can provide a high contrast preference. Libadwaita applications automatically support it; applications cannot disable it.
High contrast appearance can be combined with the dark style and is independent from it.
All standard GTK and Libadwaita widgets automatically support the high contrast appearance. Applications that use custom drawing or styles may need to support it manually.
-
Use style classes such as
.dimmedinstead of changing widget opacity manually. -
Use the helper variables when possible, instead of hardcoding colors and opacities.
-
The
AdwStyleManager:high-contrastproperty can be used to check the current appearance. -
AdwApplicationallows loading additional styles for high contrast appearance via thestyle-hc.cssandstyle-hc-dark.cssresources.
Custom Styles
AdwApplication provides a simple way to load additional styles from
GResource, relative to the application’s base path (see
g_application_set_resource_base_path()).
The following resources will automatically be loaded if present:
style.csscontains styles that are always used.style-dark.csscontains styles only used with the dark appearance.style-hc.csscontains styles used with the high contrast appearance.style-hc-dark.csscontains styles used when both dark and high contrast
Styles are stacked on top of each other: when using dark appearance, both
style.css and style-dark.css are loaded, and so on.