Skip to Content
Veila
Configuration

Visuals Reference

Full reference for all [visuals.*] sections in config.toml.

Color Values

Color fields accept these formats:

color = "#202833"            # hex RGB
color = "#202833CC"          # hex RGBA (last two digits = alpha)
color = "rgb(32, 40, 51)"
color = "rgba(32, 40, 51, 0.8)"

All visual styling lives under [visuals.*] in config.toml.

Migrating Old Visual Keys

Update old flat keys in your config, custom themes, and includes to nested sections. veila check-config reports old keys as unknown; bundled themes already use the current format.

For example:

[visuals.clock]
color = "#F8FBFFF5"
font_size = 88

[visuals.input]
background_color = "#FFFFFF0A"
width = 310
radius = 10

Replace these old keys under [visuals]:

Old key(s)Nested replacement
input_font_family, input_font_weight, input_font_style, input_font_size[visuals.input]: font_family, font_weight, font_style, font_size
input_width, input_height, input_radius, input_border_width, input_mask_color[visuals.input]: width, height, radius, border_width, mask_color
input_border[visuals.input]: border_color
avatar_background_color, avatar_size, avatar_radius, avatar_placeholder_padding, avatar_icon_color, avatar_ring_color, avatar_ring_width[visuals.avatar]: remove the avatar_ prefix
username_color, username_font_size[visuals.username]: color, font_size
clock_font_family, clock_font_weight, clock_font_style, clock_font_size, clock_style, clock_format, clock_color, clock_meridiem_font_size, clock_meridiem_x, clock_meridiem_y[visuals.clock]: remove the clock_ prefix
date_color, date_font_size[visuals.date]: color, font_size
placeholder_color[visuals.placeholder]: color
eye_icon_color[visuals.eye]: color
keyboard_color, keyboard_background_size, keyboard_size[visuals.keyboard]: remove the keyboard_ prefix
battery_color, battery_background_color, battery_background_size, battery_size[visuals.battery]: remove the battery_ prefix
status_color[visuals.status]: color
foreground, muted, pending, rejected[visuals.palette]: keep the same key names
panelSet [visuals.avatar].background_color and each [[visuals.backdrop]].color explicitly
panel_borderRemove it; it had no effect on the lock scene

Replace [visuals] input = "#..." or input color arrays with [visuals.input].background_color. Keep nested values if both formats exist.

Precedence: theme → includes → main config. Migration may activate previously ignored input styling; compare a preview and run veila check-config --config /path/to/config.toml.

Backdrop

Add backdrops for blur panels, solid panels, or widget anchors.

[[visuals.backdrop]]
name = "auth_panel"
enabled = true
show_when = "always"
mode = "blur"
color = "#00000040"
blur_strength = 12
radius = 24
border_color = "#FFFFFF18"
border_width = 1
width = 540
height = 600
full_width = false
full_height = true
inset_top = 110
inset_bottom = 110
inset_left = 0
inset_right = 0
halign = "right"
x = -100
z = 0
KeyWhat it doesDefault
nameBackdrop name for relative_tounset
enabledShow or hide this backdrop layertrue
show_whenConditional visibility. Supports "always", "battery", "weather" and "now_playing""always"
modeBackdrop mode. Supports "blur" and "solid""blur"
colorFill or blur tint color, including alpha"#080A0E6B"
blur_strengthPanel blur, capped at 24. Wallpaper blur supports 0..255.12
radiusRadius in pixels0
border_colorBorder color, including alpha"#FFFFFF"
border_widthBorder width in pixels0
widthBackdrop width in pixels. Ignored when full_width = true560
heightBackdrop height in pixels. Ignored when full_height = true600
rotateClockwise rotation in degrees around the backdrop center0
full_widthExpand the backdrop to the full output widthfalse
full_heightExpand the backdrop to the full output heightfalse
inset_topTop trim in pixels when full_height = true0
inset_bottomBottom trim in pixels when full_height = true0
inset_leftLeft trim in pixels when full_width = true0
inset_rightRight trim in pixels when full_width = true0
halignHorizontal anchor for placement"center"
valignVertical anchor for placement"top"
xHorizontal offset from halign0
yVertical offset from valign0
zLayer order. Higher values draw above lower values0

