Skip to content

Lock Screen

Jump to bottom
P3DROVFX edited this page Oct 12, 2026 · 1 revision

Lock Screen

The lock screen is a real Wayland session lock drawn by the shell (the ext-session-lock-v1 protocol): while it is up, the compositor will not show or accept input for any other client. On top of the security it is a showpiece — your wallpaper (image or video) blurred and tinted, the same desktop widgets you arranged, a Now Playing strip and a live sports score at the top, notifications with privacy rules, a fingerprint prompt, shaped password characters, a touch keyboard for tablets and an Always On Display. The legacy hyprlock is kept as an optional fallback.

Quick start

  • Super + L locks the screen (it calls lock activate and loginctl lock-session). Or the Session screen (Ctrl + Alt + Delete), the Dashboard, the launcher (lock), or idle.
  • Type your password and press Enter (or touch the confirm button). A configured fingerprint reader unlocks by touch without typing.
  • Settings → Lock Screen has a live preview of the real lock screen at the top: hover a look to try it, change effects with sliders, and arrange widgets and islands (the button opens Edit Mode on the Lock Screen tab).
qs -c ii ipc call lock activate     # lock now
qs -c ii ipc call lock sleep        # lock with an instant opaque shade, for suspend
qs -c ii ipc call lock focus        # re-focus the prompt

When it locks (idle)

~/.config/hypr/hypridle.conf ships a conservative ladder; edit it to taste:

