Types

Named types referenced across the config. Every field in /config/ that shows a type like Color or ClickAction links here.

ActiveIndicator

Visual indicator style for the active workspace.

Value	Meaning
"background"	Entire button gets a colored background.
"underline"	Small colored bar under the workspace button.

AnimationType

Enter/exit transition style for transient surfaces (OSD, toasts, notifications). Driven per frame by the custom revealer (GskTransform + opacity).

Value	Meaning
"none"	No transition; surfaces appear and disappear instantly.
"fade"	Cross-fade opacity in and out.
"slide-up"	Slide in from / out to the top edge.
"slide-down"	Slide in from / out to the bottom edge.
"slide-left"	Slide in from / out to the left edge.
"slide-right"	Slide in from / out to the right edge.
"swing-up"	Slide in from / out to the top edge with a rotating swing.
"swing-down"	Slide in from / out to the bottom edge with a rotating swing.
"swing-left"	Slide in from / out to the left edge with a rotating swing.
"swing-right"	Slide in from / out to the right edge with a rotating swing.
"bounce"	Scale in from a shrunken state with an elastic overshoot, then settle.
"genie"	Suck in toward / out to the surface's anchored edge (macOS "genie"
minimize, approximated with an affine scale-and-slide). Auto-orients to
the edge the surface sits on.
"zoom"	Scale in smoothly from the center with no overshoot.
"rotate"	Spin in: rotate into place while scaling up and fading in.
"flip"	Card flip: open out from a vertical edge (horizontal scale through zero).

AnimationType2

Enter/exit transition style for transient surfaces (OSD, toasts, notifications). Driven per frame by the custom revealer (GskTransform + opacity).

Value	Meaning
"none"	No transition; surfaces appear and disappear instantly.
"fade"	Cross-fade opacity in and out.
"slide-up"	Slide in from / out to the top edge.
"slide-down"	Slide in from / out to the bottom edge.
"slide-left"	Slide in from / out to the left edge.
"slide-right"	Slide in from / out to the right edge.
"swing-up"	Slide in from / out to the top edge with a rotating swing.
"swing-down"	Slide in from / out to the bottom edge with a rotating swing.
"swing-left"	Slide in from / out to the left edge with a rotating swing.
"swing-right"	Slide in from / out to the right edge with a rotating swing.
"bounce"	Scale in from a shrunken state with an elastic overshoot, then settle.
"genie"	Suck in toward / out to the surface's anchored edge (macOS "genie"
minimize, approximated with an affine scale-and-slide). Auto-orients to
the edge the surface sits on.
"zoom"	Scale in smoothly from the center with no overshoot.
"rotate"	Spin in: rotate into place while scaling up and fading in.
"flip"	Card flip: open out from a vertical edge (horizontal scale through zero).

AppIconSource

Icon source for app volume entries in the dropdown.

Value	Meaning
"mapped"	lys-shell's curated symbolic icons matched by app name.
"native"	Native application icons reported by PulseAudio.

Appearance

Light/dark appearance mode.

Auto keeps each provider's own light setting and the configured static palette as-is. Light/Dark force the mode: dynamic providers switch their light flag, and the static palette swaps to its built-in light/dark variant when one exists.

Value	Meaning
"auto"	Follow each provider's own setting / the configured palette.
"light"	Force the light variant.
"dark"	Force the dark variant.

BarButtonVariant

Visual style variants for bar buttons.

Value	Meaning
"basic"	Icon + label, minimal background.
"block-prefix"	Icon in colored pill container that blends into button edge.
"icon-square"	Button background with colored icon container inside.

BarCount

Frequency bar count clamped to 1-256.

Number in [1, 256].

Serialises as uint16.

BarGroup

Named group of modules. The name becomes a CSS ID selector.

