Introducing Libadwaita

The logo of libadwaita

GNOME 41 will come with libadwaita, the GTK 4 port of libhandy that will play a central role in defining the visual language and user experience of GNOME applications.


For the past 20 years, GNOME has had human interface guidelines — HIG for short — that are followed by applications targeting the platform.

Implementing the HIG is a lot of manual work for application developers. This led to lots of verbose copypasted UI code, full of slight interpretation variations and errors, making applications hard to maintain and full of visual and behaviorial inconsistencies. The fact these guidelines are not set in stone and evolve every so often made these inconsistencies explode.

Following these guidelines can be streamlined via a library offering tailored widgets and styles. This role has been filled by GTK because of its strong bonds with the GNOME project: Adwaita is both GNOME’s visual language and GTK’s default theme. This is somewhat problematic though, as GTK serves multiple audiences and platforms, and this favores GNOME over them.

This also leads to life cycle mismatches, as GTK machinery must be extremely stable and can’t evolve at a rapid pace, while the GNOME guidelines and Adwaita evolve in comparison much faster, and can benefit from a library that can keep up with the latest designs

Untangling Them

The need to give GNOME a faster moving library quickly grew in the community, and many widget libraries filled the gap: libdazzle, libegg, libgd, or libhandy to name a few. This improved the situation, but it only worked around the issues instead of solving them. GNOME needs a blessed library implementing its HIG rapidly, developed in collaboration with its design team. Such a library would define the visual language of GNOME by offering the stylesheet and the patterns in a single package.

This would allow GTK to grow independently from GNOME, at a pace fitting its needs. It could narrow its focus on more generic widgetry and on its core machinery, simplifying its theming support in the process to make it more flexible. This would in turn give other users of GTK an even playing field: from GTK’s POV, GNOME, elementary and Inkscape would be no different, and that hypothetical GNOME library would fill the same role as elementary’s Granite.

The introduction of that library should not make GTK less useful on other platforms, or make GTK applications harder to build (or uglier). It should simply be another library you can choose to link against if you want to make your application fit well into GNOME.


To solve both GTK’s need of independence and GNOME’s need to move faster, we are creating the libadwaita project.

Adwaita is the name of GNOME’s visual language and identity, and it is already used by two projects implementing it: the Adwaita GTK stylesheet and the Adwaita icon set. This new libadwaita library intends to extend that concept by being the missing code part of Adwaita. The library will be implemented as a direct GTK 4 continuation and replacement of libhandy, and it will be developed by libhandy’s current developers.

The Adwaita stylesheet will be moved to libadwaita, including its variants such as HighContrast and HighContrastInverse. GTK will keep a copy of that stylesheet renamed Default, that will focus on the needs of vanilla GTK applications. See gtk!3079 and gtk#3582 for more information. We want that to happen early in the development of libadwaita.

As it will implement the GNOME HIG, the library’s developers will work in close collaboration with the GNOME design team. The design team will also review the initial set of widgets and styles inherited from libhandy, ensuring they are aligned with the guidelines they developed and that they will refresh for GNOME 41.

This transition is being developed in close collaboration between the GTK developers, the libhandy developers, and the GNOME design team. It has also been discussed with various other GNOME and elementary developers.


If you are a GNOME application developer, you likely want to port your application from GTK 3 (and libhandy) to GTK 4 and libadwaita in time for GNOME 41. You can find libadwaita on GNOME’s GitLab, and you can reach the developers on the Matrix room at You can also join the room via IRC at #libadwaita on GIMPnet.

The libadwaita project will follow revisions of the HIG, and releases will follow GNOME’s schedule. Each version of the library will target a specific version of GNOME, the first stable version being released alongside GNOME 41.

The first stable version of the library will be 1.0. We won’t use the GNOME version number as major versions of the Adwaita library will span multiple GNOME releases, the contrary would be unmanageable for application developers. Major versions will be parallel-installable.

The library isn’t quite ready to be used yet, we have to fix some remaining issues, write a migration guide, and release a first alpha version you can safely target. We will then release several alpha versions and matching migration guides, so you can safely update your application as we stabilize libadawaita 1.0 without ever breaking your build.

Starting from now, libhandy’s pace of development will slow down tremendously as we will focus on developing libadwaita. Any improvement made to libhandy must now first be implemented in libadwaita.

We hope the GTK 4 users will enjoy the newly gained independence, and that GNOME application developers will feel empowered!

Thanks to the GTK developers, GNOME design team, and Alice Mikhaylenko for helping me write this article.