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.

Variable types

Hyprlock uses the following types in addition to Hyprland’s variable types.

General

Variables in the general category:

Authentication

Variables in the auth category:

Keyboard Shortcuts and Actions

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

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.
• All position and size options can be specified in pixels or as percentages of the output size.
  • pixels: 10, 10 or 10px, 10px
  • percentages: 10%, 10.5%
  • mixed: 10%, 5px
• Supported image formats are png, jpg and webp (no animations though)

Shadowable

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

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 = screenshot
    color = rgba(25, 20, 20, 1.0)
    blur_passes = 2
}

Image

✓ Shadowable

Draws an image.

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

image {
    monitor =
    path = /home/me/cutie.png
    size = 150
    rounding = 0 # no rounding

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

Shape

✓ Shadowable

Draws a shape.

shape {
    monitor =
    size = 360, 60
    color = rgba(0, 0, 0, 0.0) # no fill
    rounding = -1 # circle
    border_size = 4
    border_color = rgba(0, 207, 230, 1.0)

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

Input Field

✓ Shadowable

Draws a password input field.

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

input-field {
    monitor =
    size = 20%, 5%
    outline_thickness = 3
    inner_color = rgba(0, 0, 0, 0.0) # no fill

    outer_color = rgba(33ccffee) rgba(00ff99ee) 45deg
    check_color=rgba(00ff99ee) rgba(ff6633ee) 120deg
    fail_color=rgba(ff6633ee) rgba(ff0066ee) 40deg

    font_color = rgb(143, 143, 143)
    fade_on_empty = false
    rounding = 15

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

Label

✓ Shadowable

Draws a label.

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
• $FPRINTMESSAGE - last message from fingerprint matching

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.

label {
    monitor =
    text = Hi there, $USER
    color = rgba(200, 200, 200, 1.0)
    font_size = 25
    font_family = Noto Sans

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

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.