### Configure NixOS Module

Source: https://docs.noctalia.dev/noctalia/getting-started/nixos?section=binary-cache

Examples for system-wide installation of Noctalia on NixOS.

```nix
{ inputs, ... }:
{
  imports = [
    inputs.noctalia.nixosModules.default
  ];


  programs.noctalia = {
    enable = true;


    # Enables NetworkManager, Bluetooth, UPower, and a power profile service.
    recommendedServices.enable = true;
  };
}
```

```nix
let
  # see adding the input above
in {
  imports = [
    noctalia.nixosModule
  ];


  programs.noctalia = {
    enable = true;


    # Enables NetworkManager, Bluetooth, UPower, and a power profile service.
    recommendedServices.enable = true;
  };
}
```

--------------------------------

### Noctalia Theme Configuration Examples

Source: https://docs.noctalia.dev/noctalia/templates/official/emacs?section=configuration-example

Examples for loading the theme directly or via an initialization hook.

```elisp
;; Load Noctalia theme
(load-theme 'noctalia t)
```

```elisp
;; Load Noctalia theme after startup
(add-hook 'after-init-hook (lambda () (load-theme 'noctalia t)))
```

--------------------------------

### Install base16-nvim with Lazy

Source: https://docs.noctalia.dev/noctalia/templates/community/neovim

Use this configuration snippet with the Lazy package manager to install the base16 colorscheme and initialize the matugen setup.

```lua

return { 'RRethy/base16-nvim',
  config = function()
    require('matugen').setup()
  end,
}

```

--------------------------------

### Install Vesktop on Arch Linux

Source: https://docs.noctalia.dev/noctalia/templates/community/discord

Use the AUR helper to install the Vesktop client.

```bash
# Example for Vesktop (Arch Linux)
paru -S vesktop
```

--------------------------------

### Example plugin commands

Source: https://docs.noctalia.dev/noctalia/plugins/official-plugins

Commands to interact with the reference example plugin's widgets and panels.

```bash
plugin noctalia/example:hello focused set "New label"
```

```bash
plugin noctalia/example:hello focused fetch "https://example.com"
```

```bash
panel-toggle noctalia/example:panel
```

--------------------------------

### Bar and Widget Configuration Examples

Source: https://docs.noctalia.dev/noctalia/bar?section=bar-level-defaults

Examples showing how to define bar-level defaults and apply specific overrides to widgets like volume and spacers.

```toml
[bar.default]
capsule         = true
capsule_fill    = "surface_variant"
capsule_opacity = 0.9
capsule_border  = "outline"


# Accent bar: primary fill + matching text
[bar.accent]
capsule            = true
capsule_fill       = "primary"
capsule_foreground = "on_primary"
capsule_padding    = 10
capsule_radius     = 8.0


[widget.volume]
capsule_fill   = "secondary"
capsule_radius = 0.0         # square this widget's capsule
capsule_border = ""          # no border on this widget


[widget.spacer]
type    = "spacer"
capsule = false
```

--------------------------------

### Initialize Matugen in init.lua

Source: https://docs.noctalia.dev/noctalia/templates/community/neovim?section=setup

Call the setup function in your init.lua to apply the theme.

```lua
 require('matugen').setup()
```

--------------------------------

### Configure Clock Widget Examples

Source: https://docs.noctalia.dev/noctalia/bar/widgets/clock

Examples showing various clock configurations including multi-line formats, 12-hour time, and seconds display.

```toml
[widget.clock]
format = "{:%H:%M}\n{:%d/%m}"
vertical_format = "{:%H\n%M}"
tooltip_format = "{:%A, %B %d, %Y}"


[widget.clock-12h]
type   = "clock"
format = "{:%-I:%M %p}"


[widget.clock-seconds]
type   = "clock"
format = "{:%H:%M:%S}"
vertical_format = "{:%H\n%M\n%S}"
```

--------------------------------

### Tray Widget Configuration Example

Source: https://docs.noctalia.dev/noctalia/bar/widgets/tray

Example configuration block for the tray widget, demonstrating how to hide specific items, pin others, and enable the drawer functionality.

```toml
[widget.tray]
hidden = ["nm-applet", "blueman", "org.kde.StatusNotifierItem-1-1"]
pinned = ["nm-applet"]
hide_passive = true
drawer = true
drawer_columns = 3
drawer_item_size = 20
detached_panel = false
```

--------------------------------

### Install qt6ct-kde on Arch-based systems

Source: https://docs.noctalia.dev/noctalia/templates/official/gtk-qt?section=gtk-34-applications

Use the paru package manager to install the qt6ct-kde package.

```bash
paru -S qt6ct-kde
```

--------------------------------

### Configure plugins and sources

Source: https://docs.noctalia.dev/noctalia/plugins

Example configuration showing how to enable plugins and define git and path-based plugin sources.

```toml
[plugins]
# Fully-qualified ids ("<author>/<plugin>") that are active.
enabled = ["noctalia/screen_recorder"]
auto_update = "all" # "all" | "official" | "none"; background git updates on startup and every 6 hours


# A git source: cached and updated by Noctalia.
[[plugins.source]]
name     = "official"
kind     = "git"
location = "https://github.com/noctalia-dev/official-plugins"
enabled  = true


# A path source: an immutable local directory Noctalia treats read-only
# (no git ops). Ideal for local development or Nix-managed plugins.
[[plugins.source]]
name     = "my-dev"
kind     = "path"
location = "~/dev/my-plugins"
enabled  = true
```

--------------------------------

### Install Noctalia on Fedora

Source: https://docs.noctalia.dev/noctalia/getting-started/installation

Install the stable version of Noctalia from default repositories.

```bash
sudo dnf install noctalia
```

--------------------------------

### Install base16-nvim with Lazy

Source: https://docs.noctalia.dev/noctalia/templates/community/neovim?section=setup

Install the base16 colorscheme plugin using the Lazy package manager.

```lua
return { 'RRethy/base16-nvim',
  config = function()
    require('matugen').setup()
  end,
}
```

--------------------------------

### Initialize matugen in init.lua

Source: https://docs.noctalia.dev/noctalia/templates/community/neovim

Call the setup function in your init.lua to apply the theme upon Neovim startup.

```lua

 require('matugen').setup()

```

--------------------------------

### Install GTK theme packages

