Adw – 1: Styles & Appearance
Description: Reference for Adw-1: 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:

1. An application wants to use dark UI. Use the `ADW_COLOR_SCHEME_PREFER_DARK` color scheme.

2. 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`

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 named colors instead of hardcoded colors. For custom drawing, use `gtk_style_context_get_color()` to get the current text color for your widget, or `gtk_style_context_lookup_color()` to look up other colors.

- If that’s not possible, use the `AdwStyleManager:dark` property to check the current appearance and vary the drawing accordingly.

- `AdwApplication` allows loading additional styles for dark appearance via the `style-dark.css` resource.

## 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 `.dim-label` instead of changing widget opacity manually.

- Use the `@borders` color for borders instead of hardcoded colors.

- The `AdwStyleManager:high-contrast` property can be used to check the current appearance.

- `AdwApplication` allows loading additional styles for high contrast appearance via the `style-hc.css` and `style-hc-dark.css` resources.

## 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.css` contains styles that are always used.
- `style-dark.css` contains styles only used with the dark appearance.
- `style-hc.css` contains styles used with the high contrast appearance.
- `style-hc-dark.css` contains 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.

## See Also

- Style Classes
- Named Colors