Skip to content
ArchEclipse

Common pages

↑↓to navigate↵to openescto close
Widgets
On this page

Configuration

Widgets

The bar modules, expandable islands, left and right panel tabs, and the launcher's query modes.

The Quickshell shell is assembled from widgets around one bar per monitor. Most widgets are small QML files under ~/.config/quickshell/archeclipse/widgets/; state lives in services/ singletons and settings come from theme/Settings.qml.

Bar modules#

The default bar is defined in widgets/bar/DefaultBar.qml. It draws the central pill and its cells:

ModuleFileShows
WorkspacesWorkspaces.qmlWorkspace indicators and occupancy
Window titleWindowTitle.qmlActive window title
MediaMediaPill.qmlCurrent player and playback state
TrayTray.qmlStatusNotifier tray items
NetworkNetworkWidget.qmlConnectivity and bandwidth
VolumeVolume.qmlSink volume and mute
BrightnessBrightness.qmlBacklight/DDC brightness
BatteryBattery.qmlBattery state, when a battery exists
ClockClock.qmlDate and time using the configured format
BandwidthBandwidth.qmlNetwork throughput
Resource monitorResourceMonitor.qmlCPU/GPU/memory sampling

The bar also includes hot zones, side pills, the control card and expandable islands:

IslandPurpose
SearchIslandLauncher surface
OverviewIslandWorkspace/window overview (SUPER + SHIFT + TAB)
WallpaperIslandWallpaper picker (SUPER + W)
PlayerIslandMedia controls
WeatherIslandWeather details
SystemMonitorIslandDetailed resource view
OsdIslandVolume/brightness feedback
ScreenshotIslandScreenshot and area-capture actions
RecordingIslandRecording state and stop control
ControlCardQuick controls inside the default bar
LeftIsland / RightIslandPanel hosts for the side tabs

Islands expand in place with a clip/fade animation. Hover behaviour uses a dwell threshold (revealInPressure) and a close delay (revealOutPressure). See Bar for the state machine and IPC.

Left panel tabs#

The left panel is a StackLayout of lazy-loaded tabs, in this fixed order:

  1. UserProfile — avatar, identity, repo statistics and version information.
  2. BooruViewer — image board browser with configurable tags and sources.
  3. ChatBot — OpenRouter-backed chat with optional context from the active workspace, window, clipboard and file.
  4. MangaViewer — MangaDex/MangaLib reader. Upstream marks it WIP.
  5. SettingsWidget — the Settings panel.
  6. CustomScripts — one-click utility actions.
  7. KeyBinds — live list generated from the Hyprland configuration.
  8. Donations — supporter and donation information.

Tabs are created on first selection and then kept alive. The last selected tab is persisted in settings.

Custom scripts#

The Custom Scripts tab is a list of utility actions rather than arbitrary shell scripts. Entries include restarting the bar, launching Hyprpicker, opening nwg-displays for resolution changes, updating packages, clearing the clipboard, toggling recording and opening common apps. Entries that need a missing binary offer to install it. The definitions live in widgets/leftPanel/CustomScriptsWidget.qml.

Right panel widgets#

The right panel renders only the widgets listed in Settings.rightPanelWidgets. The canonical set is:

WidgetContents
WaifuRandom wallpaper/image viewer
MediaPlayer controls, progress and lyrics
NotificationHistoryPast notifications
CalendarMonth view and events
SystemResourcesLive CPU, memory, GPU and temperature

Drag the widget selector inside the right panel to reorder them, or use the visibility controls to disable one. The order and enabled flags persist; icons come from code, so saved files only store names, order and enabled state. Unknown names are dropped on load.

Right panel

Launcher#

The launcher's query pipeline is in services/Launcher.qml. Opening it with no query shows recent apps and quick actions. Recognized prefixes and inputs:

InputResult
plain textFuzzy app search, then suggestions
>helpList every query mode
>quickappsFavourite apps; >quickapps term filters
>recentRecently launched apps
>commandsSystem commands
appsEvery installed application
cb <text>Clipboard history (text, HTML, images)
note <text>Add a note; note lists notes
emoji <text>Search the bundled emoji index
term <command>Run a command in foot
app --argLaunch an app with arguments
hello > esTranslate text (translate-shell)
example.comOpen a URL
2+2Arithmetic
100c to fUnit conversion

Notes and launch history are stored under ~/.cache/quickshell/launcher/. Clipboard history is owned by ClipboardService, which runs wl-paste --watch and stores images under ~/.cache/quickshell/launcher/clipboard-images/.

Adding a widget#

Widgets are ordinary QML modules. Adding one is a code change, not a settings change:

  1. Add the .qml file under the appropriate module directory.
  2. Register it in that directory's qmldir, or import qs.<module> will not see it.
  3. If it belongs in the right panel, add the canonical name and icon to Settings.defaultRightPanelWidgets() and render it in RightIsland.qml. Only the five names above are currently accepted.
  4. For a left-panel tab, add it to LeftIsland.qml's tabOrder and to the IPC validator in services/Ipc.qml.

The shell has no build step; restart the bar with SUPER + B or lua ~/.config/hypr/config/scripts/bar.lua after editing QML.