Skip to main content
Version: 2.1

lockscreen (module) somewm-only

lockscreen.init() creates a password prompt and cover surfaces using the Lock API. The default config calls it after loading the theme.

Usage​

-- In rc.lua, after beautiful.init()
require("lockscreen").init({
bg_color = "#000000",
font_large = "monospace bold 64",
clock_format = "%I:%M %p",
})

Call init() once, after beautiful.init(). Omit its argument to use theme defaults. Later calls are ignored, including their options.

Configuration Options​

OptionTypeDefaultbeautiful fallbackDescription
bg_colorstringbeautiful.bg_normal or "#1a1a2e"lockscreen_bg_colorBackground color
fg_colorstringbeautiful.fg_normal or "#e0e0e0"lockscreen_fg_colorText color
input_bgstringbeautiful.bg_focus or "#2a2a4e"lockscreen_input_bgPassword input background
border_colorstringbeautiful.border_color_active or "#4a4a6e"lockscreen_border_colorInput box border color
error_colorstringbeautiful.bg_urgent or "#ff6b6b"lockscreen_error_colorError message color
fontstring"sans 14"lockscreen_font or fontRegular text font
font_largestring"sans bold 48"lockscreen_font_largeClock display font
clock_formatstring"%H:%M"lockscreen_clock_formatClock format (strftime)
date_formatstring"%A, %B %d"lockscreen_date_formatDate format (strftime)
lock_screenscreen/function/nilnilnoneScreen for interactive UI (nil = primary)

Config Resolution Order​

For colour and font options, the module checks in order:

  1. opts.option (passed to init())
  2. beautiful.lockscreen_option (theme variable)
  3. Core beautiful variable (e.g., beautiful.bg_normal for bg_color)
  4. Built-in default

Keyboard Input​

KeyAction
Printable charactersAppend one UTF-8 character. Further input is ignored once the password exceeds 256 bytes
ReturnSubmit password for PAM verification
BackSpaceDelete last character (UTF-8 aware)
EscapeClear entire password
Caps Lock (active)Shows "Caps Lock is on" warning while typing

Password characters are displayed as bullets (U+25CF) rather than plaintext.

Multi-Monitor Behavior​

The lock screen creates two types of surfaces:

  • Interactive surface on the primary screen (or the screen specified by lock_screen): shows clock, date, password input, and status text.
  • Cover surfaces on all other screens: opaque background-only wiboxes that block content.

On screen hotplug while locked:

  • Screen added: A new cover is created and shown immediately.
  • Interactive screen removed: The UI migrates to the new primary screen. The cover on that screen is promoted to an interactive surface.

Signals Used​

The module connects to these signals internally:

SignalPurpose
lock::activateShow lock surfaces, start keygrabber
lock::deactivateHide all surfaces, clear password, stop keygrabber
screen.addedCreate cover for new screen, show if locked
screen.removedMigrate interactive UI or remove cover

See Also​