Hyprland 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.conf

exec-once = vicinae server # exclude this if using uwsm

# use whatever shortcut floats your boat
bind = $mainMod, Space, exec, vicinae toggle

# old rule syntax (Hyprland < 0.53)
# blur
# layerrule = blur, vicinae
# layerrule = ignorealpha 0, vicinae
# disable animation for vicinae only
# layerrule = noanim, vicinae

# named rule syntax (Hyprland 0.53+)
# blur
layerrule {
    name = vicinae-blur
    blur = on
    ignore_alpha = 0
    match:namespace = vicinae
}

# disable animation for vicinae only
layerrule {
    name = vicinae-no-animation
    no_anim = on
    match:namespace = vicinae
}

# anonymous rule syntax (Hyprland 0.53+)
# layerrule = blur on, ignore_alpha 0, match:namespace vicinae
# layerrule = no_anim on, match:namespace vicinae

On first startup, Vicinae will use a lot of CPU in order to populate the file index.

uwsm - Universal Wayland Session Manager

If you use uwsm to launch and manage hyprland then as always you should use the provided systemd service to start vicinae as well. Exclude the exec-once line 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.conf

bind = $mainMod, P, exec, 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.conf

misc {
    focus_on_activate = true
}