# Configuring Omarchy Bar Position and Transparency: A Complete Guide

> Master omarchy bar position and transparency. Learn how to effortlessly configure these settings using CLI commands, gestures, or the Style menu for instant visual customization.

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

---

**Omarchy bar position and transparency are controlled through the `bar` object in `~/.config/omarchy/shell.json`, configurable via CLI commands (`omarchy bar position <edge>` and `omarchy bar transparent <bool>`), interactive gestures, or the Style menu, with all methods updating the same canonical configuration and applying changes instantly via IPC.**

Configuring Omarchy bar position and transparency personalizes your Quickshell-based desktop environment by anchoring the status bar to any screen edge and controlling background opacity. The bar implementation (`omarchy.bar` plugin) reads its settings from a JSON subtree in the user's shell configuration, supporting programmatic updates through the `omarchy-bar` CLI tool and immediate visual feedback through IPC notifications. Whether you prefer terminal commands, direct file edits, UI gestures, or menu selections, all configuration methods converge on the same `~/.config/omarchy/shell.json` file, ensuring consistent state across sessions.

## Understanding the Bar Configuration Architecture

The Omarchy bar is implemented as a **Quickshell plugin** declared in [`manifest.json`](https://github.com/omacom/omarchy/blob/main/manifest.json) with `id: omarchy.bar` and `kind: bar`, instantiated from `Bar.qml` and hosted within the main shell. According to the Omarchy source code, the host shell (`shell/shell.qml`) loads the configuration from `~/.config/omarchy/shell.json` (falling back to [`config/omarchy/shell.json`](https://github.com/omacom/omarchy/blob/main/config/omarchy/shell.json)) and injects the `barConfig` property into the plugin instance.

The configuration schema defines two primary settings:
- **`bar.position`** – Accepts string values `"top"`, `"bottom"`, `"left"`, or `"right"` to control screen anchoring
- **`bar.transparent`** – Boolean `true` or `false` that determines whether the background is fully opaque or reveals the desktop wallpaper

When modifications occur, the bar reacts to **IPC updates** immediately without requiring a restart, as the running instance watches the configuration file and internal IPC channels for changes.

## Changing Bar Position via CLI

The `omarchy-bar` script provides direct manipulation of the bar's screen position through the `omarchy bar position` command. This CLI tool updates the user's [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json) and notifies the running bar via the internal IPC channel.

Move the bar to the bottom edge:

```bash
omarchy bar position bottom

```

Anchor the bar to the left side:

```bash
omarchy bar position left

```

Valid position arguments include `top`, `bottom`, `left`, and `right`. The change takes effect immediately, repositioning the Quickshell bar to the specified screen edge.

## Toggling Bar Transparency via CLI

Control background opacity using the `omarchy bar transparent` command, which accepts boolean values or a toggle switch:

Toggle between opaque and transparent modes:

```bash
omarchy bar transparent toggle

```

Explicitly enable or disable transparency:

```bash

# Enable transparency (wallpaper visible through bar)

omarchy bar transparent true

# Disable transparency (solid background)

omarchy bar transparent false

```

As implemented in `bin/omarchy-bar`, these commands modify the `bar.transparent` value in the JSON configuration and trigger an IPC update to the running bar instance.

## Direct Configuration File Editing

For manual configuration, edit the `bar` object in `~/.config/omarchy/shell.json`. The user configuration file becomes the **canonical source** after the first modification, superseding any default values shipped with the distribution.

Example configuration placing the bar on the right with transparency enabled:

```json
{
  "bar": {
    "position": "right",
    "transparent": true,
    "layout": {}
  }
}

```

After saving changes to `~/.config/omarchy/shell.json`, the bar detects the file modification and reloads automatically. Alternatively, execute `omarchy reload` to force an immediate refresh.

## Interactive Configuration Methods

Beyond CLI and file editing, Omarchy supports intuitive gesture-based configuration defined in the bar plugin's QML implementation.

**Repositioning via drag:**
Drag an empty section of the bar (click-and-hold on neutral space) to move it to a different screen edge. The gesture updates `bar.position` in [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json) through the same IPC mechanism as the CLI commands.

**Toggling transparency via double-click:**
Double-left-click the empty center area of the bar to toggle the `bar.transparent` boolean value instantly.

## Menu-Driven Configuration

The Omarchy menu provides graphical access to bar settings through entries defined in `default/omarchy/omarchy-menu.jsonc`. Navigate to **Style → Menu Bar** to access:

- **Position** – Select from Top, Bottom, Left, or Right
- **Transparency** – Toggle between Opaque and Transparent modes

These menu entries invoke the same `omarchy-bar` CLI commands internally, ensuring consistency with terminal-based configuration. The menu mappings reference `"style.bar.position"` and `"style.bar.transparency"` keys that correlate to the CLI functionality.

## Key Source Files and References

Understanding the following source files helps troubleshoot configuration issues and customize advanced behavior:

| File | Purpose |
|------|---------|
| [`shell/plugins/bar/README.md`](https://github.com/omacom/omarchy/blob/main/shell/plugins/bar/README.md) | Documents the bar plugin architecture, configuration schema, and user-facing commands |
| `bin/omarchy-bar` | Implements the `omarchy bar` CLI commands that modify [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json) and trigger IPC updates |
| `shell/shell.qml` | Host shell script that loads [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json) and provides the `barConfig` property to the bar plugin |
| [`config/omarchy/shell.json`](https://github.com/omacom/omarchy/blob/main/config/omarchy/shell.json) | Default configuration file shipped with the distribution |
| `default/omarchy/omarchy-menu.jsonc` | Menu definitions mapping UI selections to bar configuration commands |
| `~/.config/omarchy/shell.json` | User-specific configuration file that becomes the canonical source after first modification |

The bar plugin exposes properties such as `bar.position` and `bar.vertical` to widgets, allowing custom components to adapt their layout based on the current bar orientation and transparency state.

## Summary

- **Omarchy bar position and transparency** are stored in the `bar` object within `~/.config/omarchy/shell.json`, supporting values `"top"`, `"bottom"`, `"left"`, `"right"` for position and boolean values for transparency.
- **Three configuration methods** exist: CLI commands (`omarchy bar position|transparent`), direct JSON file editing, and interactive gestures (drag-to-move, double-click-to-toggle).
- **Immediate application** occurs via IPC updates to the running Quickshell bar instance without requiring session restarts.
- **Menu integration** at Style → Menu Bar provides graphical access to the same CLI functionality.
- **Source authority** transitions from default [`config/omarchy/shell.json`](https://github.com/omacom/omarchy/blob/main/config/omarchy/shell.json) to user-specific `~/.config/omarchy/shell.json` after initial modification.

## Frequently Asked Questions

### How do I move the Omarchy bar to a different screen edge?

Use the command `omarchy bar position <edge>` where `<edge>` is `top`, `bottom`, `left`, or `right`. For example, `omarchy bar position bottom` anchors the bar to the bottom of the screen. You can also drag an empty area of the bar to reposition it interactively, or use the Style → Menu Bar → Position menu.

### What happens to my bar configuration when I edit shell.json manually?

When you save changes to `~/.config/omarchy/shell.json`, the running bar detects the file modification through its file watcher and applies updates immediately via IPC. If the bar does not update automatically within a few seconds, run `omarchy reload` to force a configuration refresh.

### Can I make the Omarchy bar semi-transparent instead of fully transparent or opaque?

The current implementation in `bin/omarchy-bar` and the bar plugin's QML configuration treats transparency as a boolean value (`true` or `false`) rather than an opacity percentage. The `bar.transparent` setting switches between fully opaque and fully transparent backgrounds that reveal the desktop wallpaper. For partial transparency, you would need to modify the `Bar.qml` source or create a custom theme override.

### Where does Omarchy store the default bar configuration before I make changes?

Default settings are defined in [`config/omarchy/shell.json`](https://github.com/omacom/omarchy/blob/main/config/omarchy/shell.json) within the Omarchy installation directory. Once you modify the bar position or transparency using any method (CLI, gestures, or menu), the system creates or updates `~/.config/omarchy/shell.json`, which then becomes the canonical source that overrides all defaults for subsequent sessions.