Modal

Modals let you collect structured input from the user.

ItsMyBot modals support placeholders across titles, labels, descriptions, and input values, so the modal can adapt to the current context before it is shown.

If you want a faster starting point, open the Modal Builder. It generates the same YAML structure documented here.

At the top level, a modal contains:

a title
a custom-id
a components array

Top-level modal components are limited to:

text-display
label

Prop

Type

Example

title: "Feedback"
custom-id: "script_feedback_modal"
components:
  - type: text-display
    content: "Tell us what happened and attach files if needed."

  - type: label
    label: "Message"
    description: "Explain the issue clearly."
    component:
      type: text-input
      style: "paragraph"
      custom-id: "message"
      required: true
      min-length: 10

  - type: label
    label: "Category"
    description: "Choose one category."
    component:
      type: radio-group
      custom-id: "category"
      required: true
      options:
        - label: "Bug"
          value: "bug"
        - label: "Suggestion"
          value: "suggestion"

  - type: label
    label: "Attachments"
    description: "Upload screenshots or files."
    component:
      type: file-upload
      custom-id: "files"
      max-values: 3

Component Conditions

Modal components support the same condition system used elsewhere in ItsMyBot. This lets you show or hide parts of the modal depending on context.

You can find the available condition list in Scripting Conditions.

Prop

Type

Top-Level Components

`text-display`

Use text-display when you want to explain the modal before the user starts filling fields.

Prop

Type

Example

components:
  - type: text-display
    content: "Please complete every required field."

`label`

label is the field wrapper used inside modals.

It renders:

a visible label
an optional description
exactly one modal input component

Supported input components inside label.component:

text-input
select-menu
file-upload
checkbox
checkbox-group
radio-group

Prop

Type

Example

components:
  - type: label
    label: "Username"
    description: "Enter the account name you want to use."
    component:
      type: text-input
      custom-id: "username"
      style: "short"
      required: true

Input Components

`text-input`

Use text-input for free-form user text.

Prop

Type

Example

component:
  type: text-input
  style: "paragraph"
  custom-id: "details"
  placeholder: "Explain the issue"
  min-length: 10
  max-length: 1000
  required: true

Use select-menu when the user should choose from a predefined list.

Prop

Type

Prop

Type

Example

component:
  type: select-menu
  custom-id: "fruits"
  placeholder: "Select your favorite fruits"
  min-values: 1
  max-values: 2
  options:
    - label: "Apple"
      value: "apple"
    - label: "Orange"
      value: "orange"

`file-upload`

Use file-upload when the user should attach screenshots, logs, or other files.

Prop

Type

Example

component:
  type: file-upload
  custom-id: "attachments"
  required: false
  max-values: 3

`checkbox`

Use checkbox for a single boolean choice.

Prop

Type

Example

component:
  type: checkbox
  custom-id: "agree_rules"
  default: true

`checkbox-group`

Use checkbox-group when the user can select multiple options from one field.

Prop

Type

`checkbox-group` options

Prop

Type

Example

component:
  type: checkbox-group
  custom-id: "platforms"
  required: true
  min-values: 1
  max-values: 2
  options:
    - label: "Java"
      value: "java"
      description: "Java Edition players"
    - label: "Bedrock"
      value: "bedrock"
      description: "Bedrock Edition players"
      default: true

`radio-group`

Use radio-group when the user must choose one option from a list.

Prop

Type

`radio-group` options

Prop

Type

Example

component:
  type: radio-group
  custom-id: "priority"
  required: true
  options:
    - label: "Low"
      value: "low"
      description: "General issue with no immediate urgency"
    - label: "High"
      value: "high"
      description: "Needs quick attention"
      default: true

Script Interactions

To detect a modal submission with a script, the modal custom-id must start with script_.

See Script interaction custom-id format for argument parsing, and modalSubmit for the submitted variables.

Modal

Component Conditions

Top-Level Components

`text-display`

`label`

Input Components

`text-input`

`select-menu`

`select-menu` options

`file-upload`

`checkbox`

`checkbox-group`

`checkbox-group` options

`radio-group`

`radio-group` options

Script Interactions

On this page