# Omarchy Shell Bar Layout Configuration: JSON Schema, Loading Logic, and Runtime Updates

> Configure the Omarchy shell bar layout using JSON schema for left, center, and right widgets. Learn about loading logic and runtime updates without restarts for the omacom/omarchy repository.

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

---

**The Omarchy shell bar layout is defined in `~/.config/omarchy/shell.json` using a JSON object with `left`, `center`, and `right` arrays that specify widget IDs and optional size parameters, which the shell validates and hot-reloads without requiring a restart.**

The Omarchy desktop environment uses a declarative configuration system to render its top-level status bar. Understanding the Omarchy shell bar layout configuration file format and loading behavior enables precise control over widget placement, spacing, and runtime customization.

## Configuration File Location and Schema

The primary configuration resides at **`~/.config/omarchy/shell.json`**, falling back to the repository default at **`$OMARCHY_PATH/config/omarchy/shell.json`** when the user file is absent or malformed. The JSON schema requires a top-level **`version`** field set to `1` and a **`bar`** object containing a **`layout`** dictionary with three mandatory arrays: **`left`**, **`center`**, and **`right`**.

```json
{
  "version": 1,
  "bar": {
    "layout": {
      "left":   [{ "id": "omarchy.workspaces", "size": 2 }],
      "center": [{ "id": "omarchy.clock" }],
      "right":  [{ "id": "omarchy.tray" }]
    }
  },
  "plugins": []
}

```

Each entry requires an **`id`** property matching a registered plugin identifier (e.g., `omarchy.clock`). The optional **`size`** numeric hint controls relative spacing allocation. Widget entries may also be plain strings; the shell normalizes these to object form during initialization, as verified by the plugin registry test that checks "clone restoration normalizes string entries" at line 346 in `test/shell.d/fixtures/plugin-registry/shell.qml`.

## Loading Mechanism and Validation

In `shell/shell.qml`, the loading logic prioritizes the user configuration file, defaulting to the system path when unavailable. The implementation at lines 30-34 handles this fallback chain. The shell enforces schema compliance through the test suite in [`test/shell.d/config-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/config-test.sh) at line 16, which validates the presence of the `version: 1` field and the three layout arrays. Upon successful validation, the **`Bar`** component receives the resolved configuration via the **`barConfig`** property, injected by `shell.qml` during initialization.

## Runtime Modifications and Hot-Reloading

Changes to the layout propagate immediately through a hot-reload mechanism that replaces the entire bar subtree rather than performing deep merges. This behavior is documented in [`shell/plugins/bar/README.md`](https://github.com/omacom/omarchy/blob/main/shell/plugins/bar/README.md) at lines 12-18. Because the file is the single source of truth, any change is picked up by the running shell through its hot-reload mechanism—no deep-merge is performed; the whole bar subtree is replaced with the new JSON content.

The **`omarchy bar`** CLI provides imperative manipulation commands. For example, adding a widget to the right section:

```bash
omarchy bar add omarchy.battery --section right

```

This command updates the [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json) file directly, inserting the widget ID into the specified array. The running shell detects the file change and reconstructs the bar layout accordingly.

## Default Layout and Widget Settings

The repository ships with a default configuration placing workspaces on the left, a clock in the center, and a system tray on the right. This default is asserted in [`test/shell.d/clock-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/clock-test.sh) at line 264, which verifies the center section contains the clock widget.

Individual widget instances receive their configuration through `shell/Ui/BarWidget.qml`, which parses the **`settings`** property from each layout entry at line 9. This allows per-widget customization such as custom formats or display modes within the declarative JSON structure.

## Practical Configuration Examples

### Adding Multiple Widgets to the Center Section

```json
{
  "version": 1,
  "bar": {
    "layout": {
      "left":   [{ "id": "omarchy.workspaces" }],
      "center": [
        { "id": "omarchy.clock" },
        { "id": "omarchy.weather" }
      ],
      "right":  [{ "id": "omarchy.tray" }]
    }
  }
}

```

Save this to `~/.config/omarchy/shell.json` to display both clock and weather widgets centered in the bar.

### Programmatic Widget Removal

Within QML scripts or plugins, interact with the registry to remove widgets dynamically:

```javascript
// Remove battery widget from layout
registry.putBarWidget("omarchy.battery", { remove: true });

```

The registry updates the underlying JSON array, triggering the bar's reactive reconstruction.

## Summary

- **Omarchy shell bar layout configuration** resides in `~/.config/omarchy/shell.json` with a fallback to `$OMARCHY_PATH/config/omarchy/shell.json`.
- The JSON schema requires `version: 1` and three arrays (`left`, `center`, `right`) containing widget objects with `id` and optional `size` properties.
- `shell/shell.qml` (lines 30-34) implements the loading priority and validation logic confirmed by [`test/shell.d/config-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/config-test.sh) (line 16).
- Runtime changes trigger hot-reload of the entire bar subtree without deep merging, as documented in [`shell/plugins/bar/README.md`](https://github.com/omacom/omarchy/blob/main/shell/plugins/bar/README.md) (lines 12-18).
- The CLI command `omarchy bar add [widget-id] --section [left|center|right]` manipulates the configuration file directly.
- `shell/Ui/BarWidget.qml` (line 9) handles per-widget settings parsing from the layout entries.

## Frequently Asked Questions

### Where is the Omarchy bar layout configuration file stored?

The primary user configuration is located at `~/.config/omarchy/shell.json`. If this file is missing or contains invalid JSON, the shell falls back to the default configuration at `$OMARCHY_PATH/config/omarchy/shell.json`, as implemented in `shell/shell.qml` at lines 30-34.

### What properties are required for each widget entry in the layout arrays?

Each entry must include an **`id`** property containing the plugin identifier (e.g., `omarchy.clock`). An optional **`size`** integer controls spatial allocation. Entries may be specified as plain strings or objects; the shell normalizes strings to object form during initialization according to the test logic at line 346 of `test/shell.d/fixtures/plugin-registry/shell.qml`.

### How does the Omarchy shell handle configuration changes while running?

The shell implements a hot-reload mechanism that monitors the configuration file for changes. When detected, it replaces the entire bar subtree with the new configuration rather than merging changes selectively. This behavior ensures the file remains the single source of truth and is documented in [`shell/plugins/bar/README.md`](https://github.com/omacom/omarchy/blob/main/shell/plugins/bar/README.md) at lines 12-18.

### Can I rearrange widgets without manually editing the JSON file?

Yes. The `omarchy bar` CLI provides sub-commands to manipulate the layout programmatically. For example, `omarchy bar add omarchy.battery --section right` appends the battery widget to the right section, automatically updating [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json) and triggering the hot-reload mechanism.