> For the complete documentation index, see [llms.txt](https://yowsef-development.gitbook.io/yowsef-development-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yowsef-development.gitbook.io/yowsef-development-docs/menus/inputs.md).

# inputs

Inputs let players fill in values directly inside a dialog, replacing chat prompts or sign interactions. They are only available on `confirmation` type menus.

## 1. Defining Input Fields

Input fields are defined under the `inputs:` key in a menu file. There are four supported types.

{% tabs %}
{% tab title="Text Input (`text`)" %}
A free-text field for names, reasons, or any string value.

```yaml
inputs:
  - type: text
    key: "home_name"         # Used as $(home_name) in commands
    label: "<white>Home Name"
    initial: "home"          # Pre-filled value (optional)
    max-length: 24           # Max character limit
    width: 250               # Width in pixels
    multiline: false         # true = multi-line text area
```

For multi-line text areas:

```yaml
  - type: text
    key: "reason"
    label: "<white>Reason"
    max-length: 256
    width: 300
    multiline: true
    multiline-lines: 5       # Number of visible lines
```

{% endtab %}

{% tab title="Number Range Slider (`number-range`)" %}
A numeric slider between a min and max value.

```yaml
  - type: number-range
    key: "pay_amount"
    label: "<white>Amount"
    min: 1.0
    max: 1000000.0
    step: 1.0                # Snap increment
    initial: 100.0
    label-format: "Amount: $%s"  # %s is replaced with the current value
    width: 300
```

{% endtab %}

{% tab title="Boolean Toggle (`bool`)" %}
A native client toggle switch (on/off).

```yaml
  - type: bool
    key: "pvp"
    label: "<red>PvP Enabled"
    initial: true
```

{% endtab %}

{% tab title="Single Option Dropdown (`single-option`)" %}
A dropdown where the player picks one value from a list.

```yaml
  - type: single-option
    key: "language"
    label: "<yellow>Language"
    options:
      - value: "en"
        label: "English"
      - value: "ar"
        label: "العربية"
      - value: "es"
        label: "Español"
    initial: "en"            # Must match one of the option values
```

{% endtab %}
{% endtabs %}

## 2. Using Input Values in Commands

When the player clicks the confirm button, input values are substituted into commands using the `$(key)` syntax:

```yaml
confirm-button:
  label: "<green>Set Home"
  action: command-template
  command-template: "/sethome $(home_name)"
  action-key: "dm:sethome"
```

If the player typed `farm`, the command `/sethome farm` is executed.

Use `command-template` (not `static-run-command`) whenever you need `$(key)` substitution.

## 3. Chaining Multiple Commands

Separate commands with `;` to run multiple in sequence from one confirm button:

```yaml
confirm-button:
  label: "<green>Save"
  action: "run-commands"
  action-key: "dm:settings_save"
  command: "/pvp $(pvp); /scoreboard $(scoreboard); /lang $(language)"
```

Each command runs one-by-one as the player.

## 4. Full Example — Settings Menu

```yaml
settings-menu:
  title: "<gray><bold>⚙ Settings"
  type: confirmation
  body:
    - type: plain-message
      content: "<gray>Adjust your preferences. Confirm to save."
  inputs:
    - type: bool
      key: "pvp"
      label: "<red>PvP Enabled"
      initial: true
    - type: single-option
      key: "particles"
      label: "<light_purple>Particle Level"
      options:
        - value: "OFF"
          label: "<gray>Off"
        - value: "LOW"
          label: "<green>Low"
        - value: "HIGH"
          label: "<aqua>High"
      initial: "HIGH"
    - type: number-range
      key: "chat_range"
      label: "<white>Local Chat Range (blocks)"
      min: 10.0
      max: 500.0
      step: 10.0
      initial: 200.0
      label-format: "Range: %s blocks"
      width: 300
  confirm-button:
    label: "<green>Save"
    width: 140
    action: "run-commands"
    action-key: "dm:settings_save"
    command: "/pvp $(pvp); /particles $(particles); /localchatrange $(chat_range)"
  deny-button:
    label: "<gray>Cancel"
    width: 100
    action: close
    action-key: "dm:cancel"
```


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://yowsef-development.gitbook.io/yowsef-development-docs/menus/inputs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.