swaync - Configuration file

CONFIGURATION

Using a text editor with a JSON language server is recommended when editing the config file to be able to detect config errors

ignore-gtk-theme
type: bool
default: true
description: Unsets the GTK_THEME environment variable, fixing a lot of
issues with GTK themes ruining the users custom CSS themes.

positionX
type: string
default: right
values: left, right, center
description: Horizontal position of control center and notification window

positionY
type: string
default: top
values: top, center, bottom
description: Vertical position of control center and notification window

layer
type: string
default: overlay
values: background, bottom, top, overlay
description: Layer of notification window relative to normal windows.
background is below all windows, overlay is above all windows.

layer-shell
type: bool
default: true
description: Wether or not the windows should be opened as layer-shell
surfaces. Note: Requires swaync restart to apply

cssPriority
type: string
default: application
values: application, user
description: Which GTK priority to use when loading the default and user
CSS files. Pick "user" to override XDG_CONFIG_HOME/gtk-3.0/gtk.css

control-center-positionX
type: string
default: right
values: left, right, center
description: Optional: Horizontal position of the control center.
Supersedes positionX if not set to ‘none‘.

control-center-positionY
type: string
default: top
values: top, center, bottom
description: Optional: Vertical position of the control center.
Supersedes positionY if not set to ‘none‘.

control-center-margin-top
type: integer
default: 0
description: The margin (in pixels) at the top of the notification center. 0 to disable

control-center-margin-bottom
type: integer
default: 0
description: The margin (in pixels) at the bottom of the notification center. 0 to disable

control-center-margin-right
type: integer
default: 0
description: The margin (in pixels) at the right of the notification center. 0 to disable

control-center-margin-left
type: integer
default: 0
description: The margin (in pixels) at the left of the notification center. 0 to disable

control-center-layer
type: string
default: top
values: background, bottom, top, overlay
description: Layer of control center window relative to normal windows.
background is below all windows, overlay is above all windows.

control-center-exclusive-zone
type: bool
default: true
description: Whether or not the control center should follow the
compositors exclusive zones. An example would be setting it to
false to cover your panel/dock.

notification-2fa-action
type: bool
default: true
description: If each notification should display a ’COPY "1234"’ action

timeout
type: integer
default: 10
description: The notification timeout for notifications with normal priority

timeout-low
type: integer
default: 5
description: The notification timeout for notifications with low priority

timeout-critical
type: integer
default: 0
description: The notification timeout for notifications with critical priority. 0 to disable

notification-window-width
type: integer
default: 500
description: Width of the notification in pixels

notification-window-height
type: integer
default: -1
description: Max height of the notification in pixels. -1 to use
the full amount of space given by the compositor.

notification-window-preferred-output
type: string
default: ""
description: The preferred output to open the notification window
(popup notifications). Can either be the monitor connector
name (ex: "DP-1"), or the full name, manufacturer model serial
(ex: "Acer Technologies XV272U V 503023B314202").
If the output is not found, the currently focused one is picked.

keyboard-shortcuts
type: bool
default: true
description: If control center should use keyboard shortcuts

notification-grouping
type: bool
default: true
description: If notifications should be grouped by app name

image-visibility
type: string
default: always
values: always, when-available, never
description: An explanation about the purpose of this instance.

transition-time
type: integer
default: 200
description: The notification animation duration. 0 to disable

hide-on-clear
type: bool
default: false
description: Hides the control center after pressing "Clear All"

hide-on-action
type: bool
default: true
description: Hides the control center when clicking on notification action

text-empty
type: string
default: "No Notifications"
description: Text that appears when there are no notifications to show

fit-to-screen
type: bool
default: true
description: Whether the control center should expand vertically to fill the screen

relative-timestamps
type: bool
default: true
description: Display notification timestamps relative to now e.g. "26 minutes ago".
If false, a local iso8601-formatted absolute timestamp is displayed.

control-center-height
type: integer
default: 500
description: Height of the control center in pixels.
A value of -1 means that it will fit to the content.
Ignored when ’fit-to-screen’ is set to ’true’.
Also limited to the height of the monitor, unless

control-center-width
type: integer
default: 500
description: The control center width in pixels

control-center-preferred-output
type: string
default: ""
description: The preferred output to open the control center. Can either
be the monitor connector name (ex: "DP-1"), or
the full name, manufacturer model serial
(ex: "Acer Technologies XV272U V 503023B314202"). If the
output is not found, the currently focused one is picked.

