# How to Use Placeholders in Omarchy Theme Templates

> Learn how to use {{ variable }} placeholders in Omarchy theme templates to customize your configuration files using colors.toml and the omarchy-refresh-config command.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-22

---

**Omarchy theme templates use `{{ variable }}` placeholder syntax that maps to keys defined in a theme's [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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:

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

```toml
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`](https://github.com/basecamp/omarchy/blob/main/colors.toml) file that maps keys to concrete values. The engine requires exact key matching between the TOML fields and the template placeholders.

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

```bash
omarchy-refresh-config hyprland.lua

```

This command performs the following actions:

- Locates `default/themed/hyprland.lua.tpl`
- Parses the active theme's [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/docs/theming.md) and [`default/agents/skills/omarchy/theming.md`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/docs/theming.md) and [`default/agents/skills/omarchy/theming.md`](https://github.com/basecamp/omarchy/blob/main/default/agents/skills/omarchy/theming.md).