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

> Master color blending in Omarchy templates with our guide. Learn to use Hyprland and CSS color-mix functions with theme variables for dynamic designs.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-04

---

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

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

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

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

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

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

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