How to Customize the Hyprland Status Bar: Complete Waybar Setup Guide

Hyprland does not include a built-in status bar; instead, it uses the layer-shell protocol (implemented in src/protocols/wlr-layer-shell-unstable-v1.hpp) to reserve screen space for external bars like Waybar, which you configure through JSON and CSS files while autostarting it via exec = waybar & in your Hyprland configuration.

The Hyprland compositor from the hyprwm/Hyprland repository manages window placement and input routing but deliberately delegates status bar rendering to external programs. By leveraging the layer-shell protocol, Hyprland can reserve exclusive screen zones for bars while allowing you to customize the appearance, modules, and positioning through the bar's own configuration files. This architecture provides complete flexibility to theme your setup without modifying Hyprland's core source code.

Understanding the Layer-Shell Architecture

Hyprland's Role: Space Reservation and Input Routing

Hyprland's responsibility is limited to managing the exclusive zone—the screen real estate occupied by the bar—and forwarding input events. According to the source code in src/protocols/wlr-layer-shell-unstable-v1.hpp, Hyprland implements the wlr_layer_shell_unstable_v1 protocol, which allows clients (like Waybar) to request specific layers (overlay, top, bottom) and reserve pixels that other windows cannot overlap.

The SeatManager.cpp file in src/managers/ handles input routing for these layer surfaces, ensuring clicks and keyboard events reach your status bar when focused. Additionally, src/desktop/view/Window.cpp contains specific workarounds for Waybar focus issues, demonstrating Hyprland's first-class support for external bars.

The Bar's Role: Rendering and Content

The status bar itself—typically Waybar—runs as a separate process and handles all visual rendering. The bar creates a layer-shell surface, specifies its desired dimensions, and renders content (clocks, workspaces, system trays) independently. Hyprland respects the bar's requested exclusive zone, preventing application windows from obscuring it.

Setting Up Waybar with Hyprland

Installation

Install Waybar using your distribution's package manager. Waybar is the most common choice because it natively supports the layer-shell protocol required by Hyprland.

# Arch Linux

sudo pacman -S waybar

# Debian/Ubuntu

sudo apt install waybar

# Fedora

sudo dnf install waybar

Basic Configuration

Create the Waybar configuration directory and files:

mkdir -p ~/.config/waybar
touch ~/.config/waybar/config
touch ~/.config/waybar/style.css

Edit ~/.config/waybar/config to define the bar's position, height, and modules:

{
    "layer": "top",
    "position": "top",
    "height": 28,
    "spacing": 5,
    "modules-left": ["hyprland/workspaces", "hyprland/window"],
    "modules-center": ["clock"],
    "modules-right": ["network", "battery", "pulseaudio"]
}

Autostarting in Hyprland

Add the bar to your Hyprland configuration to launch it automatically. As shown in example/hyprland.lua around line 42, you should use the exec keyword to autostart status bars:

# ~/.config/hypr/hyprland.conf

exec = waybar &

You can also set environment variables for Waybar before launching:

exec = env WAYBAR_DISABLE_UNUSED_MODULES=1 waybar &

Customizing Appearance and Position

Styling with CSS

Waybar's appearance is controlled via ~/.config/waybar/style.css. Hyprland imposes no restrictions on theming—you have full CSS control:

* {
    font-family: "JetBrains Mono", "Noto Sans";
    font-size: 13px;
}

#waybar {
    background: rgba(30, 30, 46, 0.95);
    border-bottom: 2px solid #313244;
    color: #cdd6f4;
}

#workspaces button {
    padding: 0 10px;
    border-radius: 6px;
}

#clock {
    color: #fab387;
    font-weight: 600;
    margin-right: 8px;
}

Positioning Top or Bottom

To move the bar to the bottom of the screen, modify the position field in your Waybar config:

{
    "layer": "top",
    "position": "bottom",
    "height": 30
}

Hyprland automatically respects the layer-shell anchor flags sent by Waybar, adjusting window tiling boundaries accordingly.

Advanced Configuration Techniques

Per-Monitor Bars

Configure Waybar to display different bars on specific monitors by defining multiple bars in the config:

{
    "output": "DP-1",
    "position": "top",
    "modules-left": ["hyprland/workspaces"]
},
{
    "output": "HDMI-A-1",
    "position": "bottom",
    "modules-left": ["hyprland/workspaces"]
}

Hyprland identifies monitors by their Wayland output names (visible via hyprctl monitors).

Managing Exclusive Zones

By default, Waybar requests an exclusive zone equal to its height, preventing windows from overlapping it. To create an overlay bar that floats above content, set:

{
    "layer": "top",
    "position": "top",
    "exclusive-zone": 0,
    "height": 30
}

With "exclusive-zone": 0, Hyprland allows tiled windows to render underneath the bar, creating a transparent overlay effect.

Custom Modules

Add custom scripts to your bar by referencing them in the configuration:

{
    "modules-center": ["custom/weather"],
    "custom/weather": {
        "exec": "/usr/local/bin/weather-script.sh",
        "interval": 3600
    }
}

Ensure your script outputs valid text (or JSON with return-type": "json"). Hyprland does not process this data; Waybar handles execution independently.

Summary

• Hyprland has no built-in status bar: It relies on external layer-shell clients like Waybar, as evidenced by the autostart comments in example/hyprland.lua.
• Layer-shell protocol handles integration: src/protocols/wlr-layer-shell-unstable-v1.hpp implements the protocol that allows bars to reserve exclusive screen space.
• Configuration happens outside Hyprland: You customize the bar's content via JSON (~/.config/waybar/config) and appearance via CSS (~/.config/waybar/style.css).
• Autostart with exec: Add exec = waybar & to your hyprland.conf to launch the bar automatically.
• Per-monitor support: Configure output fields in Waybar and use hyprctl monitors to identify display names.

Frequently Asked Questions

Does Hyprland include a built-in status bar?

No. The Hyprland compositor intentionally omits a built-in status bar to maintain modularity. Instead, it implements the wlr_layer_shell_unstable_v1 protocol in src/protocols/wlr-layer-shell-unstable-v1.hpp to support external bars like Waybar, which provide their own configuration systems.

Why is my status bar overlapping with application windows?

This occurs when the bar's exclusive zone is set to 0 or the bar uses the overlay layer. To fix this, ensure your bar configuration sets "exclusive-zone": [positive_number] (usually matching your bar height), and verify that Hyprland recognizes the layer-shell surface by checking hyprctl layers output.

Can I use a different status bar with Hyprland?

Yes. Any bar implementing the layer-shell protocol works with Hyprland. Alternatives include eww (ElKowar's Wacky Widgets), yambar, and waybar. Simply install your preferred bar and add its launch command (e.g., exec = yambar &) to your Hyprland configuration file.

How do I reload the status bar without restarting Hyprland?

Kill the Waybar process and relaunch it, or use Waybar's signal-based reload if available. For a full configuration refresh, run killall waybar && waybar & from a terminal, or bind this command to a key in your Hyprland config using bind = SUPER, R, exec, killall waybar && waybar &.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}