If you've been around the GNOME desktop in the past couple of releases, then you've probably heard of LibAdwaita. LibAdwaita describes itself as "Building blocks for modern GNOME applications", and that is quite precisely what it is. It allows you - A developer - to create GNOME apps with a well defined layout and theme. In of itself, that sounds great, however, this comes with one drawback on the user's end, or so you thought.

There has been a lot of fuss about LibAdwaita upon it's first announcement, mainly because at first there was no way to theme any applications made with LibAdwaita without recompiling LibAdwaita or the program you're trying to theme. However, this uproar in the community was entirely for nothing, because as it turns out, LibAdwaita is perfectly theme-able.

Taking a closer look

So, how did LibAdwaita theming start, and how is it looking now? Well, there's been changes, but generally it comes down to the following being possible:

• LibAdwaita apps will always use the new Adwaita stylesheet unless explicitly overwritten
• LibAdwaita will gain a coloring API in the future, through which the system will be able to properly define things like Accent Colors
• Apps made using LibAdwaita can define their own CSS styles to change how certain elements look
• The GTK Theme can be overwritten by hand

That is essentially the state at the moment, though, when LibAdwaita first got announced, and started public development, many of the above did not apply. Specifically, the library couldn't have it's stylesheet altered externally, either through ~/.config/gtk-4.0/gtk.css nor through the GTK_THEME environment variable.

Nowadays, that is different. Both of the above can be used to overwrite the theme, and they come with their up and downsides.

The Fun Part: Theming LibAdwaita

Now, if you've come this far then you probably want to get into modifying LibAdwaita's stylesheet yourself (or you've scrolled here specifically for that), so let's get right to it!

Method 1: Environment Variables

The first method I want to talk about to make this happen is Environment Variables. An Environment Variable is a variable which defines a certain behavior within your environment. (who would've thought)

Whilst looking through the web, I got reminded of one particular variable which we can set which applies to GTK3 and GTK4 applications: GTK_THEME

Upon setting GTK_THEME, any GTK applications will pick up on our defined theme, and skip it's usual loading of it's own stylesheet. Do note that the value of GTK_THEME is case-sensitive, so use it accordingly.

This is an example snippet that you can add to your ~/.profile, or any other place where you can define global environment variables:

export GTK_THEME="Catppuccin-Mocha-Mauve"

Method 2: CSS overrides

Another method is to manually override some CSS within ~/.config/gtk-4.0/. This method involves copying and/or symlinking your theme's gtk.css to this path, and if you're using Flatpak also setting up some overrides. However, this method won't ever be able to properly switch between Light/Dark theme without a reload!

If you want this automated, you can check out the change-libadwaita-theme.sh script from here. Alternatively, you can do the following:

ln -s /your/theme/path/gtk-4.0/gtk.css ~/.config/gtk-4.0/
# Or, if you want to copy instead of symlink:
cp -r /your/theme/path/gtk-4.0/gtk.css ~/.config/gtk-4.0/

Conclusion

Overall, whilst GNOME theming isn't dead in the slightest, it's still not as easy as it once was, and both of these methods still have their own issues. Mainly, the CSS method doesn't allow for theme switching, and the Environment Variable might break on Flatpak applications.