# How to Configure Hyprland Theme Templates in Omarchy: A Complete Guide for Customizing Your Desktop

> Learn how to configure Hyprland theme templates in Omarchy. This guide explains using *.tpl files and colors.toml to generate custom Hyprland configurations. Master your desktop appearance.

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

---

**Omarchy uses `*.tpl` template files with placeholder tokens like `{{ hypr_gradient hyprland_active_border accent }}` that are resolved against a theme's [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) and processed by the `omarchy-theme-set-templates` command to generate concrete Hyprland configuration files.**

Omarchy's Hyprland theming system separates color definitions from configuration logic through a powerful token-based template engine. This architecture allows you to customize your entire desktop appearance by editing a single [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file or overriding specific templates, without touching raw Hyprland configuration syntax. The system is implemented in the `omacom/omarchy` repository as a set of Bash utilities that resolve colors, compute gradients, and stage files for deployment.

## Understanding the Template Architecture

Omarchy's Hyprland configuration is built from **.template files** (`*.tpl`) stored in theme directories. These templates contain placeholder tokens that the system replaces with actual color values derived from your active theme.

The core templating workflow happens in `bin/omarchy-theme-set-templates` in the Omarchy source. This script orchestrates a six-stage pipeline:

1. **Color extraction** — `omarchy-theme-color` parses [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) and populates the `THEME_COLORS` associative array (lines 79‑81)
2. **Basic token substitution** — `add_template_value` creates `{{ key }}`, `{{ key_strip }}`, and `{{ key_rgb }}` variants (lines 95‑107)
3. **Mixed color calculation** — `add_mix_values` processes `{{ mix … }}` tokens using the `mix_color` AWK routine (lines 25‑58, 120‑140)
4. **Gradient generation** — `add_gradient_function_values` handles `{{ hypr_gradient … }}`, `{{ gradient_start … }}`, and `{{ shell_gradient … }}` tokens with optional angle parameters (lines 154‑176)
5. **File generation** — Templates are processed with auto-generated `sed` scripts and written to `$HOME/.local/state/omarchy/current/next-theme/` (lines 90‑99)
6. **Shell-section overrides** — Optional `shell.*.toml` files inject or replace sections in the generated [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) (lines 60‑68)

User-provided templates in `~/.config/omarchy/themed/` take precedence over built-in defaults, enabling seamless customization without modifying system files.

## Key Files in the Hyprland Theming System

