i3lock-color(1)

📦
version 2.13.c.5 · 2 versions
, in nixos 26.05, nixpkgs unstable

okay so this is the i3lock-color(1) manual, and it’s literally the improved screen-locker bestie. 💖

✨ NAME ✨

i3lock-color — improved screen locker. That’s the name, that’s the vibe, no notes.

🌈 SYNOPSIS 🌈

i3lock-color [-v] [-n] [-b] [-i image.png] [-c color] [-t] [-p pointer]
[-u] [-e] [-f] [-m]

💅 DESCRIPTION 💅

i3lock-color is a simple screen locker like slock. After starting it, you’ll see a white screen (and yes, bestie, you can configure the color or an image). You can return to your screen by entering your password. Periodt.

🦋 FEATURES 🦋

  • i3lock-color forks, so you can combine it with an alias to suspend to RAM. Run i3lock-color && echo mem > /sys/power/state to get a locked screen after waking up your computer from suspend to RAM.
  • You can specify either a background color or a PNG image which will be displayed while your screen is locked.
  • You can specify whether i3lock-color should bell upon a wrong password.
  • i3lock-color uses PAM and therefore is compatible with LDAP, etc.

🎀 OPTIONS 🎀

  • -v, --version — Display the version of your i3lock-color.
  • -n, --nofork — Don’t fork after starting.
  • -b, --beep — Enable beeping. Be sure to not do this when you are about to annoy other people, like when opening your laptop in a boring lecture.
  • -u, --no-unlock-indicator — Disable the unlock indicator. i3lock-color will by default show an unlock indicator after pressing keys. This will give feedback for every keypress and it will show you the current PAM state (whether your password is currently being verified or whether it is wrong).
  • -i path, --image=path — Display the given PNG image instead of a blank screen.
  • --raw=format — Read the image given by --image as a raw image instead of PNG. The argument is the image’s format as <width>x<height>:<pixfmt>. The supported pixel formats are: native, rgb, xrgb, rgbx, bgr, xbgr, and bgrx. The native pixel format expects a pixel as a 32-bit (4-byte) integer in the machine’s native endianness, with the upper 8 bits unused. Red, green and blue are stored in the remaining bits, in that order.

Example:

--raw=1920x1080:rgb

You can use ImageMagick’s convert(1) program to feed raw images into i3lock:

convert wallpaper.jpg RGB:- | i3lock-color --raw 3840x2160:rgb --image /dev/stdin

This allows you to load a variety of image formats without i3lock-color having to support each one explicitly. You can also use it to resize images to the screen ratio:

convert wallpaper.jpg -resize $(xdpyinfo | grep dimensions | sed -r 's/^[^0-9]*([0-9]+x[0-9]+).*$/1/') RGB:- | i3lock-color --raw $(xdpyinfo | grep dimensions | sed -r 's/^[^0-9]*([0-9]+x[0-9]+).*$/1/'):rgb --image /dev/stdin

Note that $(xdpyinfo | grep dimensions | sed -r 's/^[^0-9]*([0-9]+x[0-9]+).*$/1/') gets you the current screen dimensions in the wxh (e.g. 1920x1080) format.

  • -c rrggbbaa, --color=rrggbbaa — Turn the screen into the given color instead of white. Color must be given in 4-byte format: rrggbbaa (i.e. ff0000ff is opaque red). Use the last byte for alpha. Setting this below FF (i.e. ff000088) will allow your screen to be shown translucently if you use a compositor (e.g. compton, xcompmgr).
  • -t, --tiling — If an image is specified (via -i) it will display the image tiled all over the screen.

