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

Customize the Omarchy bar layout by editing the groupbar table in 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 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, the entire layout is governed by a Lua table named groupbar (defined at 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 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 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:

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

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

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

-- 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) 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. 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:

-- 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 or widget files, apply changes by reloading the Hyprland configuration:

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

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

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