Lua API Reference

SamWM exposes a Lua API for configuration and runtime scripting.

Configuration API (internal/config)

These functions are available in the configuration file (~/.config/samwm/config.lua):

samwm.general(table)

General compositor settings:

samwm.general({
    border_size = 2,
    gaps_inner = 5,
    gaps_outer = 10,
    resize_corner = 10,
    focus_follows_mouse = true,
    mouse_mod_move = "SUPER",
    mouse_mod_resize = "SUPER"
})

samwm.layout(table)

Layout algorithm settings:

samwm.layout({
    master_factor = 0.55,
    master_count = 1,
    smart_gaps = true,
    default = "master-stack"
})

samwm.input(table)

Input device settings:

samwm.input({
    keyboard = {
        repeat_rate = 25,
        repeat_delay = 600,
        numlock = true,
        capslock = false
    },
    mouse = {
        sensitivity = 0.0,
        natural_scroll = false,
        acceleration = "flat"
    }
})

samwm.bind(mod, key, action [, description])

Register a keybinding:

samwm.bind("SUPER", "Return", "exec alacritty", "Open terminal")
samwm.bind("SUPER", "Q", "close", "Close window")

samwm.windowrule(match_table, action_table)

Apply rules to matching windows:

samwm.windowrule(
    { class = "firefox" },
    { float = "true" }
)

samwm.appearance(table)

Visual appearance settings:

samwm.appearance({
    active_border = "#89b4fa",
    inactive_border = "#585b70",
    urgent_border = "#f38ba8",
    background = "#1e1e2e",
    font = "monospace",
    font_size = 12
})

samwm.exec(command)

Execute a command on startup:

samwm.exec("waybar")
samwm.exec("dunst")

Runtime Scripting API (pkg/lua)

The pkg/lua package provides a Lua VM for runtime scripting with compositor integration.

samwm.bind(mod, key, action)

Register a runtime keybinding.

samwm.exec(command)

Execute a shell command.

samwm.focus(direction)

Focus next or previous window:

samwm.focus("next")
samwm.focus("prev")

samwm.toggle_floating()

Toggle floating mode for the focused window.

samwm.toggle_fullscreen()

Toggle fullscreen mode for the focused window.

samwm.close_window()

Close the focused window.

samwm.switch_layout(name)

Switch to a named layout ("master-stack", "fullscreen", "floating").

samwm.on_event(event, callback)

Register a Lua callback for a compositor event:

samwm.on_event("window_created", function(data)
    samwm.log("New window: " .. data)
end)

samwm.log(message)

Log a message to stdout:

samwm.log("Hello from Lua!")

Layout Algorithms

Master-Stack

Splits the screen into a master area (left) and stack area (right). The master area contains master_count windows tiled vertically. The stack area contains remaining windows tiled vertically.

Fullscreen

Fills the entire screen with the focused window.

Floating

Windows are not automatically positioned. User places windows manually.