hyprview

hyprview is a Hyprland plugin that provides a window overview with multiple placement algorithms. It can display windows from the current workspace, all workspaces on a monitor, or include special workspaces, organizing them using various layout algorithms for easy navigation.

The plugin includes six different placement algorithms to suit different preferences:

• grid (default): Efficient dynamic grid that adapts to window count and screen aspect ratio, packing windows without wasted space.

• spiral: Arranges windows in a spiral pattern starting from the center, creating a unique and balanced layout.

• flow: Proportional row-based layout that maintains relative window sizes and distributes them evenly across rows to avoid bunching small or large windows together.

• adaptive: Individual scaling with visual hierarchy - maintains each window's aspect ratio while applying subtle size variations (larger windows scaled down slightly, smaller windows boosted) for a dynamic, organic layout.

• wide: Wide horizontal grid with uniform tile sizes, prioritizing more columns and fewer rows with generous spacing between tiles.

• scale: A clone of the Wayfire scale plugin that enlarges the center window.

hyprview.mp4

Features

• Fullscreen Windows: Include fullscreen windows and restore their original fullscreen modes and workspaces when dismissing the overview.
• Optional Fullscreen Selection: Enable fullscreen_on_select to make an explicitly selected window fullscreen.
• Workspace Overview: See all your open windows on the current workspace at a glance.
• Multi-Workspace Modes: View windows from the current workspace, all workspaces on the monitor, or include special (scratchpad) workspaces.
• Workspace Indicator: Each window tile shows its workspace ID (displayed as "wsid:N") in a configurable position with customizable size and styling. The indicator color automatically matches the window's border color (active or inactive) for easy navigation across multiple workspaces.
• Window Selection: Hover to focus and click to select a window, automatically closing the overview.
• Trackpad Gestures: Use swipe gestures to open and close the overview.
• Gesture Conflict Prevention: Blocks workspace gestures in legacy configurations. Lua configurations retain their configured gesture callbacks while the overview is open.
• Smooth Animations: Animated transitions when opening/closing the overview.
• Multi-monitor Support: Provides a separate overview for each monitor with proper scaling and positioning.
• Customizable Appearance: Change colors, borders, margins, background dimming, and radii.
• Active Window Highlighting: Distinguished border color for the currently focused window.
• Background Dimming: Configurable dark overlay when overview is active for clear visual distinction.
• Centered Grid Layout: Window grid is centered on screen for balanced visual appearance.
• Focus Restoration: Properly restores window focus when closing the overview.

Install with hyprpm

hyprpm add https://github.com/yz778/hyprview
hyprpm enable hyprview

Manual install

1. Clone this repository
2. Build the plugin: make -C src all
3. Add plugin to your hyprland.conf

plugin = /full_path_to/hyprview.so

Lua configuration (Hyprland 0.56)

Load the plugin before invoking its callbacks. The plugin registers settings with Hyprland's typed configuration API and exposes hl.plugin.hyprview.toggle(args). It accepts the same arguments as the hyprview:toggle dispatcher and returns success, error. Call it inside a gesture or binding callback, after loading:

hl.gesture({ fingers = 3, direction = "up", action = function()
  if hl.plugin.hyprview then
    hl.plugin.hyprview.toggle("on all special")
  end
end })
hl.gesture({ fingers = 3, direction = "down", action = function()
  if hl.plugin.hyprview then
    hl.plugin.hyprview.toggle("off")
  end
end })

An explicit off closes an overview opened with on; add monitor:NAME to close only that monitor. Lua gestures remain enabled while the overview is open, so a downward callback can close it. Avoid assigning competing workspace gestures to the same fingers/direction. Legacy hyprview-gesture remains available in hyprland.conf.

Fullscreen selection

By default, selecting a preview retains its previous fullscreen state. The existing sticky on mode also retains its behavior of focusing a preview without closing. To make a left-click or explicit selection close the overview and make the chosen window fullscreen, opt in:

-- Apply after the plugin is loaded (or in the config reload following its load).
hl.config({ plugin = { hyprview = { fullscreen_on_select = 1 } } })

For legacy configuration:

plugin:hyprview:fullscreen_on_select = 1

The default is 0. A downward gesture or off without a selection restores the original window states regardless of this setting. With the option enabled, clicking a preview also exits sticky on mode. Empty background clicks are ignored.

Keybinds

You can bind the overview to a key. The dispatcher accepts optional arguments to control the behavior.

# Toggle overview, show windows from current workspace only (default)
bind = SUPER, H, hyprview:toggle

# Toggle overview, show windows from all workspaces
bind = SUPER, H, hyprview:toggle, all

# Toggle overview, show windows from all workspaces including special workspaces
bind = SUPER, S, hyprview:toggle, all special

# Close the overview
bind = SUPER, ESC, hyprview:toggle, off

