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

Omarchy template variables are placeholders in .tpl files under default/themed/ that expand to color values from 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 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:

-- 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:

local active_border = {{ hypr_gradient hyprland_active_border accent }}

Given this colors.toml:

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

The rendered hyprland.lua contains:

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

If hyprland_active_border is undefined, the fallback produces:

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:

~/.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, 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:

~/.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:

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

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

Shell gradient with fallback:

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

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

Conditional Hyprland styling:

# ~/.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:

# 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:

./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, letting you verify placeholder expansion before the theme activates.

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