notification-action-filter
type: object
visibility object properties:
use-regex
type: bool
optional: true
default: false
description: Indicates if all the below fields should use
regex or not.
app-name
type: string
optional: true
description: The app-name.
desktop-entry
type: string
optional: true
description: The desktop-entry.
id-matcher
type: string
optional: true (needs at least one matcher)
description: Matches the actions identifier. Can be found by
reading the output of swaync when run with the
G_MESSAGES_DEBUG=all environment variable.
text-matcher
type: string
optional: true (needs at least one matcher)
description: Matches the actions text visible in the notification.
description: Hides matching action(s) of matching notifications.
If the notification doesn’t include one of the properties, that
property will be ignored. If all properties match the given
notification, the matching actions will be hidden.
example:

{

			"notification-action-filter": {
				"hide-chromium-settings": {

				"desktop-entry": "chromium-browser",

				"use-regex": false,

				"id-matcher": "settings",

				"text-matcher": "Settings"
				}
			},

}

notification-visibility
type: object
visibility object properties:
state
type: string
optional: false
default: enabled
values: ignored, muted, transient, enabled
description: The notification visibility state.
override-urgency
type: string
optional: true
default: unset
values: unset, low, normal, critical
description: The new urgency for the notification if set.
app-name
type: string
optional: true
description: The app-name. Uses Regex.
desktop-entry
type: string
optional: true
description: The desktop-entry. Uses Regex.
summary
type: string
optional: true
description: The summary of the notification. Uses Regex.
body
type: string
optional: true
description: The body of the notification. Uses Regex.
urgency
type: string
optional: true
default: Normal
values: Low, Normal, Critical
description: The urgency of the notification.
category
type: string
optional: true
description: Which category the notification belongs to. Uses Regex.
description: Set the visibility or override urgency of each incoming
notification.
If the notification doesn’t include one of the properties, that
property will be ignored. All properties (except for state) use
regex. If all properties match the given notification, the
notification will be follow the provided state.
Only the first matching object will be used.
example:

{

			"notification-visibility": {
				"example-name": {

				"state": "The notification state",

				"app-name": "Notification app-name Regex",

				"summary": "Notification summary Regex",

				"body": "Notification body Regex",

				"urgency": "Low or Normal or Critical",

				"category": "Notification category Regex"
				}
			}

}

widgets
type: array
Default values: ["title", "dnd", "notifications"]
Valid array values (see widget-config for more information):
notifications
required: true
optional: false
title
optional: true
dnd
optional: true
label
optional: true
mpris
optional: true
menubar
optional: true
buttons-grid
optional: true
slider
optional: true
volume
optional: true
backlight
optional: true
inhibitors
optional: true
description:
Which order and which widgets to display.
If the "notifications" widget isn’t specified, it
will be placed at the bottom.
multiple of same widget:
Append a # with any value to the end of the widget name.
Example: "title#TheMainTitle"
To address this widget specifically in the css file use the css class .TheMainTitle
example:

{

			"widgets": [

			"inhibitors",

			"title",

			"dnd",

			"notifications"
			]

}

