Wayland Layer Shell & Layer Rules

Configuring blur for Wayland layer shells can be tricky since each compositor handles it differently.

Overview​

DMS uses Wayland's layer shell protocol for all UI components: the bar, popups, modals, OSDs, and notifications. Each component type gets its own namespace, allowing your compositor to target them individually for blur effects.

Layer shell surfaces differ from regular windows—they're UI overlays positioned at specific layers (background, bottom, top, overlay). By assigning unique namespaces to each component type, you can apply blur selectively (e.g., "blur all modals" or "blur all popouts") without affecting other elements.

Component Namespaces​

Every component namespace starts with dms: followed by the rest of the namespace, DMS uses the following namespaces for layer shell components:

Modals​

Full-screen modal dialogs including settings, power menu, and clipboard history. These overlay the entire screen and optionally dim the background.

Popouts​

Popup panels triggered by bar widgets, such as the control center, app drawer, and notification center. These are anchored to the bar and slide out accordingly.

Desktop widgets​

Desktop widget (both builtins and plugins) and other layers related to desktop widgets.

Misc Components​

Namespaces for other component that aren't modals or popouts.

Tip: If you are unsure about a component's namespace, you can check it using your compositor's tools:

• Hyprland: Run hyprctl layers with the layer opened
• Niri: Run niri msg layers to list active layer surfaces

If you're a plugin dev, see the plugin development page to add your layer namespace.

Compositor Examples​

Each compositor has its own syntax for layer rules.

Hyprland​

Blur Settings​

decoration {
    blur {
        enabled = true
        size = 10
        passes = 4

        ignore_opacity = true
        new_optimizations = true
        xray = false

        noise = 0.02
        contrast = 1.1
        vibrancy = 0.2
        vibrancy_darkness = 0.3
    }

    drop_shadow = true
    shadow_range = 20
    shadow_render_power = 3
    col.shadow = rgba(00000099)
}

Layer Rules​

Add these layer rules to enable blur for DMS components:

# Animations
layerrule {
    animation = slide right
    match:namespace = dms:control-center
}

layerrule {
    animation = slide top
    match:namespace = dms:workspace-overview
}
# You can find all available animations here: https://wiki.hypr.land/Configuring/Animations/#animation-tree

# Blur
# You can use match:namespace with regex to target multiple layers
layerrule {
    blur = on
    ignore_alpha = 0
    match:namespace = dms:(color-picker|clipboard|spotlight|settings)
}

# Dim (if you prefer a dim instead of a blur effect)
layerrule {
    dimaround = on
    match:namespace = dms:(color-picker|clipboard|spotlight|settings)
}

Examples​

# Modals
layerrule {
    blur = on
    ignore_alpha = 0
    match:namespace = dms:(polkit|notification-center-modal|workspace-overview|color-picker|clipboard|spotlight|settings|process-list-modal)
}

# Shell components (bar, popouts, etc.)
layerrule {
    blur = on
    ignore_alpha = 0
    match:namespace = dms:(bar|tooltip|toast|dock-context-menu|tray-menu-window|control-center|notification-center-popout|dash|system-update|process-list-popout|battery|popout|app-launcher)
}

Performance Tuning​

If blur is impacting system performance, try these optimizations in order:

1. Reduce passes: Set passes = 2 instead of 4
2. Reduce size: Set size = 6 instead of 10
3. Use xray mode: Set xray = true to reduce blur on stacked layers

You can test blur impact in real-time:

hyprctl keyword decoration:blur:enabled false
# Test performance
hyprctl keyword decoration:blur:enabled true

You can find more about Hyprland's layer rules here.

Niri​

Niri uses a different configuration format with layer-rule blocks. Each rule can match namespaces using regex patterns.

Layer Rules​

// Block out sensitive components from screencasts
layer-rule {
    match namespace="^dms:clipboard$"

    block-out-from "screencast"
}

// Match all DMS layers with a regex
layer-rule {
    match namespace=r#"^dms:.*"#

    // Apply rules to all DMS components
}

Shadow Settings​

layer-rule {
    match namespace="^dms:bar$"
    match namespace="^dms:dock$"

    shadow {
        on
        // off
        softness 40
        spread 5
        offset x=0 y=5
        draw-behind-window true
        color "#00000064"
        // inactive-color "#00000064"
    }
}

You can find more about Niri's layer rules here.

Other Compositors​

Not all compositors support blur or layer rules. Check your compositor's documentation for available options.

DMS is compositor-agnostic—it only sets namespaces and lets the compositor handle the effects. Once you determine the appropriate layer rule syntax for your compositor, you can target the same namespaces listed above.

• MangoWC's layer rules wiki page