# Omarchy Template Helpers: Complete Guide to Theme Variables

> Explore Omarchy template helpers and theme variables to customize your configurations. Learn how to inject colors and derived values into your .tpl files with this comprehensive guide.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: getting-started
- Published: 2026-08-27

---

**Omarchy template helpers** are pure text substitution variables that inject theme colors and derived values into `.tpl` configuration files during the rendering process managed by `bin/omarchy-theme-set-templates`.

The Omarchy desktop environment uses a declarative theming pipeline that transforms abstract `.tpl` templates into concrete application configurations. Understanding the available **Omarchy template helpers** is essential for customizing terminal emulators, window managers, and shell components with dynamic theme awareness. These helpers expose palette values from [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) along with computed derivatives like RGB conversions and color mixes.

## Available Omarchy Template Helpers

The rendering engine resolves double-bracket syntax (e.g., `{{ background }}`) into concrete values using several helper categories. All helpers are pure data substitutions that do not invoke external commands.

### Palette Keys and Indexed Colors

**Direct palette keys** provide immediate access to the semantic color definitions in the theme's [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml):

- `{{ background }}` – The theme's background color
- `{{ foreground }}` – The primary text color  
- `{{ accent }}` – The theme's accent color

**Indexed color helpers** access the 16-base color palette slots directly:

```text
{{ color0 }} through {{ color15 }}

```

These correspond to the standard terminal color indices defined in `default/themes/<theme>/colors.toml`.

### Legacy Aliases

For backward compatibility, Omarchy supports **legacy aliases** that map to indexed colors:

- `{{ legacy-background }}`
- `{{ legacy-foreground }}`
- `{{ legacy-red }}`

These are documented in [`docs/theming.md`](https://github.com/basecamp/omarchy/blob/main/docs/theming.md) under the "Semantic aliases" section.

### Value Modifiers

Modifiers transform hex color values by appending a suffix to any palette key:

- **`_strip`** – Removes the leading `#` from a hex color
- **`_rgb`** – Converts hex to a comma-separated RGB triplet

For example, if `accent` is `#ff00ff`:
- `{{ accent_strip }}` resolves to `ff00ff`
- `{{ accent_rgb }}` resolves to `255,0,255`

### Mix Helpers

The **mix helper** generates a color that is an equal blend of the theme's background and foreground values:

- `{{ mix }}` – Produces the blended hex color (e.g., `#808080` when mixing `#000000` and `#ffffff`)
- `{{ mix_strip }}` – The mixed value without the `#` prefix
- `{{ mix_rgb }}` – The mixed value as comma-separated RGB

These are commonly used in `default/themed/kitty.conf.tpl` for creating subtle UI backgrounds.

### Gradient Helpers

**Gradient helpers** generate formatted color gradient strings for specific UI surfaces:

- `{{ gradient_start }}` – Fallback color when no gradient is defined
- `{{ gradient }}` – Full gradient string for general use
- `{{ hypr_gradient }}` – Hyprland-specific format (e.g., `rgba(010203ee) rgba(040506ee) 45deg`)
- `{{ shell_gradient }}` – Quickshell-specific format

As implemented in `default/themed/hyprland.lua.tpl`, `{{ hypr_gradient }}` falls back to `{{ background }}` if no gradient configuration exists, while `{{ shell_gradient }}` defaults to `{{ accent }}`.

## How the Templating Engine Processes Helpers

The `bin/omarchy-theme-set-templates` script implements a four-stage resolution pipeline:

1. **Template Discovery** – Gathers all `*.tpl` files from `default/themed/` and user overrides in `~/.config/omarchy/themed/`

2. **Palette Loading** – Reads `default/themes/<theme>/colors.toml` to build the color key map

3. **Helper Resolution** – For each `{{ … }}` token:
   - Looks up direct keys (e.g., `background`)
   - Applies suffix modifiers (`_strip`, `_rgb`) if present
   - Falls back to derived helpers (e.g., `mix`, `gradient_*`)

4. **File Generation** – Writes rendered output to the target location in `~/.config/`, preserving existing user-written files

## Practical Code Examples

### Using Color Modifiers in Alacritty

In `default/themed/alacritty.toml.tpl`:

```toml
foreground = "{{ foreground }}"
foreground_strip = "{{ foreground_strip }}"
foreground_rgb = "{{ foreground_rgb }}"

```

With `foreground = "#c0c0c0"` in the theme, this renders as:

```toml
foreground = "#c0c0c0"
foreground_strip = "c0c0c0"
foreground_rgb = "192,192,192"

```

### Generating Mixed Colors in Kitty

In `default/themed/kitty.conf.tpl`:

```text
background_mix = "{{ mix }}"
background_mix_strip = "{{ mix_strip }}"

```

Mixing `#000000` and `#ffffff` produces `#808080`.

### Creating Hyprland Gradients

In `default/themed/hyprland.lua.tpl`:

```lua
decoration = {
  colors = {
    "{{ hypr_gradient }}",   -- Resolves to full gradient or background fallback
  },
}

```

### Regenerating Templates Manually

Invoke the rendering engine directly:

```bash
"$OMARCHY_PATH/bin/omarchy-theme-set-templates"

```

## Summary

- **Omarchy template helpers** use `{{ variable }}` syntax to inject theme colors into `.tpl` files
- **Palette helpers** include `background`, `foreground`, `accent`, and indexed colors `color0` through `color15`
- **Modifiers** append `_strip` or `_rgb` to transform hex values into alternative formats
- **Derived helpers** like `mix` and `gradient` compute blended or formatted values at render time
- The `bin/omarchy-theme-set-templates` script processes all helpers during the four-stage theming pipeline
- Template files reside in `default/themed/` and resolve against `default/themes/<theme>/colors.toml`

## Frequently Asked Questions

### What file extension does Omarchy use for templates?

Omarchy uses the **`.tpl`** extension for all template files. These files contain raw configuration markup interspersed with `{{ helper }}` variables that the `bin/omarchy-theme-set-templates` script resolves into concrete values.

### How do I convert a hex color to RGB format in a template?

Append the **`_rgb`** suffix to any color helper. For example, `{{ accent_rgb }}` converts `#ff00ff` to `255,0,255`. This works with any palette key including indexed colors like `{{ color2_rgb }}` or mixed values like `{{ mix_rgb }}`.

### What happens if a gradient helper is undefined?

The gradient helpers provide intelligent fallbacks according to the Omarchy source code. `{{ hypr_gradient }}` falls back to the `{{ background }}` value, while `{{ shell_gradient }}` defaults to `{{ accent }}`. This ensures UI surfaces always have a valid color even when the theme lacks explicit gradient definitions.

### Where are the template helpers defined?

The helper resolution logic is implemented in **`bin/omarchy-theme-set-templates`**, the shell script responsible for the theming pipeline. This script parses the palette from [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) and defines the transformation rules for modifiers like `_strip` and `_rgb`, as well as the computation logic for `mix` and gradient helpers.