How to Use Color Blending in Omarchy Templates: A Complete Guide

Omarchy provides two built-in template helpers—hypr_gradient for Hyprland Lua configurations and standard CSS color-mix() for web-based applications—that enable dynamic color blending using theme variables defined in themes/*/colors.toml.

Omarchy's theming system allows you to blend colors dynamically inside template files that generate configuration files for applications ranging from Hyprland to Obsidian and VS Code. By leveraging the hypr_gradient helper and CSS color-mix functions, you can create visually consistent, theme-aware configurations without hardcoding color values. This guide explains how to implement color blending in Omarchy templates based on the actual source code in the omacom/omarchy repository.

Understanding the Two Color Blending Approaches

Omarchy templates support two distinct blending methods depending on the target application format.

• hypr_gradient: Generates a Lua table containing two colors and an angle for Hyprland configurations.
• color-mix(): Standard CSS 4 function for blending theme colors with transparency percentages.

Both methods reference theme variables (like {{ foreground }}, {{ accent }}, {{ background }}) defined in themes/*/colors.toml. When templates are rendered via bin/omarchy-theme-set-templates, these placeholders resolve to actual hex or rgba values.

Using the hypr_gradient Helper for Hyprland

The hypr_gradient helper is specifically designed for Hyprland's Lua configuration format, which expects gradient tables rather than simple color strings.

Syntax and Parameters

The helper follows this template syntax:

{{ hypr_gradient <gradient-name> <fallback-color> }}

• <gradient-name>: References a gradient definition in the theme (e.g., hyprland_active_border).
• <fallback-color>: A solid color value used if the gradient name is missing (e.g., accent or rgba(595959aa)).

Example: Hyprland Border Configuration

In default/themed/hyprland.lua.tpl, the helper generates gradient tables for window borders:

local active_border_color = {{ hypr_gradient hyprland_active_border accent }}
local inactive_border_color = {{ hypr_gradient hyprland_inactive_border rgba(595959aa) }}

return {
    active_border   = active_border_color,
    inactive_border = inactive_border_color,
}

When rendered with the aether theme, this produces a valid Lua table:

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

Fallback Behavior

If the specified gradient name does not exist in the theme, the helper renders the fallback color instead. As shown in test/cli, referencing a missing gradient with {{ hypr_gradient missing accent }} will output the accent color value rather than a gradient table.

CSS Color Mixing for Web-Based Applications

For CSS-based targets like Obsidian and VS Code themes, Omarchy supports the standard CSS color-mix() function combined with template variables.

Example: Semi-Transparent Text in Obsidian

The file default/themed/obsidian.css.tpl demonstrates blending theme colors with transparency:

:root {
  --text-muted: color-mix(in srgb, {{ foreground }} 70%, transparent);
  --text-faint: color-mix(in srgb, {{ foreground }} 55%, transparent);
}

If the theme defines foreground as #c0c0c0, the rendered CSS becomes:

:root {
  --text-muted: color-mix(in srgb, #c0c0c0 70%, transparent);
  --text-faint: color-mix(in srgb, #c0c0c0 55%, transparent);
}

Example: VS Code Theme Variables

The template default/themed/vscode-theme.json.tpl shows direct variable substitution without blending:

{
  "colors": {
    "statusBar.background": "{{ accent }}",
    "statusBar.noFolderBackground": "{{ background }}",
    "editorLineNumber.foreground": "{{ muted }}"
  }
}

Implementation and Source Files

The color blending logic is implemented in bin/omarchy-theme-set-templates, which processes templates and replaces placeholders with values from themes/*/colors.toml. According to the source code, this script provides several gradient-related helpers including hypr_gradient, gradient_start, and shell_gradient.

Key files in the omacom/omarchy repository:

• docs/theming.md: Canonical documentation describing the hypr_gradient helper syntax and table format.
• default/themed/hyprland.lua.tpl: Practical example of border color blending in Hyprland configs.
• default/themed/obsidian.css.tpl: Demonstrates CSS color-mix with template variables.
• default/themed/vscode-theme.json.tpl: Shows variable substitution for editor themes.
• test/cli: Test suite verifying correct rendering and fallback behavior.

Summary

• Use hypr_gradient when generating Hyprland Lua configurations that require gradient tables with angle properties.
• Use CSS color-mix() for web-based applications needing transparency blending with theme variables.
• Reference theme variables using {{ variable_name }} syntax, pulling from themes/*/colors.toml.
• Provide fallback colors in hypr_gradient to ensure configs render correctly even if specific gradient definitions are missing.
• Check docs/theming.md for canonical documentation of available helpers and syntax.

Frequently Asked Questions

What is the difference between hypr_gradient and color-mix?

hypr_gradient generates a Lua table specifically formatted for Hyprland's configuration system, containing two colors and an angle, while color-mix is a standard CSS 4 function that returns a single color value blended with transparency. Use hypr_gradient for Hyprland configs and color-mix for CSS-based applications.

Where are theme color variables defined?

Theme variables like {{ foreground }}, {{ accent }}, and {{ background }} are defined in colors.toml files within each theme directory under themes/*/. These variables are interpolated during the template rendering process managed by bin/omarchy-theme-set-templates.

What happens if a gradient name doesn't exist in the theme?

The hypr_gradient helper accepts a fallback color parameter as its second argument. If the specified gradient name is not found in the theme definition, the helper renders the fallback color instead. For example, {{ hypr_gradient missing accent }} will output the value of the accent variable if missing is undefined.

Can I use these blending helpers in any Omarchy template?

Yes, the helpers are available in all template files processed by the Omarchy theming system, including those in default/themed/ and custom overlays. However, choose the appropriate helper based on the target format: use hypr_gradient only for Lua configs targeting Hyprland, and color-mix for CSS-compatible targets.

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