> For the complete documentation index, see [llms.txt](https://docs.myarc.icu/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.myarc.icu/en/feature-configuration/arcitx.md).

# Arcitx text input

Arcitx is ArcMenu's built-in text input component for collecting player text right inside a menu—such as search keywords, transfer amounts, redemption codes, or custom nicknames.

Structurally, a complete Arcitx input box is made up of three cooperating parts:

1. **Frontend text node (`type: text`)**: Renders the prompt, live typing buffer, blinking caret, and final draft or submitted text on the menu canvas.
2. **Backend editing region (`type: Arcitx`)**: Starts text input when the player clicks it.
3. **Backend submit region (normal click region)**: A separate button the player clicks after finishing their edits to formally submit the text and run follow-up actions.

Keeping editing and submission as two distinct steps lets players review what they typed on the menu before running commands or spending currency, and click the input box again to make changes if they spot a mistake.

## Player workflow

1. **Click the editing region**: Enters text input mode.
2. **Type text**: Supports input method editors (IME) for CJK languages, English letters, numbers, symbols, spaces, and emoji. Pressing Space while editing inserts a space character without closing the menu or submitting early.
3. **Finish editing (save draft)**: Exit editing mode when done typing. Your text now appears on the menu as a draft without triggering submission actions yet, and you can click the editing region again at any time to revise it.
4. **Click the submit region**: Click the dedicated submit button on the menu. ArcMenu saves the draft as the committed value and executes the actions configured on that submit button.

Each input mode handles editing in its own way:

| Input mode      | Editing interface                                                                                                                             | How to finish editing and return to the menu                               |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| Touch `touch`   | Opens the vanilla anvil screen to type in the rename field.                                                                                   | Press `Esc` or click the result slot on the right side of the anvil.       |
| Mouse `mouse`   | Opens a vanilla anvil control whose visuals are hidden by the companion resource pack, so players watch the text update directly on the menu. | Press `Esc` (or click the result slot position).                           |
| Vision `vision` | Uses native local client text input and system IME directly inside the menu view without opening an anvil screen.                             | Press `Esc`, press `Enter`, or click anywhere on the menu with the cursor. |

In Vision mode, if a player clicks a button on the menu while typing, the client first finishes the active text edit and then immediately processes the click on that button. For more on switching and configuring input modes, see [Touch, Mouse and Vision input](/en/feature-configuration/input-modes.md).

## Quick-start example

Save the following configuration as `plugins/ArcMenu/menus/arcitx-demo.yml`, run `/arcmenu reload`, and open it with `/arcmenu open arcitx-demo`:

```yaml
schema-version: 1
id: arcitx-demo
canvas:
  width: 320
  height: 180
  pixels-per-block: 42.7

frontend:
  input-border:
    type: frame
    width: 260
    height: 30
    thickness: 1
    color: '#7494B8'
    offset: {y: 12, z: 1}

  input-buffer:
    type: text
    content: ''
    size: 8
    offset: {y: 9, z: 2}

  submit-background:
    type: rectangle
    width: 100
    height: 24
    color: '#3366AA'
    offset: {y: -34, z: 1}

  submit-label:
    type: text
    content: '&fSubmit'
    size: 8
    offset: {y: -37, z: 2}

backend:
  edit-input:
    type: Arcitx
    x: 0
    y: 12
    width: 260
    height: 30
    text: input-buffer
    submit: submit-input
    title: 'Enter text'
    initial: ''
    max-length: 50
    mask: ''
    display:
      before: '&7Click to enter text'
      editing: '&f{input}{caret}'
      draft: '&f{input}'
      complete: '&a{input}'
    caret:
      content: '_'
      interval: 10

  submit-input:
    x: 0
    y: -34
    width: 100
    height: 24
    actions:
      left: 'tell: &aSubmitted: {meta:input-edit-input}'
```

How the pieces fit together in this example:

* The frontend `input-buffer` node defines the font size, font family, alignment, and position on the canvas. While the menu is open, the `display` settings on `edit-input` dynamically control what text `input-buffer` shows; you can still attach position, scale, or opacity animations to `input-buffer`.
* The backend `edit-input` region sets `type: Arcitx`, binds the display node with `text: input-buffer`, and links the submit button with `submit: submit-input`.
* The backend `submit-input` region is a standard click region. Clicking it commits the input and sends the confirmation message. For more on configuring click regions and actions, see [Backend regions and click events](/en/menu-configuration/menus/backend.md) and [Actions and navigation](/en/menu-configuration/menus/actions.md).

## Configuration fields

Setting `type: Arcitx` (case-insensitive) on a `backend` region turns it into a text input box. Alongside standard backend region fields such as `x`, `y`, `width`, `height`, `priority`, `tooltip`, `condition`, and `actions`, an Arcitx region supports the following dedicated fields:

| Field              | Valid values and requirements                                   | Default                 | Description                                                                                                                                |
| ------------------ | --------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `type`             | `Arcitx`                                                        | Required                | Declares this backend region as an Arcitx text input region.                                                                               |
| `text`             | ID string of a frontend `text` node                             | Required                | The frontend text node that displays the input buffer (including text nodes inside a `group`).                                             |
| `submit`           | ID string of a normal backend region                            | Required                | The separate backend click region used to confirm and submit the input.                                                                    |
| `title`            | Any string                                                      | `Enter text`            | Title text shown at the top of the vanilla anvil screen in Touch mode.                                                                     |
| `initial`          | String no longer than `max-length`                              | `''`                    | Initial draft text when the menu first opens. Supports menu placeholders.                                                                  |
| `max-length`       | Integer from `1` to `50`                                        | `50`                    | Maximum allowed input length, measured in UTF-16 code units.                                                                               |
| `mask`             | Empty string `''` or a single Unicode character (such as `'*'`) | `''`                    | Password mask character. Leave empty to show plain text, or set a single character to replace every character of `{input}` when displayed. |
| `display.before`   | String                                                          | `&7Click to enter text` | Prompt text shown before the player has edited or submitted the field.                                                                     |
| `display.editing`  | String                                                          | `{input}{caret}`        | Text template shown while the player is actively typing.                                                                                   |
| `display.draft`    | String                                                          | `{input}`               | Text template shown after the player finishes editing, before clicking the submit button.                                                  |
| `display.complete` | String                                                          | `{input}`               | Text template shown after the player clicks the submit button.                                                                             |
| `caret.content`    | String                                                          | `_`                     | Blinking caret symbol shown during editing. Supports `&` color codes.                                                                      |
| `caret.interval`   | Positive integer `1` or greater                                 | `10`                    | Blink interval between showing and hiding the caret, in game ticks (20 ticks = 1 second).                                                  |

### Character length (`max-length`)

Standard ASCII letters, digits, and common CJK characters each take 1 UTF-16 code unit, while many emoji take 2 code units. When a player's input reaches `max-length`, ArcMenu truncates it cleanly at the limit without splitting surrogate pairs, so an emoji is never cut in half.

## Display states and template markers

The four fields under `display` correspond to the four stages of the input lifecycle:

1. **Before input (`before`)**: Shown when the menu opens and the player has not modified the input box yet. If the player opens the input box and exits without changing any characters, it returns to this state.
2. **Editing (`editing`)**: Shown while the player is actively typing, rendering `{input}` and the blinking `{caret}` in real time.
3. **Draft (`draft`)**: Shown after the player modifies the text and exits editing mode, while waiting for a click on the submit button. The player can still click the input box to edit the draft again.
4. **Submitted (`complete`)**: Shown after the player clicks the bound `submit` region. If the menu stays open, the player can click the editing region again to enter new text and click the submit button to update the submitted value.

Inside any of the four `display` strings, you can use:

* `{input}`: The current text in the player's input buffer (replaced with an equal number of mask characters if `mask` is configured).
* `{caret}`: The blinking caret symbol (blinks during `editing` and automatically resolves to empty in the other three states).
* Color codes (such as `&a` or `&#FFAA00`) and standard menu placeholders.

Text typed by the player is rendered literally. Even if a player types `&c`, `{caret}`, or `%player_name%` into the input box, it is displayed as plain text and will not alter your formatting or evaluate arbitrary placeholders.

## Reading submitted text

When a player clicks the region bound via `submit`, ArcMenu saves the current draft as the committed submission and then runs the `actions` on the submit region in order. You can read the unmasked text the player submitted using these `meta` placeholders:

| Placeholder                        | Description                                                                                                                    |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `{meta:input}`                     | The most recent text submitted by the player (across both Arcitx submissions and chat input catchers, persisted across menus). |
| `{meta:input-<editing-region-id>}` | The most recent text submitted for that specific Arcitx editing region.                                                        |

For example, if your editing region is named `search-box`, use `{meta:input-search-box}` in your submit button's actions. When a single menu contains multiple input fields—such as a username and password, or a recipient and transfer amount—the ID-specific placeholder lets you read each field independently:

```yaml
actions:
  left:
    - 'tell: &aTransferring {meta:input-amount} coins to {meta:input-target-player}'
```

### Drafts, submitted values, and validation

* **When submitted values update**: `{meta:input-...}` updates only when the player clicks the separate `submit` region. Typing, pressing `Esc` to exit editing, or clicking the anvil result slot only updates the draft.
* **Empty text and conditional validation**: Arcitx allows submitting an empty string. To require non-empty input or validate the format, combine the submit region's actions with [Conditions](/en/menu-configuration/menus/conditions.md) (for instance, checking `'{meta:input-edit-input}' != ''`).
* **Value lifecycle**: The draft buffer and the session submission value read via API belong to the currently open menu session; closing and reopening the menu resets the input box to `initial`. By contrast, `{meta:input}` and `{meta:input-<editing-region-id>}` are stored in player-level temporary data (`META`). Opening or closing a menu does not clear them; submitting again overwrites the value, while starting a chat catcher or running `remove-meta` clears them. Clicking the submit button does not automatically close the menu—add `close` or `open: <menu-id>` to the submit region's `actions` whenever you want submission to close the menu or navigate elsewhere.

## Password masking and custom completion text

### Password fields

Setting `mask: '*'` replaces `{input}` on the menu with one asterisk for each Unicode code point the player typed, while `{meta:input-...}` still provides the actual password to your actions:

```yaml
mask: '*'
display:
  before: '&7Enter password'
  editing: '&f{input}{caret}'
  draft: '&f{input}'
  complete: '&f{input}'
```

Note that `mask` applies to the bound frontend text node on the menu canvas. In Touch mode, the vanilla anvil's own rename box still shows the characters being typed, whereas Mouse mode (with the anvil-hiding companion resource pack) and Vision mode display only the masked asterisks on the menu canvas from start to finish.

### Fixed completion message

If you want players to see their plain text while typing and reviewing their draft, but hide the text or show a confirmation prompt after submission, leave `mask` empty and customize `display.complete`:

```yaml
mask: ''
display:
  before: '&7Click to enter redemption code'
  editing: '&f{input}{caret}'
  draft: '&f{input}'
  complete: '&aConfirmed — click to edit again'
```

## Structure and binding rules

When loading menus, ArcMenu validates the following binding rules so you can catch configuration mistakes right away:

1. **Target nodes must exist and match types**: `text` must point to an existing `type: text` node in the menu's `frontend`, and `submit` must point to an existing normal click region in `backend` (never to itself or to another `Arcitx` region).
2. **Exclusive one-to-one bindings**: When a menu has multiple `Arcitx` regions, each input box must bind its own dedicated `text` node and its own dedicated `submit` region; they cannot be shared.
3. **Strict geometric separation**: The editing region and its bound submit region must not overlap or share touching edges on the canvas. Leave a clear gap between their rectangles (for example, at least 1 canvas unit apart).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.myarc.icu/en/feature-configuration/arcitx.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.