Hyprland Lua Quickstart

This guide shows the best way to quickly get started with Vicinae on Hyprland.

Main configuration

Add the following to your Hyprland configuration, and you are good to go (unless you use uwsm to manage Hyprland, see below).

-- ~/.config/hypr/hyprland.lua

local mainMod = "SUPER"

-- autostart
hl.on("hyprland.start", function()
  hl.exec_cmd("vicinae server")
end)

-- use whatever shortcut floats your boat
hl.bind(mainMod .. " + Space", hl.dsp.exec_cmd("vicinae toggle"))

-- blur
hl.layer_rule({
  match = { namespace = "vicinae" },
  name = "vicinae-blur",
  blur = true,
  ignore_alpha = 0,
})

-- disable animation for vicinae only
hl.layer_rule({
  match = { namespace = "vicinae" },
  name = "vicinae-no-animation",
  no_anim = true,
})

uwsm - Universal Wayland Session Manager

If you use uwsm to launch and manage Hyprland, use the provided systemd service to start vicinae. Exclude the autostart command above and run systemctl --user enable --now vicinae.service instead; vicinae will start immediately and launch on boot moving forward.

Bind to a custom command

You can easily create a binding to open any vicinae command directly:

-- ~/.config/hypr/hyprland.lua

hl.bind(mainMod .. " + P", hl.dsp.exec_cmd("vicinae vicinae://launch/clipboard/history"))

You can do a lot with this: learn more about deeplinks.

Focus window on activation

You may want to focus an application window after vicinae triggers an action related to it.

For example: using a shortcut action in vicinae that opens a browser tab → Instantly focus the window where the action happened

You can have this behavior by adding this to your config:

-- ~/.config/hypr/hyprland.lua

hl.config({
  misc = {
    focus_on_activate = true,
  },
})