example.toml

# Noctalia configuration — all settings at their defaults.
# Copy to ~/.config/noctalia/config.toml and edit what you need.
# Most changes are hot-reloaded via inotify; startup-only settings are noted inline.

# ── Shell ─────────────────────────────────────────────────────────────────────

[accessibility]
ui_scale              = 1.0
high_contrast         = false

[shell]
corner_radius_scale   = 1.0          # 0 = square, 1 = default, 2 = extra rounded
font_family           = "sans-serif"
time_format           = "{:%H:%M}"  # default shell UI time format
date_format           = "%A, %x"    # default shell UI date format
offline_mode          = false        # block all outgoing HTTP when true
# panel_anchor_bar   = "main"        # bar panels attach to without a source bar; omit = first enabled bar
telemetry_enabled     = false        # send an anonymous startup ping
niri_overview_type_to_launch_enabled = false # opt in to type-to-launch from niri overview
polkit_agent          = false
password_style        = "default"    # default | random
settings_show_advanced = true        # show advanced settings by default in Settings
# settings_window_translucent = false  # translucent settings window background
show_location         = true         # hide weather location text in shell UI when false
# app_icon_colorize   = false        # recolor application icons across the shell
# app_icon_color      = "on_surface" # ColorSpec role or #hex when colorize is enabled
clipboard_enabled     = true         # false disables clipboard panel, history, and compositor clipboard hooks
clipboard_history_max_entries = 100 # unpinned history cap (10–10000); pinned entries are extra
# A Wayland selection is served by the app that owns it, so it dies when that app exits.
# With this on, the shell claims it back so the item stays pasteable. Caveat: a password
# manager that clears the clipboard by exiting looks identical to any other app closing,
# so its secret can be kept alive too. Apps advertising x-kde-passwordManagerHint are
# already excluded; set this to false if you rely on one that does not.
clipboard_keep_from_closed_apps = true # keep the last copied item pasteable after the app you copied it from closes
clipboard_auto_paste  = "auto"       # off | auto | ctrl_v | ctrl_shift_v | shift_insert
clipboard_image_action_command = ""  # image preview action: gimp {path}, or satty -f - via stdin
# IPC example:
# noctalia msg clipboard-clear
shared_gl_context     = true         # startup-only; false isolates GPU contexts for broken drivers
# lang                = "en"
# avatar_path         = "~/Pictures/avatar.png"

[shell.privacy]
mic_filter_regex = ""                # microphone app names to ignore in privacy indicators and OSD
cam_filter_regex = ""                # camera app names to ignore in privacy indicators and OSD
screen_filter_regex = ""             # screen-sharing app names to ignore in privacy indicators and OSD

[shell.animation]
enabled = true
speed   = 1.0                       # 0.5 = 2× slower, 2.0 = 2× faster

[shell.shadow]
direction = "down"                  # center, up, down, left, right, up_left, up_right, down_left, down_right
alpha     = 0.55                    # multiplied by each component's background opacity

[shell.panel]
transparency_mode     = "solid"     # solid | soft | glass; controls floating-panel opacity and card translucency
borders               = true        # panel shell outline and in-panel section cards
shadow                = true        # cast the global [shell.shadow] from panel surfaces
launcher_placement       = "floating" # attached | floating
clipboard_placement      = "floating" # attached | floating
control_center_placement = "attached" # attached | floating
wallpaper_placement      = "attached" # attached | floating
session_placement        = "attached" # attached | floating
launcher_position        = "center"   # auto | center | top_left | … (floating only)
clipboard_position       = "center"   # auto | center | top_left | … (floating only)
open_near_click_control_center = false # for attached/floating placement, follow the bar click instead of bar-center
open_near_click_launcher       = false # for attached/floating placement, follow the bar click instead of bar-center
open_near_click_clipboard      = false # for attached/floating placement, follow the bar click instead of bar-center
open_near_click_wallpaper      = false # for attached/floating placement, follow the bar click instead of bar-center
open_near_click_session        = false # for attached/floating placement, follow the bar click instead of bar-center

[shell.launcher]
categories    = true                    # show category filters in the launcher
show_icons    = true                    # show application icons in launcher results
compact       = false                   # use smaller icons and tighter result rows
app_grid      = false                   # show app icon grid view when results are apps only
sort_by_usage = true                    # sort apps by usage frequency
pinned        = []                      # e.g. ["firefox", "code", "kitty"] (launcher only)
fetch_exchange_rates = true             # refresh currency rates from third-party sources
provider_prefix = "/"                     # common prefix character for provider trigger words (e.g. "/" or ".")
auto_paste = "auto"                       # off | auto | ctrl_v | ctrl_shift_v | shift_insert (copy activations)

