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

Omarchy uses *.tpl template files with placeholder tokens like {{ hypr_gradient hyprland_active_border accent }} that are resolved against a theme's 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 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 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 (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 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	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, run the template processor to resolve all tokens and create the concrete Hyprland configuration:

omarchy-theme-set-templates

This command populates $HOME/.local/state/omarchy/current/next-theme/ with processed versions of all *.tpl files, including 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:

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:

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:

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:

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:

{{ 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 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 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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}