# Omarchy Theme Templates Placeholder Syntax: A Complete Guide

> Master Omarchy theme templates placeholder syntax with our complete guide. Learn to use mustache double curly braces for variable substitution and string concatenation effectively.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: deep-dive
- Published: 2026-08-25

---

**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 `}}`:

```json
"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:

```json
"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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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:

```json
{
    "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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/colors.toml) file.

### Can I use conditionals or loops in Omarchy templates?

No. According to the Omarchy source code in [`docs/theming.md`](https://github.com/basecamp/omarchy/blob/main/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.