# Input Component (Inputs)

`Inputs` Nodes are used to add interactive input components in menus, allowing players to submit numbers, text, or make choices. The input values can be referenced in actions through `$(key_name)` variable references.

***

## Configuration structure

```yaml
Inputs:
  Component key name:
    type: 'component type'
    text: 'component label text'
    # component-specific configuration...
```

* **Component key name**: unique identifier, used in actions to `$(key_name)` reference the value of this component
* **Component order**: arranged from top to bottom in the order written in YAML

***

## Referencing input values

In `Bottom` 's `actions` , you can use `$(key_name)` to reference the current value of the corresponding input field:

```yaml
Inputs:
  player_name:  # The input content corresponds to $(player_name) below
    type: 'input'
    text: 'Please enter player name'
    default: 'Please enter here...'
  volume:  # The input content corresponds to $(volume) below
    type: 'slider'
    text: 'Volume'
    min: 0
    max: 100
    step: 1
    default: 50
    format: 'Volume: %s%s'
  amount:  # The input content corresponds to $(amount) below
    type: 'input'
    text: 'Please enter quantity'
    default: 'Please enter here...'
    
Bottom:
  type: 'notice'
  confirm:
    text: '&aConfirm'
    actions:
      - 'tell: &fThe name you entered is: &e $(player_name)'
      - 'tell: &fThe volume you selected is: &e $(volume)'
      - 'tell: &fThe quantity you entered is: &e $(amount)'
```

***

## Component types

### input - text input field

Allows players to enter any text.

**Configuration items:**

| Field        | Type      | Required | Default value | Description                                         |
| ------------ | --------- | -------- | ------------- | --------------------------------------------------- |
| `type`       | `String`  | ✅        | —             | Fixed value `input`                                 |
| `text`       | `String`  | ✅        | —             | Input box label text, supports conditional judgment |
| `hide_text`  | `Boolean` | ❌        | `false`       | Whether to hide the input box's own label text      |
| `default`    | `String`  | ❌        | `""`          | Default filled text                                 |
| `max_length` | `Int`     | ❌        | `256`         | Maximum number of input characters                  |
| `width`      | `Int`     | ❌        | `250`         | Input box width (pixels)                            |
| `multiline`  | node      | ❌        | —             | Enable multiline input mode                         |

**Multiline input configuration:**

| Field                 | Type  | Default value | Description               |
| --------------------- | ----- | ------------- | ------------------------- |
| `multiline.max_lines` | `Int` | `5`           | Maximum number of lines   |
| `multiline.height`    | `Int` | `100`         | Input box height (pixels) |

**Example:**

```yaml
Inputs:
  player_name:
    type: 'input'
    text: '&aPlease enter player name'
    default: 'Steve'
    max_length: 16

  feedback:
    type: 'input'
    text: '&7Message content'
    hide_text: true
    default: 'Please enter here...'
    multiline:
      max_lines: 5
      height: 80
```

***

### slider - numeric slider

Allows players to select a value within a range by dragging the slider.

**Configuration items:**

| Field     | Type     | Required | Default value  | Description                                                                   |
| --------- | -------- | -------- | -------------- | ----------------------------------------------------------------------------- |
| `type`    | `String` | ✅        | —              | Fixed value `slider`                                                          |
| `text`    | `String` | ✅        | —              | Slider label text, supports conditional judgment                              |
| `min`     | `Double` | ✅        | `0.0`          | Minimum value                                                                 |
| `max`     | `Double` | ✅        | `10.0`         | Maximum value                                                                 |
| `default` | `Double` | ❌        | equal to `min` | Default value                                                                 |
| `step`    | `Double` | ❌        | `1.0`          | Step size for each move                                                       |
| `format`  | `String` | ❌        | `%s: %s`       | Display format (the first `%s` is the label, the second is the current value) |

**Example:**

{% hint style="warning" %}
**Important:** `min` value**must be less than** `max` value. If `min` ≥ `max`, the plugin will:

* Output a warning log in the console
* Automatically use the default value (min=0.0, max=10.0)
  {% endhint %}

```yaml
Inputs:
  volume:
    type: 'slider'
    text: '&eVolume'
    min: 0
    max: 100
    step: 5
    default: 50
    format: '&eVolume: &f%s%%'

  purchase_amount:
    type: 'slider'
    text: '&6Purchase Quantity'
    min: 1
    max: 64
    step: 1
    default: 1
    format: 'Quantity: %s'
```

***

### dropdown - drop-down selection box

Allows players to choose one item from a preset list of options.

**Configuration items:**

