# Understanding the hypr_gradient Template Helper in Omarchy

> Explore the hypr_gradient template helper in Omarchy. Learn how this Jinja-style function converts theme color tokens into Hyprland-compatible Lua tables or strings for gradients and solid colors.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: deep-dive
- Published: 2026-09-11

---

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

```jinja
{{ hypr_gradient key fallback_color }}

```

For example:

```jinja
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`](https://github.com/omacom/omarchy/blob/main/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:

```lua
{ 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**:

```lua
"#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:

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

```

If the theme contains:

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

```

The rendered output becomes:

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

```

### Handling Solid Colors

If the same theme key contains a solid color:

```yaml
hyprland_active_border: "#336699"

```

The helper outputs:

```lua
local active_border_color = "#336699"

```

### Shell Implementation Reference

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

```bash
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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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.