Skip to main content
Version: 2.2 (dev)

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

VariableTypeDefaultDescription
shadow_enabledbooleanfalseEnable shadows globally for clients
shadow_radiusinteger12Blur radius in pixels
shadow_offset_xinteger-15Horizontal offset (negative = left)
shadow_offset_yinteger-15Vertical offset (negative = up)
shadow_spreadinteger0Grow the shadow by this many pixels on every side before the blur
shadow_corner_radiusinteger0Round the shadow's corners by this many pixels
shadow_opacitynumber0.75Shadow opacity (0.0 = invisible, 1.0 = solid)
shadow_colorstring"#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.

VariableTypeDefaultDescription
shadow_drawin_enabledboolean(inherits from shadow_enabled)Enable shadows for drawins/wiboxes
shadow_drawin_radiusinteger(inherits from shadow_radius)Blur radius for drawins
shadow_drawin_offset_xinteger(inherits from shadow_offset_x)Horizontal offset for drawins
shadow_drawin_offset_yinteger(inherits from shadow_offset_y)Vertical offset for drawins
shadow_drawin_spreadinteger(inherits from shadow_spread)Spread for drawins
shadow_drawin_corner_radiusinteger(inherits from shadow_corner_radius)Corner radius for drawins
shadow_drawin_opacitynumber(inherits from shadow_opacity)Opacity for drawins
shadow_drawin_colorstring(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 defaults
  • false - 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.

OptionTypeDescription
enabledbooleanEnable/disable shadow (default: true when table is provided)
radiusintegerBlur radius in pixels
offset_xintegerHorizontal offset
offset_yintegerVertical offset
spreadintegerGrow the shadow by this many pixels on every side before the blur
corner_radiusintegerRound the shadow's corners by this many pixels
opacitynumberShadow opacity (0.0-1.0)
colorstring or tableColor 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 by corner_radius, fading out over radius pixels 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​