widget-config
type: object
description: Configure specific widget properties.
multiple of same widget:
Append a # with any value to the end of the widget name.
Example: "title#TheMainTitle"
To address this widget specifically in the css file use the css class .TheMainTitle
Widgets to customize:
notifications
type: object
css class: widget-notifications
properties:
vexpand:
type: bool
optional: true
default: true
description: Whether or not the notifications widget
should vertically expand or not
description: The Notifications Widget.
title
type: object
css class: widget-title
properties:
text:
type: string
optional: true
default: "Notifications"
description: The title of the widget
clear-all-button:
type: bool
optional: true
default: true
description: Whether to display a "Clear All" button
button-text:
type: string
optional: true
default: "Clear All"
description: "Clear All" button text
description: The notification visibility state.
dnd
type: object
css class: widget-dnd
properties:
text:
type: string
optional: true
default: "Do Not Disturb"
description: The title of the widget
description: Control Center Do Not Disturb Widget.
label
type: object
css class: widget-label
properties:
text:
type: string
optional: true
default: "Label Text"
description: The text content of the widget
clear-all-button:
type: integer
optional: true
default: 5
description: The maximum lines
description: A generic widget that allows the user to add custom text.
mpris
type: object
css classes:
widget-mpris
widget-mpris-player
widget-mpris-title
widget-mpris-subtitle
properties:
blacklist:
type: array
optional: true
default: []
description: Audio sources for the mpris widget to ignore.
Valid array values:
type: string
description: Audio source/app name. Regex allowed. Hint
‘$ qdbus | grep mpris‘ to find source names.
autohide:
type: bool
optional: true
default: false
description: Whether to hide the widget when the
player has no metadata.
show-album-art:
type: string
optional: true
default: "always"
description: Whether or not the album art should be
hidden, always visible, or only visible
when a valid album art is provided.
enum: ["right", "left"]
loop-carousel:
type: bool
optional: true
default: false
description: Whether to loop through the mpris carousel.
description: A widget that displays multiple music players.
menubar
type: object
css classes:
widget-menubar
name of element given after menu or buttons with #
patternProperties:
menu#<name>:
type: object
properties:
label:
type: string
optional: true
default: "Menu"
description: Label of button to show/hide menu dropdown
position:
type: string
optional: true
default: "right"
description: Horizontal position of the button in the bar
enum: ["right", "left"]
animation-type:
type: string
optional: true
default: "slide_down"
description: Animation type for menu
enum: ["slide_down", "slide_up", "none"]
animation-duration:
type: integer
optional: true
default: 250
description: Duration of animation in milliseconds
actions:
type: array
Default values: []
Valid array values:
type: object
properties:
label:
type: string
default: "label"
description: Text to be displayed in button
command:
type: string
default: ""
description: "Command to be executed on click"
type:
type: string
default: "normal"
description: Type of the button.
Toggle buttons receive the ’.active’ css class
enum: ["normal", "toggle"]
update-command:
type: string
default: ""
description: "Command to be executed on visibility change of
cc to update the active state of the toggle button (should
echo true or false)"
active:
type: bool
default: false
description: Wether the toggle button is active as default or not
description: A list of actions containing a label and a command
description: A button to reveal a dropdown with action-buttons
buttons#<name>:
type: object
properties:
position:
type: string
optional: true
default: "right"
description: Horizontal position of the buttons in the bar
enum: ["right", "left"]
actions:
type: array
Default values: []
Valid array values:
type: object
properties:
label:
type: string
default: "label"
description: Text to be displayed in button
command:
type: string
default: ""
description: "Command to be executed on click"
type:
type: string
default: "normal"
description: Type of the button
Toggle buttons receive the ’.active’ css class and an env
variable "SWAYNC_TOGGLE_STATE" is set. See example usage in the
default config.json
enum: ["normal", "toggle"]
update-command:
type: string
default: ""
description: "Command to be executed on visibility change of
cc to update the active state of the toggle button (should
echo true or false)"
active:
type: bool
default: false
description: Wether the toggle button is active as default or not
description: A list of actions containing a label and a command
description: A list of buttons to be displayed in the menu-button-bar
buttons-grid
type: object
css class: widget-buttons (access buttons with >flowbox>flowboxchild>button)
properties:
buttons-per-row:
type: number
actions:
type: array
Default values: []
Valid array values:
type: object
properties:
label:
type: string
default: "label"
description: Text to be displayed in button
command:
type: string
default: ""
description: "Command to be executed on click"
type:
type: string
default: "normal"
description: Type of the button
Toggle buttons receive the ’.active’ css class and an env
variable "SWAYNC_TOGGLE_STATE" is set. See example usage in the
default config.json
enum: ["normal", "toggle"]
active:
type: bool
default: false
description: Wether the toggle button is active as default or not
description: A list of actions containing a label and a command
description: A grid of buttons that execute shell commands
slider
type: object
css class: widget-slider
properties:
label:
type: string
optional: true
default: "slider"
description: Text displayed in front of the slider
cmd_setter:
type: string
optional: true
default: ""
description: command to set the value. Use $value to get
the current value.
cmd_getter:
type: string
optional: true
default: ""
description: command to get the actual value.
Use $value to get the current value.
min:
type: integer
optional: true
default: 0
description: minimum value of the slider range
max:
type: integer
optional: true
default: 100
description: maximum value of the slider range
min_limit:
type: integer
optional: true
default: 0
description: limit minimum value of the slider
max_limit:
type: integer
optional: true
default: 100
description: limit maximum value of the slider
value_scale:
type: integer
optional: true
default: 0
description: scale small value, slider round digits
description: general slider control
volume
type: object
css class:
widget-volume
per-app-volume
properties:
label:
type: string
optional: true
default: "Volume"
description: Text displayed in front of the volume slider
show-per-app:
type: bool
optional: true
default: false
description: Show per app volume control
show-per-app-icon:
type: bool
optional: true
default: false
description: Show application icon in per app control
show-per-app-label:
type: bool
optional: true
default: false
description: Show application name in per app control
expand-per-app:
type: bool
optional: true
default: false
description: If the per app section should start expanded
empty-list-label:
type: string
optional: true
default: "No active sink input"
description: Text displayed when there are not active sink inputs
expand-button-label:
type: string
optional: true
default: "â§"
description: Label displayed on button to show per app volume control
collapse-button-label:
type: string
optional: true
default: "â©"
description: Label displayed on button to hide per app volume control
animation-type:
type: string
optional: true
default: "slide_down"
description: Animation type for the per app volume control
enum: ["slide_down", "slide_up", "none"]
animation-duration:
type: integer
optional: true
default: 250
description: Duration of animation in milliseconds
description: Slider to control pulse volume
backlight
type: object
css class: widget-backlight
properties:
label:
type: string
optional: true
default: "Brightness"
description: Text displayed in front of the backlight slider
device:
type: string
optional: true
default: "intel_backlight"
description: Device in ‘/sys/class/backlight‘ or ‘/sys/class/leds‘
subsystem:
type: string
optional: true
default: "backlight"
description: Kernel subsystem for brightness control
enum: ["backlight", "leds"]
min:
type: integer
optional: true
default: 0
description: Lowest possible value for brightness
description: Slider to control screen brightness
inhibitors
type: object
css class: widget-inhibitors
properties:
text:
type: string
optional: true
default: "Inhibitors"
description: The title of the widget
clear-all-button:
type: bool
optional: true
default: true
description: Whether to display a "Clear All" button
button-text:
type: string
optional: true
default: "Clear All"
description: "Clear All" button text
description: Displayed if notifications are inhibited.