Large blur regions can delay the scene. Use smaller panels, lower blur, or mode = "solid". The secure frame appears first.

Use show_when to match a backdrop to its widget:

  • battery: show while battery data exists.
  • weather: follow weather widget visibility.
  • now_playing: follow media widget visibility.

Set relative_to to a backdrop name for panel-relative placement; otherwise widgets use screen coordinates. Panel rotation does not rotate widgets.

[[visuals.backdrop]]
name = "clock_backdrop" # Can be any unique name
width = 540
full_height = true
inset_top = 110
inset_bottom = 110
rotate = -4
halign = "right"
x = -100

[visuals.clock]
halign = "center"
valign = "top"
x = 0
y = 40
relative_to = "clock_backdrop" # Name of the backdrop to position relative to

Layer

Add custom layers for text labels and Nerd Font icons.

[[visuals.layer]]
name = "lock_icon"
enabled = true
kind = "icon"
text = "\uf023"
font_family = "Symbols Nerd Font"
font_weight = 700
font_style = "normal"
font_size = 64
color = "#FFFFFFEE"
background_color = "#00000040"
width = 120
height = 120
padding = 16
radius = 28
halign = "center"
valign = "center"
y = -180
z = 20

[[visuals.layer]]
name = "custom_message"
enabled = true
kind = "text"
text = "locked"
font_family = "Inter"
font_size = 28
color = "#FFFFFFCC"
halign = "center"
valign = "center"
y = -90
z = 21
KeyWhat it doesDefault
nameLayer name for easier theme organization.unset
enabledShow or hide this layer.true
kindLayer content type. Supports "text" and "icon"."text"
textText or Nerd Font glyph to render. Empty text hides the layer.unset
font_familyFont family used for the layer. Use an installed Nerd Font for icons.unset
font_weightFont weight.400
font_styleFont style. Supports "normal" and "italic"."normal"
font_sizeFont size in pixels.24
colorText or icon color, including alpha.palette foreground
background_colorOptional layer background color, including alpha.unset
widthOptional layer box width in pixels. Expands if the content needs more space.content width
heightOptional layer box height in pixels. Expands if the content needs more space.content height
paddingInner padding in pixels.0
radiusBackground radius in pixels.0
halignHorizontal anchor for placement."center"
valignVertical anchor for placement."center"
xHorizontal offset from halign.0
yVertical offset from valign.0
relative_toOptional named backdrop target.unset
zLayer order among custom layers. Higher values draw above lower values.0

Avatar

[visuals.avatar]
enabled = true
image_path = "/path/to/avatar.jpg"
size = 150
radius = 75
background_color = "#FFFFFF14"
placeholder_padding = 28
ring_color = "#94B2FF"
ring_width = 0
icon_color = "#FFFFFF"
halign = "center"
valign = "center"
x = 0
y = -120
KeyWhat it doesDefault
enabledShow or hide the avatar.true
image_pathAvatar image path.none
sizeAvatar diameter in pixels. Explicit sizes are preserved unless they would exceed the viewport safety limit.150
radiusAvatar corner radius in pixels. Unset keeps it fully circular.unset
background_colorAvatar fill color, including alpha."#FFFFFF0F"
placeholder_paddingInner inset for the fallback icon.28
ring_colorRing color around the avatar."#94B2FF"
ring_widthRing thickness in pixels. 0 disables it.0
icon_colorFallback icon color when no image is available."#FFFFFF"
halignHorizontal anchor for placement.unset
valignVertical anchor for placement.unset
xHorizontal offset from halign.unset
yVertical offset from valign.unset
relative_toOptional named backdrop target.unset

Without image_path, Veila uses ~/.face, then the bundled placeholder.


Username

