# How to Use Omarchy Template Variables for Theming: A Complete Guide

> Learn to use Omarchy template variables for theming. This guide shows how to leverage placeholders in tpl files to customize your theme's colors and gradients.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-01

---

**Omarchy template variables are placeholders in `.tpl` files under `default/themed/` that expand to color values from [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) using syntax like `{{ key }}`, `{{ key_rgb }}`, and gradient helpers, rendered by `bin/omarchy-theme-set-templates` when a theme is activated.**

Omarchy's theming system generates dynamic configuration files from templates, letting you define colors once in [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) and propagate them across your entire desktop environment. This article explains every available placeholder, how the rendering pipeline works, and how to write your own templates using the actual source code from `omacom/omarchy`.

## Template Placeholder Syntax

All placeholders use double curly braces with specific modifiers that control how color values are formatted. The parsing and substitution logic lives in `bin/omarchy-theme-set-templates`.

### Basic Color Placeholders

| Placeholder | Output format | Example with `accent = "#7aa2f7"` |
|-------------|-------------|-----------------------------------|
| `{{ key }}` | Raw hex value | `#7aa2f7` |
| `{{ key_strip }}` | Hex without `#` | `7aa2f7` |
| `{{ key_rgb }}` | Comma-separated RGB | `122,162,247` |

These three variants cover the majority of application configuration formats. Use `{{ key_strip }}` for programs that prefix their own hash, and `{{ key_rgb }}` for formats requiring integer components.

### Color Mixing

The `{{ mix }}` helper performs linear interpolation between two colors:

```lua
-- default/themed/kitty.conf.tpl
foreground = {{ mix background foreground 20% }}

```

With `background = "#1a1b26"` and `foreground = "#a9b1d6"`, this outputs a 20% blend toward the foreground color. The percentage can be any value from `0%` to `100%`.

### Gradient Helpers

Omarchy supports Hyprland-style gradients defined as `"rgba(...) rgba(...) angle"`. Three helpers convert these for different contexts:

| Helper | Purpose | Output when gradient exists | Output on fallback |
|--------|---------|----------------------------|------------------|
| `{{ hypr_gradient key fallback }}` | Hyprland Lua configs | Lua table `{ colors = {...}, angle = N }` | Solid hex from fallback key |
| `{{ shell_gradient key fallback }}` | Shell/TOML configs | Original gradient string | Solid hex from fallback key |
| `{{ gradient_start key fallback }}` | Single-color contexts | First stop as hex | Solid hex from fallback key |

Example from `default/themed/hyprland.lua.tpl`:

```lua
local active_border = {{ hypr_gradient hyprland_active_border accent }}

```

Given this [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml):

```toml
hyprland_active_border = "rgba(33ccffee) rgba(00ff99ee) 45deg"
accent = "#7aa2f7"

```

