Hyprspace

A plugin for Hyprland that implements a workspace overview feature similar to that of KDE Plasma, GNOME and macOS, aimed to provide a efficient way of workspace and window management.

[!NOTE] This plugin is still maintained, by combined efforts of me and all the awesome contributors. However, I do not have as much time that I could spend on this plugin as before, and Hyprland is a rapidly changing codebase. Therefore, at this time, I could not guarantee that new issues could be resolved promptly. I appreciate your acknowledgement and support for this project!

P.S.: I could recommend giving niri a try for anyone who is considering an alternative to Hyprland. It is a scrolling window manager that offers a great built-in overview feature that allows dragging windows in-between workspaces just like this plugin does. It also has better workspace management as it cleans up empty workspaces like GNOME does.

https://github.com/KZDKM/Hyprspace/assets/41317840/ed1a585a-30d5-4a79-a6da-8cc0713828f9

Jump to installation

Plugin Compatibility

• hyprsplit (tested, explicit support)
• split-monitor-workspaces (tested, explicit support)
• hyprexpo (tested, minor bugs)
• Any layout plugin (except ones that override Hyprland's workspace management)

Roadmap

• Overview interface
  • Workspace minimap
  • Workspace display
• Mouse controls
  • Moving window between workspaces
  • Creating new workspaces
  • Dragging windows between workspace views
• Configurability
  • Styling
    • Panel background
    • Workspace background & border
    • Panel on Bottom
    • Vertical layout (on left / right)
    • Panel top padding (reserved for bar / notch)
    • Panel border (color / thickness)
    • Unique styling for special workspaces
  • Behavior
    • Autodrag windows
    • Autoscroll workspaces
    • Responsive workspace switching
    • Responsive exiting
      • Exit on click / switch
      • Exit with escape key
    • Blacklisting workspaces
      • Show / hide new workspace and empty workspaces
      • Show / hide special workspace (#11)
• Animation support
• Multi-monitor support (tested)
• Monitor scaling support (tested)
• aarch64 support (No function hook used)
• Touchpad & gesture support
  • Workspace swipe (#9)
  • Scrolling through workspace panel
  • Swipe to open

Installation

Manual

To build, have hyprland headers installed and under the repo directory do:

make all

Then use hyprctl plugin load followed by the absolute path to the .so file to load, you could add this to your exec-once to load the plugin on startup

Hyprpm

hyprpm add https://github.com/KZDKM/Hyprspace
hyprpm enable Hyprspace

Nix

Refer to the Hyprland wiki on plugins, but your flake might look like this:

{
  inputs = {
    # Hyprland is **such** eye candy
    hyprland = {
      type = "git";
      url = "https://github.com/hyprwm/Hyprland";
      submodules = true;
      inputs.nixpkgs.follows = "nixpkgs";
    };
    Hyprspace = {
      url = "github:KZDKM/Hyprspace";

      # Hyprspace uses latest Hyprland. We declare this to keep them in sync.
      inputs.hyprland.follows = "hyprland";
    };
  };

... # your normal setup with hyprland

  wayland.windowManager.hyprland.plugins = [
    # ... whatever
    inputs.Hyprspace.packages.${pkgs.system}.Hyprspace
  ];
}

Usage

Opening Overview

• Bind the overview:toggle or perform a workspace swipe vertically would open / close the panel.

Interaction

• Window management:
  • Click on workspace to change to it
  • Click on a window to drag it
  • Drag a window into a workspace would move the window to the workspace
• Exiting
  • Click without dragging the window exits the overview
  • Pressing ESC exits the overview
• Navigating
  • When there are many workspaces open, scroll / swipe on the panel to pan through opened workspaces

Configuration

Dispatchers

• Use overview:toggle dispatcher to toggle workspace overview on current monitor
• Use overview:close to close the overview on current monitor if opened
• Use overview:open to open the overview on current monitor if closed
• Adding the all argument to these dispatchers would toggle / open / close overview on all monitors

Lua Configuration (Hyprland 0.55+)

Starting with Hyprland 0.55+, the configuration format has transitioned to Lua as the default (~/.config/hypr/hyprland.lua).

1. Setting Config Options

Plugin settings are structured nested within the hl.config() table under plugin.overview.

hl.config({
    plugin = {
        overview = {
            panelColor = "#1e1e2e",
            panelBorderColor = "#cba6f7",
            workspaceActiveBackground = "rgba(49, 50, 68, 0.8)",
            workspaceActiveBorder = "rgb(203, 166, 247)",
            onBottom = false,
            autoDrag = true,
            -- Add other overview settings here
        }
    }
})

2. Using Lua Dispatchers

To invoke dispatchers, Hyprspace registers Lua wrapper functions in the hl.plugin.overview namespace. These can be bound in your configuration, run inside callbacks, or executed from the command line.

The following Lua functions are available:

• hl.plugin.overview.toggle(arg): Toggles the overview on the current monitor.
• hl.plugin.overview.open(arg): Opens the overview on the current monitor.
• hl.plugin.overview.close(arg): Closes the overview on the current monitor.

3. Examples

Keybindings in hyprland.lua:

When binding Lua wrapper functions using hl.bind, you must wrap the call in a function definition:

-- Toggle overview on the current monitor using SUPER + TAB
hl.bind("SUPER + TAB", function()
    hl.plugin.overview.toggle()
end, { description = "Toggle Hyprspace overview" })

-- Toggle overview on all monitors
hl.bind("SUPER + SHIFT + TAB", function()
    hl.plugin.overview.toggle("all")
end, { description = "Toggle Hyprspace overview on all monitors" })

Styling

Colors

• plugin:overview:panelColor
• plugin:overview:panelBorderColor
• plugin:overview:workspaceActiveBackground
• plugin:overview:workspaceInactiveBackground
• plugin:overview:workspaceActiveBorder
• plugin:overview:workspaceInactiveBorder
• plugin:overview:dragAlpha overrides the alpha of window when dragged in overview (0 - 1, 0 = transparent, 1 = opaque)
• plugin:overview:disableBlur

Layout

• plugin:overview:panelHeight
• plugin:overview:panelBorderWidth
• plugin:overview:onBottom whether if panel should be on bottom instead of top
• plugin:overview:workspaceMargin spacing of workspaces with eachother and the edge of the panel
• plugin:overview:reservedArea padding on top of the panel, for Macbook camera notch
• plugin:overview:workspaceBorderSize
• plugin:overview:centerAligned whether if workspaces should be aligned at the center (KDE / macOS style) or at the left (Windows style)
• plugin:overview:hideBackgroundLayers do not draw background and bottom layers in overview
• plugin:overview:hideTopLayers do not draw top layers in overview
• plugin:overview:hideOverlayLayers do not draw overlay layers in overview
• plugin:overview:hideRealLayers whether to hide layers in actual workspace
• plugin:overview:drawActiveWorkspace draw the active workspace in overview as-is
• plugin:overview:overrideGaps whether if overview should override the layout gaps in the current workspace using the following values
• plugin:overview:gapsIn
• plugin:overview:gapsOut
• plugin:overview:affectStrut whether the panel should push window aside, disabling this option also disables overrideGaps

Animation

• The panel uses the windows curve for a slide-in animation
• Use plugin:overview:overrideAnimSpeed to override the animation speed

Behaviors

• plugin:overview:autoDrag mouse click always drags window when overview is open
• plugin:overview:autoScroll mouse scroll on active workspace area always switch workspace
• plugin:overview:exitOnClick mouse click without dragging exits overview
• plugin:overview:switchOnDrop switch to the workspace when a window is droppped into it
• plugin:overview:exitOnSwitch overview exits when overview is switched by clicking on workspace view or by switchOnDrop
• plugin:overview:showNewWorkspace add a new empty workspace at the end of workspaces view
• plugin:overview:showEmptyWorkspace show empty workspaces that are inbetween non-empty workspaces
• plugin:overview:showSpecialWorkspace defaults to false
• plugin:overview:disableGestures
• plugin:overview:reverseSwipe reverses the direction of swipe gesture, for macOS peeps?
• plugin:overview:exitKey key used to exit overview mode (default: Escape). Leave empty to disable keyboard exit.
• Touchpad gesture behavior follows Hyprland workspace swipe behavior
  • gestures:workspace_swipe_fingers
  • gestures:workspace_swipe_cancel_ratio
  • gestures:workspace_swipe_min_speed_to_force