| Field        | Type           | Required | Default value | Description                                                                                |
| ------------ | -------------- | -------- | ------------- | ------------------------------------------------------------------------------------------ |
| `type`       | `String`       | ✅        | —             | Fixed value `dropdown`                                                                     |
| `text`       | `String`       | ✅        | —             | Drop-down label text, supports conditional judgment                                        |
| `hide_text`  | `Boolean`      | ❌        | `false`       | Whether to hide the drop-down's own label text                                             |
| `options`    | `List<String>` | ✅        | —             | Option list, supports plain strings,`id => display` format, and conditional judgment lists |
| `default_id` | `String`       | ❌        | —             | ID of the default selected option                                                          |
| `width`      | `Int`          | ❌        | `200`         | Drop-down width (pixels)                                                                   |

**options support formats:**

1. **Legacy format: displayed value and submitted value are the same**

```yaml
options:
  - 'red'
  - 'green'
  - 'blue'
```

2. **New format: use `id => display` to separate submitted value from displayed value**

```yaml
options:
  - 'red => &cRed'
  - 'green => &aGreen'
  - 'blue => &bBlue'
```

3. **Conditional judgment format: compatible `allow` / `deny` returns a string list**

```yaml
options:
  - condition: "%player_is_op% == true"
    allow:
      - 'red => &cOP-Red'
      - 'green => &aOP-Green'
    deny:
      - 'red => &cPlayer-Red'
      - 'green => &aPlayer-Green'
```

> When using `id => display` :
>
> * the left side `id` will be used as the actual value of `$(variable_name)` in actions
> * the right side `display` is the text players see in the interface

**Example:**

```yaml
Inputs:
  color_select:
    type: 'dropdown'
    text: '&bSelect Color'
    hide_text: true
    options:
      - 'red => &cRed'
      - 'green => &aGreen'
      - 'blue => &bBlue'
      - 'yellow => &eYellow'
    default_id: 'green'

  server_select:
    type: 'dropdown'
    text: '&7Select Server'
    options:
      - 'lobby'
      - 'survival'
      - 'creative'
    default_id: 'lobby'
    width: 150
```

***

### checkbox - checkbox

Allows players to toggle an on/off state.

**Configuration items:**

| Field      | Type      | Required | Default value | Description                                        |
| ---------- | --------- | -------- | ------------- | -------------------------------------------------- |
| `type`     | `String`  | ✅        | —             | Fixed value `checkbox`                             |
| `text`     | `String`  | ✅        | —             | Checkbox label text, supports conditional judgment |
| `default`  | `Boolean` | ❌        | `false`       | Whether it is checked by default                   |
| `on_true`  | `String`  | ❌        | `true`        | Value passed to actions when checked               |
| `on_false` | `String`  | ❌        | `false`       | Value passed to actions when unchecked             |

**Example:**

```yaml
Inputs:
  enable_notify:
    type: 'checkbox'
    text: '&aEnable announcement notifications'
    default: true

  pvp_mode:
    type: 'checkbox'
    text: '&cEnable PvP mode'
    default: false
    on_true: 'enabled'    # When checked $(pvp_mode) = "enabled"
    on_false: 'disabled'  # When unchecked $(pvp_mode) = "disabled"
```

**Use in actions:**

```yaml
Bottom:
  confirm:
    actions:
      - 'console: pvp set %player_name% $(pvp_mode)'
      # Executed when checked: pvp set Steve enabled
      # Executed when unchecked: pvp set Steve disabled
```

***

## Complete example

```yaml
Title: '&6Player Settings'

Inputs:
  nickname:
    type: 'input'
    text: '&eNickname'
    default: '%player_name%'
    max_length: 16

  chat_volume:
    type: 'slider'
    text: '&bChat Volume'
    min: 0
    max: 10
    default: 5
    format: '%s%s'

  language:
    type: 'dropdown'
    text: '&aLanguage'
    options:
      - 'zh_cn => Simplified Chinese'
      - 'en_us => English'
    default_id: 'zh_cn'

  color_select:
    type: 'dropdown'
    text: '&bSelect Color'
    hide_text: true
    options:
      - condition: "%player_is_op% == true"
        allow:
          - 'red => &cOP-Red'
          - 'green => &aOP-Green'
          - 'blue => &bOP-Blue'
        deny:
          - 'red => &cPlayer-Red'
          - 'green => &aPlayer-Green'
          - 'blue => &bPlayer-Blue'
    default_id: 'red'

  join_notify:
    type: 'checkbox'
    text: '&7Receive player online alerts'
    default: true

Bottom:
  type: 'confirmation'
  confirm:
    text: '&a[ Save Settings ]'
    actions:
      - 'set-data: nickname $(nickname)'
      - 'set-data: chat_volume $(chat_volume)'
      - 'set-data: language $(language)'
      - 'set-data: join_notify $(join_notify)'
      - 'tell: &aSettings saved!'
      - 'sound: entity.experience_orb.pickup'
  deny:
    text: '&c[ Cancel ]'
    actions:
      - 'tell: &7Operation canceled.'
```


---

# Agent Instructions: 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://katacr.gitbook.io/plugins/kamenu-en/menu/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.