Configuring Theom - AxOS-project/Theom GitHub Wiki

Configuring Theom

The main configuration file for Theom is located at:

~/.config/.theom/config.toml

This file controls system-wide settings like themes, widgets, compositor modes, and more.

Important Notes

[!IMPORTANT] Do not change the structure Only customize the values in this file. Changing or removing keys (e.g., [appearance], theme = ...) may lead to unexpected behavior or errors.

Config Structure

[appearance]

Controls the desktop's visual theme and wallpaper.

[appearance]
theme = "light"
wallpaper = "/usr/share/backgrounds/dunes-sun.jpg"
  • theme: Can be "light" or "dark" — applies to system themes if supported.
  • wallpaper: Path to your wallpaper image. Use a full absolute path.

[bar]

Controls which system bar is used.

[bar]
polybar_layout = "stuck"
use_eww = true
  • polybar_layout: Layout style for Polybar if used. Only applies if use_eww = false.
  • use_eww: If true, Eww is used for the bar and widgets. If false, Polybar will be used.

Recommended: Use use_eww = true for a more modern and efficient setup. Polybar is deprecated.

[widgets]

Manages widget behavior and which ones are visible.

[widgets]
enable_widgets = true
show = [
    "~/.config/widgets/time.lua",
    "~/.config/widgets/uptime.lua"
]
  • enable_widgets: Enables or disables widget rendering entirely.
  • show: List of widget files to be loaded. These should be Lua files and must exist on disk.

Widgets must follow the conky lua syntax.

[compositor]

Controls window compositing (transparency, shadows, etc.).

[compositor]
compositing = true
compositing_mode = "performance"

  • compositing: Enables or disables compositing entirely.

  • compositing_mode:

    • "performance" – lightweight and fast (recommended)
    • "compatibility" – heavier, but prevents some visual glitches (e.g., useful for VMs or low-end GPUs)

[osd]

On-screen display settings (currently deprecated).

[osd]
osd = false
  • osd: This feature is deprecated. Setting this does enable the osd, but is kept for experimental purposes only.

Troubleshooting

If you accidentally break this config:

  1. Enter a TTY (Ctrl + Alt + F3)

  2. Delete or restore the config:

    rm ~/.config/.theom/config.toml
cp /usr/share/theom/config/.theom/config.toml ~/.config/.theom/

  3. Re-login