Field	Description
name	Unique name for CSS targeting (becomes #name selector).
modules	Modules contained in this group.

BarItem

One entry in a bar layout section (left, center, or right).

Three shapes are accepted, all interchangeable in the same list:

• A plain module name: clock
• A module with a CSS class for per-instance styling: {module: clock, class: primary}
• A named group that wraps several modules in a shared container, addressable by CSS ID

Examples

bar:
  layout:
    - monitor: "*"

      # Plain module
      left: [dashboard]

      # Mix of plain and classed modules on the same side
      center:
        - clock
        - {module: clock, class: secondary}

      # Named group (renders inside a GTK container with CSS ID `#status`)
      right:
        - {name: status, modules: [battery, network, volume]}

    # Groups can hold classed modules too
    - monitor: DP-2
      left:
        - name: clocks
          modules:
            - {module: clock, class: local}
            - {module: world-clock, class: remote}

BarLayout

Layout configuration for a bar on a specific monitor.

Examples

# Single modules
bar:
  layout:
    - monitor: "*"
      left: [dashboard]
      center: [clock]
      right: [systray]

    # Module with custom CSS class for per-instance styling
    - monitor: DP-1
      left:
        - {module: clock, class: primary-clock}
        - clock
      center: [media]

    # Grouped modules (share a visual container, CSS-targetable by name)
    - monitor: DP-2
      left:
        - {name: status, modules: [battery, network]}

    # Groups can also contain classed modules
    - monitor: DP-3
      left:
        - name: clocks
          modules:
            - {module: clock, class: local}
            - {module: world-clock, class: remote}

    # Inherit from another layout
    - monitor: "*"
      left: [dashboard]
      center: [clock]
      right: [systray]
    - monitor: HDMI-1
      extends: "*"
      right: [volume, systray]  # Override just this section

    # Hide bar on a specific monitor
    - monitor: HDMI-2
      show: false

Field	Description
monitor	Monitor connector name (e.g., "DP-1") or "*" for all monitors.
extends	Inherit from another layout by its monitor value (e.g., "*").
show	Whether the bar is visible on this monitor.
left	Modules in the left section.
center	Modules in the center section.
right	Modules in the right section.

BarModule

Bar module name. Built-in modules or custom modules with a custom-<id> pattern.

One of: "battery", "bitwarden", "bluetooth", "brightness", "cava", "clock", "cpu", "dashboard", "hyprland-workspaces", "idle-inhibit", "keybind-mode", "keyboard-input", "lys-wm-workspaces", "mail", "media", "mango-workspaces", "microphone", "netstat", "network", "nightlight", "niri-workspaces", "notifications", "power", "power-profiles", "ram", "recorder", "screenshot", "separator", "storage", "sway-workspaces", "systray", "treeman", "updates", "volume", "weather", "window-title", "workspaces", "world-clock".

String matching ^custom-[a-z0-9-]+$.

BitwardenPassphrasePreset

A passphrase of words from the EFF large wordlist the Bitwarden dropdown's generator makes and copies.

Example

modules: {bitwarden: {generator-passphrases: [{name: Spoken, words: 5, separator: " ", capitalize: false, number: false}]}}

Field	Description
name	Name the generator lists the preset by.
words	Number of words, 3-20.
separator	Text between the words.
capitalize	Capitalise the first letter of every word.
number	Append a digit to one of the words.

BitwardenPasswordPreset

A random-character password the Bitwarden dropdown's generator makes and copies.

Example

modules: {bitwarden: {generator-passwords: [{name: PIN-safe, length: 12, charsets: [uppercase, digits], avoid-ambiguous: true}]}}

Field	Description
name	Name the generator lists the preset by.
length	Length in characters, 5-128.
charsets	Character classes to draw from; each appears at least once.
avoid-ambiguous	Leave out the easily confused characters l, I, O, 0 and 1.

BitwardenServer

String.

BorderLocation

Border placement for bar buttons.

Value	Meaning
"none"	No border.
"top"	Border on top edge only.
"bottom"	Border on bottom edge only.
"left"	Border on left edge only.
"right"	Border on right edge only.
"all"	Border on all edges.

CavaDirection

Bar growth direction relative to the bar's attached screen edge.

Value	Meaning
"normal"	Bars grow away from the attached edge.
"reverse"	Bars grow toward the attached edge.
"mirror"	Bars grow symmetrically from center.

CavaInput

Audio capture backend.

Value	Meaning
"pipe-wire"	PipeWire multimedia server.
"pulse"	PulseAudio sound server.
"alsa"	Advanced Linux Sound Architecture.
"jack"	JACK Audio Connection Kit.
"fifo"	Named pipe (FIFO) input.
"port-audio"	PortAudio cross-platform library.
"sndio"	sndio audio subsystem (BSD).
"oss"	Open Sound System (legacy).
"shmem"	Shared memory input.
"winscap"	Windows audio capture (WASAPI).

CavaStyle

Visualization rendering style.

Value	Meaning
"bars"	Rectangular frequency bars.
"wave"	Smooth curve connecting bar peaks.
"peaks"	Bars with floating peak indicators that decay over time.

ClassedModule

A module with an associated CSS class for custom styling.

Field	Description
module	The module type.
class	CSS class added to the module's GTK widget.

ClickAction

String.

ClipboardHistoryMiB

Clipboard history budget in MiB.

Number in [8, 1024].

Serialises as uint32.

ColorValue

CSS token, hex color (#rgb, #rgba, #rrggbb, or #rrggbbaa), 'transparent', or 'auto'

Value	Meaning
"bg-base"	--bg-base - Application background.
"bg-surface"	--bg-surface - Elevated surfaces.
"bg-surface-elevated"	--bg-surface-elevated - Subtle elevation from surface (buttons on surface).
"bg-elevated"	--bg-elevated - Higher elevation surfaces.
"bg-overlay"	--bg-overlay - Popovers, dialogs.
"bg-hover"	--bg-hover - Hover state background.
"bg-active"	--bg-active - Active/pressed state background.
"bg-selected"	--bg-selected - Selected item background.
"fg-default"	--fg-default - Primary text color.
"fg-muted"	--fg-muted - Secondary text color.
"fg-subtle"	--fg-subtle - Tertiary/hint text color.
"fg-on-accent"	--fg-on-accent - Text color on accent backgrounds.
"accent"	--accent - Primary accent color.
"accent-subtle"	--accent-subtle - Subtle accent background.
"accent-hover"	--accent-hover - Accent hover state.
"status-error"	--status-error - Error state color.
"status-warning"	--status-warning - Warning state color.
"status-success"	--status-success - Success state color.
"status-info"	--status-info - Info state color.
"status-error-subtle"	--status-error-subtle - Subtle error background.
"status-warning-subtle"	--status-warning-subtle - Subtle warning background.
"status-success-subtle"	--status-success-subtle - Subtle success background.
"status-info-subtle"	--status-info-subtle - Subtle info background.
"status-error-hover"	--status-error-hover - Error hover state.
"red"	--red - Red color for stylistic/decorative use.
"yellow"	--yellow - Yellow color for stylistic/decorative use.
"green"	--green - Green color for stylistic/decorative use.
"blue"	--blue - Blue color for stylistic/decorative use.
"border-subtle"	--border-subtle - Subtle border color.
"border-default"	--border-default - Default border color.
"border-strong"	--border-strong - Strong border color.
"border-accent"	--border-accent - Accent-colored border.
"border-error"	--border-error - Error state border.

One of: "transparent", "auto".

String matching ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$.

CyclingInterval

Cycling interval in minutes, minimum 1.

Number >= 1.

Serialises as uint64.

CyclingMode

Wallpaper cycling order.

Value	Meaning
"sequential"	Alphabetical order.
"shuffle"	Random order.

DisplayMode

What identifies a workspace in the UI.

Value	Meaning
"label"	Show workspace number or name.
"icon"	Show icon from workspace-map (falls back to label if unmapped).
"none"	Show nothing - only app icons visible.

DropdownSize

Size override for a dropdown foldout panel.

Each field is optional: when unset the dropdown keeps its built-in default width (scaled by the global scale) and the height of its content. The width is a [Size]: a scale multiplier of the built-in base (e.g. 1.5) or an absolute pixel length (e.g. "480px"). The height is a pixel length only.

Field	Description
width	Panel width override. Unset uses the built-in default width.
height	Panel height cap in pixels (e.g. "400px"): the height a panel grows

DynamicLauncherConfig

Launcher installation policy.

Field	Description
install-token-apps	App ids granted an install token, with which they install

ExecutionMode

Execution mode for custom module commands.

Value	Meaning
"poll"	Run command at regular intervals defined by interval-ms.

Best for commands that complete quickly and return current state (e.g., reading a file, querying system status). | | "watch" | Spawn long-running process and update display on each stdout line.

Best for event-driven updates without polling overhead (e.g., pactl subscribe, inotifywait, tail -f). Configure restart-policy to control restarts after exit. |

FitMode

Image scaling mode.

Value	Meaning
"fill"	Scale to cover entire display, cropping excess.
"fit"	Scale to fit within display, letterboxing if needed.
"center"	Display at original size, centered.
"stretch"	Stretch to exactly fill, ignoring aspect ratio.

FitMode2

Image scaling mode.

Value	Meaning
"fill"	Scale to cover entire display, cropping excess.
"fit"	Scale to fit within display, letterboxing if needed.
"center"	Display at original size, centered.
"stretch"	Stretch to exactly fill, ignoring aspect ratio.

FontWeightClass

Font weight class for typography.

Maps to CSS classes like .weight-normal, .weight-bold, etc. Uses the existing --weight-* tokens defined in the stylesheet.

Value	Meaning
"normal"	Normal weight (--weight-normal: 400).
"medium"	Medium weight (--weight-medium: 500).
"semibold"	Semi-bold weight (--weight-semibold: 600).
"bold"	Bold weight (--weight-bold: 700).

Framerate

Visualization framerate clamped to 1-360 fps.

Number in [1, 360].

Serialises as uint32.

FrequencyHz

Frequency value in Hz, minimum 1 Hz.

Cross-field constraints (high_cutoff > low_cutoff, samplerate/2 > high_cutoff) are validated at the service builder.

Number >= 1.

Serialises as uint32.

HexColor

GTK4 CSS hex color (#rgb, #rgba, #rrggbb, or #rrggbbaa)

String matching ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$.

IconPosition

Icon position within bar buttons.

Value	Meaning
"start"	Icon before label (left for horizontal, top for vertical bars).
"end"	Icon after label (right for horizontal, bottom for vertical bars).

IconSource

Source for resolving notification icons.

Value	Meaning
"automatic"	Use per-notification images when provided, otherwise lys-shell's mapped icon.
"mapped"	Always use lys-shell's mapped icons regardless of what the app provides.
"application"	Use the full application icon chain, falling back to mapped if unavailable.

IdleInhibitDuration

Idle inhibit duration in whole minutes, 0 for indefinite.

Number in [0, 71582788].

Serialises as uint32.

LabelStrategy

What identifies each workspace's label.

Value	Meaning
"index"	Always show the index (e.g. 1, 2, 3).
"name-or-index"	Show the name when set, fall back to the index.
"name-only"	Show only the name; unnamed workspaces show nothing.
"index-and-name"	Show both, joined as "1: web". Unnamed workspaces show the index alone.

LauncherCase

Case handling (collapses rofi -case-sensitive/-case-smart).

Value	Meaning
"insensitive"	Always case-insensitive.
"smart"	Sensitive only when the query contains an uppercase char.
"sensitive"	Always case-sensitive.

LauncherCombiConfig

combi mode settings.

Field	Description
modes	Modes merged into the combined list.
display-format	Row template ({mode}, {text}).

LauncherDrunConfig

drun (application) mode settings.

Field	Description
categories	Only show apps within these categories (empty = all).
exclude-categories	Hide apps within these categories.
match-fields	Desktop-entry fields fed to the matcher.
display-format	Row template: {name}, {generic}, {exec}, {categories},
show-actions	Expose desktop-file actions as extra rows.
url-launcher	Command opening Type=Link entries.

LauncherDrunField

Desktop-entry fields searched by drun (rofi -drun-match-fields).

Value	Meaning
"name"	Localized Name.
"generic"	GenericName.
"exec"	Exec command line.
"categories"	Categories list.
"comment"	Comment.
"keywords"	Keywords list.

LauncherFileSort

File sorting in the file browser (rofi filebrowser sorting-method).

Value	Meaning
"name"	By file name.
"mtime"	By modification time.
"atime"	By access time.
"ctime"	By creation time.

LauncherFilebrowserConfig

file browser mode settings.

Field	Description
directory	Start directory ("" = home).
sorting-method	File ordering.
directories-first	List directories before files.
show-hidden	Show hidden files.
command	Command opening the picked file ("" = xdg-open).

LauncherHistoryConfig

Launch history / frecency settings.

Field	Description
enable	Record launches and rank frequently used entries first.
max-size	Maximum remembered entries per mode.

LauncherLocation

Launcher surface position (rofi -location 0-8 grid).

Value	Meaning
"center"	Centered (rofi location 0).
"north-west"	Top-left (1).
"north"	Top edge (2).
"north-east"	Top-right (3).
"east"	Right edge (4).
"south-east"	Bottom-right (5).
"south"	Bottom edge (6).
"south-west"	Bottom-left (7).
"west"	Left edge (8).

LauncherMatching

Matching method (rofi -matching).

Value	Meaning
"normal"	Tokenized substring matching.
"regex"	Regular expression.
"glob"	Glob patterns per token.
"fuzzy"	fzf-style fuzzy matching.
"prefix"	Tokenized prefix matching.

LauncherQuicklink

A link in the search panel.

Field	Description
name	Name shown and searched.
url	URL to open, with {query} where a query goes if it takes one.
keyword	Word that leads a query for this link: gh makes gh rust search it.
icon	Icon name or file (empty is a link icon).

LauncherRunConfig

run (command) mode settings.

Field	Description
run-command	Plain accept template ({cmd}).
shell-command	Run-in-terminal template ({terminal}, {cmd}).
list-command	Extra command whose stdout lines add entries.

LauncherSearchConfig

The search panel: one ranked list over apps, windows, files and more.

Field	Description
providers	What the list searches, and what it leaves out by omission.
web-engine	Web search fallback: the engine's name, shown on the row.
web-url	Web search fallback: the URL, with {query} where the search goes.
file-roots	Directories the file index walks (~ allowed). Empty indexes the home
file-exclude	Directory names the file index skips, on top of hidden ones and the
commands-dir	Directory of script commands. Empty uses launcher/commands in the
previews	Show the side pane for files, snippets and clipboard entries.
quicklinks	Links to open by name or keyword.
snippets	Text to copy by name or keyword.

LauncherSearchProvider

A source of rows in the search panel.

Value	Meaning
"apps"	Desktop entries, with their actions.
"windows"	Open windows to jump to.
"files"	Recent files and the file index.
"calculator"	Inline arithmetic and unit conversion.
"system"	Lock, suspend, log out, reboot, shut down.
"settings"	Pages of lys-settings.
"clipboard"	The clipboard history.
"emoji"	The emoji table.
"vault"	The Bitwarden vault.
"links"	Quick links and snippets.
"scripts"	Script commands from the commands directory.
"shell"	>command runs a shell command.
"web"	The web search fallback.

LauncherSnippet

A piece of text in the search panel.

Field	Description
name	Name shown and searched.
text	The text Enter copies.
keyword	Extra word it is found by.

LauncherSorting

Result sorting method (rofi -sorting-method).

Value	Meaning
"levenshtein"	Levenshtein distance to the query (rofi "normal").
"fzf"	fzf match-quality score.

LauncherSshConfig

ssh mode settings.

Field	Description
client	SSH client binary.
command	Connect template ({terminal}, {ssh-client}, {host}).
parse-hosts	Include hosts from /etc/hosts.
parse-known-hosts	Include hosts from ~/.ssh/known_hosts.

LauncherWindowConfig

window switcher mode settings.

Field	Description
format	Row template: {w} workspace, {c} class, {t} title, {n} name,
match-fields	Window fields fed to the matcher.
hide-active	Hide the currently focused window from the list.
close-on-delete	Shift-delete closes the selected window.

LauncherWindowField

Window fields searched by window mode (rofi -window-match-fields).

Value	Meaning
"title"	Window title.
"class"	Application class/app-id.
"name"	Window name.
"role"	Window role.
"desktop"	Workspace/desktop name.

Layer

Layer-shell layer a window is placed on, from furthest back to furthest front.

Value	Meaning
"background"	Below everything else, used for wallpapers and ambient surfaces.
"bottom"	Behind regular application windows.
"top"	Above regular application windows.
"overlay"	Above everything, including fullscreen application windows.

Location

Bar position on screen.

Value	Meaning
"top"	Top edge of the screen.
"bottom"	Bottom edge of the screen.
"left"	Left edge of the screen.
"right"	Right edge of the screen.

LockBackground

How the lock screen background is rendered.

Value	Meaning
"color"	Solid color fill (background-color).
"image"	A specific image file (background-image).
"wallpaper"	Reuse the current desktop wallpaper.

LockBlur

Lock background blur in pixels, 0 for none.

Number in [0, 1000].

Serialises as uint32.

LockdownConfig

Features no app may use while set.

Field	Description
disable-printing	Refuse printing.
disable-save-to-disk	Refuse saving files through the file chooser.
disable-application-handlers	Refuse opening URIs and files in other applications.
disable-location	Refuse location access.
disable-camera	Refuse camera access.
disable-microphone	Refuse microphone access.
disable-sound-output	Refuse sound output.

LoginGreeterConfig

Greeter mode: the login screen before login, as the display manager.

Field	Description
show-user-list	Show clickable avatars for the machine's login users.
show-power-buttons	Show the shutdown/reboot buttons at the bottom of the screen.
cursor-theme	Xcursor theme used on the login screen (empty = system default).
cursor-size	Logical cursor size on the login screen. Scaled automatically per

LoginLockConfig

Lock mode: the login screen locking the session via ext-session-lock-v1.

When enabled, the session locks in response to the logind Lock signal (loginctl lock-session), the lys-shell lock CLI, or the shell IPC lock() method. The lock surface grabs all input and survives client crashes (the compositor shows a solid color), unlike a layer-shell overlay.

Field	Description
enabled	Let lys-shell handle session locking. When off, lock requests are ignored
lock-on-start	Lock the session as soon as the shell starts. For autologin setups
grace-period-ms	Grace window after locking during which the screen unlocks without a
blank-timeout-ms	Black out the lock screen after this idle time (milliseconds, 0 =
pam-service	PAM service name used to authenticate the unlock. Distro-dependent:

MailAccount

One mail account in the modules.mail per-account breakdown.

Each account has its own notmuch query; the dropdown shows the per-account unread counts and the bar shows their sum.

Example

modules: {mail: {accounts: [{name: Work, query: "folder:work/INBOX and tag:unread", provider: gmail}]}}

Field	Description
name	Display name shown in the dropdown.
query	notmuch query whose match count is this account's unread total.
provider	Provider, selecting the default brand icon.
icon	Optional icon override. Empty uses the provider's default icon.

MailProvider

Mail provider, used to pick a default brand icon for an account.

Value	Meaning
"generic"	Generic mailbox; uses the plain mail glyph.
"gmail"	Gmail.
"outlook"	Microsoft Outlook.
"icloud"	Apple iCloud Mail.
"proton"	Proton Mail.
"fastmail"	Fastmail.
"yahoo"	Yahoo Mail.

MatugenScheme

Matugen color scheme type.

Value	Meaning
"content"	Adapts to image content.
"expressive"	Bold, dramatic palette.
"fidelity"	Stays close to source colors.
"fruit-salad"	Playful multi-color palette.
"monochrome"	Single-hue grayscale palette.
"neutral"	Muted, understated palette.
"rainbow"	Broad hue spread.
"tonal-spot"	Balanced Material You default.
"vibrant"	High-saturation palette.

MediaIconType

Icon display mode for the media module.

Value	Meaning
"default"	Static icon from icon-name field.
"application"	Dynamic icon from media player's desktop entry, falling back to icon-name.
"spinning-disc"	Spinning disc icon that animates during playback. Uses slightly more CPU.
"application-mapped"	Maps player to icon via glob patterns, with built-in mappings for common players.

ModuleRef

Reference to a module, optionally with a custom CSS class.

Examples

# Plain module (just the name)
left: [clock]

# Module with custom CSS class
left:
  - {module: clock, class: primary-clock}

MonitorWallpaperConfig

Per-monitor wallpaper configuration.

Field	Description
name	Monitor name (e.g., "HDMI-1", "DP-1").
fit-mode	Image scaling mode for this monitor.
wallpaper	Wallpaper image path for this monitor.

NightlightTransition

Night light transition length in whole minutes, 0 for an instant switch.

Number in [0, 120].

Serialises as uint32.

NormalizedF64

Floating-point value clamped to 0.0-1.0.

Number in [0.0, 1.0].

Serialises as double.

NotificationHistoryMemory

Notifications kept in memory.

Number in [10, 1000].

Serialises as uint32.

NotificationHistoryStored

Notifications kept on disk.

Number in [1000, 1000000].

Serialises as uint32.

Numbering

How workspace numbers are displayed.

Value	Meaning
"absolute"	Show actual Hyprland workspace IDs (1, 2, 3, 4, 5, 6...).
"relative"	Show numbers relative to monitor's starting workspace.

If monitor has workspaces 4, 5, 6 assigned, they display as 1, 2, 3. Useful when keybinds use per-monitor numbering (Shift+1 for ws 4, etc.). |

OsdMonitor

"primary" or a monitor connector name (e.g. "DP-1")

String.

OsdPosition

Screen anchor for the OSD overlay.

Value	Meaning
"top-left"	Top-left corner.
"top"	Top-center edge.
"top-right"	Top-right corner.
"right"	Right-center edge.
"bottom-right"	Bottom-right corner.
"bottom"	Bottom-center edge.
"bottom-left"	Bottom-left corner.
"left"	Left-center edge.

OsdTextAlign

Horizontal alignment of OSD toast/toggle content.

Value	Meaning
"start"	Align content to the start (left in LTR layouts).
"center"	Center content horizontally.
"end"	Align content to the end (right in LTR layouts).

PaletteConfig

Color palette configuration for the active theme.

Field	Description
bg	Base background color (darkest).
surface	Card and sidebar background.
elevated	Raised element background.
fg	Primary text color.
fg-muted	Secondary text color.
primary	Accent color for interactive elements.
red	Red semantic color.
yellow	Yellow semantic color.
green	Green semantic color.
blue	Blue semantic color.

PassphraseWords

A generated passphrase's number of words, 3-20.

Number in [3, 20].

Serialises as uint32.

PasswordCharset

A class of characters a generated password draws from.

Value	Meaning
"lowercase"	Lowercase letters, a-z.
"uppercase"	Uppercase letters, A-Z.
"digits"	Digits, 0-9.
"symbols"	The symbols !@#$%^&*.

PasswordCharsets

The character classes a generated password draws from, at least one of lowercase, uppercase, digits and symbols (!@#$%^&*). Every class listed appears in the password at least once.

See the schema for valid values.

PasswordLength

A generated password's length in characters, 5-128.

Number in [5, 128].

Serialises as uint32.

Percentage

Percentage value clamped to 0-100.

Number in [0, 100].

Serialises as uint8.

PixelLength

Absolute length in pixels (e.g. "400px").

String matching ^[0-9]+(\.[0-9]+)?px$.

PopupCloseBehavior

Behavior when the close button is clicked on a popup card.

Value	Meaning
"dismiss"	Hide the popup; notification stays in history.
"remove"	Remove the notification entirely.

PopupMonitor

"primary" or a monitor connector name (e.g. "DP-1")

String.

PopupPosition

Screen position for notification popups.

Value	Meaning
"top-left"	Top-left corner.
"top-center"	Top-center edge.
"top-right"	Top-right corner.
"bottom-left"	Bottom-left corner.
"bottom-center"	Bottom-center edge.
"bottom-right"	Bottom-right corner.
"center-left"	Center-left edge.
"center-right"	Center-right edge.

PopupStack

Value	Meaning
"per-app"	Popups from the same app share a stack.
"all"	Every popup shares one stack.
"off"	Every popup is a card of its own.

PywalContrast

Pywal contrast ratio clamped to 1.0-21.0 (WCAG range).

Number in [1.0, 21.0].

Serialises as double.

RecorderFormat

Container format / codec preset for recordings.

Value	Meaning
"mp4"	H.264 in an MP4 container.
"mkv"	H.264 in a Matroska container.

RestartDelay

Restart delay in milliseconds, clamped to >= 1.

Number >= 1.

Serialises as uint64.

RestartPolicy

Restart behavior for watch-mode custom modules.

Value	Meaning
"never"	Never restart after exit.
"on-exit"	Restart after any exit code (success or failure).
"on-failure"	Restart only after non-zero exit codes or signal termination.

RoundingLevel

Global rounding preference for UI components.

Value	Meaning
"default"	The toolkit's own rounding (lys-ui's corner radius).
"none"	Sharp corners (no rounding).
"sm"	Subtle rounding.
"md"	Moderate rounding.
"lg"	Pronounced rounding.
"full"	Pill shape (fully rounded ends).

ScaleFactor

Scale multiplier clamped to 0.25-3.0.

Number in [0.25, 3.0].

Serialises as float.

SessionAction

One action the dashboard session actions

Value	Meaning
"lock"	Lock the session
"log-out"	Logout of the current session
"reboot"	Reboot the machine
"power-off"	Power off the machine

ShadowPreset

Shadow style for the bar.

Value	Meaning
"none"	No shadow.
"drop"	Directional shadow opposite the anchor edge.
"floating"	All-around shadow.

SharePickerPage

Page shown when the screen-share picker opens.

Value	Meaning
"windows"	Per-window previews.
"outputs"	Per-output (monitor) previews.
"region"	Region selection on the shell's region overlay.

SignedNormalizedF64

Floating-point value clamped to -1.0 to 1.0.

Number in [-1.0, 1.0].

Serialises as double.

Size

Size as a scale multiplier (number) or absolute pixels (e.g. "24px")

Number >= 0.0.

String matching ^[0-9]+(\.[0-9]+)?px$.

StackingOrder

Order in which popups are stacked on screen.

Value	Meaning
"newest-first"	Newest notifications appear closest to the configured position.
"oldest-first"	Oldest notifications appear closest to the configured position.

StateColors

Per-state color overrides for a custom module.

Values are keyed in color-map by the JSON output's alt field, mirroring icon-map. Any field left unset falls back to the module's static color of the same name. Use the "default" key as a fallback state.

Field	Description
icon-color	Icon foreground color for this state.
icon-bg-color	Icon container background color for this state.
label-color	Label text color for this state.
button-bg-color	Button background color for this state.
border-color	Border color for this state.

StorageMountPoint

Storage mount targets accepted by mount-point.

Supports a single string for backwards compatibility or an array of paths.

String.

SurfaceAnimation

Per-surface enter/exit animation override. Any field left unset falls back to the global [animations] enter/exit, then to transition/duration.

Field	Description
enter	Enter transition for this surface. Unset → global enter, then transition.
exit	Exit transition for this surface. Unset → global exit, then transition.
enter-duration	Enter duration in ms. Unset → global enter-duration, then duration.
exit-duration	Exit duration in ms. Unset → global exit-duration, then duration.

TemperatureUnit

Temperature unit for display.

Value	Meaning
"metric"	Celsius (metric).
"imperial"	Fahrenheit (imperial).

ThemeProvider

Source of color palette values.

Dynamic providers (Matugen, Pywal, Wallust) inject palette tokens at runtime.

Value	Meaning
"lys-shell"	Static theming using lys-shell's built-in palettes.
"matugen"	Dynamic theming via Matugen.
"pywal"	Dynamic theming via Pywal.
"wallust"	Dynamic theming via Wallust.

ThresholdEntry

A threshold entry that maps a numeric value range to color overrides.

At least one of above or below must be set. When both are set, both conditions must be satisfied (AND logic).

YAML Example

# under modules.cpu
thresholds:
- {above: 70, icon-color: status-warning, label-color: status-warning}
- {above: 90, icon-color: status-error, label-color: status-error}

Field	Description
above	Activate when metric value >= this threshold.
below	Activate when metric value <= this threshold.
icon-color	Override icon color when threshold is active.
label-color	Override label color when threshold is active.
icon-bg-color	Override icon background color when threshold is active.
button-bg-color	Override button background color when threshold is active.
border-color	Override border color when threshold is active.

TimeFormat

Time display format.

Value	Meaning
"12h"	12-hour format with AM/PM (e.g., "6:30 AM").
"24h"	24-hour format (e.g., "06:30").

ToastPreset

A reusable toast preset, triggerable by id with lys-shell toast --preset <id>.

A preset captures a toast's text and icon so it can be fired by name. The label/icon can still be overridden per invocation, and runtime-only fields (--percentage, --duration, --class) are supplied at invoke time, not stored on the preset. Duration always follows the OSD config.

Example

osd: {presets: [{id: saved, label: Saved, icon: ld-check-symbolic}]}

# Fire it: lys-shell toast --preset saved
# With a progress bar: lys-shell toast --preset saved --percentage 80

Field	Description
id	Unique identifier. Trigger with lys-shell toast --preset <id>.
label	Toast text. An explicit label on the command line overrides this.
icon	Symbolic icon name shown beside the text.

TrayItemOverride

Custom icon and color override for tray items matching a pattern.

Field	Description
name	Glob pattern to match against item ID or title.
icon	Custom icon name (symbolic icon).
color	Custom icon color.

UrgencyBarThreshold

Minimum urgency level that shows a colored urgency bar on popup cards.

All urgency levels at or above the threshold display the bar. For example, Normal shows bars on both normal and critical popups.

Value	Meaning
"low"	Show urgency bars on all popups.
"normal"	Show urgency bars on normal and critical popups.
"critical"	Show urgency bars on critical popups only.
"none"	Never show urgency bars.

UrgentMode

Where the urgent pulse animation is applied.

Value	Meaning
"workspace"	Pulse the entire workspace.
"application"	Pulse only the app icon(s) belonging to the urgent window.

Falls back to workspace when app icons are disabled. |

UserSessionConfig

Settings for user session the in dashboard

Examples

modules: {dashboard: {user-session: {actions: [lock, log-out, reboot, power-off]}}}

Field	Description
actions	Session actions to show on dashboard

VpnShow

Whether the VPN indicator is part of the network module.

Value	Meaning
"auto"	Show the VPN state only once NetworkManager holds a VPN profile.
"always"	Always overlay the VPN state on the network icon.
"never"	Never show it; the dropdown still lists VPNs.

WallustBackend

Wallust image sampling backend.

Value	Meaning
"full"	Reads every pixel.
"resized"	Resizes image before sampling.
"wal"	Uses ImageMagick convert (pywal method).
"thumb"	Fixed 512x512 thumbnail.
"fastresize"	SIMD-accelerated resize.
"kmeans"	K-means clustering.

WallustColorspace

Wallust color space for dominant color selection.

Value	Meaning
"lab"	CIELAB perceptual color space.
"labmixed"	LAB with mixing for sparse images.
"lch"	Cylindrical LAB (hue/chroma/lightness).
"lchmixed"	LCH with mixing.
"lchansi"	LCH mapped to ANSI color ordering.

WallustPalette

Wallust palette mode.

Value	Meaning
"dark16"	8 dark colors with 16-color trick.
"dark"	8 dark colors, dark background and light contrast.
"darkcomp"	Dark with complementary counterparts.
"darkcomp16"	Dark complementary with 16-color trick.
"harddark"	Dark with hard hue colors.
"harddark16"	Hard dark with 16-color trick.
"harddarkcomp"	Hard dark complementary variant.
"harddarkcomp16"	Hard dark complementary with 16-color trick.
"light"	Light background, dark foreground.
"light16"	Light with 16-color trick.
"lightcomp"	Light with complementary colors.
"lightcomp16"	Light complementary with 16-color trick.
"softdark"	Lightest colors with dark background.
"softdark16"	Soft dark with 16-color trick.
"softdarkcomp"	Soft dark complementary variant.
"softdarkcomp16"	Soft dark complementary with 16-color trick.
"softlight"	Light with soft pastel colors.
"softlight16"	Soft light with 16-color trick.
"softlightcomp"	Soft light with complementary colors.
"softlightcomp16"	Soft light complementary with 16-color trick.
"ansidark"	ANSI-ordered dark palette for LS_COLORS.
"ansidark16"	ANSI dark with 16-color trick.

WeatherProvider

Weather data provider selection.

Value	Meaning
"open-meteo"	Open-Meteo (no API key required).
"visual-crossing"	Visual Crossing (requires API key).
"weather-api"	WeatherAPI.com (requires API key).

WeekStart

Which day appears in the first column of the calendar dropdown.

Value	Meaning
"monday"	Week starts on Monday.
"tuesday"	Week starts on Tuesday.
"wednesday"	Week starts on Wednesday.
"thursday"	Week starts on Thursday.
"friday"	Week starts on Friday.
"saturday"	Week starts on Saturday.
"sunday"	Week starts on Sunday (default).

WorkspaceClickAction

Click/scroll action: focus:this | focus:next | focus:previous | focus:last | dropdown:NAME | shell command | empty for none

String.

WorkspaceMap

Per-workspace icon and color overrides, keyed by workspace ID.

Keys are written as strings, so "1" parses into the workspace with ID 1. Negative IDs refer to Hyprland's special workspaces. Keys that don't appear in the map fall back to the default behaviour set by [HyprlandWorkspacesConfig::display_mode].

Examples

# under modules.hyprland-workspaces.workspace-map
"1": {label: Web, icon: ld-globe-symbolic, color: "#4a90d9"}
"2": {icon: ld-terminal-symbolic}
"3": {icon: ld-code-symbolic, color: accent}
"4": {label: Chat, icon: ld-message-square-symbolic, color: status-success}

# Negative IDs target Hyprland special workspaces
"-99": {icon: ld-scratch-symbolic}

WorkspaceStyle

Per-workspace styling override.

Field	Description
icon	Custom icon for this workspace. When set, the icon is shown regardless
color	Custom background color for this workspace when active.
label	Text shown instead of the workspace's name or index.