hyprlock

hyprlock is a simple, yet fast, multi-threaded and GPU-accelerated screen lock for Hyprland.

Configuration

Configuration is done via the config file at ~/.config/hypr/hyprlock.conf. It is not required, but recommended. Without it, locking shows the current screen.

General

Variables in the general category:

variabledescriptiontypedefault
disable_loading_bardisables the loading bar on the bottom of the screen while hyprlock is booting up.boolfalse
hide_cursorhides the cursor instead of making it visibleboolfalse
gracethe amount of seconds for which the lockscreen will unlock on mouse movement.int0
no_fade_indisables the fadein animationboolfalse
no_fade_outdisables the fadeout animationboolfalse
ignore_empty_inputskips validation when no password is providedboolfalse
immediate_rendermakes hyprlock immediately start to draw widgets. Backgrounds will render background:color until their background:path resource is availableboolfalse
pam_modulesets the pam module used for authentication. If the module isn’t found in /etc/pam.d, “su” will be used as a fallbackstrhyprlock
text_trimsets if the text should be trimmed, useful to avoid trailing newline in commands outputbooltrue
fractional_scalingwhether to use fractional scaling. 0 - disabled, 1 - enabled, 2 - autoint2

Keyboard Shortcuts and Actions

The following keys and key-combinations describe hyprlock’s default behaviour:

inputdescription
ESCClear password buffer
Ctrl + uClear password buffer
Ctrl + BackspaceClear password buffer

Widgets

The entire configuration of how hyprlock looks is done via widgets.

widget_name {
    monitor =
    # further options
}

monitor can be left empty for “all monitors”

Widget List

General remarks

  • All rendered text supports pango markup.
    • Additionally hyprlock will parse <br/> for your convenience. (That’s a linebreak) Remember to enable linebreaks in your spans with allow_breaks="true".
  • Positioning is done via halign, valign, position, and zindex. Position is an added offset to the result of alignment.
    • halign: left, center, right, none. valign: top, center, bottom, none
    • zindex: Widgets with larger numbers will be placed above widgets with smaller numbers. All widgets default to 0, except background which defaults to -1.

Shadowable

Some widgets are shadowable, meaning they can have a shadow. For those widgets, you get:

variabledescriptiontypedefault
shadow_passespasses for shadow, 0 to disableint0
shadow_sizesize for shadowint3
shadow_colorshadow colorcolorrgb(0,0,0)
shadow_boostboost shadow’s opacityfloat1.2

Background

Draws a background image or fills with color.

If path is empty or missing, will use color. Otherwise, the image will be used.

If path is screenshot, a screenshot of your desktop at launch will be used.

background {
    monitor =
    path = /home/me/someImage.png   # supports png, jpg, webp (no animations, though)
    color = rgba(25, 20, 20, 1.0)

    # all these options are taken from hyprland, see https://wiki.hyprland.org/Configuring/Variables/#blur for explanations
    blur_passes = 0 # 0 disables blurring
    blur_size = 7
    noise = 0.0117
    contrast = 0.8916
    brightness = 0.8172
    vibrancy = 0.1696
    vibrancy_darkness = 0.0
}

Image

✓ Shadowable

Draws an image.

If path is empty or missing, nothing will be shown.

image {
    monitor =
    path = /home/me/cutie.png
    size = 150 # lesser side if not 1:1 ratio
    rounding = -1 # negative values mean circle
    border_size = 4
    border_color = rgb(221, 221, 221)
    rotate = 0 # degrees, counter-clockwise
    reload_time = -1 # seconds between reloading, 0 to reload with SIGUSR2
    reload_cmd =  # command to get new path. if empty, old path will be used. don't run "follow" commands like tail -F

    position = 0, 200
    halign = center
    valign = center
}

Shape

✓ Shadowable

Draws a shape.

shape {
    monitor =
    size = 360, 60
    color = rgba(17, 17, 17, 1.0)
    rounding = -1
    border_size = 8
    border_color = rgba(0, 207, 230, 1.0)
    rotate = 0
    xray = false # if true, make a "hole" in the background (rectangle of specified size, no rotation)

    position = 0, 80
    halign = center
    valign = center
}