# For each provider: prefix = trigger word (empty falls back to its built-in default; triggers on
# provider_prefix + trigger, e.g. "/emo"). global = true also surfaces it in unprefixed search.
[shell.launcher.providers.calculator]
prefix = "calc"
global = true                           # also show calculator results in unprefixed search

[shell.launcher.providers.emoji]
prefix = "emo"

[shell.launcher.providers.session]
prefix = "session"
global = false                          # set true to include session actions in unprefixed search

[shell.launcher.providers.wallpaper]
prefix = "wall"

[shell.launcher.providers.windows]
prefix = "win"

[shell.mpris]
blacklist = []                      # ignore MPRIS players by bus/identity/desktop entry token

# ── Wallpaper ─────────────────────────────────────────────────────────────────

[wallpaper]
enabled             = true
fill_mode           = "crop"        # center | crop | fit | stretch | repeat | span
fill_color          = ""            # optional fallback/fill color: prefer a color role token; fixed hex also works
transition          = ["fade", "wipe", "disc", "stripes", "zoom", "honeycomb"]
transition_duration = 1500          # milliseconds
edge_smoothness     = 0.3
transition_on_startup = false       # animate the first wallpaper at shell startup (v4-style)
directory           = "~/Pictures/Wallpapers"
directory_light     = ""            # optional day-mode directory
directory_dark      = ""            # optional night-mode directory

[wallpaper.default]
path = ""                            # optional initial/default wallpaper path

[wallpaper.automation]
enabled                    = false
interval_seconds           = 1800    # seconds between changes
order                      = "random" # random | alphabetical
recursive                  = true    # include subdirectories when picking random wallpapers

# ── Theme ─────────────────────────────────────────────────────────────────────

[theme]
mode   = "dark"                     # dark | light | auto
source = "builtin"                  # builtin | wallpaper | community
builtin = "Noctalia"                # Ayu | Catppuccin | Dracula | Eldritch | Gruvbox |
                                    # Kanagawa | Noctalia | Nord | Rosé Pine | Tokyo-Night
# community_palette = "Noctalia"    # fetched from api.noctalia.dev, cached locally
# wallpaper_scheme  = "m3-content"  # m3-tonal-spot | m3-content | m3-fruit-salad |
                                    # m3-rainbow | m3-monochrome | vibrant | faithful |
                                    # dysfunctional | muted
pure_black_dark = false             # anchor dark surfaces to true black (OLED); applies to
                                    # every palette source, not just wallpaper-generated ones

[theme.templates]
enable_builtin_templates            = true
builtin_ids                = []     # opt-in; list ids with: noctalia theme --list-templates
enable_community_templates = true
community_ids              = []     # fetched from api.noctalia.dev/templates, cached locally

# User-defined templates are declared directly in config.
# [theme.templates.user.my_app]
# input_path  = "templates/my-app.css"
# output_path = "~/.config/my-app/theme.css"
# post_hook   = "my-app --reload-theme"

# ── Backdrop ──────────────────────────────────────────────────────────────────

[backdrop]
enabled                = false
blur_intensity         = 0.5        # 0.0 = no blur, 1.0 = maximum
tint_intensity         = 0.3        # 0.0 = no tint, 1.0 = opaque

# ── Notifications ─────────────────────────────────────────────────────────────

[notification]
enable_daemon      = true
show_app_name      = true
show_actions       = true           # show action buttons; when false, clicking a toast triggers its default action
layer              = "top"          # top | overlay
scale              = 1.0            # notification size multiplier applied on top of accessibility.ui_scale
background_opacity = 0.97
offset_x           = 20             # absolute horizontal margin from the screen edge
offset_y           = 8              # absolute vertical margin from the screen edge
# [notification.filter.rhythmbox]
# enabled         = true
# match           = "rhythmbox"
# show_toast      = true
# save_history    = false
# play_sound      = true
# allowed_urgencies = ["normal", "critical"]  # omit or list all three to allow every level
# IPC examples:
# noctalia msg notification-invoke-latest
# noctalia msg notification-clear-active
# noctalia msg notification-clear-history

# ── OSD ───────────────────────────────────────────────────────────────────────

