15 KiB
weight | title |
---|---|
4 | 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.
type | description |
---|---|
layoutx | number with an optional % suffix, allowing users to specify sizes as percentages of the output size. Floats (e.g. 10.5) are supported, but only have an effect when used with % . Raw pixel values will just get rounded. |
layoutxy | 2D vector version of layoutx. |
General
Variables in the general
category:
variable | description | type | default |
---|---|---|---|
disable_loading_bar | disables the loading bar on the bottom of the screen while hyprlock is booting up. | bool | false |
hide_cursor | hides the cursor instead of making it visible | bool | false |
grace | the amount of seconds for which the lockscreen will unlock on mouse movement. | int | 0 |
no_fade_in | disables the fadein animation | bool | false |
no_fade_out | disables the fadeout animation | bool | false |
ignore_empty_input | skips validation when no password is provided | bool | false |
immediate_render | makes hyprlock immediately start to draw widgets. Backgrounds will render background:color until their background:path resource is available |
bool | false |
text_trim | sets if the text should be trimmed, useful to avoid trailing newline in commands output | bool | true |
fractional_scaling | whether to use fractional scaling. 0 - disabled, 1 - enabled, 2 - auto | int | 2 |
{{< callout type=warning >}}
If you are not on hyprland, or your XDG_CURRENT_DESKTOP
is not Hyprland, the fade out will be disabled and the value of your no_fade_out
variable will be ignored.
{{< /callout >}}
Authentication
Variables in the auth
category:
variable | description | type | default |
---|---|---|---|
pam:enabled | whether to enable pam authentication | bool | true |
pam:module | sets the pam module used for authentication. If the module isn't found in /etc/pam.d , "su" will be used as a fallback |
str | hyprlock |
fingerprint:enabled | enables parallel fingerprint auth with fprintd. | bool | false |
fingerprint:ready_message | sets the message that will be displayed when fprintd is ready to scan a fingerprint. | str | (Scan fingerprint to unlock) |
fingerprint:present_message | sets the message that will be displayed when a finger is placed on the scanner. | str | Scanning fingerprint |
{{< callout type=info >}}
At least one enabled authentication method is required.
{{< /callout >}}
Keyboard Shortcuts and Actions
The following keys and key-combinations describe hyprlock's default behaviour:
input | description |
---|---|
ESC | Clear password buffer |
Ctrl + u | Clear password buffer |
Ctrl + Backspace | Clear 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 withallow_breaks="true"
.
- Additionally hyprlock will parse
- 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.
- halign:
- All
position
andsize
options can be specified in pixels or as percentages of the output size.- pixels:
10, 10
or10px, 10px
- percentages:
10%, 10.5%
- mixed:
10%, 5px
- pixels:
- 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:
variable | description | type | default |
---|---|---|---|
shadow_passes | passes for shadow, 0 to disable | int | 0 |
shadow_size | size for shadow | int | 3 |
shadow_color | shadow color | color | rgb(0,0,0) |
shadow_boost | boost shadow's opacity | float | 1.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.
variable | description | type | default |
---|---|---|---|
monitor | monitor to draw on | str | Empty |
path | image path, screenshot or empty to fill with color |
str | Empty |
color | fallback background color | color | rgba(17, 17, 17, 1.0) |
blur_passes | the amount of passes to perform. 0 disables blurring | int | 0 |
blur_size | blur size (distance) | int | 7 |
noise | how much noise to apply | float | 0.0117 |
contrast | contrast modulation for blur | float | 0.8916 |
brightness | brightness modulation for blur | float | 0.8172 |
vibrancy | Increase saturation of blurred colors | float | 0.1696 |
vibrancy_darkness | How strong the effect of vibrancy is on dark areas | float | 0.05 |
reload_time | seconds between reloading, 0 to reload with SIGUSR2. Ignored if path is screenshot . |
int | -1 |
reload_cmd | command to get new path. If empty, old path will be used. | str | Empty |
crossfade_time | cross-fade time in seconds between old and new background on reload. A negative value means no cross-fade. | float | -1.0 |
zindex | z-index of the widget | int | -1 |
{{< callout type=info >}}
Blur options are taken from hyprland. See Variables/#blur.
{{< /callout >}}
{{% details title="Example background" closed="true" %}}
background {
monitor =
path = screenshot
color = rgba(25, 20, 20, 1.0)
blur_passes = 2
}
{{% /details %}}
Image
✓ Shadowable
Draws an image.
If path
is empty or missing, nothing will be shown.
variable | description | type | default |
---|---|---|---|
monitor | monitor to draw on | str | Empty |
path | image path | str | Empty |
sizex | width of the image. height will be calculated based on the image aspect ratio | layoutx | 10% |
rounding | negative values result in a circle | int | -1 |
border_size | border size | int | 0 |
border_color | border color | gradient | rgba(221, 221, 221, 1.0) |
rotate | rotation in degrees, counter-clockwise | int | 0 |
reload_time | seconds between reloading, 0 to reload with SIGUSR2 | int | -1 |
reload_cmd | command to get new path. if empty, old path will be used. don't run "follow" commands like tail -F | str | Empty |
position | position of the image | layoutxy | 0, 0 |
halign | horizontal alignment | str | center |
valign | vertical alignment | str | center |
zindex | z-index of the widget | int | 0 |
{{% details title="Example image" closed="true" %}}
image {
monitor =
path = /home/me/cutie.png
size = 150
rounding = 0 # no rounding
position = 0, 200
halign = center
valign = center
}
{{% /details %}}
Shape
✓ Shadowable
Draws a shape.
variable | description | type | default |
---|---|---|---|
monitor | monitor to draw on | str | Empty |
size | size of the shape | layoutxy | 100, 100 |
color | color of the shape | color | rgba(17, 17, 17, 1.0) |
rounding | negative values result in a circle | int | -1 |
rotate | rotation in degrees, counter-clockwise | int | 0 |
border_size | border size | int | 0 |
border_color | border color | gradient | rgba(0, 207, 230, 1.0) |
xray | if true, make a "hole" in the background (rectangle of specified size, no rotation) | bool | false |
position | position of the shape | layoutxy | 0, 0 |
halign | horizontal alignment | str | center |
valign | vertical alignment | str | center |
zindex | z-index of the widget | int | 0 |
{{% details title="Example shape" closed="true" %}}
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
}
{{% /details %}}
Input Field
✓ Shadowable
Draws a password input field.
variable | description | type | default |
---|---|---|---|
monitor | monitor to draw on | str | Empty |
size | size of the input field. | layoutxy | 400, 90 |
outline_thickness | thickness of the outline | int | 4 |
dots_size | size of the dots. [0.2 - 0.8] | float | 0.25 |
dots_spacing | spacing between dots. [-1.0 - 1.0] | float | 0.15 |
dots_center | whether to center the dots. align left otherwise | bool | true |
dots_rounding | rounding of the dots | int | -1 |
dots_fade_time | Milliseconds until a dot fully fades in | int | 200 |
dots_text_format | text character(s) used for the input indicator, rounded rectangles are the default. | str | Empty |
outer_color | border color | gradient | rgba(17, 17, 17, 1.0) |
inner_color | color of the inner box | color | rgba(200, 200, 200, 1.0) |
font_color | color of the font | color | rgba(10, 10, 10, 1.0) |
font_family | font family | str | Noto Sans |
fade_on_empty | fade the input field when empty | bool | true |
fade_timeout | milliseconds before fade_on_empty is triggered |
int | 2000 |
placeholder_text | text rendered in the input box when it's empty | str | <i>Input Password...</i> |
hide_input | render an input indicator similar to swaylock instead of dots when set to true | bool | false |
rounding | -1 means complete rounding (circle/oval) | int | -1 |
check_color | color accent when waiting for the authentication result | gradient | rgba(204, 136, 34, 1.0) |
fail_color | color accent when authentication fails | gradient | rgba(204, 34, 34, 1.0) |
fail_text | text rendered when authentication fails | str | <i>$FAIL <b>($ATTEMPTS)</b></i> |
fail_timeout | milliseconds before fail_text and fail_color disappears |
int | 2000 |
fail_transition | transition time in ms between normal outer_color and fail_color |
int | 300 |
capslock_color | color accent when capslock is active | gradient | Empty |
numlock_color | color accent when numlock is active | gradient | Empty |
bothlock_color | color accent when both locks are active | gradient | Empty |
invert_numlock | change color if numlock is off | bool | false |
swap_font_color | swap font and inner colors on color change events | bool | false |
position | position of the input field | layoutxy | 0, 0 |
halign | horizontal alignment | str | center |
valign | vertical alignment | str | center |
zindex | z-index of the widget | int | 0 |
{{< callout type=info >}}
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
is0
: 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 not0
: if set, font and inner colors will be swapped on password check and authentication failure.swap_font_color
will narrow the accent colors from a gradient to a single color by using the first specified color.
{{< /callout >}}
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
{{% details title="Example input-field" closed="true" %}}
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
}
{{% /details %}}
Label
✓ Shadowable
Draws a label.
variable | description | type | default |
---|---|---|---|
monitor | monitor to draw on | str | Empty |
text | text to render | str | Sample Text |
text_align | multi-line text alignment inside label container. center/right or any value for default left. | str | center |
sizex | absolute width of the label. If left at 0, the width of the rendered label will be used directly. | layoutx | 0 |
color | color of the text | color | rgba(254, 254, 254, 1.0) |
font_size | size of the font. Without sizex, this also configures the size of the label. Together with sizex it can be used to specify how sharp the label should be. | int | 16 |
font_family | font family | str | Sans |
rotate | rotation in degrees, counter-clockwise | int | 0 |
position | position of the label | layoutxy | 0, 0 |
halign | horizontal alignment | str | center |
valign | vertical alignment | str | 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$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
orupdate:<time>:true
and sendingSIGUSR2
to hyprlock.<time>
can be0
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 fromhyprland.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.
{{% details title="Example label" closed="true" %}}
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
}
{{% /details %}}
User Signals
SIGUSR1
- unlocks hyprlock. For example, you can switch to a another tty and runpkill -USR1 hyprlock
.SIGUSR2
- updates labels and images. See above.