How to Use Placeholders in Omarchy Theme Templates

Omarchy theme templates use {{ variable }} placeholder syntax that maps to keys defined in a theme's colors.toml file, which are then rendered into final configuration files via the omarchy-refresh-config command.

Learning how to use placeholders in Omarchy theme templates allows you to maintain consistent theming across multiple applications without manually editing configuration files. The basecamp/omarchy repository provides a lightweight templating engine that reads .tpl files and substitutes variables with values from your active theme's TOML definitions.

Understanding the Placeholder Syntax

Omarchy employs a deliberately simple substitution engine. Placeholders follow the format {{ key }} where the key must exactly match a field name in your theme's color definition file.

The templating system processes files in three stages:

1. Template Definition – Files ending in .tpl contain raw configuration syntax interspersed with {{ variable }} markers.
2. Value Resolution – The engine reads the active theme's colors.toml and builds a lookup table of available values.
3. File Generation – Running omarchy-refresh-config writes the rendered output to the appropriate location in ~/.config/.

This mechanism supports any text-based configuration format, including Lua, TOML, YAML, JSON, and CSS, without requiring additional escaping.

Creating Template Files

Template files reside in the default/themed/ directory and serve as blueprints for application-specific configurations. You can reference any key defined in your theme's color palette using the double-brace syntax.

Hyprland Configuration Templates

In default/themed/hyprland.lua.tpl, placeholders adapt Hyprland's window manager settings to the current color scheme:

monitor = {
    default_workspace = "1",
    DPI = 96,
    background = "{{ background }}",
    accent = "{{ accent }}",
}

When rendered, the {{ background }} and {{ accent }} tokens are replaced with the hex values defined in the active theme's colors.toml.

Terminal Emulator Templates

Terminal configurations demonstrate the system's flexibility across different file formats. The default/themed/alacritty.toml.tpl file uses placeholders within a YAML structure:

colors:
  primary:
    background: "{{ background }}"
    foreground: "{{ foreground }}"
  normal:
    black:   "{{ black }}"
    red:     "{{ red }}"
    green:   "{{ green }}"
    yellow:  "{{ yellow }}"
    blue:    "{{ blue }}"
    magenta: "{{ magenta }}"
    cyan:    "{{ cyan }}"
    white:   "{{ white }}"

Similarly, default/themed/kitty.conf.tpl integrates placeholders into Kitty's configuration syntax.

Defining Theme Values in colors.toml

Each theme folder contains a colors.toml file that maps keys to concrete values. The engine requires exact key matching between the TOML fields and the template placeholders.

background = "#1e1e2e"
foreground = "#cdd6f4"
accent     = "#ff6f61"
black      = "#45475a"
red        = "#f38ba8"
green      = "#a6e3a1"

The file supports standard hex color notation and plain text values. As documented in docs/theming.md, the build process loads this file into memory before processing any template substitutions.

Rendering Templates with omarchy-refresh-config

The omarchy-refresh-config command triggers the substitution pipeline. Specify the base filename (without the .tpl extension) to generate the final configuration.

omarchy-refresh-config hyprland.lua

This command performs the following actions:

• Locates default/themed/hyprland.lua.tpl
• Parses the active theme's colors.toml
• Substitutes all {{ key }} occurrences with corresponding values
• Writes the result to ~/.config/hypr/hyprland.lua

For Alacritty, running omarchy-refresh-config alacritty.toml produces ~/.config/alacritty/alacritty.toml with resolved color values.

Fallback Behavior and Debugging

If a placeholder references a key absent from the active theme's colors.toml, the engine preserves the raw {{ key }} string in the output. This behavior, implemented in the theming pipeline documented in default/agents/skills/omarchy/theming.md, helps identify missing definitions during development by making unresolved placeholders visible in the generated files.

Summary

• Placeholder syntax uses {{ variable }} format matching keys in colors.toml.
• Template files use the .tpl extension and live in default/themed/ (e.g., hyprland.lua.tpl, kitty.conf.tpl, alacritty.toml.tpl).
• Rendering command is omarchy-refresh-config <basename>, which writes processed files to ~/.config/.
• Missing keys remain as raw placeholder text, aiding debugging.
• Documentation in docs/theming.md and default/agents/skills/omarchy/theming.md provides implementation details.

Frequently Asked Questions

What file extension should template files use?

Template files must use the .tpl extension appended to the target filename (for example, hyprland.lua.tpl or alacritty.toml.tpl). The omarchy-refresh-config command automatically strips this extension when writing the final file to your configuration directory.

Can I use placeholders in JSON or CSS files?

Yes, the templating engine treats all .tpl files as plain text. You can embed {{ variable }} syntax inside JSON, CSS, Lua, or any other configuration format without additional escaping, as the substitution occurs before the target application parses the file.

What happens if a placeholder key is missing from colors.toml?

If a placeholder references a key that does not exist in the active theme's colors.toml, the raw {{ key }} string is written to the output file unchanged. This allows you to spot missing theme definitions immediately when viewing the generated configuration.

Where are the official template examples located?

Official examples are located in the default/themed/ directory of the basecamp/omarchy repository. Key reference files include default/themed/hyprland.lua.tpl, default/themed/kitty.conf.tpl, and default/themed/alacritty.toml.tpl. Comprehensive documentation resides in docs/theming.md and default/agents/skills/omarchy/theming.md.

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