[visuals.username]
enabled = true
text = "anonymous"
font_family = "Google Sans Flex"
font_weight = 400
font_style = "normal"
color = "#FFFFFFD6"
font_size = 28
halign = "center"
valign = "center"
x = 0
y = 0
KeyWhat it doesDefault
enabledShow or hide the username label.true
textOptional display-only username override.none
font_familyFont family."Google Sans Flex"
font_weightFont weight.400
font_styleFont style. Supports "normal" and "italic"."normal"
colorText color, including alpha."#FFFFFFD6"
font_sizeUsername font size in pixels.28
halignHorizontal anchor for placement.unset
valignVertical anchor for placement.unset
xHorizontal offset from halign.unset
yVertical offset from valign.unset
relative_toOptional named backdrop target.unset

Clock

[visuals.clock]
enabled = true
style = "standard"
format = "24h"
font_family = "Geom"
font_weight = 600
font_style = "normal"
color = "#FFFFFF66"
font_size = 88
meridiem_font_size = 22
meridiem_x = 6
meridiem_y = 7
halign = "center"
valign = "top"
x = 0
y = 40
KeyWhat it doesDefault
enabledShow or hide the clock.true
styleClock layout style. Supports "standard" and "stacked"."standard"
formatTime format. Supports "24h" and "12h"."24h"
font_familyFont family."Geom"
font_weightFont weight.600
font_styleFont style. Supports "normal" and "italic"."normal"
colorText color, including alpha."#FFFFFF66"
font_sizeClock font size in pixels.88
meridiem_font_sizeAM/PM font size in pixels in 12h mode.22
meridiem_xHorizontal offset for the meridiem marker.6
meridiem_yVertical offset for the meridiem marker.7
halignHorizontal anchor for placement.unset
valignVertical anchor for placement.unset
xHorizontal offset from halign.unset
yVertical offset from valign.unset
relative_toOptional named backdrop target.unset

The clock stays on one line at any font size.


Date

[visuals.date]
format = "long"
enabled = true
font_family = "Geom"
font_weight = 600
font_style = "normal"
color = "#FFFFFF80"
font_size = 16
halign = "center"
valign = "top"
x = 0
y = 140
KeyWhat it doesDefault
enabledShow or hide the date.true
formatDate format preset. Supports "long", "iso", "dmy-dots", "ymd-dots", "mdy-slash", "dmy-slash", and "short"."long"
font_familyFont family."Geom"
font_weightFont weight.600
font_styleFont style. Supports "normal" and "italic"."normal"
colorText color, including alpha."#FFFFFF80"
font_sizeDate font size in pixels.16
halignHorizontal anchor for placement.unset
valignVertical anchor for placement.unset
xHorizontal offset from halign.unset
yVertical offset from valign.unset
relative_toOptional named backdrop target.unset

Available date formats:

FormatExample
"long"Wednesday, May 13
"iso"2026-05-13
"dmy-dots"13.05.2026
"ymd-dots"2026.05.13
"mdy-slash"05/13/2026
"dmy-slash"13/05/2026
"short"Wed, May 13

Password Input

[visuals.input]
placeholder = "Password"
reveal_on_interaction = false
reveal_mode = "input"
font_family = "Google Sans Flex"
font_weight = 400
font_style = "normal"
font_size = 16
background_color = "#FFFFFF0D"
border_color = "#FFFFFF00"
width = 310
height = 54
radius = 10
border_width = 0
mask_color = "#FFFFFF"
halign = "center"
valign = "center"
x = 0
y = 80
KeyWhat it doesDefault
placeholderPlaceholder text inside the password field."Password"
reveal_on_interactionHide auth UI until the first keypress or pointer press.false
reveal_modeHidden-auth scope. Supports "input" and "full"."input"
reveal_hintHelper text fallback used by [visuals.reveal] when needed."Press any key or click to continue"
font_familyInput font family."Google Sans Flex"
font_weightInput font weight.400
font_styleInput font style. Supports "normal" and "italic"."normal"
font_sizeInput font size in pixels.16
background_colorField fill color, including alpha."#FFFFFF0D"
border_colorField border color, including alpha."#FFFFFF00"
widthField width in pixels.310
heightField height in pixels.54
radiusField corner radius in pixels.10
border_widthField border width in pixels. 0 disables it.0
mask_colorBullet color for hidden password characters."#FFFFFF"
halignHorizontal anchor for placement.unset
valignVertical anchor for placement.unset
xHorizontal offset from halign.unset
yVertical offset from valign.unset
relative_toOptional named backdrop target.unset