After Does
2 min Dims every screen by 50 % (idleDim — a scrim in the shell, not the backlight, so it covers external monitors and the lock screen and doesn't trip brightness OSDs)
5 min loginctl lock-session → the shell locks
10 min Screens off (DPMS)
15 min Suspend

Before suspend hypridle runs qs ipc call lock sleep: it locks with an opaque shade at once, so the last frame left on the panel can never show the desktop mid-transition, and it stops the fingerprint prompt — some readers' drivers (egismoc for one) crash fprintd if the machine sleeps with a verify in flight. After wake, lockFocus fades the shade out and re-focuses the prompt (Hyprland sometimes un-focuses the lock surface on resume). If the shell isn't running, it falls back to a plain logind lock.

What is on the lock screen

The surface has a main island in the middle (fingerprint indicator, the password field, a confirm button), a left island (battery, caps lock, next alarm, weather, keyboard layout, keep-awake, active Mode) and a right island (sleep, power, restart), plus a top strip with Now Playing and live sports side by side (centred alone when only one shows), and your desktop widgets.

  • Order and visibility are yours: lock.islands.main/left/right hold the draw order and lock.islands.hidden what to take off. Edit Mode's Lock Screen tab edits them with the same drag and remove-badge gestures as the bar and dock. The main island can't be hidden — a lock you cannot answer is not a lock — and the password field itself doesn't move.
  • Widgets follow each widget's lock behaviour (hide, keep where it is, centre, lock-only, or its own position on the lock screen) — see Desktop Widgets and Edit Mode. Centred widgets get lock.centerSpacing between them and line up horizontally or vertically.
  • Password characters can be drawn as random Material shapes instead of dots (materialShapeChars), with a ripple across the wallpaper wherever you touch or click (rippleEffect). The cookie clock widget can hold still on lock.
  • Notifications (lock.notifications.*) — see below.
  • Touch keyboard — the regular on-screen keyboard is a layer-shell surface, and the session lock covers every layer, so a tablet would be impossible to unlock. The lock surface draws its own keyboard (lock.touchKeyboard.show: auto = on in touch-first families, always, never; mode: full text or a numeric pin pad).

The look

Everything over the wallpaper is real-time and adjustable under Transparency & Blur: window blur (radius 45 by default), desaturation (0.25), a colour wash (off), a vignette (0.3) and the wallpaper zoom; zero turns an effect off. Six presets: Clear, Soft, Frosted (default), Muted, Tinted, Noir. Lock wallpaper can be an image or a video (the video decodes only while the screen is locked and is muted — the lock wallpaper is only a stored path; it never takes over the desktop's own video wallpaper, see Wallpaper System).

Lock animation picks how the desktop turns into the lock screen: Parallax engine (classic: the wallpaper centres and zooms), Gnome Like (the overview design: the wallpaper zooms out into a rounded card over a blurred, dimmed backdrop) or Material Shape (a random shape closes in over a solid backdrop). The bar fades or slides away during the transition without being destroyed, so the layer topology never changes mid-animation.

Security

  • The session lock — the compositor enforces it; a crash of the lock client keeps the session locked (the protocol's design).
  • Windows are pushed away too. As an extra anti-bypass layer, while locked the shell moves each monitor to a temporary high-numbered workspace (2147483647 − n) in one hyprctl --batch, so if the lock layer ever failed, your windows would not be on screen; unlock restores the previous workspaces and pinned windows (after the zoom-in finishes, with workspace animations switched off for the batch). The bar's workspace numbers stay hidden until the restore completes, so you never see the temporary ids.
  • Password — checked through PAM (the system's pam_unix stack, via Quickshell's PAM integration); the shell never sees or stores it beyond the check.
  • Fingerprint (lock.security.fingerprint.*) — uses pam_fprintd in a second PAM transaction so touching the reader and typing never fight. Needs fprintd and an enrolled finger; Settings → Lock Screen → Fingerprint enrols and deletes prints (it shows how many touches the reader needs — 5 on a swipe reader, up to 16 on a match-on-chip press reader — and which finger each print is, with your own labels). Enrolment needs only your own password through the shell's polkit agent, no root. The prompt gives up after PAM's own three tries and re-arms on a new password attempt; after a suspend it waits for the reader to finish USB-resetting before starting.
  • Keyring (lock.security.unlockKeyring) — unlocking with your password also unlocks the login keyring, so apps don't ask for it again. Unlocking by fingerprint can't do that (no password to give), and the setting says so.
  • Guarded power (lock.security.requirePasswordToPower) — power off / restart from the lock screen ask for your password first; otherwise anyone at the keyboard can power off.
  • hyprlock fallback — lock.useHyprlock makes lock requests start hyprlock instead (using ~/.config/hypr/hyprlock.conf); lock.launchOnStartup locks at session start.

Notifications on the lock screen

Showing notifications while locked is a privacy trade-off, so it is explicit (lock.notifications):

Option Meaning
enable Show them at all
position top_left, top_right, bottom_left, bottom_right
privacy full (everything), redacted (default — the app and a "new notification" line, no content) or countOnly
onlySinceLock Only those that arrived while locked
maxShown, zoomPercent How many, and 50–200 % size
defaultPolicy, alwaysShowApps, neverShowApps Per-app rules (show / hide for apps with no rule)
filters.skipTransient, skipLowUrgency, criticalOverride Skip transient or low-urgency ones; whether critical notifications bypass redaction

The settings preview feeds sample notifications through the real component, so position, privacy, zoom and maximum are visible even with nothing to show. See Notifications.

Always On Display

The old "OLED saver" blackout became an Always On Display in the style of One UI: pure black with only the widgets the lock screen keeps, in greyscale, at their lock-screen positions. A click or key wakes it (moving the mouse doesn't; modifier keys alone don't, since Super is half of a shortcut), and the key that woke it also reaches the password field.

  • On the desktop (Super + R, qs -c ii ipc call oledSaver toggle): a black window with the widgets sliding from their desktop positions to their lock positions while the black comes up.
  • On the lock screen: after oledSaver.lockTimeout minutes (default 10; 0 = never) without input, all screens turn into the AOD. Unlocking clears it.
  • Anti burn-in (oledSaver.antiBurnIn): once a minute, only while the AOD is visible, widgets shift by a small pseudo-random orbit (up to ±24 px in steps of at least 8 px), eased, and return when you leave.
  • Master switch oledSaver.enable (it turns off the shortcut, the lock timer and any active AOD); cursorHideDelay hides the pointer after 5 s without movement.

Configuration (Config.options.lock)

Key Default
useHyprlock, launchOnStartup off, off
blur.enable / radius / extraZoom on, 45, 1
desaturate.enable / amount on, 0.25
colorWash.enable / amount off, 0.5
vignette.enable / amount on, 0.3
centerSpacing, centerAlignment 20, horizontal
nowPlaying, sports, showAlarm, showWeather, showLockedText on
zoomAnimation.enabled / style on, default (default, gnome, material-shape)
materialShapeChars, rippleEffect on, on
touchKeyboard.show / mode auto, text
security.unlockKeyring, requirePasswordToPower on, off
security.fingerprint.enable / showIndicator / labels on, on, []

Under the hood

Piece Role
modules/common/panels/lock/LockScreen.qml The WlSessionLock, per-screen surfaces, IPC (lock activate/sleep/focus/fingerStop), global shortcuts (lock, lockFocus, lockFingerStop), idle hand-off, privacy shade, keyring unlock
modules/common/panels/lock/LockContext.qml, pam/fprintd.conf PAM password and fingerprint transactions
modules/ii/lock/Lock.qml, LockSurface.qml, LockNotifications.qml The ii lock: workspace push-away and restore, the surface, notifications
services/Fingerprint.qml fprintd device state and enrolment (shared by the lock and Settings)
modules/common/functions/lock_islands.js Island order arithmetic
modules/ii/oledSaver/OledSaver.qml Desktop AOD
modules/settings/configs/lockscreen/ The Settings page: LockPreview, LockEffectsPane, LockPresetStrip…

Related pages

← Back to Home

Clone this wiki locally