hyprgrass

You can build hyprgrass from source using meson and ninja.

When running meson setup, you can pass the following configuration options:

• -Dbuildtype=debug: Creates a debug build with detailed stack traces for crash reporting.
• -Dhyprgrass-pulse=true: Enables building the hyprgrass-pulse integration.

After setup, compile using ninja -C build.

meson setup build -Dhyprgrass-pulse=true
ninja -C build

To control PulseAudio volume using touchpad gestures, use the pulse-gesture keyword in your Hyprland configuration. This integration only supports the volume action. The flags used with pulse-gesture are identical to the standard Hyprland gesture flags.

Note that the distance (in pixels) required to change the volume from 0 to 100 is determined by the Hyprland variable gestures:workspace_swipe_distance.

# binds to a touchpad gesture
pulse-gesture = 3, vertical, volume

# also bind to a hyprgrass gesture
hyprgrass-gesture = 3, vertical, emulate_touchpad, 3, vertical

If you use Nix, it is highly recommended to use Flakes.

1. Add hyprgrass to your flake.nix inputs. Important: You must set inputs.hyprland.follows = "hyprland"; to ensure compatibility.
2. Add the package to your Hyprland configuration in your home-manager module. You can include the base package or the optional hyprgrass-pulse package.

# flake.nix
{
   inputs = {
      hyprland.url = "github:hyprwm/Hyprland";
      hyprgrass = {
         url = "github:horriblename/hyprgrass";
         inputs.hyprland.follows = "hyprland"; # IMPORTANT
      };
   };
}

# home-manager module
wayland.windowManager.hyprland = {
   plugins = [
      inputs.hyprgrass.packages.${pkgs.system}.default
      # optional
      inputs.hyprgrass.packages.${pkgs.system}.hyprgrass-pulse
   ];
};

The configuration options workspace_swipe_fingers and workspace_swipe_edge have been removed. They are replaced by the hl.plugin.hyprgrass.gesture function using specific pattern definitions.

To replace workspace_swipe_fingers (e.g., 3 fingers): Use a swipe kind pattern with the desired number of fingers.

To replace workspace_swipe_edge: Use an edge kind pattern with an origin and direction.

-- workspace_swipe_fingers replacement
hl.plugin.hyprgrass.gesture({
    pattern = {kind = "swipe", fingers = 3, direction = "horizontal"},
    action = "workspace"
})

-- workspace_swipe_edge replacement
hl.plugin.hyprgrass.gesture({
    pattern = {kind = "edge", origin = "down", direction = "horizontal"},
    action = "workspace",
})

If you are experiencing crashes, building a debug version can provide more detailed stack traces. When reporting a crash, attach the log file found at ~/.cache/hypr/hyprlandCrashReport{pid}.txt.

Note: When loading a manually built debug plugin via hyprctl, you must use an absolute path, as relative paths are not supported.

git clone https://github.com/horriblename/hyprgrass
cd hyprgrass

meson setup build -Dbuildtype=debug
meson compile -C build

# Use absolute path for loading
hyprctl plugin load "$PWD/build/src/libhyprgrass.so"

When migrating to the Lua configuration, the plugin namespace has changed from touch_gestures to hyprgrass. You must update your hl.config calls to reflect this change.

Old namespace: {plugin = { touch_gestures = {...} }}

New namespace: {plugin = { hyprgrass = {...} }}

-- instead of {plugin = { touch_gestures = {...} }}
hl.config({plugin = {hyprgrass = {...}}})

The recommended way to install hyprgrass is using hyprpm. Ensure you have installed all necessary dependencies (like glm) before proceeding.

To install the base plugin:

1. Add the repository: hyprpm add https://github.com/horriblename/hyprgrass
2. Enable the plugin: hyprpm enable hyprgrass

To enable the optional PulseAudio integration (hyprgrass-pulse), run: hyprpm enable hyprgrass-pulse

To ensure plugins load automatically at startup, add the following to your Hyprland configuration: exec-once = hyprpm reload -n

The -n flag ensures hyprpm sends a notification if an update is required or if something goes wrong.

hyprpm add https://github.comlename/hyprgrass
hyprpm enable hyprgrass

# optional integration with pulse-audio
hyprpm enable hyprgrass-pulse

General plugin settings for hyprgrass, such as sensitivity, are configured within the hl.config table under the hyprgrass key.

hl.config({
    plugin = {
        hyprgrass = {
            sensitivity = 4.0,
            -- ...
        },
    },
})

IGestureManager is an interface used to manage touch gestures. It works by registering wf::touch::gesture_t objects via addTouchGesture().

During the updateGestures lifecycle, gestures are processed. Actions within a single gesture_t are chained serially: one action must reach a "completed" state before the next action in the chain can begin "running".

To prevent touch events from reaching the client window/surface (e.g., when a gesture is being actively recognized), the manager provides methods to intercept touch events (onTouchDown, onTouchUp, onTouchMove) which return a boolean indicating if the event should be blocked.

Adjust built-in Hyprland gesture settings via hl.config to improve workspace switching experience:

• workspace_swipe_touch: Boolean to enable/disable touch-based workspace swiping.
• workspace_swipe_cancel_ratio: Float determining the threshold to cancel a swipe.

hl.config({
  gestures = {
    workspace_swipe_touch = true,
    workspace_swipe_cancel_ratio = 0.15,
  },
})

Use hl.config to set core Hyprgrass parameters. Key options include:

• sensitivity: Float value for gesture sensitivity (e.g., 1.0). Higher values are recommended for tablet screens.
• long_press_delay: Delay in milliseconds before a long press is triggered.
• resize_on_border_long_press: Boolean. If true, allows resizing windows by long-pressing on window borders or gaps.
• edge_margin: Distance in pixels from the screen edge considered an 'edge'.

Note: If migrating from Hyprlang, refer to the Lua migration guide for breaking changes.

hl.config({
    plugin = {
        hyprgrass = {
            sensitivity = 1.0,
            long_press_delay = 400,
            resize_on_border_long_press = true,
            edge_margin = 10,
        }
    }
})