reveal_mode = "input" hides input and status. "full" also hides the avatar and username.


Reveal

Style the prompt shown while the password area is hidden.

[visuals.reveal]
mode = "shown"
text = "Press any key or click to continue"
color = "#FFFFFF99"
font_family = "Google Sans Flex"
font_weight = 400
font_style = "normal"
font_size = 16
KeyWhat it doesDefault
modeReveal helper visibility. Supports "shown" and "hidden"."shown"
textText shown while auth UI is hidden."Press any key or click to continue"
colorText color, including alpha.falls back to [visuals.placeholder]
font_familyFont family.falls back to [visuals.input]
font_weightFont weight.falls back to [visuals.input]
font_styleFont style.falls back to [visuals.input]
font_sizeReveal font size in pixels.falls back to [visuals.input].font_size when unset

Placeholder

Style the empty password field’s hint text.

[visuals.placeholder]
enabled = true
color = "#FFFFFF99"
KeyWhat it doesDefault
enabledShow or hide the placeholder text.true
colorPlaceholder color, including alpha."#FFFFFF99"

The placeholder text itself comes from [visuals.input].placeholder.


Status

Style authentication progress and error messages.

Submitting starts a spinner; “Checking...” appears after one second. Rejection shows an error and any retry countdown.

[visuals.status]
enabled = true
mode = "inline"
color = "#FFE0A0E0"
pending_color = "#ECECECE0"
rejected_color = "#FF5353E0"
halign = "center"
valign = "bottom"
x = 0
y = -24
KeyWhat it doesDefault
enabledShow or hide status output.true
modeAuth feedback mode. Supports "inline", "external", and "hidden"."inline"
colorGeneral status text color, including alpha."#FFE0A0E0"
pending_colorPending auth color override.unset
rejected_colorRejected auth color override.unset
halignHorizontal anchor for external placement.unset
valignVertical anchor for external placement.unset
xHorizontal offset from halign.unset
yVertical offset from valign.unset
relative_toOptional named backdrop target.unset

Use inline for feedback inside the field, external for a separate widget, or hidden to hide it.


Eye icon

Style the button that shows or hides the typed password.

[visuals.eye]
enabled = true
color = "#FFFFFFB8"
KeyWhat it doesDefault
enabledShow or hide the reveal toggle icon.true
colorIcon color, including alpha."#FFFFFFB8"

Caps Lock icon

Style the Caps Lock warning icon.

[visuals.caps_lock]
enabled = true
color = "#FFD37AA3"
KeyWhat it doesDefault
enabledShow or hide the Caps Lock icon.true
colorIcon color, including alpha.unset

Keyboard

Style the active keyboard layout indicator.

[visuals.keyboard]
enabled = true
background_color = "#FFFFFF0D"
background_size = 46
radius = 23
color = "#FFFFFFAD"
size = 16
halign = "right"
valign = "top"
x = -24
y = 17
KeyWhat it doesDefault
enabledShow or hide the keyboard layouttrue
background_colorBackground color"#FFFFFF0D"
background_sizeHeight in pixels. 0 to hide background46
radiusRadius in pixels23
colorText color"#FFFFFFAD"
sizeKeyboard label font size16
halignHorizontal anchor for placement"right"
valignVertical anchor for placement"top"
xHorizontal offset from halign-24
yVertical offset from valign17
relative_toNamed backdrop targetunset

Battery

Style the battery indicator.

