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

# Submenus, lists, and input

> Give an item a second action, open a submenu of preset choices, or ask for text. Pass the selected value to a shell command and refresh a menu in place.

A ReCircles item can open another set of choices or collect a value before it runs a command. This Messages menu offers two ways to send a desktop notification. It uses `notify-send` from libnotify and a running desktop notification service.

## Try both actions

Save this as `messages.json`. The item’s primary action opens the `presets` submenu. Its secondary action opens a text box titled **Write a message**.

```json messages.json theme={null}
{
  "title": "Messages",
  "items": [
    {
      "label": "Send a message",
      "icon": "mail-message-new",
      "left_click": { "submenu": "presets" },
      "right_click": {
        "input": { "title": "Write a message", "default": "Taking a break" },
        "command": "notify-send ReCircles \"$RECIRCLES_INPUT\""
      }
    }
  ],
  "submenus": {
    "presets": {
      "title": "Choose a message",
      "layout": "list",
      "options": ["Back in five", "Ready for review"],
      "command": "notify-send ReCircles {input}"
    }
  }
}
```

```sh theme={null}
recircles add messages ./messages.json
recircles --run messages
```

* **Left-click** the item, then select **Ready for review**. ReCircles supplies that label to the shared command and your desktop displays the notification.
* **Reopen the menu and right-click** the item (or select it and press **Shift+Enter**). Edit the text and choose **Done**. **Cancel** discards it.

Define all named submenus in the root `submenus` object. From any level, use the exact key, such as `presets`, to enter it. For a short one-off list, you can put `options` and `command` together inside a click action.

## Pass the selected value

ReCircles runs commands through `sh -c`. The value is the submitted text in an input box, the chosen option in a list, or the clicked item’s label for an ordinary item action. These two forms both pass one value to `notify-send`.

| Command in the shell | How the value is passed |
| - | - |
| `notify-send ReCircles {input}` | ReCircles substitutes a shell-quoted argument. Write the placeholder unquoted. `{}` is an alias. |
| `notify-send ReCircles "$RECIRCLES_INPUT"` | The shell expands the environment variable. Double quotes keep spaces and punctuation together. Escape the quotes when writing this form in JSON. |

For a menu that always starts with text entry, save this as `quick-note.json` and register it with `recircles add quick-note ./quick-note.json`. Running `recircles --run quick-note` opens the input box directly.

```json quick-note.json theme={null}
{
  "title": "Write a message",
  "layout": "input",
  "command": "notify-send ReCircles \"$RECIRCLES_INPUT\""
}
```

## Refresh the menu after a command

A plain command launches and closes ReCircles. Set `reload` to `true` when you want to stay in the current menu. A reload action can also stand alone. This complete menu lets you edit the installed JSON while the menu is open, then select **Reload menu** to see the changes.

```json refreshable.json theme={null}
{
  "title": "Shortcuts",
  "items": [
    { "label": "Home folder", "left_click": "xdg-open \"$HOME\"" },
    { "label": "Reload menu", "left_click": { "reload": true } }
  ]
}
```

Set `on_open` on a menu or named submenu to run a command when you enter it. A refresh reads the installed JSON file from disk after the command succeeds. If a script generates menu entries, have it update that file. Printing JSON to standard output does not update the menu.

When an action has both `command` and `submenu`, ReCircles runs the action command, runs the destination’s `on_open` if present, then reads the menu file and displays the destination. A reload follows the same sequence using the current section’s `on_open`. Enable `loading_animation` to show a loading indicator while waiting.


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