Skip to main content

Notifications

kiln is the freedesktop notification service: notifications arrive over DBus and the compositor draws them itself.

1. kiln is the notification daemon​

kiln implements the freedesktop notification service (org.freedesktop.Notifications) itself: notify-send, browsers, chat apps, and volume scripts deliver straight to the compositor, which draws the popups as part of its own scene. Do not run mako, dunst, or another daemon alongside; they would compete for the same DBus name. The service advertises body, actions, and icon-static capabilities.

There is nothing to enable. A DBus session must exist (the standard make run line launches kiln under dbus-run-session), and notifications appear stacked at the top-right, colored by urgency.

2. Raise your own​

kiln.notify{} creates a notification from config code; the same constructor the DBus intake uses:

kiln.notify {
title = "Battery",
message = "15% remaining",
urgency = "critical",
}

It returns the notification object. The notification reference lists every accepted field. Passing the id of a visible notification replaces it in place, so repeated volume popups update one notification.

Critical notifications never expire. n:dismiss() ends one; notification.all() lists active notifications across all screens.

3. Tune timeouts per urgency​

When timeout is not given, the per-urgency default from the theme applies:

kiln.theme.notification_timeout = { low = 3, normal = 5, critical = 0 }

The display's size, insets, stacking gap, corner radius, and urgency border colors are all notification_* theme variables.

4. React to notifications: rules, actions, do-not-disturb​

The notification global is a class like client and tag; its four signals are in the signals reference. added fires before the notification is first drawn, so properties set there apply from the start:

notification.on("added", function(n)
if n.app_name == "spotify" then
n.timeout = 2
end
end)

Writing n.timeout re-arms the expiry, and writing the text or icon redraws. Actions are invoked with n:invoke(key); the stock display wires each action button's press to exactly that.

Do-not-disturb is one flag: notification.suspended = true queues arrivals instead of showing them; setting it back to false shows the queue in arrival order. notification.pending is the read-only queue.

kiln.key {
mods = { "mod", "shift" }, key = "d",
desc = "toggle do-not-disturb", group = "system",
press = function()
notification.suspended = not notification.suspended
end,
}

5. Replace the display wholesale​

The entire presentation is one replaceable function: kiln.defaults.notify_display(s) runs inside every screen's frame and declares whatever the notifications should look like. Assign your own, or set it to nil to render nothing at all (signals still fire, so a nil display plus your own listeners is a valid setup).

A display at the bottom-right of each notification's assigned screen:

local kiln = require("kiln")
local ui = kiln.ui

kiln.defaults.notify_display = function(s)
local list = {}
for _, n in ipairs(notification.all()) do
if n.screen == s then list[#list + 1] = n end
end
if #list == 0 then
return
end
local th = kiln.theme
ui.column({
id = "notifications",
float = {
to = "root", band = "overlay",
anchor = { parent = "right_bottom", element = "right_bottom" },
offset = { x = -12, y = -12 },
},
gap = 8,
}, function()
for _, n in ipairs(list) do
ui.column({
id = "notif:" .. n.seq,
w = 300, color = th.bg, radius = 6, pad = 10, gap = 4,
border = { width = 1,
color = n.urgency == "critical" and th.urgent or th.muted },
on_press = function() n:dismiss() end,
}, function()
if n.title ~= nil then
ui.text(n.title)
end
if n.message ~= nil then
ui.text(n.message, { size = 12 })
end
end)
end
end)
end

n.seq is a unique sequence number suitable for an element ID. Action buttons can call n:invoke(a.key); a progress bar can read n.value.

The stock display does not filter by n.screen: it draws all active notifications on every output that redraws. The filter above restricts each notification to its assigned screen. If you change n.screen, also dirty the old screen to remove its previous drawing. Notifications assigned to a removed screen need reassignment before this display can show them again.

See also​