# How to Add a New Template File to the Omarchy Theming System

> Easily add a new template file to the Omarchy theming system. Create a *.tpl file and run omarchy-theme-set-templates to render your custom theme.

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

---

**Adding a new template file to the Omarchy theming system requires creating a `*.tpl` file in `default/themed/` with Jinja-style placeholders, then running the `omarchy-theme-set-templates` command to render the output into your `~/.config/` directory.**

Omarchy, maintained by `omacom`, is an open-source Linux configuration framework that manages application theming through a declarative template architecture. When adding a new template file to the Omarchy theming system, you insert variable placeholders—such as `{{ accent }}` or `{{ background }}`—that automatically populate with values from your active theme’s [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml), ensuring consistent color propagation across all supported applications.

## Understanding the Omarchy Template Architecture

Omarchy stores source templates in the `default/themed/` directory of the repository. Each file uses the `.tpl` extension and contains plain text configuration mixed with variable placeholders. These placeholders map directly to keys defined in the active theme’s [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file, located at `themes/<theme_name>/colors.toml`.

The rendering logic resides in `bin/omarchy-theme-set-templates`. This script reads the active theme variables, substitutes all placeholders using Jinja-style syntax, and writes the final, concrete configuration files into your user’s `~/.config/` directory while preserving the original subdirectory layout. This separation of template source and rendered output allows dynamic theme switching without manually editing static configuration files.

## Creating a New Template File

To add support for a new application, create a `.tpl` file containing the target program’s standard configuration syntax with Omarchy placeholder variables.

First, navigate to the template source directory:

```bash
cd "$OMARCHY_PATH/default/themed"

```

Create a new template with appropriate placeholders. For example, to template a configuration file for a hypothetical application named `myapp`, create `myapp.conf.tpl`:

```bash
cat > myapp.conf.tpl <<'EOF'

# MyApp configuration generated from the active Omarchy theme

background = "{{ background }}"
foreground = "{{ foreground }}"
accent     = "{{ accent }}"
EOF

```

**Standard placeholders** like `{{ background }}`, `{{ foreground }}`, and `{{ accent }}` are universally available across Omarchy themes, though you can reference any custom key defined in the theme’s [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml). Existing templates such as `default/themed/hyprland.lua.tpl` and `default/themed/alacritty.toml.tpl` demonstrate advanced usage of nested placeholders and conditional logic.

## Rendering and Deploying Templates

After creating or modifying a template, execute the rendering command to generate the actual configuration files in `~/.config/`:

```bash
omarchy-theme-set-templates

```

This command processes every `.tpl` file in `default/themed/`, substitutes variables from the active theme’s [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml), and mirrors the directory structure in your configuration folder. Omarchy triggers this rendering automatically when switching themes, but manual execution is required after adding new template files to ensure immediate deployment.

To render a specific template rather than the entire set, use the `--only` flag followed by the target base filename:

```bash
omarchy-theme-set-templates --only hyprland.lua

```

## Key Files in the Omarchy Theming System

Reference these source files when extending the theming system according to the `omacom/omarchy` codebase:

- **`default/themed/`** – The root directory containing all `*.tpl` source files
- **`default/themed/hyprland.lua.tpl`** – A fully-featured example demonstrating complex placeholder usage for window manager configuration
- **`default/themed/alacritty.toml.tpl`** – Shows terminal emulator templating with color variable substitution
- **`bin/omarchy-theme-set-templates`** – The CLI entry point that orchestrates template rendering and deployment
- **[`docs/theming.md`](https://github.com/omacom/omarchy/blob/main/docs/theming.md)** – Official documentation covering the template workflow and variable naming conventions
- **`themes/<theme_name>/colors.toml`** – The source of truth for all color values consumed by templates during rendering

## Summary

- **Place new templates** in `default/themed/` using the `*.tpl` extension so Omarchy recognizes them as theme sources during the rendering cycle
- **Use Jinja-style syntax** (`{{ variable }}`) to mark values that should be substituted from the active theme’s [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml)
- **Run `omarchy-theme-set-templates`** to render all templates and write them to `~/.config/` whenever you add or modify template files
- **Use the `--only` flag** to render a specific template by name when you want to avoid regenerating the entire configuration directory
- **Reference existing templates** like `hyprland.lua.tpl` for implementation patterns and standard placeholder naming conventions

## Frequently Asked Questions

### Where should I place new template files in the Omarchy repository?

Place new template files in the `default/themed/` directory at the root of the repository. According to the `omacom/omarchy` source code, the `omarchy-theme-set-templates` command recursively scans this location for `*.tpl` files during the rendering process.

### What placeholder syntax does Omarchy use for theme variables?

Omarchy uses double curly brace syntax (`{{ variable_name }}`) for placeholders, compatible with Jinja2-style templating. Variables reference keys defined in your active theme’s [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file, such as `{{ background }}`, `{{ foreground }}`, or `{{ accent }}`.

### How do I apply theme changes after editing a template file?

Run the `omarchy-theme-set-templates` command located at `bin/omarchy-theme-set-templates` to immediately render all templates and deploy them to `~/.config/`. This command is automatically invoked when switching themes via Omarchy's theme management utilities, but must be run manually after adding new template files.

### Can I render only a specific template instead of regenerating everything?

Yes. Pass the `--only` flag followed by the base filename (without the `.tpl` extension) to `omarchy-theme-set-templates` to process a single template. For example, `omarchy-theme-set-templates --only hyprland.lua` renders only the Hyprland configuration while leaving other files untouched.