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. This file must exist to run hyprlock.

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:

Animations

Variables in the animations category:

Keywords

The animation and bezier keywords can be used just like in hyprland.conf.

For Example:

bezier = linear, 1, 1, 0, 0
animation = fade, 1, 1.8, linear

Available animations can be found in the animation tree. The optional STYLE parameter for the animation keyword is currently unused by hyprlock.

Check out Hyprland’s animation documentation for more information.

Animation tree

global
  ↳ fade
    ↳ fadeIn - fade to lockscreen
    ↳ fadeOut - fade back to the wayland session
  ↳ inputField
    ↳ inputFieldColors - fade between colors and gradients
    ↳ inputFieldFade - fade_on_empty animation
    ↳ inputFieldWidth - adaptive width animation
    ↳ inputFieldDots - fade in/out for individual dots in the input field

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 selection

monitor is available for all widgets and can be left empty for “all monitors”.

It takes the same string that is used reference monitors in the hyprland configuration. So either use the portname (e.g. eDP-1) or the monitor description (e.g. desc:Chimei Innolux Corporation 0x150C).

See Monitors.

Variable substitution

The following variables in widget text options will be substituted.

• $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)
• $LAYOUT - current keyboard layout
• $ATTEMPTS - failed authentication attempts
• $FAIL - last authentication fail reason
• $PAMPROMPT - pam auth last prompt
• $PAMFAIL - pam auth last fail reason
• $FPRINTPROMPT - fingerprint auth last prompt
• $FPRINTFAIL - fingerprint auth last fail reason

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.

placeholder_text and fail_text both support variable substitution.

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.

Dynamic labels

The text option supports variable substitution and launching shell 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.
• $TIME and $TIME12 will use timezone from TZ environment variable. If it’s not set, system timezone will be used, falling back to UTC in case of errors.
• 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.