---
name: "swaync"
section: "5"
platform: "linux"
package: "swaync"
version: "0.12.6-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/swaync/5"
---

# swaync(5)

Configuration file

## NAME

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"
```