Skip to main content
Version: 2.1

naughty

The naughty library handles desktop notifications. It receives notifications from applications via the D-Bus org.freedesktop.Notifications interface and displays them on screen.

Deviations from AwesomeWM​

Notifications use the standard D-Bus service on Wayland. The widget and rule APIs follow AwesomeWM.

Modules​

ModulePurpose
naughty.notificationNotification object
naughty.layout.boxDefault notification display widget
naughty.widget.iconNotification icon widget
naughty.widget.titleNotification title widget
naughty.widget.messageNotification message widget
naughty.list.actionsNotification action buttons widget
naughty.actionNotification action (clickable button)
ruled.notificationRule-based notification configuration

Display Handler​

The default config already registers a request::display handler. A config without one can use:

local naughty = require("naughty")

naughty.connect_signal("request::display", function(n)
naughty.layout.box { notification = n }
end)

naughty.notification​

naughty.notification creates a notification object. The constructor still accepts text as an alias for message, but the resulting object has no text property.

naughty.notification {
title = "Title",
message = "Body text",
timeout = 5,
}

Parameters​

ParameterTypeDefaultDescription
titlestring""Notification title
messagestring""Notification body
timeoutnumber5Auto-dismiss time in seconds (0 = never)
urgencystring"normal""low", "normal", or "critical"
positionstring"top_right"Screen position (see Positions)
iconstringnilPath to icon image
icon_sizenumbernilIcon size in pixels
bgstringtheme defaultBackground colour
fgstringtheme defaultForeground colour
actionstable{}List of naughty.action objects
ignore_suspendbooleanfalseShow even when notifications are suspended
categorystringnilNotification category (e.g., "email.arrived")
app_namestringnilApplication name

Actions​

invoked belongs to each action, not the notification. The default action widget passes the action and its notification to the handler:

local naughty = require("naughty")
local open = naughty.action { name = "Open" }
open:connect_signal("invoked", function(action, notification)
print(action.name, notification.title)
end)

local n = naughty.notification {
title = "Download complete",
message = "document.pdf",
actions = { open },
}

Calling open:invoke(n) emits the same signal. Calling it without an argument passes nil as the notification.

naughty.config.defaults​

Fallback values used unless properties, rules, presets, or theme settings override them:

PropertyTypeDefaultDescription
timeoutnumber5Auto-dismiss time in seconds
positionstring"top_right"Screen position
marginnumberDPI-scaled 5Margin inside the notification
icon_sizenumbernilIcon size override

Spacing​

naughty.config.padding defaults to DPI-scaled 4 pixels from the workarea edge. spacing defaults to DPI-scaled 1 pixel between notifications. For example:

naughty.config.spacing = 4  -- Gap between stacked notifications

Positions​

ValueLocation
"top_left"Top-left corner
"top_middle"Top centre
"top_right"Top-right corner (default)
"bottom_left"Bottom-left corner
"bottom_middle"Bottom centre
"bottom_right"Bottom-right corner

Urgency Presets​

Legacy D-Bus notifications use naughty.config.presets by urgency. Connecting ruled.notification’s request::rules handler replaces this preset matching with rules. Use the notification rules below in a modern config.

PresetDefault TimeoutDescription
naughty.config.presets.low5Subtle, low-priority
naughty.config.presets.normalInherits defaultsNo preset override
naughty.config.presets.critical0 (never)Requires manual dismissal

Presets accept notification properties. Lua-created notifications use a preset only when it is passed explicitly as preset = naughty.config.presets.critical:

naughty.config.presets.critical.bg = "#ff0000"
naughty.config.presets.critical.fg = "#ffffff"
naughty.config.presets.critical.timeout = 0

Notification Rules​

ruled.notification applies properties to notifications matching specified criteria.

local ruled = require("ruled")

ruled.notification.connect_signal("request::rules", function()
ruled.notification.append_rule {
rule = { app_name = "Spotify" },
properties = { timeout = 3 }
}
end)

Rule Matching Fields​

FieldTypeDescription
app_namestringApplication name (e.g., "Spotify", "discord")
titlestringNotification title (supports Lua patterns)
messagestringNotification body text (supports Lua patterns)
urgencystring"low", "normal", or "critical"
categorystringNotification category (e.g., "email.arrived")

String matching accepts equality or Lua patterns. All fields in rule must match. rule_any matches any listed alternative. If both are present, either rule or rule_any can match:

ruled.notification.append_rule {
rule_any = {
app_name = { "Spotify", "vlc" },
category = { "device.error", "network.error" },
},
properties = { timeout = 3 },
}

Rule Settable Properties​

PropertyTypeDescription
timeoutnumberAuto-dismiss time in seconds (0 = never)
implicit_timeoutnumberFallback timeout if notification doesn't specify one
never_timeoutbooleanForce timeout to 0
positionstringScreen position
screenscreenTarget screen
ignore_suspendbooleanShow even when suspended
ignorebooleanCompletely ignore this notification
bgstringBackground colour
fgstringForeground colour
iconstringIcon path
icon_sizenumberIcon size in pixels

Suspension​

Suspend notifications to prevent them from displaying:

naughty.suspended = true   -- Suspend all notifications
naughty.suspended = false -- Resume (queued notifications appear)

Notifications with ignore_suspend = true still display while suspended.

Access queued notifications during suspension:

for _, n in ipairs(naughty.notifications.suspended) do
print(n.title)
end

Removed functions​

These functions are absent in 2.1. Calling one raises a Lua error.

RemovedUse instead
naughty.notify(args)naughty.notification(args)
naughty.suspend()naughty.suspended = true
naughty.resume()naughty.suspended = false
naughty.toggle()naughty.suspended = not naughty.suspended
naughty.is_suspended()naughty.suspended
naughty.destroy(n, reason)n:destroy(reason)
naughty.getById(id)naughty.get_by_id(id)
naughty.reset_timeout(n, t)n:reset_timeout(t)
naughty.replace_text(n, title, text)Set n.title and n.message

Signals​

Notification Lifecycle​

SignalArgumentsDescription
request::displaynNotification ready for the configured display handler
request::rules(none)Rules should be registered (via ruled.notification)
addednNotification created
destroyedn, reasonNotification dismissed or expired

Notification Object Signals​

SignalArgumentsDescription
invoked (on a naughty.action)action, notificationAction invoked. Connect to the action object
property::titlenTitle changed
property::messagenMessage changed
property::urgencynUrgency changed

Theme Variables​

Notifications are styled via beautiful variables. See Theme Variables: Notifications for the full list.

Key variables:

VariableDescription
notification_bgBackground colour
notification_fgForeground colour
notification_border_colorBorder colour
notification_border_widthBorder width in pixels
notification_widthDefault width
notification_max_widthMaximum width
notification_max_heightMaximum height
notification_icon_sizeDefault icon size
notification_fontFont
notification_shapeShape function

See Also​