[visuals.battery]
enabled = true
background_color = "#FFFFFF0D"
background_size = 46
radius = 23
color = "#FFFFFFAD"
size = 20
halign = "right"
valign = "top"
x = -78
y = 17
KeyWhat it doesDefault
enabledShow or hide the batterytrue
background_colorBackground color"#FFFFFF0D"
background_sizeHeight in pixels. 0 to hide the chip background46
radiusRadius in pixels23
colorIcon and text color"#FFFFFFAD"
sizeBattery icon size20
halignHorizontal anchor for placement"right"
valignVertical anchor for placement"top"
xHorizontal offset from halign-78
yVertical offset from valign17
relative_toNamed backdrop targetunset

Power Buttons

Configure suspend, reboot, and poweroff buttons under [visuals.power.<action>].

The supervisor handles power actions through logind. Disabled buttons cannot send actions; themes cannot run power commands.

[visuals.power.suspend]
enabled = true
background_color = "#FFFFFF0D"
background_size = 46
radius = 23
color = "#FFFFFFAD"
size = 20
confirm = false
halign = "right"
valign = "top"
x = -132
y = 21

[visuals.power.reboot]
enabled = false
confirm = true
x = -186
y = 21

[visuals.power.poweroff]
enabled = false
confirm = true
x = -240
y = 21
KeyWhat it doesDefault
enabledShow or hide this power buttonfalse
background_colorBackground color"#FFFFFF0A"
background_sizeHeight in pixels. 0 to hide the chip background46
radiusRadius in pixels23
colorIcon color"#FFFFFFAD"
sizeIcon size20
confirmRequire a second click before sending the actionfalse for suspend, true for reboot and poweroff
halignHorizontal anchor for placement"right"
valignVertical anchor for placement"top"
xHorizontal offset from halign-132, -186, or -240
yVertical offset from valign21
relative_toNamed backdrop targetunset

With confirmation enabled, click twice within 5 seconds.


Power Status

Style the countdown indicator for automatic power actions.

This feature is unfinished and may not work as expected.

[visuals.power_status]
enabled = false
halign = "right"
valign = "top"
x = -24
y = 17
KeyWhat it doesDefault
enabledShow or hide the power countdown/status chip.false
halignHorizontal anchor for placement."right"
valignVertical anchor for placement."top"
xHorizontal offset from halign.-24
yVertical offset from valign.17
relative_toOptional named backdrop target.unset

The indicator appears while locked with an active power timer.


Weather

Style the weather widget. Enable it first in Weather settings.

Weather icon

[visuals.weather.icon]
enabled = true
size = 40
opacity = 80
halign = "left"
valign = "bottom"
x = 40
y = -122
KeyWhat it doesDefault
enabledShow or hide the weather icon.true
sizeIcon size in pixels.40
opacityIcon opacity percentage.50
halignHorizontal anchor for placement."left"
valignVertical anchor for placement."bottom"
xHorizontal offset from halign.30
yVertical offset from valign.-112
relative_toOptional named backdrop target.unset

Temperature

[visuals.weather.temperature]
enabled = true
font_size = 40
font_family = "Geom"
font_weight = 600
font_style = "normal"
letter_spacing = 0
color = "#FFFFFF74"
halign = "left"
valign = "bottom"
x = 30
y = -66
KeyWhat it doesDefault
enabledShow or hide the temperature text.true
font_sizeTemperature font size in pixels.40
font_familyFont family."Geom"
font_weightFont weight.600
font_styleFont style."normal"
letter_spacingExtra letter spacing.0
colorText color, including alpha."#FFFFFF74"
halignHorizontal anchor for placement."left"
valignVertical anchor for placement."bottom"
xHorizontal offset from halign.30
yVertical offset from valign.-66
relative_toOptional named backdrop target.unset

Location

[visuals.weather.location]
enabled = true
font_size = 22
font_family = "Google Sans Flex"
font_weight = 400
font_style = "normal"
color = "#D6E3FF5C"
halign = "left"
valign = "bottom"
x = 30
y = -34
KeyWhat it doesDefault
enabledShow or hide the location text.true
font_sizeLocation font size in pixels.22
font_familyFont family."Google Sans Flex"
font_weightFont weight.400
font_styleFont style."normal"
colorText color, including alpha."#D6E3FF5C"
halignHorizontal anchor for placement."left"
valignVertical anchor for placement."bottom"
xHorizontal offset from halign.30
yVertical offset from valign.-34
relative_toOptional named backdrop target.unset

