Omarchy Template Helpers: Complete Guide to Theme Variables

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

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

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

foreground = "{{ foreground }}"
foreground_strip = "{{ foreground_strip }}"
foreground_rgb = "{{ foreground_rgb }}"

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

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

Generating Mixed Colors in Kitty

In default/themed/kitty.conf.tpl:

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

Mixing #000000 and #ffffff produces #808080.

Creating Hyprland Gradients

In default/themed/hyprland.lua.tpl:

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

Regenerating Templates Manually

Invoke the rendering engine directly:

"$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 and defines the transformation rules for modifiers like _strip and _rgb, as well as the computation logic for mix and gradient helpers.

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