Notifications

[notification]
enable_daemon            = true        # when false, don't claim org.freedesktop.Notifications; internal toasts still work
show_app_name            = true        # show the sending application name in toasts
show_actions             = true        # show action buttons; when false, clicking a toast triggers its default action
position                 = "top_right" # top_right | top_left | top_center | bottom_right | bottom_left | bottom_center
layer                    = "top"       # top | overlay; overlay appears above fullscreen apps
scale                    = 1.0         # toast size multiplier on top of shell.ui_scale
background_opacity       = 0.97        # toast card background alpha; lower values let compositor blur show through
border                   = true        # outline around toast cards; set false for a borderless look
offset_x                 = 20          # absolute horizontal margin from the screen edge
offset_y                 = 8           # absolute vertical margin from the screen edge
monitors                 = []          # empty = all monitors; otherwise connector/description selectors (e.g. ["eDP-1", "DP-1"])
collapse_on_dismiss      = true        # slide remaining toasts to close gaps when one is dismissed
history_retention_hours  = 0           # delete stored history older than this; 0 keeps it indefinitely

[notification.filter.rhythmbox]
enabled         = true
match           = "rhythmbox"
# match_content   = "now playing"           # optional regex matched against summary or body
show_toast      = true
save_history    = false
play_sound      = true
# allow_permanent = true                      # allow this sender to create persistent (0-timeout) toasts
# override_duration = 5000                    # override the timeout (in ms) for all toasts from this sender
# allowed_urgencies = ["normal", "critical"]  # omit or list all three to allow every level

• layer = "top" keeps toasts above normal app windows.
• layer = "overlay" shows toasts above fullscreen apps.
• offset_x and offset_y are absolute margins from the nearest screen edge for the configured position.
• monitors = [] shows notifications on all monitors (default).
• When monitors is non-empty, toasts are only created on matching monitors.
• If none of the configured monitors are currently connected (e.g. an external display was undocked), Noctalia falls back to showing toasts on all available monitors so notifications never disappear silently. Targeting is restored automatically when a configured monitor reconnects.
• Selector matching follows monitor override rules: exact connector name (eDP-1) or a word-boundary token in the monitor description.
• Internal Noctalia notifications (shell and plugins) are toast-only and are never stored in notification history.
• history_retention_hours removes stored external notifications older than the configured number of hours. The default 0 retains history indefinitely; accepted values are 0–8760.
• collapse_on_dismiss = true (default) causes remaining toasts to slide into a compact stack when one is dismissed. Set to false for stable-slot behavior where toasts keep their original positions.
• border = true (default) draws an outline around toast cards. Set to false for a borderless look.
• history_retention_hours = 0 (default) keeps notification history entries forever. Set to a positive integer (1–8760) to automatically remove entries older than that many hours from control-center history. Active on-screen toasts are never removed. Configure in Settings → Notifications → History.

Filtering

Notifications can be filtered before toasts and sounds. External Freedesktop notifications can also be kept out of control-center history. Internal shell/plugin toasts use the same toast/sound filters, but they are never written to history (the save-history flag does not apply to them).

• [notification.filter.<name>] - per-sender rules evaluated in filter_order (first matching enabled filter wins). Each filter has:
• match - one case-insensitive token matched against the app name (exact or substring), desktop-entry, or category.
• match_content - optional regular expression matched against the notification summary or body.
• allowed_urgencies - when non-empty, only listed urgency levels pass this filter. Values: low, normal, critical. Omit or list all three to allow every level.
• show_toast - show a toast popup (default true).
• save_history - keep the notification in control-center history (default true). External notifications only; internals are never stored.
• play_sound - play the notification sound when a toast is shown (default true).
• allow_permanent - allow this sender to create persistent (0-timeout) toasts (default true). When false, persistent toasts are forced to the standard expiration timeout.
• override_duration - force a specific display duration in milliseconds, overriding both the default timeout and any timeout requested by the sender.

When no filter matches, all flags default to allow. A fully suppressed notification (no toast and no history) still returns a valid D-Bus id; CloseNotification on that id succeeds without showing a toast.

To hide a plugin toast such as Audio Switcher, match its summary or body and disable the toast:

[notification.filter.audio-switcher]
enabled       = true
match_content = "Audio Switcher|Output switched"
show_toast    = false
play_sound    = false

Configure filtering in Settings → Notifications → Filtering, or in the Noctalia TOML config stack.

Disable notification history

To keep showing external notification toasts without retaining them in control-center history, add a catch-all filter:

[notification]
filter_order = ["no_history"]

[notification.filter.no_history]
enabled       = true
match_content = ".*"
show_toast    = true
save_history  = false
play_sound    = true

The empty app match and .* content regex match every notification for toast/sound purposes. Because the first matching enabled filter wins, keep no_history first in filter_order if you add other filters. In Settings, leave App empty, enter .* for Content Regex, and disable Save to history. Note that a catch-all with show_toast = false would also hide internal shell/plugin toasts.

This affects new notifications only. Use noctalia msg notification-clear-history to remove entries already stored in history.

Related IPC

For Do Not Disturb status/toggle commands and notification clear actions, see Media & UI → Notifications.