Source: https://docs.noctalia.dev/noctalia/templates/official/gtk-qt?section=gtk-34-applications

Install the necessary theme and configuration tools for Arch Linux or other distributions.

```bash
# Arch Linux / Manjaro
paru -S adw-gtk-theme nwg-look


# Other distributions
# Install adw-gtk-theme and nwg-look from your package manager
```

--------------------------------

### Default installation layout

Source: https://docs.noctalia.dev/noctalia/getting-started/installation

The standard file layout used by Meson for the binary and assets.

```text
/usr/local/bin/noctalia
/usr/local/share/noctalia/assets/...
```

--------------------------------

### Enable greetd

Source: https://docs.noctalia.dev/noctalia/getting-started/installation

Enable and start the greetd service.

```bash
sudo systmectl enable --now greetd
```

--------------------------------

### Build and install in Release Mode

Source: https://docs.noctalia.dev/noctalia/getting-started/installation

Configure, build, and install Noctalia in release mode.

```bash
# Optimized release build in build-release/
just configure release
just build release


# Install the selected build mode. This does not build or reconfigure.
sudo just install release
```

--------------------------------

### Install Noctalia with guix package

Source: https://docs.noctalia.dev/noctalia/getting-started/installation

Command to install noctalia-git into the user profile.

```bash
guix install noctalia-git
```

--------------------------------

### Install Stable Noctalia on openSUSE

Source: https://docs.noctalia.dev/noctalia/getting-started/installation?section=alternative-build-from-source-using-xbps-src

Refresh repositories and install the stable version of Noctalia.

```bash
sudo zypper refresh
sudo zypper install noctalia
```

--------------------------------

### Install to a custom prefix

Source: https://docs.noctalia.dev/noctalia/getting-started/installation

Configure and install Noctalia to a custom directory instead of the default /usr/local.

```bash
just configure release "$HOME/.local"
just build release
just install release
```

--------------------------------

### Sync and install Noctalia on Void Linux

Source: https://docs.noctalia.dev/noctalia/getting-started/installation

Update the repository index and install the Noctalia package.

```bash
sudo xbps-install -S
sudo xbps-install noctalia
```

--------------------------------

### For loop block example

Source: https://docs.noctalia.dev/noctalia/theming/templates?section=data-model

An example of using a for loop to iterate over colors.

```text
<* for name, value in colors *>
{{ name }}={{ value.default.hex }}
<* endfor *>
```

--------------------------------

### Define Plugin-level and Widget-level Settings

Source: https://docs.noctalia.dev/noctalia/plugins/development/manifest

Example showing a plugin-level setting for shared configuration and a widget-level setting for specific widget presentation.

```toml
# Plugin-level: shared by widget + shortcut + service, edited in Settings → Plugins.
[[setting]]
key     = "interval"
type    = "int"
label_key = "settings.interval.label"
description_key = "settings.interval.description"
default = 5


[[widget]]
id    = "hello"
entry = "widget.luau"


  # Widget entry setting: this bar widget only.
  [[widget.setting]]
  key     = "label"
  type    = "string"
  label_key = "settings.label.label"
  default = "Hello"
```

--------------------------------

### Install Noctalia on Arch Linux

Source: https://docs.noctalia.dev/noctalia/getting-started/installation

Install Noctalia from the official extra repository using pacman.

```bash
sudo pacman -S noctalia
```

--------------------------------

### Manual Configuration Steps

Source: https://docs.noctalia.dev/noctalia/templates/community/terminal-templates

Configuration entries and generation script for manual setup of terminal sequences.

```toml
[theme.templates.user.terminal-sequences]
input_path = '~/.config/noctalia/templates/terminal-sequences'
output_path = '~/.cache/terminal-sequences'
post_hook = 'tee /dev/pts/[0-9]* < ~/.cache/terminal-sequences'
```

```bash
#!/usr/bin/env bash


TEMPLATE_PATH=~/.config/noctalia/templates/terminal-sequences


mkdir -p ~/.config/noctalia/templates


{
    printf '\033]10;{{colors.terminal_foreground.default.hex}}\007'
    printf '\033]11;{{colors.terminal_background.default.hex}}\007'


    printf '\033]4;0;{{colors.terminal_normal_black.default.hex}}\007'
    printf '\033]4;1;{{colors.terminal_normal_red.default.hex}}\007'
    printf '\033]4;2;{{colors.terminal_normal_green.default.hex}}\007'
    printf '\033]4;3;{{colors.terminal_normal_yellow.default.hex}}\007'
    printf '\033]4;4;{{colors.terminal_normal_blue.default.hex}}\007'
    printf '\033]4;5;{{colors.terminal_normal_magenta.default.hex}}\007'
    printf '\033]4;6;{{colors.terminal_normal_cyan.default.hex}}\007'
    printf '\033]4;7;{{colors.terminal_normal_white.default.hex}}\007'


    printf '\033]4;8;{{colors.terminal_bright_black.default.hex}}\007'
    printf '\033]4;9;{{colors.terminal_bright_red.default.hex}}\007'
    printf '\033]4;10;{{colors.terminal_bright_green.default.hex}}\007'
    printf '\033]4;11;{{colors.terminal_bright_yellow.default.hex}}\007'
    printf '\033]4;12;{{colors.terminal_bright_blue.default.hex}}\007'
    printf '\033]4;13;{{colors.terminal_bright_magenta.default.hex}}\007'
    printf '\033]4;14;{{colors.terminal_bright_cyan.default.hex}}\007'
    printf '\033]4;15;{{colors.terminal_bright_white.default.hex}}\007'


    printf '\033]19;{{colors.terminal_selection_fg.default.hex}}\007'
    printf '\033]17;{{colors.terminal_selection_bg.default.hex}}\007'
    printf '\033]12;{{colors.terminal_cursor.default.hex}}\007'
} > "$TEMPLATE_PATH"
```

--------------------------------

### Taskbar Configuration Example

Source: https://docs.noctalia.dev/noctalia/bar/widgets/taskbar

A complete configuration block for the [widget.taskbar] section, demonstrating common settings for pinning, workspace grouping, and visual indicators.

