dotfiles/dot_config/hypr/hyprland_lua_api.md

Hyprland Lua API Documentation

1. Introduction

Since Hyprland v0.55, the traditional hyprlang syntax has been deprecated in favor of a powerful Lua configuration system. The configuration file is located at ~/.config/hypr/hyprland.lua. This system allows for dynamic scripting, logic-based configurations, and better integration with external tools through Lua's standard libraries and Hyprland's internal API (hl).

2. Global Configuration (hl.config)

The hl.config function is used to set global variables. It accepts a table where keys correspond to configuration sections.

hl.config({
  general = {
    border_size = 2,
    gaps_in = 5,
    gaps_out = 20,
    layout = "dwindle",
    ["col.active_border"] = "rgba(33ccffee) rgba(00ff99ee) 45deg",
    ["col.inactive_border"] = "rgba(595959aa)"
  },
  decoration = {
    rounding = 10,
    blur = {
      enabled = true,
      size = 3,
      passes = 1
    },
    shadow = {
      enabled = true,
      range = 4,
      render_power = 3,
      color = "rgba(1a1a1aee)"
    }
  },
  input = {
    kb_layout = "us",
    follow_mouse = 1,
    touchpad = {
      natural_scroll = false
    }
  },
  gestures = {
    workspace_swipe = true
  },
  misc = {
    force_default_wallpaper = 0,
    disable_hyprland_logo = true
  }
})

Main Categories

• General: border_size, gaps_in, gaps_out, layout, col.active_border, col.inactive_border, allow_tearing, no_focus_fallback.
• Decoration: rounding, rounding_power, active_opacity, inactive_opacity, blur (subcategory), shadow (subcategory), glow (subcategory).
• Animations: enabled, workspace_wraparound.
• Input: kb_layout, kb_model, sensitivity, repeat_rate, follow_mouse, touchpad (subcategory), tablet (subcategory).
• Gestures: workspace_swipe_distance, workspace_swipe_touch, workspace_swipe_create_new.
• Group: auto_group, insert_after_current, col.border_active, groupbar (subcategory).
• Misc: disable_hyprland_logo, vrr, animate_manual_resizes, enable_swallow, focus_on_activate.
• Binds: pass_mouse_when_bound, scroll_event_delay, workspace_back_and_forth.
• XWayland: enabled, use_nearest_neighbor, force_zero_scaling.
• Render: direct_scanout, ctm_animation, cm_enabled.
• Cursor: no_hardware_cursors, zoom_factor, inactive_timeout, hide_on_key_press.
• Ecosystem: no_update_news, no_donation_nag, enforce_permissions.

3. Monitors (hl.monitor)

Monitors are configured using the hl.monitor function.

Syntax:

hl.monitor({
  output = "DP-1",      -- Name or "desc:..."
  mode = "1920x1080@144", -- Resolution@Hz or "preferred", "highres", "highrr"
  position = "0x0",     -- Layout position or "auto"
  scale = 1,            -- Scale factor or "auto"
  transform = 0,        -- Rotation (0-7)
  disabled = false,     -- Whether to disable the output
  mirror = "DP-2",      -- Mirror another output
  bitdepth = 10,        -- 8 or 10
  vrr = 1               -- VRR mode
})

4. Window Rules (hl.window_rule)

Window rules allow targeting windows by properties to apply static or dynamic effects.

Syntax:

hl.window_rule({
  name = "my-rule", -- Optional for handle management
  match = {
    class = "kitty",
    title = ".*term.*",
    floating = true
  },
  opacity = "0.8",
  rounding = 10
})

Props (Match fields)

class, title, initial_class, initial_title, tag, xwayland, floating, fullscreen, focus, group, modal, workspace.

Effects

• Static: float, tile, fullscreen, move, size, center, pseudo, workspace, monitor, pin.
• Dynamic: opacity, border_color, rounding, animation, no_blur, idle_inhibit, dim_around, no_anim, stay_focused.

5. Layer Rules (hl.layer_rule)

Layer rules target Wayland layers like waybar, rofi, and wallpapers.

hl.layer_rule({
  match = { namespace = "waybar" },
  blur = true,
  ignore_alpha = 0.5
})

6. Workspace Rules (hl.workspace_rule)

Workspace rules define behavior for specific workspaces.

hl.workspace_rule({
  workspace = "3",
  monitor = "DP-1",
  default = true,
  persistent = true,
  gaps_in = 0,
  gaps_out = 0,
  no_border = true
})

7. Keybinds (hl.bind, hl.unbind, hl.define_submap)

Keybinds are created using hl.bind.

Syntax:

hl.bind(keys, dispatcher, flags)

Examples:

-- Simple command
hl.bind("SUPER + Q", hl.dsp.exec_cmd("kitty"))

-- Lua function with logic
hl.bind("SUPER + T", function()
  local win = hl.get_active_window()
  if win then print(win.title) end
end)

-- Flags
hl.bind("SUPER + L", hl.dsp.exec_cmd("swaylock"), { locked = true })

Submaps

hl.define_submap("resize", function()
  hl.bind("right", hl.dsp.window.resize({ x = 10, y = 0, relative = true }), { repeating = true })
  hl.bind("escape", hl.dsp.submap("reset"))
end)
hl.bind("ALT + R", hl.dsp.submap("resize"))

8. Dispatchers (hl.dsp.*)

Dispatchers perform compositor actions.

Category	Dispatchers
General	exec_cmd(cmd, rules?), focus({ direction/window/monitor/workspace }), exit(), dpms({ action }), global(string)
Window	close(), kill(), float({ action }), fullscreen({ mode, action }), move({ direction/workspace/monitor/coords }), resize({ x, y, relative }), pin(), tag({ tag })
Workspace	rename({ workspace, name }), move({ monitor }), toggle_special(name)
Group	toggle(), next(), prev(), active(index), lock({ action })

9. Events (hl.on)

Define callbacks for compositor events.

hl.on("window.open", function(window)
  print("New window opened: " .. window.class)
end)

Events: hyprland.start, window.active, workspace.active, monitor.added, config.reloaded.

10. Timers (hl.timer)

Timers for delayed or repeating actions.

local myTimer = hl.timer(function()
  hl.notification.create({ text = "Timer fired!" })
end, { timeout = 1000, type = "oneshot" })

11. Convenience Functions

• hl.get_active_window()
• hl.get_active_workspace()
• hl.get_monitors()
• hl.get_config(key)
• hl.get_cursor_pos()

12. Environment Variables (hl.env)

Set environment variables.

hl.env("QT_QPA_PLATFORM", "wayland;xcb")
hl.env("XCURSOR_SIZE", "24")

13. Custom Layouts (hl.layout.register)

Register custom Lua-based layouts.

14. Permissions (hl.permission)

Control sensitive application access.

hl.permission({ binary = "/usr/bin/grim", type = "screencopy", mode = "allow" })

15. Plugins

Configure and interact with plugins.

if hl.plugin.csgo_vulkan_fix ~= nil then
  hl.config({ plugin = { csgo_vulkan_fix = { fix_mouse = false } } })
end

16. Animations & Curves (hl.animation, hl.curve)

Define easing curves and apply them to the animation tree.

hl.curve("myBezier", { type = "bezier", points = { {0.1, 1}, {1, 0.1} } })
hl.animation({ leaf = "windows", enabled = true, speed = 8, curve = "myBezier", style = "popin 80%" })