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

> Learn how to customize your Hyprland status bar with Waybar. This guide explains the JSON and CSS configuration needed to set up your custom bar.

- Repository: [Hypr Development/Hyprland](https://github.com/hyprwm/Hyprland)
- Tags: how-to-guide
- Published: 2026-07-29

---

**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`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/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.

```bash

# 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:

```bash
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:

```json
{
    "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`](https://github.com/hyprwm/Hyprland/blob/main/example/hyprland.lua) around line 42, you should use the `exec` keyword to autostart status bars:

```ini

# ~/.config/hypr/hyprland.conf

exec = waybar &

```

You can also set environment variables for Waybar before launching:

```ini
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:

```css
* {
    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:

```json
{
    "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:

```json
{
    "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:

```json
{
    "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:

```json
{
    "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`](https://github.com/hyprwm/Hyprland/blob/main/example/hyprland.lua).
- **Layer-shell protocol handles integration**: [`src/protocols/wlr-layer-shell-unstable-v1.hpp`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/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 &`.