> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rekosk.dev/recircles/llms.txt
> Use this file to discover all available pages before exploring further.

# Menu JSON fields

> Find the accepted fields, types, defaults, and aliases for a custom menu, a named submenu, a clickable item, or an action that asks for input.

A ReCircles menu file describes one root menu. Its `items` array sets the display order. Each item has a label and can define a primary and a secondary action. For complete files you can run, see [Build a Places menu](https://docs.rekosk.dev/recircles/menus/create.md) and [Submenus, lists, and input](https://docs.rekosk.dev/recircles/menus/actions.md).

## Menu and submenu fields

All fields in this table are optional. An input layout or a section with `options` needs at least one of `command`, `submenu`, or `reload: true`.

| Field | Type and default | What it does |
| - | - | - |
| `title` | String, defaults to menu ID or submenu key | Display name. |
| `layout` | String, `ring` | `ring` uses the launcher’s overflow preference. `list` shows vertical text choices. `input` opens a text box. |
| `items` | Array of objects, `[]` | Explicit items in display order. |
| `options` | Array of nonblank strings, `[]` | Append choices after the explicit items. Each uses the shared action. |
| `command` | String, unset | Shell command for submitted input, options, and items with neither click action set. |
| `submenu` | String, unset | Destination key in the root `submenus` map. |
| `reload` | Boolean, `false` | Reload the installed menu in place after the action. A submenu destination takes precedence. |
| `on_open` | String, unset | Run a nonblank shell command and reread the file on entry or refresh. |
| `loading_animation` | Boolean, `false` at root | Show the loading indicator during a refresh. Submenus inherit the root value unless they specify one. |
| `submenus` | Object, `{}`, root only | Map nonblank names to submenu definitions. Submenus can reference other entries in this same map. |
| `prompt` | String, unset | Section prompt or idle message. |
| `placeholder` | String, unset | Accepted input hint. Use `title` for instructions you need visible in the current input box. |
| `default` | String, empty | Initial input text. |
| `password` | Boolean, `false` | Mask input characters on screen. |
| `allow_empty` | Boolean, `false` | Allow an empty submission. |

## Item fields

| Field | Type | What it does |
| - | - | - |
| `label` | Required nonblank string | Text for this choice. Also available as the value when running an ordinary item action. |
| `icon` | Optional string | GTK icon name, absolute image path, or `~/` path. The list layout uses text rows. |
| `left_click` | Optional string or object | Primary action, also available through Activate (default **Enter**). |
| `right_click` | Optional string or object | Secondary action, also available through Secondary Activate (default **Shift+Enter**). |

For a shared command, leave both click fields off the item. If you define only `right_click`, the primary click has no action.

## Action object fields

A command string is shorthand for an object with a single `command` field. Each action object needs a nonblank `command`, a valid `submenu`, or `reload: true`. Add any of the following to control how the action runs.

| Field | Accepted value | What it does |
| - | - | - |
| `command` | String | Launch a shell command with the selected or submitted value. |
| `submenu` | String | Open a named destination after any command finishes. |
| `reload` | Boolean | Keep the current menu open and read its file again. |
| `loading_animation` | Boolean | Override the section’s indicator for this action. |
| `input` | Boolean, prompt string, or input object | Collect text before running the action. `false` disables the prompt. |
| `options` | Array of nonblank strings | Open an inline list and run the action with the chosen label. |
| `title`, `prompt` | Strings | Name the input box or inline list and provide prompt text. |
| `placeholder`, `default` | Strings | Input hint and initial text. |
| `password`, `allow_empty` | Booleans | Mask text or permit an empty submission. |

An `input` object accepts `title`, `prompt`, `placeholder`, `default`, `password`, and `allow_empty`. Text fields inside it take priority over the corresponding action fields. If both `input` and `options` are enabled, the text box opens first and submission runs the action directly.

## Accepted aliases

| Canonical spelling | Also accepted |
| - | - |
| `layout` | `type`, `kind` |
| `ring` layout | `default`, `auto` |
| `list` layout | `dropdown`, `pick`, `pick_and_choose`, `choose`, `select` |
| `input` layout | `string`, `text`, `prompt` |
| `label` | `name` |
| `left_click` / `right_click` | `left` / `right` |
| `options` | `choices` |
| `default` (input text) | `initial` |
| `reload` | `update` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.