Note: For all image options, with a multi-monitor setup, the image is visible on all screens.

  • -C, --centered — If an image is specified (via -i) it will display the image centered on the screen.
  • -F, --fill — If an image is specified (via -i) it will scale the image until it fills the screen. A portion of the image will be cropped.
  • -M, --max — If an image is specified (via -i) it will scale the image until either the width or the height fits the screen without being cropped. The border color can be set via -c.
  • -L, --scale — If an image is specified (via -i) it will stretch the image until both the width and the height fits the screen.
  • -p win|default, --pointer=win|default — If you specify default, i3lock-color does not hide your mouse pointer. If you specify win, i3lock-color displays a hardcoded Windows-Pointer (thus enabling you to mess with your friends by using a screenshot of a Windows desktop as a locking-screen).
  • -e, --ignore-empty-password — When an empty password is provided by the user, do not validate it. Without this option, the empty password will be provided to PAM and, if invalid, the user will have to wait a few seconds before another try. This can be useful if the XF86ScreenSaver key is used to put a laptop to sleep and bounce on resume or if you happen to wake up your computer with the enter key.
  • -f, --show-failed-attempts — Show the number of failed attempts, if any.
  • --debug — Enables debug logging. Note, that this will log the password used for authentication to stdout.
⚠️ bestie, --debug really does log the password used for authentication to stdout — that’s the warning, not a drill.

