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

Configure Omarchy shell appearance by editing 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, 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 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)

Themes are stored under themes/ in the Omarchy installation. For example, the built-in tokyo-night theme includes its own shell.toml alongside colors.toml.

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

   └─ shell.toml       # appearance overrides

shell.toml Structure and Key Sections

Each section controls a distinct aspect of the shell UI. Colors use template placeholders from 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

[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.

[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

[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

[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.

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

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

Option 2: Start from the Template

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:

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

Reloading the Shell After Changes

Quickshell does not auto-detect shell.toml changes. Use one of these methods:

# 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 → active theme's shell.toml → falls back to the rendered template if files are missing.

Complete Example: Minimal Dark Theme

# 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 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 tokens (e.g., {{ red }}) for consistent theming

Frequently Asked Questions

What happens if I delete shell.toml from my theme?

Quickshell falls back to 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, 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 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.

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