# How to Customize the Omarchy Bar Layout: A Complete Guide to Panel and Widget Configuration

> Learn how to customize the Omarchy bar layout by editing the groupbar table in looknfeel.lua. This guide covers panel ordering and widget assignments for a personalized setup.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-21

---

**Customize the Omarchy bar layout by editing the `groupbar` table in [`default/hypr/looknfeel.lua`](https://github.com/basecamp/omarchy/blob/main/default/hypr/looknfeel.lua), which defines panel ordering and widget assignments, then reload the Hyprland configuration to apply changes.**

The Omarchy desktop environment provides a flexible, Lua-configurable bar system built on Hyprland. To customize the Omarchy bar layout, you modify the central configuration files in the `basecamp/omarchy` repository, specifically the [`looknfeel.lua`](https://github.com/basecamp/omarchy/blob/main/looknfeel.lua) file that controls panel structure and the `apps/` directory that houses individual widget implementations.

## Understanding the Omarchy Bar Architecture

The Omarchy bar operates as a **layer-shell client** (`omarchy-shell`) that renders groups of widgets in discrete panels. According to the source code in [`default/hypr/looknfeel.lua`](https://github.com/basecamp/omarchy/blob/main/default/hypr/looknfeel.lua), the entire layout is governed by a Lua table named `groupbar` (defined at [`looknfeel.lua#L40`](https://github.com/basecamp/omarchy/blob/quattro/default/hypr/looknfeel.lua#L40)).

Each entry in the `groupbar` table represents a panel identified by a numeric index (1-9). Panels contain ordered lists of widget module names, which correspond to Lua files in `default/hypr/apps/`. The shell reads this configuration at startup to construct the visual bar and manage widget lifecycles.

Key architectural components include:

- **`groupbar` table**: The master layout definition containing panel configurations
- **Widget modules**: Individual Lua scripts in `default/hypr/apps/*.lua` implementing specific UI elements
- **Panel toggling**: Keyboard shortcuts mapped in [`default/hypr/bindings/utilities.lua`](https://github.com/basecamp/omarchy/blob/main/default/hypr/bindings/utilities.lua) that control panel visibility
- **Layer-shell rules**: Special compositor directives ensuring instant panel rendering without fade animations

## Modifying the Bar Layout in looknfeel.lua

To reshape the bar, edit [`default/hypr/looknfeel.lua`](https://github.com/basecamp/omarchy/blob/main/default/hypr/looknfeel.lua) and manipulate the `groupbar` table structure.

### Adding New Panels

Insert a new table entry into `groupbar` to create additional panels. Each panel requires a `widgets` array specifying which modules to load:

```lua
-- In default/hypr/looknfeel.lua
groupbar = {
  -- Existing panels...
  {
    name = "my-apps",                     -- Optional identifier
    widgets = { "my-widget", "omarchy-shell" }  -- Widget loading order
  },
}

```

After defining the panel, create the corresponding widget script at [`default/hypr/apps/my-widget.lua`](https://github.com/basecamp/omarchy/blob/main/default/hypr/apps/my-widget.lua):

```lua
-- my-widget.lua – a simple clock widget implementation
local widget = {}

function widget.init()
  omarchy.notify("my-widget", "Clock started")
end

function widget.render()
  return os.date("%H:%M")
end

return widget

```

### Reordering Existing Panels

Panels render in the order they appear in the `groupbar` table. To reposition a panel, rearrange the table entries:

```lua
-- Move system panel to the leftmost position
groupbar = {
  { name = "system", widgets = { "system" } },
  { name = "launcher", widgets = { "omarchy-shell" } },
  -- Additional panels follow...
}

```

### Removing Panels

Delete unwanted panels by removing their entry from the table or using Lua's `table.remove`:

```lua
-- Remove the 5th panel from the configuration
table.remove(groupbar, 5)

```

## Creating Custom Widgets for the Bar

Widgets are self-contained Lua modules that the `omarchy-shell` client dynamically loads. Each widget must implement standard lifecycle functions and reside in `default/hypr/apps/`.

A minimal widget structure requires:

- **`init()`**: Called when the widget loads into the panel
- **`render()`**: Returns the display content (strings, icons, or formatted output)

The core Omarchy shell widget ([`default/hypr/apps/omarchy-shell.lua`](https://github.com/basecamp/omarchy/blob/main/default/hypr/apps/omarchy-shell.lua)) provides the base functionality and layer-shell integration. Custom widgets inherit the drawing context from this shell implementation and must return renderable content in their `render()` functions.

## Configuring Panel Toggle Keybindings

Panel visibility is controlled through keybindings defined in [`default/hypr/bindings/utilities.lua`](https://github.com/basecamp/omarchy/blob/main/default/hypr/bindings/utilities.lua). The default shortcuts use `SUPER+SHIFT+SPACE` and `SUPER+CTRL+<number>` to toggle specific panels.

To bind a custom shortcut to a specific panel index, use the `o.bind_toggle` function:

```lua
-- In default/hypr/bindings/utilities.lua
o.bind_toggle(
  "SUPER + ALT + P",               -- Keyboard shortcut
  "Toggle my-apps panel",          -- Human-readable description
  "panel",                         -- Action type
  "right",                         -- Panel side (right/left)
  7)                               -- Panel index (must exist in groupbar)

```

The panel index parameter must correspond to the position in the `groupbar` table (1-indexed). Incorrect indices will result in non-functional keybindings.

## Reloading Your Configuration

After modifying [`looknfeel.lua`](https://github.com/basecamp/omarchy/blob/main/looknfeel.lua) or widget files, apply changes by reloading the Hyprland configuration:

```bash
omarchy-refresh-config hypr/looknfeel.lua

```

This command triggers the `omarchy-shell` layer-shell client to re-read the `groupbar` definition and reconstruct the panels without requiring a full system restart. Ensure your Lua syntax is valid before reloading, as configuration errors may prevent the bar from rendering correctly.

## Summary

- The Omarchy bar layout is defined in [`default/hypr/looknfeel.lua`](https://github.com/basecamp/omarchy/blob/main/default/hypr/looknfeel.lua) via the `groupbar` Lua table
- Each panel in `groupbar` contains an ordered list of widget modules from `default/hypr/apps/`
- Create custom widgets by implementing `init()` and `render()` functions in new Lua files
- Control panel visibility with `o.bind_toggle()` in [`default/hypr/bindings/utilities.lua`](https://github.com/basecamp/omarchy/blob/main/default/hypr/bindings/utilities.lua)
- Apply changes using `omarchy-refresh-config hypr/looknfeel.lua` without restarting Hyprland
- Panels are indexed 1-9 and can be reordered by rearranging the `groupbar` table entries

## Frequently Asked Questions

### Where is the Omarchy bar layout defined?

The bar layout is defined in [`default/hypr/looknfeel.lua`](https://github.com/basecamp/omarchy/blob/main/default/hypr/looknfeel.lua) within the `groupbar` table, which specifies panel ordering and widget assignments. This file controls how the `omarchy-shell` layer-shell client constructs the visual interface at startup.

### How do I add a custom widget to the Omarchy bar?

Create a new Lua file in `default/hypr/apps/` implementing `widget.init()` and `widget.render()` functions, then reference the filename (without extension) in the `widgets` array of your desired panel within the `groupbar` table in [`looknfeel.lua`](https://github.com/basecamp/omarchy/blob/main/looknfeel.lua).

### What keyboard shortcuts toggle panels in Omarchy?

Default shortcuts include `SUPER+SHIFT+SPACE` for general panel toggling and `SUPER+CTRL+<number>` for specific panels (1-9). Custom shortcuts can be added using `o.bind_toggle()` in [`default/hypr/bindings/utilities.lua`](https://github.com/basecamp/omarchy/blob/main/default/hypr/bindings/utilities.lua) with parameters for the key combination, description, action type, panel side, and panel index.

### Do I need to restart Hyprland to see bar layout changes?

No, run `omarchy-refresh-config hypr/looknfeel.lua` to reload the configuration dynamically. The `omarchy-shell` client will re-parse the `groupbar` table and rebuild the panels without requiring a full session restart, though invalid Lua syntax may require manual correction before the bar renders correctly.