| File | Path in Repository | Purpose |
|------|-------------------|---------|
| `hyprland.lua.tpl` | `default/themed/hyprland.lua.tpl` | Built-in template with gradient placeholders for window borders, animations, and UI elements |
| `omarchy-theme-set-templates` | `bin/omarchy-theme-set-templates` | Main orchestration script that resolves all tokens and writes concrete config files |
| `omarchy-theme-color` | `bin/omarchy-theme-color` | Utility that parses [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) and outputs tab-separated key-value pairs |
| `omarchy-refresh-hyprland` | `bin/omarchy-refresh-hyprland` | Deployment helper that copies generated configs to `~/.config/hypr/` with backup preservation |
| [`hyprland.md`](https://github.com/omacom/omarchy/blob/main/hyprland.md) | [`default/agents/skills/omarchy/hyprland.md`](https://github.com/omacom/omarchy/blob/main/default/agents/skills/omarchy/hyprland.md) | Skill documentation for AI assistants and users |

## How to Generate and Apply Hyprland Theme Configurations

### Step 1: Generate Themed Configuration Files

After selecting a theme or editing its [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml), run the template processor to resolve all tokens and create the concrete Hyprland configuration:

```bash
omarchy-theme-set-templates

```

This command populates `$HOME/.local/state/omarchy/current/next-theme/` with processed versions of all `*.tpl` files, including [`hyprland.lua`](https://github.com/omacom/omarchy/blob/main/hyprland.lua) with all gradients and colors expanded to their final hex values.

### Step 2: Deploy to Active Hyprland Configuration

Copy the generated configuration to your live Hyprland setup:

```bash
omarchy-refresh-hyprland

```

This helper preserves a backup of your previous configuration before overwriting `~/.config/hypr/hyprland.lua`. The change takes effect on the next Hyprland reload or restart.

## Customizing Hyprland Themes with User Templates

Omarchy prioritizes user templates over built-in defaults during processing (lines 90‑93 in `omarchy-theme-set-templates`). This allows surgical overrides without maintaining full configuration forks.

### Override a Gradient Token

Create a user template at `~/.config/omarchy/themed/hyprland.lua.tpl` with a custom active border color:

```lua
general {
    col.active_border = {{ hypr_gradient hyprland_active_border #ff8800 }}
}

```

The bright orange hex value `#ff8800` replaces whatever theme color would normally populate this token. Re-run `omarchy-theme-set-templates` to regenerate with your override.

### Use Mixed Color Tokens

Templates support on-the-fly color interpolation with the `{{ mix … }}` syntax:

```lua
decoration {
    shadow_color = {{ mix surface bg 30% }}
}

```

The `add_mix_values` function scans for these constructs and invokes `mix_color`—an AWK-based interpolation routine (lines 25‑58)—to compute a color 30% between `surface` and `bg` from your theme's palette.

### Access Color Variants

Every theme color automatically generates three token variants:

- `{{ accent }}` — Raw hex value (e.g., `#7aa2f7`)
- `{{ accent_strip }}` — Hex without `#` prefix (e.g., `7aa2f7`)
- `{{ accent_rgb }}` — Comma-separated RGB (e.g., `122, 162, 247`)

Use these as needed for different Hyprland configuration contexts:

```lua
general {
    col.active_border = rgb({{ accent_rgb }})
}

```

## Advanced Gradient Configuration

The `add_gradient_function_values` routine (lines 154‑176) supports three gradient token types with optional angle parameters:

- `{{ hypr_gradient color1 color2 [angle] }}` — Full Hyprland gradient description
- `{{ gradient_start color1 color2 [angle] }}` — Starting color of calculated gradient
- `{{ shell_gradient color1 color2 [angle] }}` — Shell-specific gradient format

Example with 45-degree rotation:

```lua
{{ hypr_gradient primary secondary 45 }}

```

Omarchy computes the gradient and emits Hyprland-compatible syntax. Angles default to 0 degrees (left-to-right) when omitted.

## Troubleshooting Template Resolution

If your customizations don't appear after running `omarchy-theme-set-templates`:

- **Verify template location** — User templates must be in `~/.config/omarchy/themed/`, not the theme directory
- **Check for syntax errors** — Malformed tokens like `{{hypr_gradient` (no space) won't match the regex patterns in lines 154‑176
- **Inspect generated files** — Examine `$HOME/.local/state/omarchy/current/next-theme/hyprland.lua` to confirm token resolution
- **Review color definitions** — Ensure [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) contains all keys referenced by your templates; missing keys propagate as empty strings

## Summary

- **Omarchy's Hyprland theming** uses `*.tpl` templates with `{{ … }}` tokens that resolve against [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) values
- **`omarchy-theme-set-templates`** processes templates through a six-stage pipeline: color extraction, basic substitution, mixing, gradients, file generation, and shell overrides
- **User templates** in `~/.config/omarchy/themed/` override built-in defaults without requiring repository modifications
- **`omarchy-refresh-hyprland`** deploys generated configurations to `~/.config/hypr/` with automatic backup
- **Gradient and mix tokens** enable dynamic color computation from theme palettes using `{{ hypr_gradient … }}` and `{{ mix … }}` syntax

## Frequently Asked Questions

### What file format do Omarchy Hyprland templates use?

Omarchy Hyprland templates use the `.tpl` extension and contain valid Hyprland configuration syntax interspersed with `{{ … }}` placeholder tokens. These tokens are processed by `omarchy-theme-set-templates` before deployment. The `hyprland.lua.tpl` file in `default/themed/` demonstrates the complete set of available tokens for window borders, animations, and decoration settings.

### Where does Omarchy store generated Hyprland configurations?

Generated configurations are staged in `$HOME/.local/state/omarchy/current/next-theme/` before deployment. The `omarchy-refresh-hyprland` command then copies [`hyprland.lua`](https://github.com/omacom/omarchy/blob/main/hyprland.lua) from this directory to `~/.config/hypr/hyprland.lua`. This two-step process allows inspection of generated files before they affect your running desktop.

### How do I create a completely custom Hyprland color scheme?

Create `~/.config/omarchy/themed/hyprland.lua.tpl` with your desired configuration and hardcoded colors or custom `{{ … }}` tokens. Alternatively, define a new theme directory with a complete [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) and select it via Omarchy's theme switching commands. The templating system processes your files first, so any token you define will be available to other templates.

### Can I use Omarchy's color mixing for non-Hyprland applications?

Yes. The `{{ mix … }}` and gradient tokens work in any `*.tpl` file processed by `omarchy-theme-set-templates`. The system generates [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) and other configuration files using the same resolution pipeline. Shell-specific overrides via `shell.*.toml` files (lines 60‑68) let you inject application-specific color logic without duplicating the mixing calculations.