```toml
[widget.taskbar]
pinned = ["firefox", "code", "kitty"]
pinned_opacity = 0.5
icon_scale = 1.0
item_spacing = 4  # Flat taskbar only; ignored when workspace grouping is enabled
group_by_workspace = true
show_all_outputs = true
only_active_workspace = true
show_workspace_label = true
workspace_label_placement = "corner"
hide_empty_workspaces = true
workspace_group_capsule = true
workspace_group_content = "icons"
group_single_icon_per_app = true
show_active_indicator = true
active_indicator_color = "primary"
active_opacity = 1.0
inactive_opacity = 1.0
focused_color = "primary"
occupied_color = "secondary"
empty_color = "secondary"
urgent_color = "error"
focused_output_only = false  # true = only the focused monitor highlights its active workspace
```

--------------------------------

### Implement plugin lifecycle hooks

Source: https://docs.noctalia.dev/noctalia/plugins/development/entries?section=cleaning-up-when-an-entry-exits

Use onEnable to start services and onExit to handle cleanup during disable or uninstall events.

```lua
function onEnable()
  noctalia.runAsync("systemctl --user start my-plugin.service")
end


function onExit(_signal, reason)
  if reason == "disable" then
    noctalia.runAsync("systemctl --user stop my-plugin.service")
  elseif reason == "uninstall" then
    noctalia.runAsync("systemctl --user disable --now my-plugin.service")
  end
end
```

--------------------------------

### Install Unstable Noctalia on openSUSE

Source: https://docs.noctalia.dev/noctalia/getting-started/installation?section=alternative-build-from-source-using-xbps-src

Refresh repositories and install the git version of Noctalia.

```bash
sudo zypper refresh
sudo zypper install noctalia-git
```

--------------------------------

### Automated Setup Script

Source: https://docs.noctalia.dev/noctalia/templates/community/terminal-templates

A bash script that automates the creation of the configuration file and the terminal sequence template.

```bash
#!/usr/bin/env bash


CONFIG_PATH=~/.config/noctalia
TEMPLATE_PATH=$CONFIG_PATH/templates/terminal-sequences


mkdir -p $CONFIG_PATH/templates


cat >> $CONFIG_PATH/config.toml <<'EOF'
[theme.templates.user.terminal-sequences]
input_path = '~/.config/noctalia/templates/terminal-sequences'
output_path = '~/.cache/terminal-sequences'
post_hook = 'tee /dev/pts/[0-9]* < ~/.cache/terminal-sequences'
EOF


{
    printf '\033]10;{{colors.terminal_foreground.default.hex}}\007'
    printf '\033]11;{{colors.terminal_background.default.hex}}\007'


    printf '\033]4;0;{{colors.terminal_normal_black.default.hex}}\007'
    printf '\033]4;1;{{colors.terminal_normal_red.default.hex}}\007'
    printf '\033]4;2;{{colors.terminal_normal_green.default.hex}}\007'
    printf '\033]4;3;{{colors.terminal_normal_yellow.default.hex}}\007'
    printf '\033]4;4;{{colors.terminal_normal_blue.default.hex}}\007'
    printf '\033]4;5;{{colors.terminal_normal_magenta.default.hex}}\007'
    printf '\033]4;6;{{colors.terminal_normal_cyan.default.hex}}\007'
    printf '\033]4;7;{{colors.terminal_normal_white.default.hex}}\007'


    printf '\033]4;8;{{colors.terminal_bright_black.default.hex}}\007'
    printf '\033]4;9;{{colors.terminal_bright_red.default.hex}}\007'
    printf '\033]4;10;{{colors.terminal_bright_green.default.hex}}\007'
    printf '\033]4;11;{{colors.terminal_bright_yellow.default.hex}}\007'
    printf '\033]4;12;{{colors.terminal_bright_blue.default.hex}}\007'
    printf '\033]4;13;{{colors.terminal_bright_magenta.default.hex}}\007'
    printf '\033]4;14;{{colors.terminal_bright_cyan.default.hex}}\007'
    printf '\033]4;15;{{colors.terminal_bright_white.default.hex}}\007'


    printf '\033]19;{{colors.terminal_selection_fg.default.hex}}\007'
    printf '\033]17;{{colors.terminal_selection_bg.default.hex}}\007'
    printf '\033]12;{{colors.terminal_cursor.default.hex}}\007'
} > "$TEMPLATE_PATH"
```

--------------------------------

### Conditional theme loading

Source: https://docs.noctalia.dev/noctalia/templates/official/emacs?section=additional-notes

Examples for loading the theme during startup or via hooks.

```elisp
;; Load Noctalia theme
(load-theme 'noctalia t)
```

```elisp
;; Load Noctalia theme after startup
(load-hook 'after-init-hook (lambda () (load-theme 'noctalia t)))
```

--------------------------------

### Manual Configuration Steps

Source: https://docs.noctalia.dev/noctalia/templates/community/terminal-templates?section=troobleshooting

Configuration entries and generation script for manual setup of terminal sequences.

```toml

[theme.templates.user.terminal-sequences]
input_path = '~/.config/noctalia/templates/terminal-sequences'
output_path = '~/.cache/terminal-sequences'
post_hook = 'tee /dev/pts/[0-9]* < ~/.cache/terminal-sequences'
```

```bash

#!/usr/bin/env bash


TEMPLATE_PATH=~/.config/noctalia/templates/terminal-sequences


mkdir -p ~/.config/noctalia/templates


{
    printf '\033]10;{{colors.terminal_foreground.default.hex}}\007'
    printf '\033]11;{{colors.terminal_background.default.hex}}\007'


    printf '\033]4;0;{{colors.terminal_normal_black.default.hex}}\007'
    printf '\033]4;1;{{colors.terminal_normal_red.default.hex}}\007'
    printf '\033]4;2;{{colors.terminal_normal_green.default.hex}}\007'
    printf '\033]4;3;{{colors.terminal_normal_yellow.default.hex}}\007'
    printf '\033]4;4;{{colors.terminal_normal_blue.default.hex}}\007'
    printf '\033]4;5;{{colors.terminal_normal_magenta.default.hex}}\007'
    printf '\033]4;6;{{colors.terminal_normal_cyan.default.hex}}\007'
    printf '\033]4;7;{{colors.terminal_normal_white.default.hex}}\007'


    printf '\033]4;8;{{colors.terminal_bright_black.default.hex}}\007'
    printf '\033]4;9;{{colors.terminal_bright_red.default.hex}}\007'
    printf '\033]4;10;{{colors.terminal_bright_green.default.hex}}\007'
    printf '\033]4;11;{{colors.terminal_bright_yellow.default.hex}}\007'
    printf '\033]4;12;{{colors.terminal_bright_blue.default.hex}}\007'
    printf '\033]4;13;{{colors.terminal_bright_magenta.default.hex}}\007'
    printf '\033]4;14;{{colors.terminal_bright_cyan.default.hex}}\007'
    printf '\033]4;15;{{colors.terminal_bright_white.default.hex}}\007'


    printf '\033]19;{{colors.terminal_selection_fg.default.hex}}\007'
    printf '\033]17;{{colors.terminal_selection_bg.default.hex}}\007'
    printf '\033]12;{{colors.terminal_cursor.default.hex}}\007'
} > "$TEMPLATE_PATH"
```

