Improving the appearance of CSD applications in KDE Plasma 5

UPDATE: Full support for CSD applications was introduced in KDE Plasma 5.18, so these instructions are only necessary if you are running an earlier version. If you followed the instructions below and then upgraded to Plasma 5.18, you will want to reverse the steps below to avoid any conflicts with Plasma’s built-in CSD application support.

If you’ve tried running GTK3 applications in KDE Plasma 5, you may have noticed that some of them appear and behave a bit strangely. As an example, here is the GNOME document viewer (“evince”) running in Plasma using the default “Breeze” visual style:

This application, among many others, uses “client side decoration”, or “CSD”, which means the control of the window is provided by the application rather than the window manager, allowing buttons and custom controls to be drawn in the window’s title bar (here called a “header bar”). This feature works fine within GNOME, but does not translate well to Plasma due to technical and philosophical differences between the two environments, as I understand it. You can read about some of the issues this feature has caused here and here.

Besides appearing ugly (square corners, no window shadow or defined boundary), these applications also cannot easily be resized (there is no way to grab the border) and only basic window management is functional.

A workaround for this issue is to use “gtk3-nocsd“, which adds a kwin window border and title bar around the application, and removes the window controls from the GTK3 header bar. Here is the result:

We now have a proper window border with rounded corners and shadows. The window can easily be resized, and all of the wonderful functionality of the kwin window manager can be used. However, the dark header bar–now just beneath the title bar–is visually inconsistent with other applications, and also looks buggy due to being misaligned at the edges with the window frame color. Furthermore, the window title is duplicated between the title bar and header bar.

Fortunately, GTK3 themes are written in CSS, so it is not difficult to fix these remaining issues. Changing the header bar background, button and text colors, hiding the window title and vertically centering the subtitle text gives the following result:

Aah! Now this fits much better into the Plasma ecosystem. If you’d like to replicate these results on your own system, follow these instructions:

  1. Install “gtk3-nocsd“. In Kubuntu / KDE neon, you can find the package in the distro repositories. In Arch / Manjaro, it is in the AUR. For other systems, please follow the instructions on the gtk3-nocsd page.
  2. In System Settings, choose the “Breeze” visual style for both Qt and GTK applications, along with the “Breeze” color scheme. These settings are located in:
    1. Appearance -> Colors
    2. Appearance -> Application Style -> Application Style
    3. Appearance ->Application Style -> GNOME/GTK Application Style
  3. Copy the following into “~/.config/gtk-3.0/gtk.css“:
    headerbar {
      border-radius: 0;
      color: #232627;
      background-color: #eff0f1;}
      headerbar .path-bar button {
        color: #232627;}
      headerbar button {
        color: #232627;}
        headerbar button:disabled {
          color: rgba(35, 38, 39, 0.35);}
        headerbar button:backdrop {
          color: #bdc3c7;}
        headerbar button.flat {
          color: #232627;}
          headerbar button.flat:disabled {
            color: rgba(35, 38, 39, 0.35);}
          headerbar button.flat:backdrop {
            color: #bdc3c7;}
        headerbar button:hover {
          color: #232627;}
          headerbar button:hover:backdrop {
            color: #bdc3c7;}
      headerbar .title {
        color: transparent;
        font-size: 0pt;}
  4. Log off and back on.

Please let me know how this works for you, and whether or not you run into any issues. I made this fix using KDE neon with Plasma 5.16.4, so I don’t know how well it will work with earlier versions. There is also the possibility that a future update to breeze-gtk might conflict with my CSS tweak, so keep that in mind when updating.