example:
{

"widget-config": {
	"title": {
		"text": "Notifications",
		"clear-all-button": true,
		"button-text": "Clear All"
	},
	"dnd": {
		"text": "Do Not Disturb"
	},
	"label": {
		"max-lines": 5,
		"text": "Label Text"
	},
	"mpris": {
		"blacklist": ["playerctld"],
		"autohide": true,
		"show-album-art": "always",
		"loop-carousel": false
	},
	"menubar": {
		"menu#power": {
			"label": "Power",
			"position": "right",
			"actions": [
				{

				"label": "Shut down",

				"command": "systemctl poweroff"
				},
				...
			]
		},
		"buttons#screenshot": {
			"position": "left",
			"actions": [
				{

				"label": "Screenshot",

				"command": "grim"
				},
				...
			]
		}
	},
	"buttons": {
		"actions": [
			{
				"label": "wifi",
				"command": "rofi-wifi-menu"
			},
			...
		]
	}
}

}

Scripts

script-fail-notify
type: bool
default: true
description: Sends a notification if a script fails to run

scripts
type: object
script object properties:
exec
type: string
optional: false
description: The script to run. Can also run regular shell commands.
app-name
type: string
optional: true
description: The app-name. Uses Regex.
desktop-entry
type: string
optional: true
description: The desktop-entry. Uses Regex.
summary
type: string
optional: true
description: The summary of the notification. Uses Regex.
body
type: string
optional: true
description: The body of the notification. Uses Regex.
urgency
type: string
optional: true
default: Normal
values: Low, Normal, Critical
description: The urgency of the notification.
category
type: string
optional: true
description: Which category the notification belongs to. Uses Regex.
sound-file
type: string
optional: true
description: Which sound file the notification requested. Uses Regex.
sound-name
type: string
optional: true
description: Which sound name the notification requested. Uses Regex.
run-on
type: string
optional: true
values: action, receive
default: receive
description: Whether to run this action when the notification is
received, or when an action is taken on it.
description: Which scripts to check and potentially run for every
notification. If the notification doesn’t include one of the properties,
that property will be ignored. All properties (except for exec) use regex.
If all properties match the given notification, the script will be run.
Only the first matching script will be run.
example:

{

			"scripts": {
				"example-script": {

				"exec": "Your shell command or script here...",

				"app-name": "Notification app-name Regex",

				"summary": "Notification summary Regex",

				"body": "Notification body Regex",

				"urgency": "Low or Normal or Critical",

				"category": "Notification category Regex"
				}
			}

}

You can also use these environment variables in your script:
$SWAYNC_BODY="Notification body content"
$SWAYNC_DESKTOP_ENTRY="Desktop entry"
$SWAYNC_URGENCY="Notification urgency"
$SWAYNC_TIME="Notification time"
$SWAYNC_APP_NAME="Notification app name"
$SWAYNC_CATEGORY="SwayNC notification category"
$SWAYNC_REPLACES_ID="ID of notification to replace"
$SWAYNC_ID="SwayNC notification ID"
$SWAYNC_SUMMARY="Notification summary"
$SWAYNC_HINT_[NAME]="Value of the hint [NAME]"
$SWAYNC_SOUND_NAME="The name of the requested sound"
$SWAYNC_SOUND_FILE="The file path of the requested sound"

Updated 2026-06-01 - jenkler.se | uex.se