# Toggle overview with different placement algorithms
bind = SUPER, G, hyprview:toggle, placement:spiral
bind = SUPER, T, hyprview:toggle, placement:flow
bind = SUPER, A, hyprview:toggle, placement:adaptive
bind = SUPER, W, hyprview:toggle, placement:wide
bind = SUPER, F, hyprview:toggle, placement:scale

Dispatchers

hyprview:toggle

The hyprview dispatcher uses a flexible argument format: hyprview:<action>[,<mode>].

• <action> (required): toggle
• <mode> (optional): A comma-separated list of keywords to define which windows to display.
  • on: Turn overview on
  • off: Turn overview off
  • all: Show windows from all workspaces on the monitor.
  • special: Include windows from the special (scratchpad) workspace.
  • placement:<algorithm>: Select the placement algorithm. Available algorithms:
    • placement:grid (default): Efficient dynamic grid
    • placement:spiral: Spiral pattern from center
    • placement:flow: Proportional row-based flow
    • placement:adaptive: Individual scaling with hierarchy
    • placement:wide: Wide horizontal uniform grid
    • placement:scale: Center-focused scale (like Wayfire's scale)
  • Combining them (e.g., all special placement:flow) works as expected.

Gestures

You can configure a trackpad gesture to control the overview.

# hyprland.conf

# 3-finger swipe up/down to toggle the overview
hyprview-gesture = 3,vertical,toggle

# To remove a gesture
hyprview-gesture = 3,down,unset

The syntax is hyprview-gesture = <fingers>,<direction>[,mod:<modmask>][,scale:<scale>],<action>.

• <fingers>: Number of fingers (e.g., 3).
• <direction>: up, down, left, right.
• [mod:<modmask>]: Optional modifier keys (e.g., mod:SUPER).
• [scale:<scale>]: Optional gesture scale factor.
• <action>:
  • toggle: Toggles the overview.
  • unset: Removes the gesture.

Customization

You can customize the appearance and behavior of the overview by setting the following variables in your hyprland.conf:

Variable	Type	Description	Default
plugin:hyprview:active_border_color	int (hex)	Border color for the currently focused window. Also used for workspace ID text in active window labels.	0xFFCA7815
plugin:hyprview:bg_dim	float	Opacity of the background dim overlay (0.0 = no dim, 1.0 = fully black).	0.4
plugin:hyprview:border_radius	int	Radius of window borders in pixels.	5
plugin:hyprview:border_width	int	Width of window borders in pixels.	5
plugin:hyprview:gesture_distance	int	The swipe distance required for the gesture.	200
plugin:hyprview:inactive_border_color	int (hex)	Border color for inactive windows. Also used for workspace ID text in inactive window labels.	0x88c0c0c0
plugin:hyprview:margin	int	Margin around each grid tile.	10
plugin:hyprview:workspace_indicator_enabled	int	Show workspace ID in window labels (0 = disabled, 1 = enabled).	1
plugin:hyprview:window_name_enabled	int	Show window info centered on bottom border as [wsid] class • title (0 = disabled, 1 = enabled). When enabled, replaces the old workspace indicator overlay.	1
plugin:hyprview:window_name_font_size	int	Font size for window labels in points.	20
plugin:hyprview:window_name_bg_opacity	float	Opacity of the window label background (0.0 = transparent, 1.0 = opaque).	0.85
plugin:hyprview:window_text_color	int (hex)	Color for window class and title text in labels (format: 0xRRGGBBAA).	0xFFFFFFFF (white)

Deprecated Settings (Will be removed in next major version)

Variable	Type	Description	Default	Replacement
plugin:hyprview:workspace_indicator_font_size	int	⚠️ DEPRECATED - Font size now controlled by window_name_font_size.	28	Use window_name_font_size
plugin:hyprview:workspace_indicator_position	string	⚠️ DEPRECATED - Position now centered on bottom border when window_name_enabled = 1.	(empty)	Always centered (when window names enabled)
plugin:hyprview:workspace_indicator_bg_opacity	float	⚠️ DEPRECATED - Background opacity now controlled by window_name_bg_opacity.	0.85	Use window_name_bg_opacity

Note: When window_name_enabled = 1 (default), the workspace indicator is integrated into the window label format: [workspace_id] class • title. The label is centered on the bottom border with separate color control:

• Workspace ID ([workspace_id]): Uses border color (active = active_border_color, inactive = inactive_border_color)
• Window info (class • title): Uses window_text_color (default: white)

The deprecated workspace indicator settings (font_size, position, bg_opacity) are ignored when window names are enabled. To use the old overlay-style workspace indicator, set window_name_enabled = 0.

Migration Guide: The old overlay-style workspace indicator (shown in the corner of each tile) has been replaced with an integrated label system. If you have custom settings for the old workspace indicator:

• Replace workspace_indicator_font_size with window_name_font_size
• Replace workspace_indicator_bg_opacity with window_name_bg_opacity
• The workspace_indicator_position setting is no longer needed as labels are always centered on the bottom border
• These deprecated settings will be removed in the next major version