okay bestie, we're deep in the option buffet now — grab a drink, this is the good part 💅

  • -S number, --screen=number — tells i3lock which display gets the unlock indicator and the clock. no option given means they show up on every screen. heads up: this number is zero indexed, and the ordering depends on libxinerama (so like, it's vibes-based per setup, test it).
  • -B sigma, --blur=sigma — screenshot time ✨ it captures the screen and blurs it using sigma (that's the radius, bestie). images can still be overlaid over the blurred screenshot, so you're not locked out of stickers. alternatively: you can skip this whole option and instead give a translucent background color with the -c option — fully transparent or translucent — and let a compositor do the blurring for you (e.g. compton, picom). delegation, queen behaviour 👑
  • -k, --clock, --force-clock — displays the clock. --force-clock also shows the clock when there's indicator text, which is super useful if your clock isn't positioned together with the indicator 🕰️
  • --indicator — forces the indicator to stay visible 24/7 instead of only popping up on activity. main character energy, always on camera 💫
  • --radius — the radius of the circle. defaults to 90.
  • --ring-width — how thick the ring unlock indicator is. defaults to 7.0.
  • --{inside, ring}-color=rrggbbaa — sets the *idle color for the interior circle and the ring. note: use the individual options per element *unless your shell supports brace expansion (in which case you remove the spaces inside the curly braces). no cap, read that twice 🎀
  • --{inside, ring}ver-color=rrggbbaa — interior circle and ring color **while the password is being verified. the "hold on bestie, checking" era.
  • --{inside, ring}wrong-color=rrggbbaa — interior circle and ring color during those **incorrect password flashes. make it a dramatic red, you know you want to 💀
  • *--line-color=rrggbbaa* — the color of the line separating the inside circle from the outer ring. the little boundary, the personal space 🦋
  • --line-uses-{inside, ring} — overrides --line-color: the line just matches the {inside, ring} color instead. note: these two options conflict with each other, so pick one, don't be messy 🙈
  • *--{key, bs}hl-color=rrggbbaa* — the color of the highlight arcs on the ring when you press a key and when you hit backspace. instant feedback, we love to see it ⌨️
  • *--separator-color=rrggbbaa* — the color of the "seperators" (their spelling, luv u) at both ends of those highlight arcs on the ring.
  • --{verif, wrong, modif}-color=rrggbbaa — the color of the **status text while verifying, and when the password is wrong.
  • *--{layout, time, date, greeter}-color=rrggbbaa* — sets text colors. yes, all of them. go feral 🌈
  • --keylayout mode — displays the keylayout. it's positionable just like date, time, and the indicator. the modes go like this:
    • 0 — displays the full string returned by the query, i.e. "English (US)"
    • 1 — displays up until the first parenthesis, i.e. "English"
    • 2 — displays just the contents of the parenthesis, i.e. "US"

for all the following -str or -text options, some control characters (i.e. \n, \t) are supported. see CONTROL CHARACTERS for more details, iykyk.

  • --time-str="%H:%M:%S" — the format used to generate the time string. see strftime(3) for a full list of format specifiers.
  • --date-str="%A, %m %Y" — the format used to generate the date string.
  • --verif-text="verifying…" — the string shown while verifying the password/input/key/etc.
  • --wrong-text="wrong!" — the string shown when an incorrect password gets entered.
  • --noinput-text="no input" — the string shown when you press backspace with literally nothing to delete 😭
  • --lock-text="locking…" — the string shown while acquiring pointer and keyboard focus.
  • --lockfailed-text="lock failed!" — the string shown after failing to acquire pointer and keyboard focus. the tragedy arc 💀
  • --greeter-text="" — sets the greeter text.
  • --no-modkey-text — hides the modkey indicator (Num, Caps Lock ...). bye clutter 👋
  • --{time, date, layout, verif, wrong, modif, greeter}-align — sets the text alignment for the time, date, keylayout, verification, wrong, modifier and greeter texts. options:
    • 0 — centered (default)
    • 1 — left aligned
    • 2 — right aligned
  • *--{time, date, layout, verif, wrong, greeter, modif}outline-color=rrggbbaa* — sets the color of the outlines. yes, the glow-up is customizable ✨
  • *--{time, date, layout, verif, wrong, greeter}-font=sans-serif* — sets the font used to render the various strings.
  • *--{time, date, layout, verif, wrong, greeter}-size=number* — sets the font size used to render the various strings.
  • *--{time, date, layout, verif, wrong, greeter, modifier}outline-width=number* — sets the width of the outline.
  • --ind-pos="x-position:y-position" — where the unlock indicator sits. valid variables include:
    • x — x position of the current display. corresponds to the leftmost column of pixels on that display.
    • y — y position of the current display. corresponds to the topmost row of pixels on that display.
    • w — width of the current display.
    • h — height of the current display.
    • r — unlock indicator radius.
  • --time-pos="x-position:y-position" — where the time string sits. all the variables from --ind-pos work here, plus:
    • ix — x position of the indicator on the current display.
    • iy — y position of the indicator on the current display.
    • and if you're running the --bar-indicator option, these are also on the menu:
      • bw — width of the bar indicator.
      • bx — x position of the bar indicator on the current display.
      • by — y position of the bar indicator on the current display.
  • --date-pos="x-position:y-position" — where the date string sits. everything from --ind-pos and --time-pos works, plus:
    • tx — x position of the timestring on the current display.
    • ty — y position of the timestring on the current display.
  • --greeter-pos="x-position:y-position" — where the greeter string sits. all the variables from --ind-pos and --time-pos are usable here.
  • --pass-{media, screen, power, volume}-keys — lets these keys behave normally even while the screen is locked, by passing them through:
    • media — XF86AudioPlay, XF86AudioPause, XF86AudioStop, XF86AudioPrev, XF86AudioNext, XF86AudioMute, XF86AudioLowerVolume, XF86AudioRaiseVolume, XF86AudioMicMute
    • screen — XF86MonBrightnessUp, XF86MonBrightnessDown
    • power — XF86PowerDown, XF86PowerOff, XF86Sleep
    • volume — XF86AudioMute, XF86AudioLowerVolume, XF86AudioRaiseVolume
  • --custom-key-commands — enables custom shell commands for the media, screen, power and volume keys. it's an alternative to --pass-media keys that'll work in any environment. glow-up unlocked 🔥
  • --cmd-** — a shell command to run when the corresponding key is pressed. requires --custom-key-commands. the mapping is:
    • brightness-up — XF86MonBrightnessUp
    • brightness-down — XF86MonBrightnessDown
    • media-play — XF86AudioPlay
    • media-pause — XF86AudioPause
    • media-stop — XF86AudioStop
    • media-next — XF86AudioNext
    • media-prev — XF86AudioPrev
    • audio-mute — XF86AudioMute
    • volume-up — XF86AudioRaiseVolume
    • volume-down — XF86AudioLowerVolume
    • mic-mute — XF86AudioMicMute
    • power-down — XF86PowerDown
    • power-off — XF86PowerOff
    • power-sleep — XF86Sleep

🫶 the bar indicator era (still OPTIONS, don't worry)

  • --bar-indicator — replaces the usual ring indicator with a bar indicator. and yeah, it comes with perks 😌
  • --bar-direction={0, 1, 2} — sets which direction the bars grow in. 0 is the default (downwards, or rightwards, depending on the bar orientation). 1 is the reverse, and 2 is both.
  • --bar-orientation={vertical,horizontal} — whether the bar is vertically or horizontally oriented. defaults to horizontal.
  • --bar-step — the step each bar decreases by when a key is pressed. one random bar gets set to its max height, then each neighbor is set to (height - step*distance).
  • --bar-max-height — the maximum height a bar can reach. when a key is pressed, a random bar is set to this value, then its neighbors get its height minus the step value.
  • --bar-base-width — the thickness of the "base" bar that all the bars originate from. this bar also takes on the ring verification and wrong colors, so you get your authentication feedback from it 💫
  • --bar-color — sets the default color of the bar base.
  • --bar-periodic-step — how much the bars decrease by each time the screen is redrawn.
  • --bar-pos — works similarly to the time/date/indicator expressions. if you give it only one number, that sets the vertical offset from the top or left edge. if you give it two numbers as x:y, it sets the starting position of the bar.
  • --bar-count — the number of minibars to draw on each screen.
  • --bar-total-width — the total width of the bar. can be an expression.
  • --redraw-thread — starts a separate thread for redrawing the screen. potentially worse from a security standpoint, but it makes the bar indicator keep doing its usual periodic redraws while PAM is authenticating. tradeoffs, bestie ⚖️
  • *--refresh-rate=seconds-as-double* — the refresh rate of the indicator, in seconds. this should automatically align itself, but it's somewhat buggy currently. values less than one will work, but may result in poor system performance. don't come for me, that's just what the page says 🫠
  • --composite — some compositors have problems with i3lock-color trying to render over them, so this argument is disabled by default. however, some will work properly with it, so it's been left enabled. (yeah it says both, that's genuinely what it says 🙈)
  • --no-verify — does not verify the password entered by the user and unlocks immediately. use only for quickly testing new configurations, and remember to remove it to actually lock your screen! fr fr, do not ship this one 💀
  • --slideshow-interval — the interval to wait until switching to the next image.
  • --slideshow-random-selection — randomizes the order of the images. chaos, but make it aesthetic 🦋

✨ CONTROL CHARACTERS ✨

Okay so bestie, listen — control characters are fully supported in text OPTIONS and they work pretty much exactly like they do anywhere else. No weird lock-screen plot twist, no cap. 💅

Carriage Return (\r)

Moves you to the start of the line (the left edge). 📍

Heads up though: the characters that were already rendered still live there. So you're moving the cursor back, not hitting undo. It's giving "I'm standing somewhere new but the old vibes are still haunting the room" 😭

Line Feed (\n)

Moves you to the start of the next line (left edge). Fresh line, clean slate, main character energy. ✨

Backspace (\b)

Overwrites the last one char, if there is one. 🫶

Same little caveat as \r though: the rendered character would still live there. Backspace moves you back, it does not delete the vibe. 🙈

Tab (\t)

Moves to the next tab stop position. 🎀

The width of one character for the purpose of moving is the same as the character 'a'.

Note: the width may be strange if the font is not mono-spaced. So like, if you picked a cute proportional font and your tabs are looking unhinged — that's why, bestie, it's not you. 💀

🌈 SEE ALSO 🌈

  • xautolock(1) — use i3lock-color as your screen saver 👑
  • convert(1) — feed a wide variety of image formats to i3lock-color 🖼️

🦋 HOMEPAGE 🦋

https://github.com/Raymo111/i3lock-color

Please report bugs and submit pull-requests as follows — yes, there are two doors, pick the right one, iykyk:

💖 AUTHORS 💖

The icons who made this happen, fr fr:

  • Michael Stapelberg <michael+i3lock at stapelberg dot de>
  • Jan-Erik Rediger <badboy at archlinux.us>
  • Pandora <pandora at techfo dot xyz>
  • Raymond Li <i3lock-color at raymond.li>

And that's the whole page, bestie — you ate that. 🍓 This little masterpiece lives on Linux, dated JAN 2022, and answers to the name i3lock-color(1). Go lock your screen in style. 💜

📦 where this page comes from