--------------------------------

### Install Debian repository signing key

Source: https://docs.noctalia.dev/noctalia/getting-started/installation

Download and install the Noctalia APT repository signing key.

```bash
wget https://pkg.noctalia.dev/deb/nickh-archive-keyring.deb && sudo dpkg -i nickh-archive-keyring.deb
```

--------------------------------

### Fullscreen screenshot (pick monitor)

Source: https://docs.noctalia.dev/noctalia/ipc/media-and-ui?section=clipboard

Opens the display picker on multi-monitor setups.

```bash
screenshot-fullscreen pick
```

--------------------------------

### Palette Color Examples

Source: https://docs.noctalia.dev/noctalia/theming/templates?section=data-model

Examples of accessing specific palette colors with different modes and formats.

```text
{{ colors.primary.default.hex }}
{{ colors.surface.light.hsl }}
{{ colors.terminal_foreground.default.hex_stripped }}
```

--------------------------------

### Example config.toml structure

Source: https://docs.noctalia.dev/noctalia/configuration?section=automatic-configuration-migrations

A single configuration file using TOML format to define theme and bar settings.

```toml
[theme]
mode = "dark"


[bar.default]
position = "top"
```

--------------------------------

### Install Noctalia Package

Source: https://docs.noctalia.dev/noctalia/getting-started/nixos?section=binary-cache

Add the Noctalia package to your system environment.

```nix
{ inputs, pkgs, ... }:
{
  environment.systemPackages = [
    inputs.noctalia.packages.${pkgs.stdenv.hostPlatform.system}.default
  ];
}
```

```nix
let
  # see adding the input above
in {
  environment.systemPackages = [
    noctalia.package
  ];
}
```

--------------------------------

### Install dependencies on Debian/Ubuntu

Source: https://docs.noctalia.dev/noctalia/getting-started/installation

Use apt to install the required system dependencies for Noctalia on Debian or Ubuntu.

```bash
sudo apt install just meson libwayland-dev \
  wayland-protocols libfreetype-dev libfontconfig-dev \
  libcairo2-dev libpango1.0-dev librsvg2-dev libxkbcommon-dev \
  libepoxy-dev libgles-dev libwebp-dev libcurl4-gnutls-dev \
  libmd4c-dev nlohmann-json3-dev libsdbus-c++-dev libsecret-1-dev \
  libsodium-dev libstb-dev libtomlplusplus-dev \
  libpipewire-0.3-dev libpam0g-dev libpolkit-agent-1-dev \
  libpolkit-gobject-1-dev libqalculate-dev libwireplumber-0.5-dev \
  libxml2-dev libjemalloc-dev git
```

--------------------------------

### Common IPC command examples

Source: https://docs.noctalia.dev/noctalia/ipc

Examples of common actions triggered via the Noctalia IPC interface.

```bash
noctalia msg dock-toggle
noctalia msg volume-up
noctalia msg panel-toggle launcher
noctalia msg screenshot-region
```

--------------------------------

### Configure [widget.workspaces] settings

Source: https://docs.noctalia.dev/noctalia/bar/widgets/workspaces

Example configuration for the workspaces widget, demonstrating style selection, label behavior, and color roles.

```toml
[widget.workspaces]
style = "regular"       # regular | minimal | focus_hint
show_labels = true      # false = unlabeled pills (Focus Hint: app icon only)
show_icons = true       # focus_hint only; false = active pill without the focused app icon
label_source = "id"     # id | name
max_label_chars = 2     # truncate long workspace names (e.g. "VESKTOP" → "VE")
labels_only_when_occupied = true  # (1) (2*) ( ) (4) - occupied tags and the active tag show labels (*active but empty)
hide_when_empty = true
show_all_outputs = false  # true = include workspaces from every monitor; this bar's monitor comes first
pill_scale = 1.0
active_pill_size = 2.2
inactive_pill_size = 1.0
focused_color = "primary"
occupied_color = "secondary"
empty_color = "surface_variant"
urgent_color = "error"
change_color_on_hover = true  # false = keep configured workspace colors while hovering
focused_output_only = false  # true = only the focused monitor highlights its active workspace
```

--------------------------------

### Install dependencies on Fedora

Source: https://docs.noctalia.dev/noctalia/getting-started/installation

Use dnf to install the required system dependencies for Noctalia on Fedora.

```bash
sudo dnf install meson gcc-c++ just \
  wayland-devel wayland-protocols-devel \
  libEGL-devel mesa-libGLES-devel \
  freetype-devel fontconfig-devel \
  cairo-devel pango-devel harfbuzz-devel \
  libxkbcommon-devel glib2-devel \
  libsecret-devel libsodium-devel \
  sdbus-cpp-devel pipewire-devel wireplumber-devel \
  pam-devel polkit-devel libcurl-devel libwebp-devel libjxl-devel libsndfile-devel librsvg2-devel \
  libqalculate-devel libxml2-devel \
  md4c-devel tomlplusplus-devel \
  json-devel stb_image_resize2-devel stb_image_write-devel \
  jemalloc-devel
```

--------------------------------

### Configure sysmon widgets

Source: https://docs.noctalia.dev/noctalia/bar/widgets/sysmon

Examples of various sysmon widget configurations for different system metrics.