[osd]
position = "top_right"              # top_right | top_left | top_center | bottom_right | bottom_left | bottom_center | center_right | center_left
position_vertical = "top_center"    # same options; used when orientation = "vertical"
orientation = "horizontal"          # horizontal | vertical (volume/brightness sliders only; text popups stay horizontal)
scale = 1.0                         # OSD size multiplier applied on top of accessibility.ui_scale
background_opacity = 0.97           # background opacity of OSD popups
offset_x = 20                       # absolute horizontal margin from the screen edge
offset_y = 8                        # absolute vertical margin from the screen edge
# monitors = ["DP-1"]               # connector names; omit or leave empty for all monitors

[osd.kinds]
volume = true                       # master volume OSD toggle
volume_output = true                # output (speaker) volume; requires volume = true
volume_input = true                 # input (microphone) volume; requires volume = true
brightness = true                   # display brightness changes
wifi = true                         # Wi-Fi toggle
bluetooth = true                    # Bluetooth toggle
power_profile = true                # power profile changes
caffeine = true                     # idle inhibitor (caffeine) toggle
nightlight = true                   # night light toggle
dnd = true                          # Do Not Disturb toggle
lock_keys = true                    # Caps/Num/Scroll Lock changes; disable to stop polling when no widget uses them
keyboard_layout = true              # input keyboard layout changes
privacy = true                      # microphone/camera/screen-share capture changes

# ── Lock Screen ───────────────────────────────────────────────────────────────

[lockscreen]
enabled                 = true
blurred_desktop         = false       # use a desktop snapshot as the lock screen background (requires wlr-screencopy)
blur_intensity          = 0.5         # lock screen background blur (0.0 = none, 1.0 = maximum)
tint_intensity          = 0.3         # surface-color tint over the lock screen background
# wallpaper             = ""          # optional image path for the lock screen; empty uses the desktop wallpaper
# monitors              = ["DP-1"]    # connectors that show the lock screen; empty shows all monitors, others stay black

# ── System Monitor ────────────────────────────────────────────────────────────

[system.monitor]
enabled = true                      # sample CPU, memory, network, load, temperature, GPU VRAM, and disk statistics
cpu_poll_seconds = 2.0              # CPU usage, CPU temperature, and load average
cpu_freq_activity_threshold = 2.5   # GHz; value tint starts when CPU clock crosses this
cpu_freq_critical_threshold = 4.5   # GHz; full highlight at/above this
gpu_poll_seconds = 5.0              # GPU temperature and VRAM usage
memory_poll_seconds = 2.0           # RAM usage
network_poll_seconds = 3.0          # network throughput
disk_poll_seconds = 10.0            # disk usage and swap usage; graph widgets use the fastest poll above

# ── Calendar ──────────────────────────────────────────────────────────────────

[calendar]
enabled                     = false
refresh_minutes             = 15

# Calendar tab of the control center.

[control_center.calendar]
show_events_card            = true
show_week_numbers           = false         # ISO 8601 week numbers in the month grid
event_date_format           = "%A %e %B"    # date format used for events
event_time_format           = "%H:%M"       # time format used for events

# ── Weather ───────────────────────────────────────────────────────────────────

[weather]
enabled         = false
refresh_minutes = 30
unit            = "celsius"         # celsius | fahrenheit
effects         = true              # visual weather effects
# Weather uses the coordinates resolved by [location] (see below).

# ── Audio ─────────────────────────────────────────────────────────────────────

[audio]
enable_overdrive = false            # allow volume above 100% (up to 150%)
enable_sounds = false               # master toggle for UI feedback sounds
sound_volume = 0.5                  # 0.0 - 1.0
volume_change_sound = ""            # empty = bundled sounds/volume-change.wav
notification_sound = ""             # empty = bundled sounds/notification.wav

# ── Brightness ────────────────────────────────────────────────────────────────

[brightness]
enable_ddcutil = false
# ignore_mmids = []                 # skip these monitors from ddcutil; run: ddcutil --verbose detect
# minimum_brightness = 0.0          # never let brightness drop below this floor (0.0 to 1.0)

# Per-monitor backend override:
# [brightness.monitor.eDP-1]
# backend = "backlight"             # auto | none | backlight | ddcutil
# backlight_device = "intel_backlight"  # explicit sysfs device name or path; run: noctalia msg brightness-list-backlight-devices
# [brightness.monitor.DP-1]
# backend = "ddcutil"

# ── Night Light ───────────────────────────────────────────────────────────────

