# Quickshell Window Switcher
### The ultimate Hyprland Overview
A modern, fluid, and highly customizable **Window Switcher (Exposé)** for **Hyprland**, built entirely in QML using the [Quickshell](https://github.com/outfoxxed/quickshell) framework.
It provides a native Wayland experience similar to macOS Mission Control or GNOME Activities, featuring a suite of advanced mathematical layouts designed to visualize your windows beautifully on any screen size.
## 📸 Gallery
See `qs-hyprview` in action with its different layout algorithms.
| | | |
| :---: | :---: | :---: |
| 
**Smart Grid** | 
**Bands** | 
**Masonry** |
| 
**Hero** | 
**Spiral** | 
**Satellite** |
| 
**Vortex** | 
**Staggered** | **What's next?** |
## ✨ Features
* **⚡ Native Performance:** Built on Qt6/QML and Wayland Layershell for zero latency and smooth 60fps animations.
* **🧮 10 Layout Algorithms:** A collection of layouts ranging from productive grids to scenic orbital views.
* **🔍 Instant Search:** Filter windows by title, class, or app name immediately upon typing.
* **🎮 Full Navigation:** Supports both Keyboard (Arrows/Tab/Enter) and Mouse (Hover/Click).
* **🎨 Smart Safe Area:** All layouts calculate a 90% "Safe Area" to ensure hover animations never clip against screen edges.
* **⚙️ Live Thumbnails:** Live window contents via Hyprland screencopy.
* **💐 Matugen Integration:** allows you to change the layout color to match your desktop.
## 🛠️ Dependencies
* **Hyprland**: The Wayland compositor.
* **Quickshell**: The QML shell framework.
* **Qt6**: Core libraries (usually pulled in by Quickshell).
## 🚀 Installation
1. Clone this repository:
```bash
git clone https://github.com/dom0/qs-hyprview.git
```
2. Ensure `quickshell` is installed and in your PATH.
## ⚙️ Configuration & Usage
### Launching
To start the daemon (add this to your `hyprland.conf` with `exec-once`):
```bash
quickshell -p /path/to/cloned/repo
# Or clone into $XDG_CONFIG_HOME/quickshell (usually ~/.config/quickshell) and run with -c flag:
quickshell -c qs-hyprview
```
### Toggle (Open/Close)
The project exposes an IPC handler named `expose`. You can bind a key in Hyprland to toggle the view.
**In `hyprland.conf`:**
```ini
# "smartgrid", "justified", "masonry", "bands", "hero", "spiral"
# "satellite", "staggered", "columnar", "vortex", "random"
$layout = 'masonry'
# Toggle overview visibility
bind = $mainMod, TAB, exec, quickshell ipc -p /path/to/cloned/repo call expose toggle $layout
# Open overview
bind = $mainMod, TAB, exec, quickshell ipc -p /path/to/cloned/repo call expose open $layout
# Close overview
bind = $mainMod, TAB, exec, quickshell ipc -p /path/to/cloned/repo call expose close
# Or, using XDG_CONFIG_HOME:
#bind = $mainMod, TAB, exec, quickshell ipc -c qs-hyprview call expose toggle $layout
#bind = $mainMod, TAB, exec, quickshell ipc -c qs-hyprview call expose open $layout
#bind = $mainMod, TAB, exec, quickshell ipc -c qs-hyprview call expose close
```
### Visual optimizations
You can optimize your experience by adding an opaque/blurred background (dimming area) or pop-in animations using native Hyprland features.
**In `hyprland.conf`:**
```ini
# dimming area
decoration {
dim_around = 0.8
}
layerrule = dimaround, quickshell:expose
```
```ini
# blur area
decoration {
blur {
enabled = true
size = 3
passes = 1
}
}
layerrule = blur, quickshell:expose
```
```ini
# popin animation
animations {
enabled = yes
animation = layersIn, 1, 1.5, default, popin
}
```
### Customization
You can modify the core properties at the top of `shell.qml`:
```qml
// Set to true for live window updates (monitor refresh rate, higher CPU usage), false for static snapshots (~8fps)
property bool liveCapture: false
// Automatically move mouse cursor to the center of selected window
property bool moveCursorToActiveWindow: true
```
## 🎨 Matugen Dynamic Colorscheme From Wallpaper
### Manual Configuration
If you don't want to use Matugen, you can simply edit common/Appearance.qml and change the hexadecimal values to match your color of choice (mainly m3Primary and m3OnPrimary).
### Dynamic Colors (Matugen)
1. Copy the template (qs-hyprspace-template.qml) from this repo to matugen's templates folder
2. Add the following to your ~/.config/matugen/config.toml:
```
[templates.qs-hyprview]
input_path = "~/.config/matugen/templates/qs-hyprview-template.qml"
output_path = "~/.config/quickshell/qs-hyprview/common/Appearance.qml"
```
3. Generate your colorscheme:
```
matugen image /path/to/your/wallpaper
```
## 📐 Layout Algorithms
This project includes a sophisticated `LayoutsManager` offering **10 distinct algorithms**:
### 1. Smart Grid (`smartgrid`)
The default layout. It uses an **Iterative Best-Fit** algorithm. It simulates every possible row/column combination to find the exact grid configuration that results in the largest possible thumbnails without overflowing the screen.
### 2. Justified (`justified`)
A **Justified Layout** (similar to Google Images). It places windows in rows, maintaining fixed height and original aspect ratios, and scales the row to fit the screen width perfectly.
### 3. Masonry (`masonry`)
A **Waterfall** layout (Pinterest-style). It optimizes vertical space by placing windows in dynamic columns. It automatically calculates the optimal number of columns based on the window count.
### 4. Bands (`bands`)
Organizes windows by **Workspace**. Creates a horizontal "Band" for each active workspace, grouping relevant tasks together. Windows are justified within their workspace band.
### 5. Hero (`hero`)
A focus-centric layout.
* **Hero Area:** The active window takes up 40% of the screen (left side).
* **Stack:** All other windows share the remaining 60% (right side) in a smart grid or column.
### 6. Spiral (`spiral`)
A scenic layout based on the **Golden Ratio (BSP)**.
* Windows split the screen in a spiral pattern (Left half, Top-Right half, etc.).
* The first window is separated by a larger gap to emphasize focus.
* If many windows are open, the spiral stops after 3 cuts and arranges the rest in a grid.
### 7. Satellite (`satellite`)
An **Orbital** layout.
* The active window sits in the center of the screen.
* All other windows orbit around it in an ellipse.
* Visually stunning and great for focusing on one task while keeping an eye on the surroundings.
### 8. Staggered (`staggered`)
A **Honeycomb/Brick** layout.
* Similar to a grid, but every odd row is shifted horizontally by half a cell width.
* Creates a more organic, less rigid look compared to standard grids.
### 9. Columnar (`columnar`)
Divides the screen into vertical strips.
* Ignores rows completely and gives every window maximum vertical space.
* Excellent for **Ultrawide** monitors (21:9 / 32:9).
### 10. Vortex (`vortex`)
A depth-based Phyllotaxis layout (Sunflower pattern), designed for a scenographic and immersive experience.
* Center Focus: The active window sits in the absolute center at maximum scale.
* Depth Effect: Subsequent windows spiral outwards, gradually decreasing in size and z-index. This creates a 3D "tunnel" effect where older windows fade into the background.
### 🎲 Random (`random`)
Feeling adventurous? This mode selects one of the above algorithms at random every time you open the dashboard.
## ⌨️ Controls
| Input | Action |
| :--- | :--- |
| **Typing** | Instantly filters windows by Title, Class, or App ID |
| **Arrows (↑ ↓ ← →)** | Spatial navigation between thumbnails |
| Ctrl + (H/J/K/L) | Vim-style spatial navigation |
| **Tab / Shift+Tab** | Sequential navigation |
| **Enter** | Activate selected window |
| **Middle Click** | Close hovered window |
| **Esc / Click BG** | Close dashboard |
## 🤝 Contributing
Pull Requests are welcome! If you want to add a new layout algorithm or improve performance, please open an issue or submit a PR.
## 📄 License
Distributed under the GNU General Public License v3.0. See `LICENSE` for more information.
---
Made with ❤️ for the Hyprland community