Hyprland Titlebars on Omarchy

Hyprland Titlebars on Omarchy

Omarchy Hyprland Titlebars is a native Hyprland plugin (a fork of hyprbars, maintained under the omacom org) that gives Omarchy's floating workspaces their window titlebars — drag to move, double-click to maximize, theme-neutral colors, and window-aware titles.

TL;DR

omarchy pkg add omarchy-hyprland-titlebars

Takes ~1 minute (v0.2.2-2, BSD-3-Clause + MIT). This is not an app you launch — there's no window, no launcher icon. It's a Hyprland plugin that Omarchy's own Lua config loads automatically, but only while a workspace is floating. If you never float anything, it does nothing visible — that's by design.

Getting started (5 minutes)

1. Install.

Run the command above. The plugin lands at the fixed path /usr/lib/omarchy-hyprland-titlebars/titlebars.so — that path is a contract with Omarchy core, which loads it with hl.plugin.load("/usr/lib/omarchy-hyprland-titlebars/titlebars.so") from its Lua config, only while a workspace floats.

2. See it work.

Float a window (Super + T toggles tiling/floating, or pop one out) and the titlebar appears: theme-neutral colors, the app's name, and buttons. Drag the titlebar to move the window. Double-click it to maximize. Drag a maximized window's titlebar and it comes back to its floating size, landing under your pointer. Buttons highlight in their own icon color at low opacity on hover, so the effect follows any theme without a setting.

3. The 3 things you need to know:

• Titles are smarter than the raw window title — A titlebar shows the app's name when a desktop entry claims the window's class (via StartupWMClass or its file name), and the window's own title otherwise. Web apps get their page title or just their domain — which is why web.whatsapp.com reads "WhatsApp" instead of a URL. Your own entries in $XDG_DATA_HOME/applications win over system ones, and an entry added while Hyprland runs is picked up within a couple of seconds.
• It's a hyprbars fork with Omarchy opinions — It registers itself with Hyprland as hyprbars and keeps the hl.plugin.hyprbars.add_button() Lua interface and all plugin.hyprbars.* options, because Omarchy's config is written against those names. The fork (adapted from the Omarchy Windows 98 theme's vendored hyprbars, with Hyprland 0.56 Lua API support) adds three options: enabled (defaults to false, unlike upstream's true — a loaded-but-unconfigured plugin draws nothing instead of surprise bars), bar_color_inactive (transparent falls back to bar_color), and workspace_tag (scope titlebars to floating windows carrying a tag; untag or tile and the titlebar space releases immediately).
• Custom buttons can target the clicked window safely — Button action commands and on_double_click may contain %WINDOW%, replaced synchronously with the clicked titlebar's window address (e.g. 0x1234abcd) before the command spawns — so async actions stay aimed at the clicked window even if focus moved. The replacement is hex only; no window title or app-controlled text enters the command. Example from the README:

  hl.plugin.hyprbars.add_button({
    bg_color = "rgb(f7768e)", fg_color = "rgb(1a1b26)", size = 18, icon = "×",
    action = [[hyprctl dispatch 'hl.dsp.window.close({ window = "address:%WINDOW%" })']],
  })

4. Colors, font, rounding, actions come from Omarchy's config.

No theme styling is embedded in the renderer — the plugin draws what Omarchy tells it. That's why it's theme-neutral and why switching Omarchy themes doesn't need a plugin update.

5. Config location.

There is no per-user config file — behavior is driven by Omarchy's own Hyprland Lua configuration (plugin.hyprbars.* options and the add_button interface). The package files: /usr/lib/omarchy-hyprland-titlebars/titlebars.so, licenses under /usr/share/licenses/omarchy-hyprland-titlebars/.

Practical notes: This exists because Omarchy core has no build step, so the plugin ships as its own package built by omarchy-pkgs from the repo's release tags. It coexists safely with the Windows XP theme's own hyprbars fork (symbols carry an OmarchyFloating prefix, built with -fno-gnu-unique for clean load/unload).

Common issues & fixes

After a Hyprland update, floating windows lose their titlebars (or Hyprland refuses to load the plugin)

A Hyprland plugin only loads into the exact Hyprland build it was compiled against — Hyprland refuses mismatched builds. The package pins hyprland=0.56.2 as a dependency, and omarchy-pkgs rebuilds the plugin whenever Hyprland changes, moving the pin automatically (rebuild_on in .omarchy/package.json).

Fix: A normal package update should heal this itself — if titlebars vanish after an update, check that the titlebars package actually upgraded alongside Hyprland (pacman -Q omarchy-hyprland-titlebars), and don't try to load an old titlebars.so by hand.

You installed it and see no titlebars anywhere

Almost certainly because nothing is floating. The plugin is loaded from Omarchy's Lua config only while a workspace floats — tiled workspaces never get titlebars, by design.

Fix: Float a window (Super + T) and look again. If you loaded the plugin manually (e.g. via hyprpm) and still see nothing, remember this fork defaults enabled to false — unlike upstream hyprbars, a loaded-but-unconfigured plugin deliberately draws nothing.

A titlebar shows a cryptic raw window title instead of the app name

Titles come from desktop entries: the app name appears when an entry claims the window's class through StartupWMClass or its file name. No matching entry → the raw window title.

Fix: Add your own desktop entry in ~/.local/share/applications/ (yours wins over system entries) with the right StartupWMClass — it's picked up within a couple of seconds, no Hyprland restart needed.

You want titlebars on floating windows but not on every floating window

Use the fork's workspace_tag option: set it and titlebars apply only to floating windows carrying that tag. Remove the tag (or tile the window) and the titlebar space releases immediately.

Fix: This is a per-config option in Omarchy's Lua — there's no GUI for it; it's a tinkerer's knob. (UNVERIFIED on-machine: confirm the exact option path before publishing.)

Pairs well with / If you hate this, try

Pairs well with

• Omarchy's floating workspace mode itself — that's the whole point. The Windows 98 / Windows XP Omarchy themes, which vendor their own hyprbars forks this package was adapted from (they coexist cleanly). hyprctl for inspecting window addresses when writing custom %WINDOW% buttons.

If you hate this, try

• Pure tiling — the Omarchy default. Don't install the package at all and floating windows stay bare, exactly like stock Omarchy. Or the upstream hyprbars plugin if you want the unmodified original with its own defaults (this fork's enabled=false default and tag scoping are Omarchy opinions).

Comparison: titlebar options on Omarchy

Verdict: Install this if you float windows on Omarchy and want titlebars that match the system's config; skip it if you live in pure tiling; grab upstream hyprbars only if you're configuring Hyprland by hand outside Omarchy's opinions.