Omarchy Theme Templates Placeholder Syntax: A Complete Guide

Omarchy theme templates use mustache-style double curly braces {{ variable_name }} for variable substitution, supporting plain values and string concatenation but no conditional logic.

The Omarchy desktop environment uses a lightweight templating system to generate color-coordinated configuration files across applications. Understanding the Omarchy theme templates placeholder syntax is essential for customizing themes or debugging color generation in the basecamp/omarchy repository.

Mustache-Style Syntax in Omarchy

Omarchy implements a deliberately minimal templating engine using double curly braces to wrap variable names. When the theme builder processes *.tpl files, it replaces each placeholder with corresponding values defined in themes/*/colors.toml.

Basic Variable Substitution

The fundamental pattern wraps variable names in {{ and }}:

"parameter": "{{ cyan }}",
"variable": "{{ foreground }}",
"type": "{{ theme_type }}"

These placeholders map directly to keys in the theme's color definition files. For example, {{ foreground }} injects the theme's primary text color, while {{ theme_type }} resolves to either dark or light based on the active theme configuration.

String Concatenation Support

Omarchy's placeholder syntax allows literal suffixes for string concatenation without additional operators. Append characters directly after the closing braces:

"focusBorder": "{{ accent }}80",
"list.activeSelectionBackground": "{{ accent }}30"

In {{ accent }}80, the renderer substitutes the accent color value and appends the literal characters 80, producing a hex color with alpha transparency (e.g., #ff990080).

Where Placeholders Are Defined

All template files reside in default/themed/ with the .tpl extension. The placeholder values originate from colors.toml files within individual theme directories.

Key implementation files include:

• default/themed/vscode-theme.json.tpl — VS Code color theme template containing dozens of placeholders like {{ muted }} and {{ cyan }}
• default/themed/*.tpl — Complete collection of application templates (Alacritty, Hyprland, Waybar) using identical syntax
• docs/theming.md — Official documentation describing the placeholder mechanism and color variable naming conventions

Real-World Example: VS Code Template

The VS Code theme template at default/themed/vscode-theme.json.tpl demonstrates practical placeholder usage:

{
    "type": "{{ theme_type }}",
    "semanticHighlighting": true,
    "semanticTokenColors": {
        "parameter": "{{ cyan }}",
        "variable": "{{ foreground }}",
        "comment": { "foreground": "{{ muted }}", "fontStyle": "italic" }
    },
    "colors": {
        "foreground": "{{ foreground }}",
        "focusBorder": "{{ accent }}80",
        "button.background": "{{ accent }}",
        "list.activeSelectionBackground": "{{ accent }}30"
    }
}

This template generates the final vscode-theme.json by substituting each placeholder with hex color values from the active theme's configuration.

Limitations of the Templating System

According to the basecamp/omarchy source code, the placeholder system intentionally excludes advanced templating features:

• No conditional logic — {{#if}} or similar constructs are not implemented
• No loops — Iteration over color arrays is unsupported
• No filters — String manipulation or color adjustment functions (lighten/darken) must occur in the theme definition files, not the templates

Templates function as pure substitution lists where each {{ variable }} receives exactly one scalar value from the theme's color registry.

Summary

• Omarchy uses mustache-style double curly braces ({{ variable }}) for all template substitutions
• Plain variables like {{ foreground }} and {{ accent }} inject color values from colors.toml
• String concatenation works by appending literals (e.g., {{ accent }}80) for alpha transparency or suffixes
• Template files use the .tpl extension in default/themed/ and include targets for VS Code, Alacritty, and window managers
• The system does not support conditionals, loops, or filters, maintaining simplicity through pure variable expansion

Frequently Asked Questions

What is the basic placeholder syntax in Omarchy?

Omarchy uses mustache-style double curly braces to wrap variable names, such as {{ foreground }} or {{ accent }}. When the theme builder runs, these placeholders are replaced with corresponding hex color values defined in the theme's colors.toml file.

Can I use conditionals or loops in Omarchy templates?

No. According to the Omarchy source code in docs/theming.md, the templating system deliberately omits logic constructs. Templates support only variable substitution and string concatenation. For conditional color behavior, you must create separate theme files with different static values.

Where are placeholder values defined in Omarchy?

Placeholder values originate in themes/*/colors.toml files within the repository. The theme builder reads these definitions and substitutes them into template files located in default/themed/*.tpl during the build process.

How do I create semi-transparent colors in Omarchy templates?

Append hexadecimal alpha values directly after the closing braces. For example, {{ accent }}80 renders the accent color followed by 80 (50% opacity in hex), while {{ accent }}30 produces approximately 19% opacity. This concatenation happens at the string level without mathematical operations.

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