```toml
[widget.cpu]
type = "sysmon"
stat = "cpu_usage"


[widget.cpu-graph]
type       = "sysmon"
stat       = "cpu_usage"
visualization = "graph"
show_value    = false


[widget.temp]
type = "sysmon"
stat = "cpu_temp"


[widget.ram]
type = "sysmon"
stat = "ram_used"


[widget.disk]
type = "sysmon"
stat = "disk_used_pct"
path = "/"


[widget.wifi-download]
type      = "sysmon"
stat      = "net_rx"
interface = "wlan0"


[widget.wifi-upload]
type                  = "sysmon"
stat                  = "net_tx"
network_speed_unit    = "mb"      # auto | kb | mb
network_speed_compact = true      # show "1.2M" instead of "1.2 MB/s"
```

--------------------------------

### Install Flatpak GTK themes

Source: https://docs.noctalia.dev/noctalia/templates/official/gtk-qt?section=gtk-34-applications

Install the adw-gtk3 theme within the Flatpak sandbox for Flatpak-based applications.

```bash
flatpak install org.gtk.Gtk3theme.adw-gtk3-dark
flatpak install org.gtk.Gtk3theme.adw-gtk3
```

--------------------------------

### Configure Shell Settings

Source: https://docs.noctalia.dev/noctalia/configuration/shell?section=app-icon-colorization

Example configuration for hot corners, media player blacklists, window switcher behavior, privacy filters, and screenshot settings.

```toml
# Configure each corner independently. Available actions:
# none | launcher | window-switcher | control-center | command
[hot_corners.top_left]
action = "none"


[hot_corners.bottom_right]
action = "command"
command = "swaylock -f"




[shell.mpris]
blacklist = []           # optional list of players to hide from media widgets/control-center


[shell.window_switcher]
mru = false              # order windows by most recently used (Alt+Tab) instead of workspace layout


[shell.privacy]
mic_filter_regex    = "" # ignore matching microphone application names
cam_filter_regex    = "" # ignore matching camera process names
screen_filter_regex = "" # ignore matching screen-share application names


[shell.screenshot]
save_to_file         = true                       # write captures as PNG to the output directory
directory            = ""                          # output folder; empty = XDG_PICTURES_DIR or ~/Pictures
filename_pattern     = ""                          # empty = screenshot_%Y%m%d_%H%M%S
copy_to_clipboard    = true                        # also place the PNG on the clipboard
freeze_screen        = true                        # freeze the desktop before region selection
confirm_region       = false                       # confirm region captures with Enter or Space
remember_last_region = false                       # pre-select the last region (also after cancel)
show_cursor          = false                       # include the mouse pointer in captures
pipe_to_command      = false                       # pipe the PNG to a shell command on stdin
pipe_command         = ""                          # annotator/uploader, e.g. "swappy -f -" or "satty -f -"
```

--------------------------------

### Minimal Plugin Manifest

Source: https://docs.noctalia.dev/noctalia/plugins/development

Example of a plugin.toml file defining identity and a widget entry point.

```toml
id         = "me/hello"
name       = "Hello"
version    = "1.0.0"
plugin_api = 3
author     = "me"


[[widget]]
id    = "hello"
entry = "widget.luau"
```

--------------------------------

### Install Noctalia Git Snapshot on Fedora

Source: https://docs.noctalia.dev/noctalia/getting-started/installation

Enable the LionHeartP Copr repository and install the git snapshot version of Noctalia.

```bash
sudo dnf copr enable lionheartp/Hyprland
```

```bash
sudo dnf install noctalia-git
```

--------------------------------

### Inline expression examples

Source: https://docs.noctalia.dev/noctalia/theming/templates?section=data-model

Examples of accessing theme token map values using inline expressions.

```text
{{ colors.primary.default.hex }}
{{ colors.surface.dark.rgb }}
{{ mode }}
{{ image }}
```

--------------------------------

### Configure Weather Widget

Source: https://docs.noctalia.dev/noctalia/bar/widgets/weather

Example configuration for the weather widget in the project settings file.

```toml
[widget.weather]
max_length       = 180
show_condition   = false
show_temperature = false
```

--------------------------------

### Configure active_window widget

Source: https://docs.noctalia.dev/noctalia/bar/widgets/active-window

Example configuration block for the active_window widget in the project settings.

```toml
[widget.active_window]
min_length = 80
max_length = 260
icon_size = 14
title_scroll = "on_hover"
display = "icon_and_text"
show_empty_label = true
```

--------------------------------

### Palette tone access examples

Source: https://docs.noctalia.dev/noctalia/theming/templates?section=conditionals

Examples of accessing palette tones using plain integers or underscore-prefixed integers.

```text
bg0 = '{{ palettes.primary.0.hex }}'
bg40 = '{{ palettes.primary.40.hex }}'
bg99 = '{{ palettes.primary._99.hex }}'
fg = '{{ palettes.neutral.90.rgb }}'
```

--------------------------------

### Configuring Widget Background

Source: https://docs.noctalia.dev/noctalia/desktop/widgets

Example of setting the background properties for a widget.

```toml
[desktop_widgets.widget.clock_main.settings]
background       = true
background_color = "surface"
```

--------------------------------

### Configure Media Widget Settings

Source: https://docs.noctalia.dev/noctalia/bar/widgets/media

Example configuration for the media widget, adjusting artwork size, artist display order, and visibility behavior.

```toml
[widget.media]
artist_first = true
art_size     = 24
hide_when_no_media = true
```

--------------------------------

### Refresh and Install Noctalia on openSUSE

Source: https://docs.noctalia.dev/noctalia/getting-started/installation

Refresh repositories and install either the stable or git version of Noctalia.

```bash
sudo zypper refresh
sudo zypper install noctalia
```

```bash
sudo zypper refresh
sudo zypper install noctalia-git
```

--------------------------------

### Automated Setup Script

Source: https://docs.noctalia.dev/noctalia/templates/community/terminal-templates?section=setup

A complete bash script to configure the Noctalia template path and generate the terminal sequence file.