Now Playing

Style media artwork, artist, and title.

[visuals.now_playing]
enabled = true
fade_duration_ms = 320
KeyWhat it doesDefault
enabledMaster switch for the now-playing widget.true
fade_duration_msCross-fade duration for metadata transitions.320

Artwork

[visuals.now_playing.artwork]
enabled = true
size = 44
radius = 8
opacity = 90
halign = "right"
valign = "bottom"
x = -388
y = -56
KeyWhat it doesDefault
enabledShow or hide the artwork block.true
sizeArtwork size in pixels, capped to the viewport safety limit.44
radiusArtwork corner radius. Clamped to half the resolved artwork size.8
opacityArtwork opacity percentage.90
halignHorizontal anchor for placement."right"
valignVertical anchor for placement."bottom"
xHorizontal offset from halign.-388
yVertical offset from valign.-56
relative_toOptional named backdrop target.unset

Artwork loads after lock confirmation and may appear after the text. Oversized images are skipped.

Artist

[visuals.now_playing.artist]
enabled = true
width = 318
color = "#FFFFFF63"
font_family = "Google Sans Flex"
font_size = 16
font_weight = 400
font_style = "normal"
halign = "right"
valign = "bottom"
x = -52
y = -88
KeyWhat it doesDefault
enabledShow or hide the artist line.true
widthMaximum text width before truncation.318
colorText color, including alpha."#FFFFFF63"
font_familyFont family."Google Sans Flex"
font_sizeArtist font size in pixels.16
font_weightFont weight.400
font_styleFont style."normal"
halignHorizontal anchor for placement."right"
valignVertical anchor for placement."bottom"
xHorizontal offset from halign.-52
yVertical offset from valign.-88
relative_toOptional named backdrop target.unset

Title

[visuals.now_playing.title]
enabled = true
width = 318
color = "#FFFFFFAF"
font_family = "Google Sans Flex"
font_size = 16
font_weight = 400
font_style = "normal"
halign = "right"
valign = "bottom"
x = -52
y = -56
KeyWhat it doesDefault
enabledShow or hide the title line.true
widthMaximum text width before truncation.318
colorText color, including alpha."#FFFFFFAF"
font_familyFont family."Google Sans Flex"
font_sizeTitle font size in pixels.16
font_weightFont weight.400
font_styleFont style."normal"
halignHorizontal anchor for placement."right"
valignVertical anchor for placement."bottom"
xHorizontal offset from halign.-52
yVertical offset from valign.-56
relative_toOptional named backdrop target.unset

Artist and title text stays on one line, with an ellipsis when too long.


Monitor Output

Every monitor is locked. By default, each shows the full UI:

[visuals.outputs]
ui_mode = "all"

Use "single" for one prompt and background-only secondary monitors:

[visuals.outputs]
ui_mode = "single"
ui_output = "DP-1"

ui_output accepts one monitor name, not a list.

KeyWhat it doesDefault
ui_modeChooses whether the full UI is rendered on all outputs or only one. Supports "all" and "single"."all"
ui_outputOutput name used when ui_mode = "single".focused output, then first available output

Set ui_output to pin the prompt. Otherwise it follows keyboard or pointer focus, starting on the first configured output.

Each monitor uses its own size and scale, including fractional scaling when supported.


Default Palette

Widgets use these colors when no individual color is set.

[visuals.palette]
foreground = "#F0F4FA"
muted = "#444E66"
pending = "#ECECEC"
rejected = "#FF5353"
KeyWhat it doesDefault
foregroundShared foreground text color."#F0F4FA"
mutedShared muted text color."#444E66"
pendingShared pending-state fallback color."#ECECEC"
rejectedShared rejected-state fallback color."#FF5353"

On this page