While working on a desktop clock extension, I ran into an issue I couldn’t find documented anywhere in the GNOME Shell extension guides or Mutter source comments. Posting here in case it saves someone time.
The problem
Adding a custom St.BoxLayout to Main.layoutManager._backgroundGroup works correctly on the primary monitor. On secondary monitors, the actor receives zero allocation in the secondary ClutterStageView and doesn’t render at all — no errors, just nothing.
Root cause
Without visible content to paint, Clutter skips assigning a layout allocation to the actor in the secondary monitor’s stage view. The actor exists in the scene graph but has no geometry.
The fix
Add a near-invisible background color to the container:
const container = new St.BoxLayout({
style: 'background-color: rgba(0, 0, 0, 0.01);',
});
Main.layoutManager._backgroundGroup.add_child(container);
Giving the actor something to paint forces Clutter to assign it a proper allocation in the secondary ClutterStageView. The result: the widget renders correctly on all monitors, sits below all windows, and survives wallpaper changes and monitor hotplug.
Tested on GNOME 46–50, Wayland only.
Question
Is there a cleaner or more canonical way to achieve this? I’d expect something like this to be documented in the extension development guide.
I used this technique to build Modern Clock — a GNOME Shell port of the KDE Modern Clock desktop widget (Mond-style, Anurati font, configurable position, multi-monitor):