```bash

#!/usr/bin/env bash


CONFIG_PATH=~/.config/noctalia
TEMPLATE_PATH=$CONFIG_PATH/templates/terminal-sequences


mkdir -p $CONFIG_PATH/templates


cat >> $CONFIG_PATH/config.toml <<'EOF'
[theme.templates.user.terminal-sequences]
input_path = '~/.config/noctalia/templates/terminal-sequences'
output_path = '~/.cache/terminal-sequences'
post_hook = 'tee /dev/pts/[0-9]* < ~/.cache/terminal-sequences'
EOF


{
    printf '\033]10;{{colors.terminal_foreground.default.hex}}\007'
    printf '\033]11;{{colors.terminal_background.default.hex}}\007'


    printf '\033]4;0;{{colors.terminal_normal_black.default.hex}}\007'
    printf '\033]4;1;{{colors.terminal_normal_red.default.hex}}\007'
    printf '\033]4;2;{{colors.terminal_normal_green.default.hex}}\007'
    printf '\033]4;3;{{colors.terminal_normal_yellow.default.hex}}\007'
    printf '\033]4;4;{{colors.terminal_normal_blue.default.hex}}\007'
    printf '\033]4;5;{{colors.terminal_normal_magenta.default.hex}}\007'
    printf '\033]4;6;{{colors.terminal_normal_cyan.default.hex}}\007'
    printf '\033]4;7;{{colors.terminal_normal_white.default.hex}}\007'


    printf '\033]4;8;{{colors.terminal_bright_black.default.hex}}\007'
    printf '\033]4;9;{{colors.terminal_bright_red.default.hex}}\007'
    printf '\033]4;10;{{colors.terminal_bright_green.default.hex}}\007'
    printf '\033]4;11;{{colors.terminal_bright_yellow.default.hex}}\007'
    printf '\033]4;12;{{colors.terminal_bright_blue.default.hex}}\007'
    printf '\033]4;13;{{colors.terminal_bright_magenta.default.hex}}\007'
    printf '\033]4;14;{{colors.terminal_bright_cyan.default.hex}}\007'
    printf '\033]4;15;{{colors.terminal_bright_white.default.hex}}\007'


    printf '\033]19;{{colors.terminal_selection_fg.default.hex}}\007'
    printf '\033]17;{{colors.terminal_selection_bg.default.hex}}\007'
    printf '\033]12;{{colors.terminal_cursor.default.hex}}\007'
} > "$TEMPLATE_PATH"
```

--------------------------------

### Install dependencies on Arch Linux

Source: https://docs.noctalia.dev/noctalia/getting-started/installation

Use pacman to install the required system dependencies for Noctalia on Arch Linux.

```bash
sudo pacman -S meson gcc just \
  wayland wayland-protocols \
  libglvnd freetype2 fontconfig \
  cairo pango harfbuzz \
  libxkbcommon glib2 \
  libsecret libsodium \
  sdbus-cpp libpipewire wireplumber polkit \
  pam curl libwebp libjxl libsndfile librsvg \
  libqalculate libxml2 \
  md4c tomlplusplus \
  nlohmann-json stb \
  jemalloc
```

--------------------------------

### If-else conditional block example

Source: https://docs.noctalia.dev/noctalia/theming/templates?section=data-model

An example of using if-else conditional logic within a template.

```text
<* if {{ loop.first }} *>
first
<* else *>
not first
<* endif *>
```

--------------------------------

### Configure Settings Widget

Source: https://docs.noctalia.dev/noctalia/bar/widgets/settings

Example configuration for the settings widget using a custom image path and enabling colorization.

```toml
[widget.settings]
custom_image = "/path/to/settings.png"
custom_image_colorize = true
```

--------------------------------

### Install wlopm for DPMS

Source: https://docs.noctalia.dev/noctalia/compositor-settings/labwc

Command to install wlopm on Arch Linux.

```bash
sudo pacman -S wlopm
```

--------------------------------

### Split configuration file structure

Source: https://docs.noctalia.dev/noctalia/configuration?section=automatic-configuration-migrations

Example directory layout for organizing configuration across multiple TOML files.

```text
~/.config/noctalia/
├── bar.toml
├── theme.toml
└── widgets.toml
```

--------------------------------

### Install GTK theme packages

Source: https://docs.noctalia.dev/noctalia/templates/official/gtk-qt?section=qt-applications

Commands to install the required adw-gtk-theme and nwg-look packages on Arch Linux or other distributions.

```bash

# Arch Linux / Manjaro
paru -S adw-gtk-theme nwg-look


# Other distributions
# Install adw-gtk-theme and nwg-look from your package manager

```

--------------------------------

### Define plugin entries

Source: https://docs.noctalia.dev/noctalia/plugins/development/manifest

Example of declaring a widget entry with a settings schema and a headless service entry.

```toml
[[widget]]
id    = "hello"
entry = "widget.luau"


  [[widget.setting]]
  key     = "label"
  type    = "string"
  label   = "Label"
  default = "Hello"


[[service]]
id    = "ticker"
entry = "ticker.luau"
```

--------------------------------

### Emerge Noctalia on Gentoo

Source: https://docs.noctalia.dev/noctalia/getting-started/installation

Install the package using the emerge command.

```bash
emerge --ask gui-apps/noctalia
```

--------------------------------

### Configuring Widget Text Styling

Source: https://docs.noctalia.dev/noctalia/desktop/widgets

Example of setting text color and shadow properties for a widget.

```toml
[desktop_widgets.widget.clock_main.settings]
color  = "primary"
shadow = true
```

--------------------------------

### Configure audio_visualizer widget

Source: https://docs.noctalia.dev/noctalia/bar/widgets/audio-visualizer

Example configuration for the audio_visualizer widget within a TOML-based widget definition file.

```toml
[widget.audio-vis]
type       = "audio_visualizer"
width      = 64
bands      = 20
centered   = true
show_when_idle = true
color_1 = "primary"
color_2 = "secondary"
```

--------------------------------

### Install Noctalia on Debian

Source: https://docs.noctalia.dev/noctalia/getting-started/installation

Update package lists and install the noctalia package.

```bash
sudo apt update
sudo apt install noctalia
```

--------------------------------

### Volume Widget Configuration

Source: https://docs.noctalia.dev/noctalia/desktop/widgets?section=sysmon

Example configuration for a volume widget, including positioning and visual settings.

```toml

[desktop_widgets.widget.volume_main]
type     = "volume"
output   = "DP-1"
cx       = 400.0
cy       = 800.0
box_width  = 0.0
box_height = 0.0
rotation = 0.0


[desktop_widgets.widget.volume_main.settings]
device       = "output"
glyph        = ""
fill_color   = "primary"
track_color  = "on_surface_variant"
show_device  = true
scroll_step  = 5
shadow       = true
background   = true

```

