qs-network-widget

Status: alpha. This is early, untested code under active development. Expect breakage, missing features and breaking changes without notice. Nothing here is ready for a production desktop.

A Quickshell (Qt6 / QML) network control panel that opens from the Waybar network module as a flyout menu. It is built specifically for Hyprland-Dots and depends on that project's layout, theming pipeline and helper scripts. It is not a general-purpose standalone widget and is not packaged or supported outside that setup.

What it does

• Wi-Fi
  • Lists available wireless networks with signal strength.
  • Connects to a network from the list.
  • Marks the network currently in use.
• Bluetooth
  • Lists paired devices.
  • Shows connection state, signal strength (RSSI) and battery level where BlueZ reports them.
  • Connects and disconnects devices.
• Radio control
  • Wi-Fi on/off and Bluetooth on/off toggles.
  • Airplane mode, which soft-blocks all radios through rfkill.
• Throughput graphs
  • Live read/write (RX/TX) rate display for the active interfaces.
• Theming
  • Colours are pulled from the wallust palette generated by Hyprland-Dots, so the panel follows the current wallpaper like the rest of the desktop.

Repository layout

• src/quickshell/ — the widget itself: QML components, services and the colour/theme loader.
• src/wallust/ — wallust template and config used to emit the palette the widget reads.
• template/ — early LLM-generated sketches kept as a design reference only. This code is not tested and not wired up. It was generated without any knowledge of the Hyprland-Dots layout, so treat it as a rough sketch of the UI, not as a starting point.
  • It does not implement the full feature set. Some intended behaviour is missing entirely, and some that is present is wrong.
  • The real implementation in src/ supersedes it and is expected to diverge heavily. Do not extend template/; read it, then write real code in src/.

Requirements

• Quickshell (Qt6 / QML)
• NetworkManager (nmcli)
• BlueZ (bluetoothctl)
• rfkill
• wallust, driven by Hyprland-Dots
• A Waybar configuration with a module that launches this panel

Installation

There is no installer yet, and installation is not a single step: the widget has to be registered with the Hyprland-Dots wallust setup before it will be themed. See Theming below.

Installation instructions will be added once the widget reaches a usable state.

Theming

Colours come from wallust rather than being hardcoded, so the panel follows the current wallpaper like the rest of the desktop.

Hyprland-Dots selects its wallust config by version, so registering the widget means adding its [templates] block to both configs. Adding it to only one leaves the panel themeless for whichever wallust version is installed:

• ~/.config/hypr/wallust/wallust.toml (wallust v3)
• ~/.config/hypr/wallust/wallust-v4.toml (wallust v4)

The template file itself also has to be installed into the templates directory that Hyprland-Dots passes to wallust, because that directory is what wallust searches:

colors-qs-network.json  ->  ~/.config/hypr/wallust/templates/

Both files are in this repository under template/wallust/. The palette is written to ~/.config/quickshell/qs-network-colors.json, alongside the Quickshell palette Hyprland-Dots already generates for the rest of its shell. When wallust regenerates it, the panel reloads it without a restart.

Contributing

This project is a companion to Hyprland-Dots, and changes here usually need to line up with changes there. Before opening a pull request, read AGENTS.md in this repository: it covers the shell conventions, branch target, changelog format and commit-message style used across both projects.

License

GNU General Public License v3.0. See LICENSE.

Links

• Hyprland-Dots: https://github.com/LinuxBeginnings/Hyprland-Dots
• Quickshell: https://quickshell.org/