[nightlight]
enabled              = false
force                = false
temperature_day      = 6500         # Kelvin
temperature_night    = 4000         # Kelvin

# ── Location ──────────────────────────────────────────────────────────────────
# Single source of "where am I"; feeds Weather, Night Light, and Theme auto mode.

[location]
auto_locate      = false             # resolve coordinates from IP when true
address          = ""                # e.g. "Toronto, ON"; geocoded when auto_locate = false
# latitude       = 52.5200           # manual coordinates, used when auto_locate and address are off
# longitude      = 13.4050
# custom_schedule = true    # schedule day/night from the times below instead of coordinates
# sunset         = "20:30"           # HH:MM — night start
# sunrise        = "07:30"           # HH:MM — day start

# ── Idle ──────────────────────────────────────────────────────────────────────

# Optional `[idle]` keys:
#   pre_action_fade_seconds — fade a fullscreen surface-color overlay in over this many seconds, then run `command`.
#                             Use 0 for immediate commands with no overlay. Input during the fade cancels.
# [idle]
# pre_action_fade_seconds = 2.0

[idle.behavior.lock]
timeout = 600
action = "lock"
enabled = false

[idle.behavior.screen-off]
timeout = 660
action = "screen_off"
enabled = false

# ── Keybinds ──────────────────────────────────────────────────────────────────

[keybinds]
validate = ["return", "kp_enter", "space"]
cancel   = ["escape"]
left     = ["left"]
right    = ["right"]
up       = ["up"]
down     = ["down"]
tab_next = ["tab"]
tab_previous = ["shift+iso_left_tab"]
delete   = ["del"]

# ── Bar ───────────────────────────────────────────────────────────────────────

[bar.main]
position           = "top"          # top | bottom | left | right
thickness          = 34
background_opacity = 1.0
radius             = 12
margin_ends        = 180
margin_edge        = 10
padding            = 14
widget_spacing     = 6
scale              = 1.0
shadow             = true
auto_hide          = false
# smart_auto_hide    = false       # show when the active workspace is empty; hide when it has windows
# show_on_workspace_switch = true   # with auto_hide: briefly reveal when the active workspace changes
reserve_space      = true
capsule            = false
# capsule_fill     = "surface_variant"
# capsule_radius   = 8.0            # omit/blank in Settings for automatic pill radius; 0.0 = square
# capsule_opacity  = 1.0
# capsule_border   = "outline"      # uncomment for a border on all widgets

start  = ["launcher", "wallpaper", "workspaces"]
center = ["clock"]
end    = ["media", "tray", "notifications", "clipboard", "network", "bluetooth", "volume", "brightness", "battery", "control-center", "session"]

# Commands for the bar margin outside widget sections (dead zone):
# [bar.main.dead_zone.actions]
# left = "panel-toggle launcher"
# right = "panel-toggle control-center"
# middle = "none"
# scroll_up = "none"
# scroll_down = "none"

# Per-monitor override example — only the fields you list are overridden:
# [bar.main.monitor.dp1]
# match     = "DP-1"
# thickness = 44
# [bar.main.monitor.dp1.dead_zone.actions]
# left = "panel-toggle launcher"

# ── Dock ──────────────────────────────────────────────────────────────────────

[dock]
enabled             = false         # set true to activate
position            = "bottom"      # top | bottom | left | right
icon_size           = 48
main_axis_padding   = 16
cross_axis_padding  = 8
item_spacing        = 6
background_opacity  = 0.88
radius              = 16
radius_top_left     = 16
radius_top_right    = 16
radius_bottom_left  = 16
radius_bottom_right = 16
margin_ends         = 0
margin_edge         = 8
shadow              = true
show_running        = true
auto_hide           = false
# smart_auto_hide   = false       # show when the active workspace is empty; hide when it has windows
reserve_space       = true
layer               = "top"         # top | overlay
active_scale        = 1.0
inactive_scale      = 0.85
magnification       = true
magnification_scale = 1.45
active_opacity      = 1.0
inactive_opacity    = 0.85
show_dots           = false
show_instance_count = true
launcher_position   = "none"       # none | start | end
launcher_icon       = "grid-dots"  # Tabler glyph name
active_monitor_only = false
pinned              = []            # e.g. ["firefox", "code", "kitty"]

# ── Desktop Widgets ───────────────────────────────────────────────────────────

[desktop_widgets]
enabled = false
# When set, widget_order is the active widget list and stacking order.
# widget_order = ["clock_main"]

