# Creating a Custom Omarchy Theme with colors.toml and Template Placeholders

> Learn to create a custom Omarchy theme by customizing colors.toml and using template placeholders. Generate desktop configurations easily with Omarchy.

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

---

**Omarchy generates desktop configurations by substituting color tokens defined in [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) into template files using `{{ placeholder }}` syntax, then applying them via the `omarchy-refresh-config` command.**

Omarchy is a declarative desktop environment that separates visual styling from application logic. Creating a custom omarchy theme requires only editing a structured [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) palette and running the refresh utility to populate template placeholders across Hyprland, Alacritty, and Kitty configurations.

## How the Omarchy Theming Engine Works

The theming pipeline implemented in the `omacom/omarchy` repository follows four discrete stages:

1. **Load the palette** – The engine reads `themes/<theme-name>/colors.toml`, which defines hexadecimal color tokens such as `background`, `foreground`, `accent`, and terminal ANSI colors.
2. **Render templates** – Files in `default/themed/*.tpl` contain `{{ token }}` placeholders. The renderer substitutes each placeholder with the corresponding value from the TOML palette.
3. **Write concrete configs** – The `omarchy-refresh-config` command (implemented in `bin/omarchy`) writes the rendered files to the user’s `~/.config/` directory, backing up existing configurations.
4. **Apply the theme** – Window managers and terminals reload automatically or on next startup, picking up the new color values from the concrete config files.

Because the system is data-driven, you can create new themes without modifying the core rendering logic—only the [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file and optional template adjustments are required.

## Creating Your First Custom Theme

### Step 1: Copy an Existing Reference Theme

Clone an established theme directory as your starting point. The `themes/white` and `themes/nord` directories provide complete token sets that satisfy all template requirements.

```bash

# Copy the white theme as a template

cp -r $OMARCHY_PATH/themes/white $OMARCHY_PATH/themes/example

# Or reference the Nord palette online

# https://github.com/omacom/omarchy/blob/quattro/themes/nord/colors.toml

```

### Step 2: Define Your Palette in colors.toml

Edit the new theme’s [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) to specify your desired color scheme. The file must define standard tokens used by templates across the desktop environment.

```toml

# themes/example/colors.toml

background = "#1e1e2e"
foreground = "#cdd6f4"
accent     = "#f5c2e7"
red        = "#f38ba8"
green      = "#a6e3a1"
yellow     = "#f9e2af"
blue       = "#89b4fa"
magenta    = "#cba6f7"
cyan       = "#89dceb"

```

View the reference implementation at [[`themes/white/colors.toml`](https://github.com/omacom/omarchy/blob/main/themes/white/colors.toml)](https://github.com/omacom/omarchy/blob/quattro/themes/white/colors.toml) to see the complete set of required tokens.

### Step 3: Understanding Template Placeholders

Template files in `default/themed/` use double-brace syntax to reference TOML tokens. When `omarchy-refresh-config` runs, it performs literal string substitution.

For example, [`default/themed/hyprland.lua.tpl`](https://github.com/omacom/omarchy/blob/quattro/default/themed/hyprland.lua.tpl) contains:

```lua
-- default/themed/hyprland.lua.tpl
default_border_color = "{{ background }}"
default_active_border_color = "{{ accent }}"
default_text_color = "{{ foreground }}"

```

After processing the *example* theme, the output becomes:

```lua
-- rendered ~/.config/hypr/hyprland.lua
default_border_color = "#1e1e2e"
default_active_border_color = "#f5c2e7"
default_text_color = "#cdd6f4"

```

Similarly, [`default/themed/alacritty.toml.tpl`](https://github.com/omacom/omarchy/blob/quattro/default/themed/alacritty.toml.tpl) maps the same tokens to terminal color settings.

### Step 4: Apply with omarchy-refresh-config

Run the refresh command to generate and install the concrete configuration files:

```bash

# Generate configs from your custom theme

omarchy-refresh-config example

```

This command reads [`themes/example/colors.toml`](https://github.com/omacom/omarchy/blob/main/themes/example/colors.toml), processes all `*.tpl` files in `default/themed/`, and writes the results to `~/.config/hypr/`, `~/.config/alacritty/`, and other appropriate locations. Restart your window manager or log out to activate the new theme.

## Key Source Files and Templates

| Path | Description |
|------|-------------|
| [[`themes/white/colors.toml`](https://github.com/omacom/omarchy/blob/main/themes/white/colors.toml)](https://github.com/omacom/omarchy/blob/quattro/themes/white/colors.toml) | Minimal baseline palette demonstrating required color tokens. |
| [[`themes/nord/colors.toml`](https://github.com/omacom/omarchy/blob/main/themes/nord/colors.toml)](https://github.com/omacom/omarchy/blob/quattro/themes/nord/colors.toml) | Comprehensive example with full terminal color mappings. |
| [`default/themed/hyprland.lua.tpl`](https://github.com/omacom/omarchy/blob/quattro/default/themed/hyprland.lua.tpl) | Window manager configuration template using `{{ placeholder }}` syntax. |
| [`default/themed/alacritty.toml.tpl`](https://github.com/omacom/omarchy/blob/quattro/default/themed/alacritty.toml.tpl) | Terminal emulator template consuming the same TOML tokens. |
| `bin/omarchy` | Contains the `omarchy-refresh-config` implementation that orchestrates the rendering pipeline. |

## Summary

- Omarchy themes are defined declaratively in [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) files that specify hexadecimal color tokens.
- **Template placeholders** in `default/themed/*.tpl` files use `{{ token }}` syntax to reference these colors.
- The **`omarchy-refresh-config`** command renders templates and writes concrete configs to `~/.config/`.
- Creating a custom theme requires only copying an existing theme directory, editing [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml), and running the refresh command.
- Source templates for Hyprland and Alacritty demonstrate how placeholders map to final configuration values.

## Frequently Asked Questions

### What file format does Omarchy use for color definitions?

Omarchy uses **TOML** (`.toml`) files to define color palettes. Each theme directory contains a [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file that maps semantic names like `background`, `accent`, and `red` to hexadecimal color codes, which the rendering engine consumes during template substitution.

### Where are the theme templates stored in the repository?

Template files are located in the [`default/themed/`](https://github.com/omacom/omarchy/blob/quattro/default/themed/) directory of the `omacom/omarchy` repository. These `*.tpl` files contain placeholder strings that the `omarchy-refresh-config` command replaces with values from your active theme’s [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml).

### How do I apply a theme without restarting my session?

Run the **`omarchy-refresh-config <theme-name>`** command to regenerate configuration files immediately. While the command writes the new configs to disk instantly, some components like the window manager may require a reload (e.g., `hyprctl reload`) or logout to visually apply the updated colors.

### Can I add custom placeholders beyond the standard color tokens?

Yes. The templating engine performs literal substitution of any key defined in [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml). If you add a custom token such as `custom_highlight = "#ff00ff"` to your [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml), you can reference it in any `*.tpl` file using `{{ custom_highlight }}`, and the renderer will include it in the final output.