Repository navigation
Settings App
Almost everything in the shell is configurable from one window: Settings. It is a normal floating window (a Quickshell FloatingWindow, titled illogical-impulse Settings), not a layer, so you can move it, resize it, tile it or put it on its own workspace. It is a hub of 37 pages in six groups, a search box that finds individual options, deep links so other parts of the shell (and the Welcome App) can land you exactly on the right section, and a navigation history with back / forward.
| How | What |
|---|---|
| Super + I | Toggle Settings (quickshell:settingsToggle) |
qs -c ii ipc call settings toggle / open
|
Toggle / open |
qs -c ii ipc call settings openPage <pageId> |
Open a page, e.g. network
|
qs -c ii ipc call settings openSubPage <pageId> <subPage> |
Open a page and one of its sub-pages |
qs -c ii ipc call settings openSection <pageId> "<section title>" |
Open a page and scroll to / highlight a section |
| A settings button anywhere in the shell | Most widgets, popups, dialogs and the Welcome have a gear or "Open settings" link that is a deep link into the right page |
A deep link is validated against SettingsPageRegistry: unknown page ids are ignored, and a link to the page you're already looking at still scrolls to and highlights the section. The target can be a page, a sub-page (a nested page inside it) and a section title to flash.
- Top row — your user header (name and avatar; click it to open the User Profile page, which is not in the sidebar) and the search bar.
-
Sidebar — the pages grouped under collapsible headers. Whether a group is collapsed is remembered between sessions (
Persistent.states.settings.collapsedGroups). -
Content — the page, with a skeleton while it loads. If your
config.jsonwas malformed or had to be repaired on start, a health banner appears at the top of the window with what happened (a successful migration is silent). It comes back for every new problem even if you dismissed an earlier one.
| Group | Pages |
|---|---|
| Look & Feel | Colors & Themes · Bar · Interface & Fonts · Presets |
| Modules | Tablet · Sidebars · Dock · Dynamic Island |
| Desktop & Windows | Background · Workspaces · Overview · Windows · Tiling · Lock Screen · Widgets |
| Tools | Launcher · Dictation · Screen Capture · Notifications · Overlays & OSD · Modes · Cheat Sheet |
| Services & Integrations | Media & Music · Language & Time · Weather · AI Assistant · Tasks & Accounts |
| System | Displays · Hyprland · Network · Sound & Alerts · Touch Gestures · Power · Devices & Phone · Usage Stats · Privacy & Content · About & Updates |
Three more pages exist but have no sidebar entry: User Profile (the header), Clipboard (reached through the Launcher page and by deep link) and Search Results.
Pages that only make sense for some panel families are hidden for the others — Tablet only appears in the tablet family, while Dock, Dynamic Island, Modes, Cheat Sheet and Tiling apply to ii and waffle only. A group whose pages are all unavailable disappears too. The family itself is chosen in Interface & Fonts.
A page is a vertical list of sections. Where a feature has many options, the page shows a row with an icon, a title and a one-line description; clicking it slides in a sub-page over the page (the page cross-fades behind it) and a back button returns. Examples: Bar → Clock widget, Weather bar widget, System tray, Port watcher; Background → Parallax, Video wallpaper; Colors → OpenRGB, Wallpaper Engine; Presets → Publish, Preset detail, Diff. Sub-pages can nest (Google Drive → Advanced Drive), and the nesting is part of the history.
Features that can be turned off generally have a master switch at the top of their sub-page — flipping it off greys out the options beneath instead of hiding them, so you can still see what the feature does.
The search box finds options, not only pages. Typing builds an index of every page's sections the first time you search in a session (the index is dropped again when Settings closes to save memory); Enter opens a Search Results page listing matches with the page they come from, and clicking one jumps to the page (and sub-page) and highlights the section. Matching uses the section titles, the option labels, and each page's aliases — the registry lists synonyms such as "Waffle", "Wallpaper Engine", "Right-click menu" or "Switch shell" so a search finds the right page even when it uses different words. Pages drawn with tiles and live previews are indexed through dedicated search sources rather than their own file.
- Mouse back / forward buttons (side buttons) walk a session history: pages and the open sub-page, including nested ones. The history is capped at 10 entries and is never saved — it starts empty each time Settings opens.
- Ctrl + Page Down / Page Up — next / previous sidebar page, stopping at the ends. Ctrl + Tab / Ctrl + Shift + Tab cycle through the pages and wrap around. Hidden pages are skipped.
Settings is the biggest single window in the shell, so it is built to cost nothing while closed and little while open.
-
Unloaded on close. By default (
appearance.settingsUnloadDelay: 0) the whole window is freed when you close it. Set a number of seconds to keep it alive that long (a quick reopen then just shows the hidden window), or-1to never unload it — faster reopen for more memory. - Pre-compiled. Fifteen seconds after the shell starts, Settings and every page are compiled asynchronously (no objects are created), which removes the slow first open and the slow first visit to each page.
- Pages load on demand and progressively. Only the current page exists; its sections load in order as they approach the viewport, with skeleton placeholders reserving their height, and sections that a search hit points to are prioritised.
-
Settings performance mode (
appearance.settingsPerformanceMode, on by default; Interface & Fonts) turns off the decorative scroll fade and several effects inside Settings. Turn it off for the full look if your GPU is fine with it. - Screenshots of the screen hide Settings temporarily while the capture runs, so it doesn't end up in your screenshot.
| Key | Default | Meaning |
|---|---|---|
appearance.settingsPerformanceMode |
true |
Cheaper rendering inside Settings |
appearance.settingsUnloadDelay |
0 |
Seconds Settings stays loaded after closing; -1 = never unload |
Which settings exist, with defaults, is documented in Configuration Reference; everything is stored in ~/.config/illogical-impulse/config.json.
| Piece | Role |
|---|---|
SettingsWindow.qml |
The window, page loader, history, keyboard shortcuts, deep-link handling |
shell.qml (settingsLoader) |
Loads / unloads the window, warm-up compile, garbage collection after close |
modules/common/SettingsPageRegistry.qml |
Pages, groups, sub-pages, aliases, family filter, hidden pages |
modules/settings/ |
Sidebar, UserHeader, SearchBar, ConfigHealthBanner, page skeleton |
modules/settings/configs/ |
One *Config.qml per page plus widgets/, sections/ and per-feature folders |
modules/common/widgets/ConfigSubPageHost.qml, SubPageEntryButton.qml, ProgressiveSectionLoader.qml
|
Sub-page sliding, entry rows, lazy sections |
services/SearchRegistry.qml |
The option index and scoring |
GlobalStates.qml |
settingsOpen, pending page / sub-page / section, the settings IPC target |