Understanding the hypr_gradient Template Helper in Omarchy

The hypr_gradient helper is a Jinja-style template function that converts theme color tokens into Hyprland-compatible Lua tables or strings, intelligently handling both gradient specifications and solid color fallbacks.

The hypr_gradient helper is a critical component of the Omarchy theming system that bridges theme definitions with Hyprland window manager configurations. Implemented in the omacom/omarchy repository, this utility processes color tokens and gradient specifications, converting them into the specific Lua table format required by Hyprland's configuration files.

What is the hypr_gradient Template Helper?

hypr_gradient is a template processing function designed for Omarchy's theme engine. It resolves theme keys that may contain either solid colors or Hyprland-style gradient definitions, then emits the appropriate Lua syntax for Hyprland's configuration files.

Theme authors invoke the helper using Jinja-style syntax:

{{ hypr_gradient key fallback_color }}

For example:

local active_border_color = {{ hypr_gradient hyprland_active_border accent }}

The helper checks if hyprland_active_border exists in the current theme. If found, it parses the value; if missing, it substitutes the fallback color (in this case, accent).

Implementation and Core Logic

The helper's implementation resides in the theme template processing script, with gradient parsing delegated to a dedicated geometry module.

Primary Implementation File

The core logic lives in bin/omarchy-theme-set-templates around line 141, within the hypr_gradient_value() function. This shell function performs the initial token lookup and determines whether to apply gradient parsing or return a solid color.

Gradient Parsing Dependency

When the helper detects a potential gradient, it delegates parsing to geometry.parseGradientSpec in shell/Commons/BorderGeometry.js (around line 345). This specialized parser extracts color stops and angle information from strings matching the pattern rgba(..) rgba(..) <angle>deg.

Processing Logic and Fallback Behavior

The helper executes a three-step resolution process:

1. Token Resolution – Retrieves the value associated with the requested key from the active theme
2. Gradient Detection – Tests if the token matches the Hyprland gradient syntax using the geometry parser
3. Format Conversion – Returns either a Lua table (for gradients) or a string (for solid colors/fallbacks)

Gradient to Lua Table Conversion

When the parser identifies a valid gradient specification like rgba(33ccffee) rgba(00ff99ee) 45deg, the helper outputs a Lua table:

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

This format matches exactly what Hyprland expects for gradient definitions in its configuration.

Solid Color and Fallback Handling

If the token is a plain color (e.g., #336699 or rgba(595959aa)), or if the key does not exist in the theme, the helper returns a simple Lua string:

"#336699"

According to the test suite in test/cli/gradient-test.txt.tpl (lines 300-456), the fallback mechanism activates immediately when a key is missing, substituting the user-provided fallback color. The specific fallback test case appears around lines 450-453, verifying that {{ hypr_gradient missing accent }} correctly yields the fallback value.

Usage Examples

Converting Theme Gradients

When a theme defines hyprland_active_border as a gradient:

-- hyprland.lua.tpl
local active_border_color = {{ hypr_gradient hyprland_active_border accent }}

If the theme contains:

hyprland_active_border: "rgba(33ccffee) rgba(00ff99ee) 45deg"

The rendered output becomes:

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

Handling Solid Colors

If the same theme key contains a solid color:

hyprland_active_border: "#336699"

The helper outputs:

local active_border_color = "#336699"

Shell Implementation Reference

The underlying shell logic in bin/omarchy-theme-set-templates operates conceptually as follows:

hypr_gradient_value() {
  key=$1
  fallback=$2
  token=$(theme_get "$key")
  
  if [[ -z "$token" ]]; then
    echo "\"$fallback\""
    return
  fi
  
  gradient=$(geometry.parseGradientSpec "$token")
  
  if [[ "$gradient.enabled" == "true" ]]; then
    echo "{ colors = { \"${gradient.colors[0]}\", \"${gradient.colors[1]}\" }, angle = ${gradient.angle} }"
  else
    echo "\"$token\""
  fi
}

This pseudocode represents the actual implementation found at line 141 of the template processing script.

Documentation and Testing

The helper is documented in docs/theming.md (lines 169-171), where it appears in the template helper reference table. The documentation specifies the exact syntax and fallback behavior for theme authors.

Validation occurs through the test file test/cli/gradient-test.txt.tpl, which contains both normal gradient cases and fallback scenarios (lines 300-456). These tests ensure that the helper correctly handles the boundary between gradient and non-gradient inputs.

Summary

• The hypr_gradient helper converts theme color tokens into Hyprland-compatible Lua syntax
• Implementation resides in bin/omarchy-theme-set-templates at approximately line 141 within the hypr_gradient_value() function
• Gradient parsing utilizes geometry.parseGradientSpec from shell/Commons/BorderGeometry.js
• The helper outputs Lua tables for gradients ({ colors = {...}, angle = n }) and strings for solid colors
• Fallback colors are applied automatically when theme keys are missing or undefined
• Documented in docs/theming.md (lines 169-171) and tested in test/cli/gradient-test.txt.tpl (lines 300-456)

Frequently Asked Questions

What file contains the hypr_gradient implementation?

The primary implementation is located in bin/omarchy-theme-set-templates at approximately line 141, specifically within the hypr_gradient_value() shell function. Gradient string parsing is handled by shell/Commons/BorderGeometry.js.

How does hypr_gradient handle missing theme tokens?

When the requested key does not exist in the current theme, the helper immediately returns the fallback color provided as the second argument. According to the test suite in test/cli/gradient-test.txt.tpl (lines 450-453), this behavior is validated to ensure consistent fallback output.

What format does Hyprland expect for gradient definitions?

Hyprland requires gradients as Lua tables with a specific structure: { colors = { "rgba(...)", "rgba(...)" }, angle = <number> }. The hypr_gradient helper automatically generates this structure when it detects gradient syntax (two rgba values followed by an angle in degrees) in the theme token.

Can hypr_gradient be used outside of Hyprland templates?

While designed specifically for Hyprland configuration generation, the helper is technically available in any Omarchy template processed by omarchy-theme-set-templates. However, its output format (Lua tables and strings) is optimized for Hyprland's Lua-based configuration system, making it most appropriate for .lua.tpl template files.

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