# [desktop_widgets.grid]
# visible        = true
# cell_size      = 16
# major_interval        = 4
# center_guides_visible = false
# snap_to_center        = true

# [desktop_widgets.widget.clock_main]
# type     = "clock"
# output   = "DP-1"
# cx       = 960.0
# cy       = 540.0
# scale    = 1.5
# rotation = 0.0

# [desktop_widgets.widget.clock_main.settings]
# format = "{:%H:%M}"
# background_opacity = 0.8

# [lockscreen_widgets]
# enabled = false
# widget_order = ["clock_main"]

# [lockscreen_widgets.widget.clock_main]
# type     = "clock"
# output   = "DP-1"
# cx       = 1600.0
# cy       = 120.0
# scale    = 1.5
# rotation = 0.0

# [lockscreen_widgets.widget.clock_main.settings]
# format = "{:%H:%M}"
# background_opacity = 0.8

# ── Control Center ────────────────────────────────────────────────────────────

# Shortcut buttons shown on the right side of the dashboard (up to 6).
# [[control_center.shortcuts]]
# type = "wifi"
# [[control_center.shortcuts]]
# type = "bluetooth"
# [[control_center.shortcuts]]
# type = "nightlight"
# [[control_center.shortcuts]]
# type = "notification"
# [[control_center.shortcuts]]
# type = "wallpaper"
# [[control_center.shortcuts]]
# type = "screen_recorder"
# [[control_center.shortcuts]]
# type = "session"

# ── Hooks ─────────────────────────────────────────────────────────────────────

[hooks]

# started           = "notify-send 'Noctalia' 'Shell started'"
# wallpaper_changed = []
# colors_changed    = []
# theme_mode_changed = "notify-send 'Noctalia' \"Theme mode: $NOCTALIA_THEME_MODE\""
# session_locked    = []
# session_unlocked  = []
# logging_out       = []
# rebooting         = []
# shutting_down     = []
# wifi_enabled      = []
# wifi_disabled     = []
# bluetooth_enabled  = []
# bluetooth_disabled = []
# battery_state_changed   = "notify-send 'Power' \"Battery: $NOCTALIA_BATTERY_STATE\""
# battery_under_threshold = "notify-send 'Power' \"Battery at ${NOCTALIA_BATTERY_PERCENT}%\""
# power_profile_changed   = "notify-send 'Power' \"Profile: $NOCTALIA_POWER_PROFILE\""
# [widget.launcher]
# custom_image = "/path/to/image.png"
# custom_image_colorize = false

# [widget.control-center]
# custom_image = "/path/to/image.png"
# custom_image_colorize = false

# [widget.notifications]
# hide_when_no_unread = true

# [widget.network_rx]
# network_speed_unit = "mb"          # auto | kb | mb
# network_speed_compact = true       # show "1.2M" instead of "1.2 MB/s"
#
# [widget.network_tx]
# network_speed_unit = "mb"          # auto | kb | mb
# network_speed_compact = true       # show "1.2M" instead of "1.2 MB/s"

# [widget.network]
# vpn_status     = "replace"         # replace | both | hidden
# show_label     = true
# show_vpn_label = false             # replace: replaces network label; both: adds VPN label

# [widget.volume.effects_profile_glyphs]
# eq_desktop = "device-speaker"

# [widget.keyboard_layout]
# display                 = "short"    # "short" (e.g. "DE") or "full" (full layout name)
# show_icon               = true
# show_label              = true
# hide_when_single_layout = false      # hide the widget when only one layout is configured
# cycle_command           = ""         # custom command to cycle layouts (empty = compositor backend)
# [widget.keyboard_layout.custom_labels]  # override display labels by exact layout name
# "German (Neo 2)"        = "Neo2"
# "English (US)"          = "EN"

# [widget.lock_button]
# type                = "custom_button"
# glyph               = "lock"
# tooltip             = "Lock screen"
# command             = "noctalia msg session lock"
# right_command       = ""
# middle_command      = ""
# scroll_up_command   = ""
# scroll_down_command = ""
#
# [widget.clock]
# format = "{:%H:%M}\n{:%d/%m}"
# vertical_format = "{:%H\n%M}"
# tooltip_format = "{:%A, %B %d, %Y}"
# scale = 1.0                         # multiplies the bar scale for this widget only
# font_weight = 700
# interactive = false                 # pass clicks/scrolls through to the bar and disable hover/tooltips