Script API - v26.60
    Preparing search index...

    Class ModalFormData

    Used to create a fully customizable pop-up form for a player.

    import { world, DimensionLocation } from '@minecraft/server';
    import { ModalFormData } from '@minecraft/server-ui';

    function showBasicModalForm(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
    const players = world.getPlayers();

    const modalForm = new ModalFormData().title('Example Modal Controls for §o§7ModalFormData§r');

    modalForm.toggle('Toggle w/o default');
    modalForm.toggle('Toggle w/ default', true);

    modalForm.slider('Slider w/o default', 0, 50, 5);
    modalForm.slider('Slider w/ default', 0, 50, 5, 30);

    modalForm.dropdown('Dropdown w/o default', ['option 1', 'option 2', 'option 3']);
    modalForm.dropdown('Dropdown w/ default', ['option 1', 'option 2', 'option 3'], 2);

    modalForm.textField('Input w/o default', 'type text here');
    modalForm.textField('Input w/ default', 'type text here', 'this is default');

    modalForm
    .show(players[0])
    .then(formData => {
    players[0].sendMessage(`Modal form results: ${JSON.stringify(formData.formValues, undefined, 2)}`);
    })
    .catch((error: Error) => {
    log('Failed to show form: ' + error);
    return -1;
    });
    }

    image

    import { Player, world } from "@minecraft/server";
    import { ModalFormData } from "@minecraft/server-ui";
    let form = new ModalFormData();
    let effectList = [
    { name: "Regeneration", id: "minecraft:regeneration" },
    { name: "Resistance", id: "minecraft:resistance" },
    { name: "Fire Resistance", id: "minecraft:fire_resistance" },
    { name: "Poison", id: "minecraft:poison" },
    ];
    form.title("Effect Generator");
    form.textField("Target", "Target of Effect");
    form.dropdown(
    "Effect Type",
    effectList.map((effect) => effect.name)
    );
    form.slider("Effect Level", 0, 255, {
    defaultValue: 1,
    tooltip: "Level of the effect",
    valueStep: 1,
    });
    form.toggle("Hide Effect Particle", {
    defaultValue: true,
    tooltip: "Toggle to hide/show effect particles",
    });
    for (const player of world.getAllPlayers()) {
    form.show(player).then((response) => {
    if (response.canceled) {
    player.sendMessage("Canceled due to " + response.cancelationReason);
    } else {
    const [targetName, dropdownValue, effectLevel, hideParticles] =
    response.formValues;
    if (
    typeof dropdownValue !== "string" ||
    typeof dropdownValue !== "number" ||
    typeof effectLevel !== "number" ||
    typeof hideParticles !== "boolean"
    )
    return player.sendMessage("Cannot process form result.");
    const target = world
    .getAllPlayers()
    .find((player) => player.name === targetName);
    if (!(target instanceof Player))
    return player.sendMessage("Target does not exist.");
    target.addEffect(effectList[dropdownValue].id, 50, {
    amplifier: effectLevel,
    showParticles: !hideParticles,
    });
    }
    });
    }
    import { Player, world } from "@minecraft/server";
    import { ModalFormData } from "@minecraft/server-ui";
    let form = new ModalFormData();
    let effectList = [
    { name: "Regeneration", id: "minecraft:regeneration" },
    { name: "Resistance", id: "minecraft:resistance" },
    { name: "Fire Resistance", id: "minecraft:fire_resistance" },
    { name: "Poison", id: "minecraft:poison" },
    ];
    form.title("Effect Generator");
    form.textField("Target", "Target of Effect");
    form.dropdown(
    "Effect Type",
    effectList.map((effect) => effect.name)
    );
    form.slider("Effect Level", 0, 255, 1);
    form.toggle("Hide Effect Particle", true);
    for (const player of world.getAllPlayers()) {
    form.show(player).then((response) => {
    if (response.canceled) {
    player.sendMessage("Canceled due to " + response.cancelationReason);
    } else {
    const [targetName, dropdownValue, effectLevel, hideParticles] =
    response.formValues;
    if (
    typeof dropdownValue !== "string" ||
    typeof dropdownValue !== "number" ||
    typeof effectLevel !== "number" ||
    typeof hideParticles !== "boolean"
    )
    return player.sendMessage("Cannot process form result.");
    const target = world
    .getAllPlayers()
    .find((player) => player.name === targetName);
    if (!(target instanceof Player))
    return player.sendMessage("Target does not exist.");
    target.addEffect(effectList[dropdownValue].id, 50, {
    amplifier: effectLevel,
    showParticles: !hideParticles,
    });
    }
    });
    }

    Modal Form v2.0.0-beta features

    @minecraft/server-ui v2.0.0-beta module currently adds headers, dividers, labels and more. The following images demostrates those features (subject to change).

    Modal form v2

    Image from xKingDark

    export class ModalFormData {
    divider(): ModalFormData;
    dropdown(
    label: minecraftserver.RawMessage | string,
    items: (minecraftserver.RawMessage | string)[],
    dropdownOptions?: ModalFormDataDropdownOptions,
    ): ModalFormData;
    header(text: minecraftserver.RawMessage | string): ModalFormData;
    label(text: minecraftserver.RawMessage | string): ModalFormData;
    show(player: minecraftserver.Player): Promise<ModalFormResponse>;
    slider(
    label: minecraftserver.RawMessage | string,
    minimumValue: number,
    maximumValue: number,
    sliderOptions?: ModalFormDataSliderOptions,
    ): ModalFormData;
    submitButton(submitButtonText: minecraftserver.RawMessage | string): ModalFormData;
    textField(
    label: minecraftserver.RawMessage | string,
    placeholderText: minecraftserver.RawMessage | string,
    textFieldOptions?: ModalFormDataTextFieldOptions,
    ): ModalFormData;
    title(titleText: minecraftserver.RawMessage | string): ModalFormData;
    toggle(label: minecraftserver.RawMessage | string, toggleOptions?: ModalFormDataToggleOptions): ModalFormData;
    }
    Index
    • Returns ModalFormData

      Adds a section divider to the form.

      This function can't be called in early-execution mode.

      import { Player, system } from "@minecraft/server";
      import { ModalFormData } from "@minecraft/server-ui";

      // Run `/scriptevent example:profilesettings` in chat to open the form.
      system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
      if (id !== "example:profilesettings" || !(sourceEntity instanceof Player)) return;

      const form = new ModalFormData();
      form.title("Profile Settings");
      form.textField("Display Name", "Enter name");
      form.divider();
      form.toggle("Show Online Status", { defaultValue: true });

      form.show(sourceEntity).then((response) => {
      if (response.canceled || !response.formValues) return;
      const [name, onlineStatus] = response.formValues;
      sourceEntity.sendMessage(`Saved: Name = ${name}, Online = ${onlineStatus}`);
      });
      });
    • Parameters

      • label: string | RawMessage

        The label to display for the dropdown.

      • items: (string | RawMessage)[]

        The selectable items for the dropdown.

      • OptionaldropdownOptions: ModalFormDataDropdownOptions

        The optional additional values for the dropdown creation.

      Returns ModalFormData

      Adds a dropdown with choices to the form.

      This function can't be called in early-execution mode.

      import { Player, system } from "@minecraft/server";
      import { ModalFormData } from "@minecraft/server-ui";

      // Run `/scriptevent example:gamedifficulty` in chat to open the form.
      system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
      if (id !== "example:gamedifficulty" || !(sourceEntity instanceof Player)) return;

      const difficulties = ["Easy", "Normal", "Hard"];

      const form = new ModalFormData();
      form.title("Game Settings");
      form.dropdown("Difficulty", difficulties, { defaultValueIndex: 1 });

      form.show(sourceEntity).then((response) => {
      if (response.canceled || !response.formValues) return;
      const [difficultyIndex] = response.formValues;
      const difficulty = typeof difficultyIndex === "number" ? difficulties[difficultyIndex] : undefined;
      if (difficulty) {
      sourceEntity.sendMessage(`Selected difficulty: ${difficulty}.`);
      }
      });
      });
    • Parameters

      Returns ModalFormData

      Adds a header to the form.

      This function can't be called in early-execution mode.

      import { Player, system } from "@minecraft/server";
      import { ModalFormData } from "@minecraft/server-ui";

      // Run `/scriptevent example:audiopreferences` in chat to open the form.
      system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
      if (id !== "example:audiopreferences" || !(sourceEntity instanceof Player)) return;

      const form = new ModalFormData();
      form.title("Preferences");
      form.header("Audio Controls");
      form.slider("Volume", 0, 100, { defaultValue: 80, valueStep: 10 });

      form.show(sourceEntity).then((response) => {
      if (response.canceled || !response.formValues) return;
      const [volume] = response.formValues;
      sourceEntity.sendMessage(`Saved volume: ${volume}`);
      });
      });
    • Parameters

      Returns ModalFormData

      Adds a label to the form.

      This function can't be called in early-execution mode.

      import { Player, system } from "@minecraft/server";
      import { ModalFormData } from "@minecraft/server-ui";

      // Run `/scriptevent example:guildregistration` in chat to open the form.
      system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
      if (id !== "example:guildregistration" || !(sourceEntity instanceof Player)) return;

      const form = new ModalFormData();
      form.title("Registration");
      form.label("Enter your guild application details below.");
      form.textField("Guild Tag", "3 to 4 letters");

      form.show(sourceEntity).then((response) => {
      if (response.canceled || !response.formValues) return;
      const [tag] = response.formValues;
      sourceEntity.sendMessage(`Applied with tag: ${tag}`);
      });
      });

      The image below is a demo of a label that says 'Hello, world!' in form.

      label hello world

      Image from xKingDark

    • Parameters

      • player: Player

        Player to show this dialog to.

      Returns Promise<ModalFormResponse>

      Creates and shows this modal popup form. Returns asynchronously when the player confirms or cancels the dialog.

      This function can't be called in restricted-execution mode.

      This function can't be called in early-execution mode.

      import { Player, system } from "@minecraft/server";
      import { ModalFormData } from "@minecraft/server-ui";

      // Run `/scriptevent example:playerfeedback` in chat to open the form.
      system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
      if (id !== "example:playerfeedback" || !(sourceEntity instanceof Player)) return;

      const form = new ModalFormData();
      form.title("Player Feedback");
      form.textField("Comments", "Type here");

      form.show(sourceEntity).then((response) => {
      if (response.canceled || !response.formValues) {
      sourceEntity.sendMessage("Feedback form canceled.");
      return;
      }
      const [comments] = response.formValues;
      sourceEntity.sendMessage(`Feedback submitted: ${comments}`);
      });
      });
    • Parameters

      • label: string | RawMessage

        The label to display for the slider.

      • minimumValue: number

        The minimum selectable possible value.

      • maximumValue: number

        The maximum selectable possible value.

      • OptionalsliderOptions: ModalFormDataSliderOptions

        The optional additional values for the slider creation.

      Returns ModalFormData

      Adds a numeric slider to the form.

      This function can't be called in early-execution mode.

      import { Player, system } from "@minecraft/server";
      import { ModalFormData } from "@minecraft/server-ui";

      // Run `/scriptevent example:musicvolume` in chat to open the form.
      system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
      if (id !== "example:musicvolume" || !(sourceEntity instanceof Player)) return;

      const form = new ModalFormData();
      form.title("Audio Setup");
      form.slider("Music Volume", 0, 100, { defaultValue: 50, valueStep: 5 });

      form.show(sourceEntity).then((response) => {
      if (response.canceled || !response.formValues) return;
      const [volume] = response.formValues;
      sourceEntity.sendMessage(`Music volume set to: ${volume}`);
      });
      });
    • Parameters

      Returns ModalFormData

      import { Player, system } from "@minecraft/server";
      import { ModalFormData } from "@minecraft/server-ui";

      // Run `/scriptevent example:bugreport` in chat to open the form.
      system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
      if (id !== "example:bugreport" || !(sourceEntity instanceof Player)) return;

      const form = new ModalFormData();
      form.title("Bug Report");
      form.textField("Summary", "Describe what happened");
      form.submitButton("Send Report");

      form.show(sourceEntity).then((response) => {
      if (response.canceled || !response.formValues) return;
      const [summary] = response.formValues;
      sourceEntity.sendMessage(`Report sent: ${summary}`);
      });
      });
    • Parameters

      • label: string | RawMessage

        The label to display for the textfield.

      • placeholderText: string | RawMessage

        The place holder text to display.

      • OptionaltextFieldOptions: ModalFormDataTextFieldOptions

        The optional additional values for the textfield creation.

      Returns ModalFormData

      Adds a textbox to the form.

      This function can't be called in early-execution mode.

      import { Player, system } from "@minecraft/server";
      import { ModalFormData } from "@minecraft/server-ui";

      // Run `/scriptevent example:createclan` in chat to open the form.
      system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
      if (id !== "example:createclan" || !(sourceEntity instanceof Player)) return;

      const form = new ModalFormData();
      form.title("Clan Creation");
      form.textField("Clan Name", "e.g. Ironclads", { defaultValue: "Miners" });

      form.show(sourceEntity).then((response) => {
      if (response.canceled || !response.formValues) return;
      const [clanName] = response.formValues;
      sourceEntity.sendMessage(`Clan created: ${clanName}`);
      });
      });
    • Parameters

      Returns ModalFormData

      This builder method sets the title for the modal dialog.

      This function can't be called in early-execution mode.

      import { Player, system } from "@minecraft/server";
      import { ModalFormData } from "@minecraft/server-ui";

      // Run `/scriptevent example:worldoptions` in chat to open the form.
      system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
      if (id !== "example:worldoptions" || !(sourceEntity instanceof Player)) return;

      const form = new ModalFormData();
      form.title("Custom World Options");
      form.toggle("Keep Inventory", { defaultValue: true });

      form.show(sourceEntity).then((response) => {
      if (response.canceled || !response.formValues) return;
      const [keepInventory] = response.formValues;
      sourceEntity.sendMessage(`Keep Inventory set to: ${keepInventory}`);
      });
      });
    • Parameters

      Returns ModalFormData

      Adds a toggle checkbox button to the form.

      This function can't be called in early-execution mode.

      import { Player, system } from "@minecraft/server";
      import { ModalFormData } from "@minecraft/server-ui";

      // Run `/scriptevent example:whispersettings` in chat to open the form.
      system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
      if (id !== "example:whispersettings" || !(sourceEntity instanceof Player)) return;

      const form = new ModalFormData();
      form.title("Chat Settings");
      form.toggle("Receive Private Whispers", { defaultValue: true });

      form.show(sourceEntity).then((response) => {
      if (response.canceled || !response.formValues) return;
      const [whispersEnabled] = response.formValues;
      sourceEntity.sendMessage(`Whispers enabled: ${whispersEnabled}`);
      });
      });

      label toggle with options

      Image from xKingDark