Shadows somewm-only
The compositor draws shadows around clients and drawins, including wiboxes and popups. Widgets inside a wibox do not get separate compositor shadows.
Theme Variables
Configure global shadow defaults in your theme.lua. Shadows are disabled by default and must be explicitly enabled.
Client Shadow Variables
These control shadows for application windows (clients):
| Variable | Type | Default | Description |
|---|---|---|---|
shadow_enabled | boolean | false | Enable shadows globally for clients |
shadow_radius | integer | 12 | Blur radius in pixels |
shadow_offset_x | integer | -15 | Horizontal offset (negative = left) |
shadow_offset_y | integer | -15 | Vertical offset (negative = up) |
shadow_spread | integer | 0 | Grow the shadow by this many pixels on every side before the blur |
shadow_corner_radius | integer | 0 | Round the shadow's corners by this many pixels |
shadow_opacity | number | 0.75 | Shadow opacity (0.0 = invisible, 1.0 = solid) |
shadow_color | string | "#000000" | Shadow color as "#RRGGBB" or "#RRGGBBAA" (alpha multiplies opacity) |
shadow_clip and per-object clip_directional are accepted but have no effect in 2.1. Shadows fade on every side. Content hides the portions behind it.
Drawin/Wibox Shadow Variables
These control shadows for drawins and wiboxes (panels, popups, notifications). If not specified, they inherit from the client shadow settings.
| Variable | Type | Default | Description |
|---|---|---|---|
shadow_drawin_enabled | boolean | (inherits from shadow_enabled) | Enable shadows for drawins/wiboxes |
shadow_drawin_radius | integer | (inherits from shadow_radius) | Blur radius for drawins |
shadow_drawin_offset_x | integer | (inherits from shadow_offset_x) | Horizontal offset for drawins |
shadow_drawin_offset_y | integer | (inherits from shadow_offset_y) | Vertical offset for drawins |
shadow_drawin_spread | integer | (inherits from shadow_spread) | Spread for drawins |
shadow_drawin_corner_radius | integer | (inherits from shadow_corner_radius) | Corner radius for drawins |
shadow_drawin_opacity | number | (inherits from shadow_opacity) | Opacity for drawins |
shadow_drawin_color | string | (inherits from shadow_color) | Color for drawins |
Theme Example
local theme = {}
-- Enable shadows for all windows
theme.shadow_enabled = true
theme.shadow_radius = 12
theme.shadow_offset_x = -15
theme.shadow_offset_y = -15
theme.shadow_opacity = 0.75
theme.shadow_color = "#000000"
-- Disable shadows for panels/wiboxes (optional)
theme.shadow_drawin_enabled = false
Client Properties
client.shadow
The shadow property controls shadows on individual clients.
Type: boolean or table
Access: Read/Write
When set to a boolean:
true- Enable shadow using theme defaultsfalse- Disable shadow for this client
Each assignment starts from theme defaults, not the previous override. A table enables the shadow unless enabled = false. Assigning nil disables it.
| Option | Type | Description |
|---|---|---|
enabled | boolean | Enable/disable shadow (default: true when table is provided) |
radius | integer | Blur radius in pixels |
offset_x | integer | Horizontal offset |
offset_y | integer | Vertical offset |
spread | integer | Grow the shadow by this many pixels on every side before the blur |
corner_radius | integer | Round the shadow's corners by this many pixels |
opacity | number | Shadow opacity (0.0-1.0) |
color | string or table | Color as "#RRGGBB"/"#RRGGBBAA" string or {r, g, b, a} table (values 0.0-1.0). Alpha multiplies opacity |
Examples:
-- Enable shadow with theme defaults
c.shadow = true
-- Disable shadow
c.shadow = false
-- Custom shadow configuration
c.shadow = {
radius = 8,
opacity = 0.5,
color = "#FF0000" -- Red shadow
}
-- Partial override (other values use theme defaults)
c.shadow = {
offset_x = -25,
offset_y = -25
}
-- Color as RGBA table
c.shadow = {
color = {0.5, 0.0, 0.5, 1.0} -- Purple
}
Reading Shadow Configuration
Reading client.shadow returns false when disabled, or a table of the current settings when enabled.
local s = c.shadow
if s then
print("Shadow enabled with radius:", s.radius)
print("Shadow color:", s.color)
else
print("Shadow disabled")
end
Drawin/Wibox Properties
drawin.shadow
The shadow property on drawins and wiboxes works identically to the client shadow property.
Type: boolean or table
Access: Read/Write
Examples:
-- Wibox with shadow
local mywibox = wibox {
width = 300,
height = 50,
visible = true,
shadow = true
}
-- Popup with custom shadow
local popup = awful.popup {
widget = wibox.widget.textbox("Popup"),
shadow = {
radius = 16,
opacity = 0.8
}
}
-- Notification-style glow effect
local notification_box = wibox {
width = 400,
height = 100,
shadow = {
color = "#3399FF",
radius = 20,
opacity = 0.6
}
}
Signals
property::shadow
Emitted when the shadow property changes on a client or drawin.
client.connect_signal("property::shadow", function(c)
local shadow = c.shadow
if shadow then
print(c.name .. " now has shadows enabled")
end
end)
Using Rules
Client rules accept a shadow property. Rules apply when a client is managed, not every time floating or fullscreen changes.
Dynamic Control
awesome.shadow_reload() rereads beautiful.shadow_* defaults and updates existing shadows. Per-object overrides remain in effect.
local beautiful = require("beautiful")
beautiful.shadow_enabled = true
awesome.shadow_reload()
Complete Example
See Configure shadows for theme settings, rules, and runtime changes.
Technical Notes
- The shadow is the window's frame grown by
spread, moved by the offset, rounded bycorner_radius, fading out overradiuspixels on every side - It is rendered as a nine-patch (4 corner patches, 4 stretched edge strips, solid interior), so resizing reuses the patches
- The falloff uses a smoothstep function that visually approximates Gaussian blur
- Shadow nodes are placed below content in the wlroots scene graph
See Also
- How-To: Shadows - Practical guide for common shadow configurations
- Theme Tutorial - Introduction to theming
- Beautiful Theme Variables - All theme variables