--------------------------------

### Configure greeter sync in TOML

Source: https://docs.noctalia.dev/noctalia/configuration/shell

Example configuration for enabling auto-sync and setting a custom privilege command in the shell configuration file.

```toml
[shell.greeter_sync]
auto_sync = true
privilege_command = "ghostty -e pkexec"
```

--------------------------------

### Configure Mango autostart

Source: https://docs.noctalia.dev/noctalia/getting-started/faq?section=configuration

Add this line to your ~/.config/mango/config.conf file.

```text
exec-once=noctalia
```

--------------------------------

### Install Python Pywalfox on Arch Linux

Source: https://docs.noctalia.dev/noctalia/templates/community/firefox

Command to install the legacy Python-based Pywalfox host on Arch Linux or Manjaro.

```bash
# Arch Linux / Manjaro
paru -S python-pywalfox
```

--------------------------------

### Configure desktop widgets in TOML

Source: https://docs.noctalia.dev/noctalia/desktop/widgets

Example configuration for enabling desktop widgets and defining a clock widget with specific coordinates and settings.

```toml
[desktop_widgets]
enabled = true


[desktop_widgets.widget.clock_main]
type     = "clock"
output   = "DP-1"
cx       = 960.0
cy       = 540.0
box_width  = 0.0
box_height = 0.0
rotation = 0.0
flip_x   = false
flip_y   = false


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

--------------------------------

### Configure Launcher Widget

Source: https://docs.noctalia.dev/noctalia/bar/widgets/launcher

Example TOML configuration for the launcher widget, setting a custom glyph and enabling image colorization.

```toml
[widget.launcher]
glyph = "menu-2"
custom_image_colorize = true
```

--------------------------------

### Desktop Widget Configuration Format

Source: https://docs.noctalia.dev/noctalia/desktop/widgets

Example of the base configuration structure for desktop widgets, including the widget order and a clock widget definition.

```toml
[desktop_widgets]
enabled = true
schema_version = 2
widget_order = ["clock_main"]


[desktop_widgets.grid]
visible               = true
cell_size             = 16
major_interval        = 4


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


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

--------------------------------

### custom_button Configuration

Source: https://docs.noctalia.dev/noctalia/bar/widgets/custom-button

Configuration schema and example for the custom_button widget.

```APIDOC
## custom_button Configuration

### Description
The custom_button widget displays a glyph or custom image with an optional label. Actions for mouse events are defined within the widget's action block.

### Settings
- **glyph** (string) - Default: "heart" - Bar glyph name: Noctalia alias, Tabler icon name, or U+/0x codepoint.
- **custom_image** (string) - Default: "" - Path to a custom image displayed instead of the glyph.
- **custom_image_colorize** (bool) - Default: false - When true, tint the custom image with the widget icon color.
- **label** (string) - Default: "" - Optional text label shown next to the glyph or image.
- **tooltip** (string) - Default: "" - Optional hover tooltip.

### Configuration Example
```toml
[widget.quick-action]
type = "custom_button"
custom_image = "/path/to/icon.png"
custom_image_colorize = true
label = "Action"

[widget.quick-action.actions]
left = "exec notify-send Noctalia"
right = "exec notify-send 'Other action'"
```
```

--------------------------------

### Render a desktop widget with ui.*

Source: https://docs.noctalia.dev/noctalia/plugins/development/declarative-ui?section=context-menus

Example of a desktop widget using desktopWidget.render to display a clock and a button. The update function is configured to tick on second boundaries.

```lua
local color = noctalia.getConfig("color")


function update()
  desktopWidget.setWantsSecondTicks(true) -- tick update() on second boundaries
  desktopWidget.render(ui.column({ gap = 10, align = "center" }, {
    ui.label({ text = os.date("%H:%M:%S"), fontSize = 32, fontWeight = "bold", color = color }),
    ui.row({ gap = 8 }, {
      ui.button({ text = "Ping", variant = "primary", onClick = "ping" }),
    }),
  }))
end


function ping()
  noctalia.notify("Desktop widget", "button clicked")
end
```

--------------------------------

### Sysmon Widget Configuration

Source: https://docs.noctalia.dev/noctalia/desktop/widgets?section=sysmon

Example configuration for a system monitor widget, demonstrating both graph and gauge display modes.

```toml

[desktop_widgets.widget.sysmon_main]
type     = "sysmon"
output   = "DP-1"
cx       = 200.0
cy       = 800.0
box_width  = 0.0
box_height = 0.0
rotation = 0.0


[desktop_widgets.widget.sysmon_main.settings]
display        = "graph"
stat           = "cpu_usage"
stat2          = "cpu_temp"
interface      = ""
color          = "primary"
color2         = "secondary"
show_label     = true
shadow         = true
background     = true


# Gauge mode example:
# display         = "gauge"
# gauge_layout    = "horizontal"   # icon | vertical pill | value (row)
# highlight_color = "error"
# label_min_width = 0

```

--------------------------------

### Dispatching Plugin Events

Source: https://docs.noctalia.dev/noctalia/ipc/plugins

Examples of sending events to specific plugin entries using the plugin command family.

```bash
noctalia msg plugin noctalia/screen_recorder:service all toggle
noctalia msg plugin noctalia/screen_recorder:service all start focused
noctalia msg plugin noctalia/example:hello focused set "New label"
```

--------------------------------

### Bind Window Switcher in Hyprland

Source: https://docs.noctalia.dev/noctalia/ipc/shell?section=general

Example configuration for binding the window switcher overlay to a keyboard shortcut in Hyprland.

```lua
hl.bind("ALT + TAB", hl.dsp.exec_cmd("noctalia msg window-switcher"))
```

--------------------------------

### Configure Hjem Module

Source: https://docs.noctalia.dev/noctalia/getting-started/nixos?section=binary-cache

Examples for integrating Noctalia into Hjem using flakes or npins/tarball.

```nix
{ inputs, ... }:
{
  hjem = {
    extraModules = [
      inputs.noctalia.hjemModules.default
    ];


    users.drfoobar = {
      programs.noctalia = {
        enable = true;


        settings = { ... };
      };
    };
  };
}
```