The rendered [`hyprland.lua`](https://github.com/omacom/omarchy/blob/main/hyprland.lua) contains:

```lua
local active_border = { colors = { "rgba(33ccffee)", "rgba(00ff99ee)" }, angle = 45 }

```

If `hyprland_active_border` is undefined, the fallback produces:

```lua
local active_border = "#7aa2f7"

```

## The Template Rendering Pipeline

Understanding the full flow helps debug theme issues and extend the system.

### Stage 1: Theme Staging

The `bin/omarchy-theme-set` script creates a clean workspace:

```bash
~/.local/state/omarchy/current/next-theme/

```

It copies the base theme from `themes/<name>/`, then overlays user customizations from `~/.config/omarchy/themes/<name>/`.

### Stage 2: Color Generation

If the theme lacks a [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml), Omarchy generates one from terminal configuration files using the logic in `bin/omarchy-theme-set`.

### Stage 3: Template Processing

The `bin/omarchy-theme-set-templates` script scans for `*.tpl` files and renders them:

1. User templates in `~/.config/omarchy/themed/` are processed first
2. Built-in templates in `default/themed/` are processed next
3. Any template with a matching name in the user directory skips the built-in version

Rendered output writes to the corresponding non-`.tpl` filename. Existing non-template files are never overwritten—this protects hand-written configurations.

### Stage 4: Activation

The staged directory moves to the active theme location, a hook fires for custom scripts, and dependent applications retint automatically.

## Creating Custom Templates

### Built-in Template Location

Add templates to `default/themed/` in the Omarchy repository for system-wide use. Current templates include:

- `hyprland.lua.tpl` — Hyprland window manager configuration
- `shell.toml.tpl` — Shell notification and UI colors
- `kitty.conf.tpl` — Kitty terminal configuration
- `foot.ini.tpl` — Foot terminal configuration

### User Template Location

Place custom templates in:

```bash
~/.config/omarchy/themed/

```

A user template named `myapp.conf.tpl` supersedes any built-in `myapp.conf.tpl`. This mechanism lets you override specific files without forking the entire theme.

### Practical Template Examples

**Simple RGB for Foot terminal:**

```ini

# ~/.config/omarchy/themed/foot.ini.tpl

[colors]
background={{ background_rgb }}
foreground={{ foreground_rgb }}

```

**Shell gradient with fallback:**

```toml

# ~/.config/omarchy/themed/shell.toml.tpl

[notifications]
border = {{ shell_gradient hyprland_active_border accent }}

```

**Conditional Hyprland styling:**

```lua

# ~/.config/omarchy/themed/hyprland.lua.tpl

local accent = "{{ accent }}"
local border = {{ hypr_gradient hyprland_active_border accent }}
local border_solid = "{{ gradient_start hyprland_active_border accent }}"

```

## Security and Deny-listing

The `bin/omarchy-theme-set` script defines `INSTALLED_THEME_DENIED`—a list of patterns that cannot be copied from git-cloned installed themes. This prevents malicious themes from overwriting sensitive files. The deny-list is hardcoded in the script and applies only to themes installed via `omarchy-theme-install`, not built-in or user-local themes.

## Testing Template Output

Verify your templates without applying the full theme:

```bash

# Stage and render without activating

omarchy-theme-set <name> --dry-run 2>/dev/null || \
  bash -c 'source bin/omarchy-theme-set-templates && render_templates ~/.local/state/omarchy/current/next-theme/colors.toml default/themed/'

```

The `test/cli` and `test/shell` suites in the repository contain automated tests for gradient parsing and placeholder substitution. Run these when modifying core template logic:

```bash
./test/cli/theming.bats
./test/shell/gradients.bats

```

## Summary

- **Template variables** use `{{ key }}` syntax in `.tpl` files under `default/themed/` or `~/.config/omarchy/themed/`
- **Modifiers** (`_strip`, `_rgb`) and **helpers** (`mix`, `hypr_gradient`, `shell_gradient`, `gradient_start`) transform color values for different formats
- **`bin/omarchy-theme-set-templates`** performs the actual placeholder substitution during theme activation
- **User templates take precedence** over built-ins when filenames match
- **Gradient helpers** provide fallbacks for themes without gradient definitions, ensuring robust configuration generation

## Frequently Asked Questions

### What file extension do Omarchy templates use?

Omarchy templates use the `.tpl` extension. The `bin/omarchy-theme-set-templates` script specifically searches for `*.tpl` files and strips that extension when writing the rendered output.

### Can I use template variables outside of color values?

No. The template system in `bin/omarchy-theme-set-templates` is purpose-built for color substitution. It does not support arbitrary variable expansion, conditionals, or loops—only the documented placeholder syntax for color manipulation.

### Why isn't my template being rendered?

Check three things: the file must have `.tpl` extension, it must be in a searched directory (`default/themed/` or `~/.config/omarchy/themed/`), and the destination file must not already exist as a non-template file. The renderer protects existing files to prevent overwriting manual configurations.

### How do I debug what values are being substituted?

Inspect the staged theme directory at `~/.local/state/omarchy/current/next-theme/` after running `omarchy-theme-set`. The rendered files appear alongside [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml), letting you verify placeholder expansion before the theme activates.