Input Field

✓ Shadowable

Draws a password input field.

input-field {
    monitor =
    size = 200, 50
    outline_thickness = 3
    dots_size = 0.33 # Scale of input-field height, 0.2 - 0.8
    dots_spacing = 0.15 # Scale of dots' absolute size, 0.0 - 1.0
    dots_center = false
    dots_rounding = -1 # -1 default circle, -2 follow input-field rounding
    outer_color = rgb(151515)
    inner_color = rgb(200, 200, 200)
    font_color = rgb(10, 10, 10)
    fade_on_empty = true
    fade_timeout = 1000 # Milliseconds before fade_on_empty is triggered.
    placeholder_text = <i>Input Password...</i> # Text rendered in the input box when it's empty.
    hide_input = false
    rounding = -1 # -1 means complete rounding (circle/oval)
    check_color = rgb(204, 136, 34)
    fail_color = rgb(204, 34, 34) # if authentication failed, changes outer_color and fail message color
    fail_text = <i>$FAIL <b>($ATTEMPTS)</b></i> # can be set to empty
    fail_timeout = 2000 # milliseconds before fail_text and fail_color disappears
    fail_transition = 300 # transition time in ms between normal outer_color and fail_color
    capslock_color = -1
    numlock_color = -1
    bothlock_color = -1 # when both locks are active. -1 means don't change outer color (same for above)
    invert_numlock = false # change color if numlock is off
    swap_font_color = false # see below

    position = 0, -20
    halign = center
    valign = center
}
ℹ️

Colors information

When outline_thickness set to 0, the color of the inner box will be changed instead of the outer.

Behaviour of swap_font_color is as follows:

  • outline_thickness is 0: if set, font color will be swapped with inner one on color change events (e.g. Caps-lock on or password check).
  • outline_thickness is not 0: if set, font and inner colors will be swapped on password check and authentication failure.

Available variables for placeholder_text:

  • $PROMPT - prompt text provided by pam. Usually this will be “Password: “, but it depends on your pam configuration.

Available variables for fail_text:

  • $FAIL - pam fail reason
  • $ATTEMPTS - number of failed authentication attempts

Label

✓ Shadowable

Draws a label.

label {
    monitor =
    text = Hi there, $USER
    text_align = center # center/right or any value for default left. multi-line text alignment inside label container
    color = rgba(200, 200, 200, 1.0)
    font_size = 25
    font_family = Noto Sans
    rotate = 0 # degrees, counter-clockwise

    position = 0, 80
    halign = center
    valign = center
}

Available variables for text:

  • $USER - username (e.g. linux-user)
  • $DESC - user description (e.g. Linux User)
  • $TIME - current time in 24-hour format (e.g. 13:37)
  • $TIME12 - current time in 12-hour format (e.g. 1:37 PM)
  • $PROMPT - last pam prompt
  • $FAIL - last pam fail reason
  • $ATTEMPTS - failed attempts
  • $LAYOUT - current keyboard layout

text also supports launching commands, for example:

text = cmd[update:1000] echo "<span foreground='##ff2222'>$(date)</span>"

Worth noting:

  • update: - time is in ms.
  • label can be forcefully updated by specifying update:<time>:1 or update:<time>:true and sending SIGUSR2 to hyprlock. <time> can be 0 in this case.
  • $ATTEMPTS[<string>] format can be used to show <string> when there are no failed attempts. You can use pango-markup here. <string> can be empty to hide.
  • $LAYOUT[<str0>,<str1>,...] format is available to replace indexed layouts. You can use settings from hyprland.conf, e.g. $LAYOUT[en,ru,de]. Also, single ! character will hide layout. E.g. $LAYOUT[!] will hide default (0 indexed) and show others.
  • Variables seen above are parsed before the command is ran.
  • do not run commands that never exit. This will hang the AsyncResourceGatherer and you won’t have a good time.

User Signals

  • SIGUSR1 - unlocks hyprlock. For example, you can switch to a another tty and run pkill -USR1 hyprlock.
  • SIGUSR2 - updates labels and images. See above.