```nix
let
  # see adding the input above
in {
  hjem = {
    extraModules = [
      noctalia.hjemModule
    ];


    users.drfoobar = {
      programs.noctalia = {
        enable = true;


        settings = { ... };
      };
    };
  };
}
```

--------------------------------

### Configure Hyprland autostart

Source: https://docs.noctalia.dev/noctalia/getting-started/faq?section=how-do-i-use-noctalia-colors-with-an-external-wallpaper-app

Add the execution command to your ~/.config/hypr/hyprland.lua file within the hyprland.start event hook.

```lua
hl.on("hyprland.start", function()\n  hl.exec_cmd("noctalia")\nend)
```

--------------------------------

### Configure plugin settings for wallhaven

Source: https://docs.noctalia.dev/noctalia/plugins/development/declarative-ui?section=context-menus

Example configuration block for the noctalia/wallhaven plugin settings.

```toml
[plugin_settings."noctalia/wallhaven"]
browser_placement = "floating"
browser_position = "bottom_left"
```

--------------------------------

### Volume Widget Configuration

Source: https://docs.noctalia.dev/noctalia/desktop/widgets

Example configuration for a volume widget, including positioning and visual settings. Requires PipeWire to function.

```toml
[desktop_widgets.widget.volume_main]
type     = "volume"
output   = "DP-1"
cx       = 400.0
cy       = 800.0
box_width  = 0.0
box_height = 0.0
rotation = 0.0


[desktop_widgets.widget.volume_main.settings]
device       = "output"
glyph        = ""
fill_color   = "primary"
track_color  = "on_surface_variant"
show_device  = true
scroll_step  = 5
shadow       = true
background   = true
```

--------------------------------

### Configure Sway autostart

Source: https://docs.noctalia.dev/noctalia/getting-started/faq?section=configuration

Add this command to your ~/.config/sway/config file.

```bash
exec noctalia
```

--------------------------------

### Build Noctalia from source on Void Linux

Source: https://docs.noctalia.dev/noctalia/getting-started/installation

Steps to build Noctalia using xbps-src, including installing dependencies, cloning the packages tree, and building the package.

```bash
# Install git, wget
sudo xbps-install git wget


# Set up the Void packages tree
git clone --depth 1 https://github.com/void-linux/void-packages.git
cd void-packages
./xbps-src binary-bootstrap


# Copy Noctalia build templates
mkdir srcpkgs/noctalia
wget https://git.voiders.dev/voiders-community/repository/raw/branch/main/pkgs/noctalia/template -P srcpkgs/noctalia/


# Build the packages
./xbps-src pkg noctalia


# Install the built packages
sudo xbps-install --repository=hostdir/binpkgs noctalia
```

--------------------------------

### Volume Widget Configuration

Source: https://docs.noctalia.dev/noctalia/desktop/widgets?section=ipc

Example configuration for a volume widget. Requires PipeWire and supports scroll-based volume control.

```toml

[desktop_widgets.widget.volume_main]
type     = "volume"
output   = "DP-1"
cx       = 400.0
cy       = 800.0
box_width  = 0.0
box_height = 0.0
rotation = 0.0


[desktop_widgets.widget.volume_main.settings]
device       = "output"
glyph        = ""
fill_color   = "primary"
track_color  = "on_surface_variant"
show_device  = true
scroll_step  = 5
shadow       = true
background   = true
```

--------------------------------

### Clock Widget Configuration

Source: https://docs.noctalia.dev/noctalia/desktop/widgets

Example of a complete configuration for a clock widget, including style, format, and visual settings.

```toml
[desktop_widgets.widget.clock_main]
type     = "clock"
output   = "DP-1"
cx       = 960.0
cy       = 540.0
box_width  = 0.0
box_height = 0.0
rotation = 0.0


[desktop_widgets.widget.clock_main.settings]
clock_style = "digital"
format = "{:%H:%M}"
color  = "on_surface"
shadow = true
center_text = false
circle = true
```

--------------------------------

### Configure Template Locations

Source: https://docs.noctalia.dev/noctalia/theming/app-theming?section=built-in-templates

Example configuration for managing templates within dotfiles located in ~/.config/noctalia/*.toml.

```toml

[theme.templates]
enable_builtin_templates   = true
enable_community_templates = true
builtin_ids                = []
community_ids              = []


[theme.templates.user.my_app]
input_path  = "$XDG_CONFIG_HOME/noctalia/templates/my-app.css"
output_path = "$XDG_CONFIG_HOME/my-app/theme.css"

```

--------------------------------

### Emoji Search Example

Source: https://docs.noctalia.dev/noctalia/launcher?section=applications

Example usage of the emoji provider prefix to search for a heart emoji.

```text
/emo heart
```

--------------------------------

### String Filters

Source: https://docs.noctalia.dev/noctalia/theming/templates?section=conditionals

Examples of string manipulation filters including replacement and case conversion.

```liquid

{{ mode | replace: "dark", "night" }}
{{ "surface container high" | snake_case }}

```

--------------------------------

### Volume Widget Configuration Examples

Source: https://docs.noctalia.dev/noctalia/bar/widgets/volume

Configuration blocks for output and input volume widgets in the Noctalia configuration file.

```toml
[widget.volume]
device = "output"   # output | input
glyph = ""          # custom active glyph; empty = built-in dynamic icons
mute_glyph = ""     # custom mute/0% glyph; empty = built-in mute icon
effects_profile_glyphs = { Gaming = "device-gamepad", Music = "music" }
show_label = false
mute_color = "error"


[widget.input-volume]
type = "volume"
device = "input"
hide_when_inactive = true   # input only: hide when no app is capturing audio


[widget.output-volume]
type = "volume"
device = "output"
```

--------------------------------

### Numeric range loop

Source: https://docs.noctalia.dev/noctalia/theming/templates?section=conditionals

Iterating over a numeric range from start to end (exclusive).

```text
<* for i in 0..16 *>
color{{ i }}=...
<* endfor *>
```

--------------------------------

### Define a floating settings panel

Source: https://docs.noctalia.dev/noctalia/plugins/development/declarative-ui?section=context-menus

Example configuration for a floating settings panel with fixed dimensions.

```toml
[[panel]]
id = "settings"
entry = "panel.luau"
width = 420
height = 410
placement = "floating"
position = "center"
open_near_click = false
```