swaync(5) File Formats Manual swaync(5)

# [NAME](#NAME)

swaync - Configuration file

# [CONFIGURATION](#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](#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"
```

2026-10-19

---

Document: swaync(5) from swaync 0.12.6-r0 (Chainguard OS)