Theming Omarchy Shell Borders with Gradients Using shell.toml

You configure gradient borders in Omarchy by defining rgba() color stops in your theme's colors.toml and referencing those values in shell.lock.toml to override the default shell border colors.

The omacom/omarchy repository provides a modern Linux desktop environment built on the Quickshell UI framework and configurable through TOML files. Theming Omarchy shell borders with gradients using shell.toml requires understanding how colors.toml defines color tokens and how shell.lock.toml maps those tokens to specific border states for the Hyprland window manager.

Understanding the Configuration Hierarchy

Omarchy resolves shell border styling through a two-layer configuration system located in each theme directory under $OMARCHY_PATH/themes/<theme-name>/.

Base Color Definitions in colors.toml

The colors.toml file defines the base color palette and gradient tokens available to the shell. Key keys include hyprland_active_border, hyprland_inactive_border, and active_border_color.

Gradient syntax follows CSS-like notation using space-separated rgba() declarations. For example, in themes/tokyo-night/colors.toml:

hyprland_active_border = "rgba(8a8588ee) rgba(e2dddcee)"
hyprland_inactive_border = "rgba(584e51aa)"
active_border_color = "#d6d3de"

Shell-Specific Overrides in shell.lock.toml

The shell.lock.toml file maps generic border keys to the color tokens defined in colors.toml. This layer allows themes to replace simple hex colors with gradient values for specific UI states.

Standard border keys include border, border-active, and border-error. In themes/tokyo-night/shell.lock.toml:

border = "#a9b1d6"
border-active = "#a9b1d6"
border-error = "#a9b1d6"

To apply a gradient, reference the exact string defined in colors.toml:

border-active = "rgba(8a8588ee) rgba(e2dddcee)"

Gradient Syntax and Examples

Quickshell supports both two-stop linear gradients and angle-based gradients for border rendering.

Two-Stop Linear Gradients

Define gradients by separating two rgba() declarations with a space. This creates a smooth transition between color stops along the window edge.

From the Tokyo-Night theme:

# themes/tokyo-night/colors.toml

hyprland_active_border = "rgba(8a8588ee) rgba(e2dddcee)"

Then activate it in your shell configuration:

border-active = "rgba(8a8588ee) rgba(e2dddcee)"

Angle-Based Gradients

For diagonal gradients, append a degree value after the color stops. The Hackerman theme demonstrates this syntax:

# themes/hackerman/colors.toml

hyprland_active_border = "rgba(26a269ee) rgba(2ec27eee) 45deg"

Apply the angled gradient to shell borders:

border-active = "rgba(26a269ee) rgba(2ec27eee) 45deg"

Runtime Border Resolution

When Quickshell initializes, it resolves border colors through the following sequence:

1. Quickshell reads the active theme from $OMARCHY_PATH/themes/<theme>/.
2. The engine loads colors.toml first, exposing keys like hyprland_active_border.
3. shell.lock.toml is parsed next, mapping border, border-active, and border-error to the color tokens.
4. If the value contains multiple rgba() stops or an angle, Quickshell generates a linear gradient for the Hyprland window borders.
5. The computed color or gradient is applied to the window manager's border rendering layer.

Disabling Outer Borders

To completely remove outer window borders regardless of gradient configuration, set pane_outer_borders to false in config/herdr/config.toml:

pane_outer_borders = false

This toggle overrides all theme-specific border settings.

Summary

• Color tokens are defined in themes/<theme>/colors.toml using keys like hyprland_active_border.
• Gradient syntax uses space-separated rgba() values or appends angles like 45deg for directional effects.
• Shell overrides occur in themes/<theme>/shell.lock.toml where border-active maps to color tokens.
• Resolution order loads colors.toml first, then applies shell.lock.toml overrides before rendering via Quickshell.
• Global disable via pane_outer_borders = false in config/herdr/config.toml removes borders entirely.

Frequently Asked Questions

What is the difference between colors.toml and shell.lock.toml?

The colors.toml file defines available color tokens and gradients for the entire theme, while shell.lock.toml maps those tokens to shell UI elements like border and border-active. Quickshell reads colors.toml first to establish the palette, then uses shell.lock.toml to determine which colors apply to specific border states.

How do I create a custom two-color gradient for active borders?

Define the gradient in your theme's colors.toml using two rgba() values separated by a space, then reference that string in shell.lock.toml under the border-active key. For example, set hyprland_active_border = "rgba(ff7f00ee) rgba(ff007fee)" in colors.toml, then set border-active = "rgba(ff7f00ee) rgba(ff007fee)" in shell.lock.toml.

Does Omarchy support angled gradients for window borders?

Yes, the Quickshell engine supports angle-based gradients by appending a degree value after the color stops in your colors.toml definition. The Hackerman theme demonstrates this with hyprland_active_border = "rgba(26a269ee) rgba(2ec27eee) 45deg", which creates a diagonal gradient across the window border.

How do I completely disable window borders in Omarchy?

Set pane_outer_borders = false in the config/herdr/config.toml file. This global configuration overrides all theme-specific border colors and gradients, effectively hiding window borders entirely.

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