Official plugins

These ship from the default official source (github.com/noctalia-dev/official-plugins). Each is installed and enabled like any other plugin - see Using Plugins. Once enabled, an entry can be driven over IPC:

Terminal window

noctalia msg plugin <author/plugin:entry> <target> <event> [payload]

<target> selects which live instances receive the event:

• focused - the entry on the focused output (bar widgets)
• <connector> or <connector>:<bar-name> - a specific output / bar
• all - every instance; also how you address a [[service]], since a service is a singleton with no output

Example

Section titled “Example” noctalia/example

A reference plugin that exercises every entry kind: a bar widget , a headless service (ticks once a second and publishes to the plugin’s state channel), a control-center shortcut , a launcher provider behind the /ex prefix, and a panel of interactive controls (toggle, slider, text input, select). The panel defaults to floating at center ; change placement under Settings → Plugins. Good starting point for reading real code.

Screen Recorder

Section titled “Screen Recorder” noctalia/screen_recorder

Screen recording and a replay buffer via gpu-screen-recorder (must be installed, natively or as the Flatpak). The recording logic lives in a headless service that runs for the whole session, so it works with no bar widget placed - the widget and control-center shortcut are thin clients. Options (codec, quality, output folder, replay buffer, …) are plugin-level settings, edited under Settings → Plugins.

The service is a singleton, so address it with all :

start and replay-start take an optional payload - focused, portal, or region - that overrides the video_source setting for that capture (any other value falls back to the configured source). The target (all) and the capture source are separate fields:

Translator

Section titled “Translator” noctalia/translator

Translate text straight from the launcher via Google Translate. A launcher provider behind the /tr prefix - type /tr <lang> <text> (e.g. /tr es hello world) and press Enter on a result to copy the translation. If the first word isn’t a language, the whole query is translated to the default target language (a plugin setting, default en). Language can be a code (fr) or a name (french, français).

Timer

Section titled “Timer” noctalia/timer

A countdown timer desktop widget with start/pause and reset buttons and a progress bar. Add it from the desktop-widgets editor (it appears in the type picker once the plugin is enabled). Also the reference implementation for the declarative ui.* desktop-widget API - see Declarative UI.

Settings: countdown duration, accent color, and progress-bar visibility.

Bongo Cat

Section titled “Bongo Cat” noctalia/bongocat

A bar cat that taps along to input events (via evtest) or to the audio spectrum. Single bar widget.

For input reactivity, set input_devices to one or more evdev paths or glob patterns. Prefer stable symlinks such as /dev/input/by-id/*-event-* or /dev/input/by-path/*-event-*; /dev/input/eventN paths can change after kernel or device updates.

Wallhaven

Section titled “Wallhaven” noctalia/wallhaven

Browse Wallhaven, download a wallpaper into your configured wallpaper directory, and apply it to all monitors. A panel browser (browser) with tag search, category/purity/sort filters, and a thumbnail grid, plus a bar widget (wallhaven) that toggles the panel. The browser panel defaults to attached at the bar; placement is configurable under Settings → Plugins (floating + screen position, open-near-click, etc.).

Requires network access ([shell].offline_mode must be off). NSFW results require a Wallhaven API key (plugin setting).

Video Wallpaper

Section titled “Video Wallpaper” noctalia/mpvpaper

Animated and video wallpapers via mpvpaper. A headless service supervises one mpvpaper instance per output; a panel (picker) browses your video directory as a thumbnail grid and applies a video per output (or to all); a bar widget (mpvpaper) toggles the panel. When a video is assigned to an output, Noctalia drops its own wallpaper surface there so the video shows through - the bar and dock still draw above it. Assignments persist across restarts.

Requires the external mpvpaper command (which pulls in mpv; mpv also renders the picker thumbnails). Works on wlr-layer-shell compositors (Niri, Hyprland, Sway, Mango). Supported files: mp4, webm, mkv, mov, gif.