# How to Configure Omarchy Shell (`shell.toml`): A Complete Guide to Theme Customization

> Customize your Omarchy shell by editing shell.toml. Learn to configure themes, bars, fonts, and spacing for a personalized look. Reload changes easily with omarchy-restart-shell.

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

---

**Configure Omarchy shell appearance by editing [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) in your active theme directory—modifying `[bar]`, `[controls]`, `[spacing]`, `[font]`, and `[hyprland]` sections—then reload with `omarchy-restart-shell`.**

Omarchy's desktop environment runs on **Quickshell**, a long-running QML host that renders the top bar, control panels, notifications, and lock screens. The visual styling for these components is controlled entirely through **[`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml)**, a TOML-based theme file. This guide walks through the exact file structure, configuration options, and reload workflow used in the `omacom/omarchy` source code.

## Where [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) Lives

The shell discovers its theme file through a specific resolution order:

1. **Runtime override**: `~/.config/omarchy/shell.json` (JSON format, user-specific)
2. **Active theme**: `themes/<name>/shell.toml` (overrides defaults)
3. **Fallback template**: `default/themed/shell.toml.tpl` ([view source](https://github.com/omacom/omarchy/blob/quattro/default/themed/shell.toml.tpl))

Themes are stored under `themes/` in the Omarchy installation. For example, the built-in `tokyo-night` theme includes its own [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) alongside [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml).

```bash
themes/
└─ tokyo-night/
   ├─ colors.toml      # palette definitions

   └─ shell.toml       # appearance overrides

```

## [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) Structure and Key Sections

Each section controls a distinct aspect of the shell UI. Colors use template placeholders from [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) (e.g., `{{ foreground }}`, `{{ red }}`) rather than hardcoded values.

### `[bar]` — Top/Bottom Panel Styling

Controls the main status bar dimensions, colors, and transparency.

| Key | Purpose | Example |
|-----|---------|---------|
| `background` | Base fill color | `"{{ background }}"` |
| `background-alpha` | Opacity (0.0–1.0) | `0.7` |
| `text` | Foreground color | `"{{ foreground }}"` |
| `active` | Accent for focused workspace, etc. | `"{{ red }}"` |
| `scale-with-font` | Auto-scale dimensions with font size | `true` |
| `size-horizontal` | Bar height on horizontal screens (px) | `28` |
| `size-vertical` | Bar width on vertical screens (px) | `32` |

```toml
[bar]
background       = "{{ background }}"
background-alpha = 0.7
text             = "{{ foreground }}"
active           = "{{ magenta }}"
scale-with-font  = true
size-horizontal  = 32
size-vertical    = 36

```

### `[hyprland]` — Border Tokens for Lock Screens and Pop-ups

Defines gradient/fallback border styles derived from Hyprland configuration, used by notifications, OSD pop-ups, and lock screen UI.

```toml
[hyprland]
active-border           = "rgba(0,0,0,0.5) rgba(255,255,255,0.5) 45deg"
active-border-foreground = "{{ foreground }}"

```

### `[controls]` — Buttons, Dropdowns, Tabs, and Interactive Elements

Styles all interactive UI chrome.

| Key | Purpose |
|-----|---------|
| `normal-color` | Default text/icon color |
| `normal-fill-alpha` | Background opacity |
| `normal-border` | Border color |
| `normal-border-width` | Border thickness (px) |
| `hover-cursor-color` | Accent on mouse hover |
| `hover-cursor-border-width` | Hover border thickness |
| `focus-color` | Focused state color |
| `selected-color` | Selected/toggled state |
| `pressed-fill-alpha` | Clicked state background opacity |

```toml
[controls]
normal-color           = "{{ foreground }}"
normal-fill-alpha      = 0.05
normal-border          = "{{ overlay0 }}"
normal-border-width    = 1
hover-cursor-color     = "{{ pink }}"
hover-cursor-border-width = 2
focus-color            = "{{ pink }}"
selected-color         = "{{ peach }}"
pressed-fill-alpha     = 0.25

```

### `[spacing]` — Margins, Gaps, and Padding

Controls layout density throughout the shell.

| Key | Default spacing token for |
|-----|---------------------------|
| `scale` | Global multiplier for all spacing |
| `scale-with-font` | Link spacing to font scale |
| `xxs`–`xxxl`, `huge` | Named spacing tokens |
| `control-gap` | Between buttons, inputs |
| `panel-gap` | Between major UI sections |

```toml
[spacing]
scale           = 1.15
scale-with-font = true
control-gap     = 8
panel-gap       = 12
md              = 16

```

### `[font]` — Typographic Scale

Establishes the base size and derived heading levels.

```toml
[font]
base-size = 13
caption   = "0.85rem"
subtitle  = "1.1rem"
heading   = "1.4rem"

```

## How to Create or Modify a Theme

### Option 1: Extend an Existing Theme

Copy the theme directory and edit its [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml):

```bash
cp -r themes/tokyo-night themes/my-theme
$EDITOR themes/my-theme/shell.toml

```

### Option 2: Start from the Template

```bash
mkdir -p themes/custom
cp default/themed/shell.toml.tpl themes/custom/shell.toml
$EDITOR themes/custom/shell.toml

```

Activate your theme (typically via `omarchy-theme` or by setting the active theme symlink).

### Option 3: User-Specific JSON Override

For quick tweaks without creating a full theme, edit `~/.config/omarchy/shell.json`. The shell reads this first and maps JSON keys to TOML sections:

```json
{
  "bar": {
    "sizeHorizontal": 34,
    "backgroundAlpha": 0.9
  },
  "spacing": {
    "scale": 1.25
  }
}

```

## Reloading the Shell After Changes

Quickshell does not auto-detect [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) changes. Use one of these methods:

```bash

# Full restart of the Quickshell process

omarchy-restart-shell

# IPC reload without process restart (if supported)

omarchy-shell shell reloadConfig

```

The shell parses [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json) → active theme's [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) → falls back to the rendered template if files are missing.

## Complete Example: Minimal Dark Theme

```toml

# themes/my-dark/shell.toml

[bar]
background       = "#1e1e2e"
background-alpha = 0.85
text             = "#cdd6f4"
active           = "#f38ba8"
scale-with-font  = true
size-horizontal  = 28
size-vertical    = 30

[hyprland]
active-border = "rgba(0,0,0,0.5) rgba(255,255,255,0.5) 45deg"

[controls]
normal-color           = "#cdd6f4"
normal-fill-alpha      = 0.05
normal-border          = "#585b70"
normal-border-width    = 1
hover-cursor-color     = "#f38ba8"
hover-cursor-border-width = 2
focus-color            = "#f38ba8"
selected-color         = "#fab387"
pressed-fill-alpha     = 0.25

[spacing]
scale       = 1.1
control-gap = 10
panel-gap   = 12

[font]
base-size = 13

```

## Summary

- **[`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml)** in `themes/<name>/` defines Omarchy's visual appearance through five sections: `[bar]`, `[hyprland]`, `[controls]`, `[spacing]`, and `[font]`
- **Template file**: `default/themed/shell.toml.tpl` provides the fallback defaults
- **Runtime override**: `~/.config/omarchy/shell.json` allows quick user-specific tweaks
- **Reload required**: Run `omarchy-restart-shell` or `omarchy-shell shell reloadConfig` after any changes
- **Color placeholders**: All color values reference [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) tokens (e.g., `{{ red }}`) for consistent theming

## Frequently Asked Questions

### What happens if I delete [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) from my theme?

Quickshell falls back to [`config/omarchy/shell.json`](https://github.com/omacom/omarchy/blob/main/config/omarchy/shell.json), then to the rendered `default/themed/shell.toml.tpl`. The shell will still function with default styling, but customizations are lost.

### Can I use raw hex colors instead of `{{ placeholder }}` tokens?

Yes. While the template uses placeholders that render from [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml), you can substitute any valid CSS color: hex (`#1e1e2e`), `rgb()`, `rgba()`, or named colors. Placeholders are recommended only for consistency with the palette.

### Why aren't my [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) changes appearing after edit?

Quickshell does not watch the file for changes. You must explicitly reload via `omarchy-restart-shell` (full process restart) or `omarchy-shell shell reloadConfig` (config re-parse). Verify you're editing the correct file in the currently active theme directory.

### How do I find which theme is currently active?

Check the symlink or configuration that points to `themes/<name>`. The shell logs the resolved path on startup; run `journalctl --user -u omarchy-shell` or check `~/.local/state/omarchy/shell.log` if available.

### What's the difference between `size-horizontal` and `size-vertical` in `[bar]`?

`size-horizontal` controls bar **height** on landscape displays; `size-vertical` controls bar **width** on portrait displays. This distinction accommodates rotated monitors or tablets with vertical orientation.