Noctalia

https://docs.noctalia.dev/noctalia
Admin
Noctalia is a minimal and highly customizable desktop shell for Wayland compositors, providing bars,...
Tokens:313,041
Snippets:3,143
Trust Score:5
Update:1 month ago
Show doc for...
Tokens:
Raw
### 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;
  };
}
```

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

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

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

### 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)))
```

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

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

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

### 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 *>
```

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

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

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

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

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

### Enable greetd

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

Enable and start the greetd service.

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

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

### 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 }}
```

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

### 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 }}
```

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

### 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 }}'
```

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

### 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 *>
```

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

### 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 }}

```

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

### Accessing Terminal Color Tokens

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

Examples of how to access terminal background and normal red color tokens using hex and rgb formats.

```text

{{ colors.terminal_background.default.hex }}
{{ colors.terminal_normal_red.default.rgb }}

```

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

### Numeric Ranges

Source: https://docs.noctalia.dev/noctalia/theming/templates?section=color-argument-filters

Examples of using numeric ranges for loops, including positive and negative values.

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

```text
<* for i in -2..3 *>
offset={{ i }}
<* endfor *>
```

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

### Iterating Over Colors

Source: https://docs.noctalia.dev/noctalia/theming/templates?section=color-argument-filters

Examples of iterating over the colors map using key-value destructuring or single variable binding.

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

```text
<* for name in colors *>
{{ name }}
<* endfor *>
```

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

### Color-Argument Filters

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

Examples of filters that accept another color as an argument for blending, harmonization, or reinterpretation.

```liquid

{{ colors.primary.default.hex | blend: "#ff0000", 0.5 }}
{{ colors.primary.default.hex | harmonize: "#00ff88" }}
{{ "#ffaa00" | to_color | darken 10 }}

```

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

### 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 wlopm for DPMS

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

Command to install wlopm on Arch Linux.

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

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

### 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()
```

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

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

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

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

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

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

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

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

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

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

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

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

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

### 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/...
```

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

### 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)
```

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

### 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,
}
```

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

### 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
```
Tokens:
Raw