Creating a Custom Omarchy Theme with colors.toml and Template Placeholders

Omarchy generates desktop configurations by substituting color tokens defined in colors.toml into template files using {{ placeholder }} syntax, then applying them via the omarchy-refresh-config command.

Omarchy is a declarative desktop environment that separates visual styling from application logic. Creating a custom omarchy theme requires only editing a structured colors.toml palette and running the refresh utility to populate template placeholders across Hyprland, Alacritty, and Kitty configurations.

How the Omarchy Theming Engine Works

The theming pipeline implemented in the omacom/omarchy repository follows four discrete stages:

1. Load the palette – The engine reads themes/<theme-name>/colors.toml, which defines hexadecimal color tokens such as background, foreground, accent, and terminal ANSI colors.
2. Render templates – Files in default/themed/*.tpl contain {{ token }} placeholders. The renderer substitutes each placeholder with the corresponding value from the TOML palette.
3. Write concrete configs – The omarchy-refresh-config command (implemented in bin/omarchy) writes the rendered files to the user’s ~/.config/ directory, backing up existing configurations.
4. Apply the theme – Window managers and terminals reload automatically or on next startup, picking up the new color values from the concrete config files.

Because the system is data-driven, you can create new themes without modifying the core rendering logic—only the colors.toml file and optional template adjustments are required.

Creating Your First Custom Theme

Step 1: Copy an Existing Reference Theme

Clone an established theme directory as your starting point. The themes/white and themes/nord directories provide complete token sets that satisfy all template requirements.

# Copy the white theme as a template

cp -r $OMARCHY_PATH/themes/white $OMARCHY_PATH/themes/example

# Or reference the Nord palette online

# https://github.com/omacom/omarchy/blob/quattro/themes/nord/colors.toml

Step 2: Define Your Palette in colors.toml

Edit the new theme’s colors.toml to specify your desired color scheme. The file must define standard tokens used by templates across the desktop environment.

# themes/example/colors.toml

background = "#1e1e2e"
foreground = "#cdd6f4"
accent     = "#f5c2e7"
red        = "#f38ba8"
green      = "#a6e3a1"
yellow     = "#f9e2af"
blue       = "#89b4fa"
magenta    = "#cba6f7"
cyan       = "#89dceb"

View the reference implementation at [themes/white/colors.toml](https://github.com/omacom/omarchy/blob/quattro/themes/white/colors.toml) to see the complete set of required tokens.

Step 3: Understanding Template Placeholders

Template files in default/themed/ use double-brace syntax to reference TOML tokens. When omarchy-refresh-config runs, it performs literal string substitution.

For example, default/themed/hyprland.lua.tpl contains:

-- default/themed/hyprland.lua.tpl
default_border_color = "{{ background }}"
default_active_border_color = "{{ accent }}"
default_text_color = "{{ foreground }}"

After processing the example theme, the output becomes:

-- rendered ~/.config/hypr/hyprland.lua
default_border_color = "#1e1e2e"
default_active_border_color = "#f5c2e7"
default_text_color = "#cdd6f4"

Similarly, default/themed/alacritty.toml.tpl maps the same tokens to terminal color settings.

Step 4: Apply with omarchy-refresh-config

Run the refresh command to generate and install the concrete configuration files:

# Generate configs from your custom theme

omarchy-refresh-config example

This command reads themes/example/colors.toml, processes all *.tpl files in default/themed/, and writes the results to ~/.config/hypr/, ~/.config/alacritty/, and other appropriate locations. Restart your window manager or log out to activate the new theme.

Key Source Files and Templates

Path	Description
[themes/white/colors.toml](https://github.com/omacom/omarchy/blob/quattro/themes/white/colors.toml)	Minimal baseline palette demonstrating required color tokens.
[themes/nord/colors.toml](https://github.com/omacom/omarchy/blob/quattro/themes/nord/colors.toml)	Comprehensive example with full terminal color mappings.
default/themed/hyprland.lua.tpl	Window manager configuration template using {{ placeholder }} syntax.
default/themed/alacritty.toml.tpl	Terminal emulator template consuming the same TOML tokens.
bin/omarchy	Contains the omarchy-refresh-config implementation that orchestrates the rendering pipeline.

Summary

• Omarchy themes are defined declaratively in colors.toml files that specify hexadecimal color tokens.
• Template placeholders in default/themed/*.tpl files use {{ token }} syntax to reference these colors.
• The omarchy-refresh-config command renders templates and writes concrete configs to ~/.config/.
• Creating a custom theme requires only copying an existing theme directory, editing colors.toml, and running the refresh command.
• Source templates for Hyprland and Alacritty demonstrate how placeholders map to final configuration values.

Frequently Asked Questions

What file format does Omarchy use for color definitions?

Omarchy uses TOML (.toml) files to define color palettes. Each theme directory contains a colors.toml file that maps semantic names like background, accent, and red to hexadecimal color codes, which the rendering engine consumes during template substitution.

Where are the theme templates stored in the repository?

Template files are located in the default/themed/ directory of the omacom/omarchy repository. These *.tpl files contain placeholder strings that the omarchy-refresh-config command replaces with values from your active theme’s colors.toml.

How do I apply a theme without restarting my session?

Run the omarchy-refresh-config <theme-name> command to regenerate configuration files immediately. While the command writes the new configs to disk instantly, some components like the window manager may require a reload (e.g., hyprctl reload) or logout to visually apply the updated colors.

Can I add custom placeholders beyond the standard color tokens?

Yes. The templating engine performs literal substitution of any key defined in colors.toml. If you add a custom token such as custom_highlight = "#ff00ff" to your colors.toml, you can reference it in any *.tpl file using {{ custom_highlight }}, and the renderer will include it in the final output.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}