# How to Customize the Actions Ring Layout in OpenLogi: A Complete Guide

> Learn how to customize the Actions Ring layout in OpenLogi. Edit your TOML file or use the GUI editor for custom actions and labels.

- Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi)
- Tags: how-to-guide
- Published: 2026-09-09

---

**Yes, you can customize the Actions Ring layout in OpenLogi by editing the `action_ring` section in your device's TOML configuration file or using the built-in GUI editor, which persists changes to eight fixed directional slots that support custom actions, labels, and per-application overrides.**

The OpenLogi input automation platform provides a customizable **Actions Ring** interface that allows users to trigger shortcuts and macros through an eight-position radial menu. You can fully customize the Actions Ring layout in OpenLogi by modifying the `ActionRingConfig` structure, which supports both global defaults and per-application configurations.

## Understanding the Actions Ring Data Model

In [`openlogi-core/src/binding/action_ring.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi-core/src/binding/action_ring.rs), OpenLogi defines the core data structures that govern the Actions Ring behavior. The `ActionRingConfig` struct serves as the root configuration container, holding the enable flag, haptics settings, default layout, and optional per-application overrides.

The default layout is generated in the `Default` implementation of `ActionRingLayout` located in the same file. This implementation pre-populates the eight slots with standard clipboard operations: Cut, Copy, Paste, Undo, Redo, PlayPause, BrowserBack, and BrowserForward.

### The Eight-Slot Layout System

Each `ActionRingLayout` maps eight fixed directional slots—`Top`, `TopRight`, `Right`, `BottomRight`, `Bottom`, `BottomLeft`, `Left`, and `TopLeft`—to `ActionRingEntry` instances. Every entry can contain a custom action, an optional display label, and an optional icon identifier, allowing granular control over the radial menu's appearance and functionality.

## Methods to Customize the Actions Ring Layout

OpenLogi provides two primary interfaces for modifying the Actions Ring: the graphical editor in `openlogi-desktop` and direct configuration file editing.

### Using the GUI Editor

The OpenLogi desktop application (`openlogi-desktop`) provides a dedicated editor implemented in [`openlogi-desktop/src/features/action_ring.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi-desktop/src/features/action_ring.rs). This interface allows you to drag-and-drop actions into the eight available slots, set custom labels, assign icons, and toggle haptic feedback. Changes made through this editor are automatically persisted to the device's [`config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/config.toml) via the runtime state management in [`openlogi-desktop/src/state/action_ring.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi-desktop/src/state/action_ring.rs).

### Editing the TOML Configuration Directly

For advanced customization, you can manually edit the `action_ring` table in your device's configuration file. Because `ActionRingConfig` derives both `Deserialize` and `Serialize`, any valid TOML matching the schema will be loaded on startup. The configuration is embedded within `DeviceConfig` as defined in [`openlogi-core/src/config/device.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi-core/src/config/device.rs), ensuring the layout persists across application restarts.

## Configuration Schema and Examples

Below is a complete TOML example demonstrating how to customize the Actions Ring layout with custom labels, icons, and action mappings:

```toml
[action_ring]
enabled = true
haptics = true

# Override the default layout for all apps

default = { slots = {
    Top = { action = "Copy", label = "Copy Invoice", icon = "Keyboard" },
    TopRight = { action = "Paste" },
    Right = { action = "Undo" },
    BottomRight = { action = "Redo" },
    Bottom = { action = "PlayPause" },
    BottomLeft = { action = "BrowserBack" },
    Left = { action = "BrowserForward" },
    TopLeft = { action = "Cut" }
} }

# Optional per-application overrides (keyed by bundle identifier on macOS)

# per_app = { "com.microsoft.VSCode" = { slots = { ... } } }

```

The `action` field accepts any builtin `Action` variant (such as `Copy`, `Paste`, or `Undo`) or a `CustomShortcut` inline table for user-defined keystrokes. The `label` and `icon` fields are optional and persist independently of the assigned action, as verified by the `custom_label` test cases in the source code.

## How Configuration Flows to the Overlay

When you invoke the "Show Actions Ring" command, the overlay system in [`openlogi-overlay/src/ring.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi-overlay/src/ring.rs) resolves the effective layout by querying the device's `ActionRingConfig`. The system first checks for a matching per-application override based on the current foreground application's bundle identifier. If no override exists, it falls back to the `default` layout. This resolution happens at invocation time, meaning changes to the configuration file take effect immediately without requiring an application restart.

## Summary

- The **Actions Ring layout** is controlled by `ActionRingConfig` in [`openlogi-core/src/binding/action_ring.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi-core/src/binding/action_ring.rs), which supports eight fixed directional slots.
- You can customize the layout either through the **GUI editor** in `openlogi-desktop` or by **editing the TOML directly** in the device's config file.
- Each slot supports **custom actions**, **display labels**, and **icon identifiers**, with values persisting across sessions via `DeviceConfig`.
- **Per-application overrides** allow different layouts for specific apps using bundle identifiers.
- The overlay renders the final layout in real-time by reading the resolved configuration from [`openlogi-overlay/src/ring.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi-overlay/src/ring.rs).

## Frequently Asked Questions

### Can I set different Actions Ring layouts for different applications?

Yes. The `ActionRingConfig` struct includes a `per_app` field that accepts a map of bundle identifiers to `ActionRingLayout` configurations. On macOS, you would use the application's bundle identifier (such as `com.microsoft.VSCode`) as the key. When the Actions Ring is triggered, OpenLogi automatically detects the foreground application and loads the corresponding override if one exists, otherwise falling back to the default layout.

### What actions can be assigned to the Actions Ring slots?

Slots can be assigned any builtin `Action` variant defined in the codebase—including clipboard operations like `Cut`, `Copy`, and `Paste`, navigation commands like `BrowserBack` and `BrowserForward`, or media controls like `PlayPause`. Additionally, you can assign custom shortcuts using the `CustomShortcut` inline table format, which allows you to define arbitrary keyboard combinations for specialized workflows.

### Where is the Actions Ring configuration stored?

The configuration resides in each device's individual TOML config file under the `[action_ring]` table. Because `ActionRingConfig` is embedded within the `DeviceConfig` struct in [`openlogi-core/src/config/device.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi-core/src/config/device.rs), the settings are persisted alongside other device-specific preferences and automatically reloaded when the OpenLogi application starts.

### Do custom labels and icons persist when changing actions?

Yes. According to the implementation in [`openlogi-core/src/binding/action_ring.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi-core/src/binding/action_ring.rs), the `ActionRingEntry` struct stores `label` and `icon` as optional fields separate from the `action` field. When you update an entry's action through either the GUI or direct TOML editing, any existing custom labels or icons remain associated with that slot unless explicitly cleared, as confirmed by the `custom_label` unit tests in the source code.