The player to show this form to.
The title text to display at the top of the form.
Optionaloptions: CustomFormOptionsThe text label to display on the button.
A callback function that is invoked when the player clicks the button.
Optionaloptions: ButtonOptions
Optional configuration for the button, such as a tooltip, disabled state, or visibility.
Adds a clickable button to the form layout. Returns the form instance to allow method chaining.
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 { CustomForm, DataDrivenScreenClosedReason } from "@minecraft/server-ui";
// Run `/scriptevent example:teleporthub` in chat to open the form.
system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
if (id !== "example:teleporthub" || !(sourceEntity instanceof Player)) return;
const form = new CustomForm(sourceEntity, "Teleport Hub");
form.button("Teleport to Spawn", () => {
sourceEntity.sendMessage("Teleported to spawn.");
});
form.show().then((reason) => {
if (reason === DataDrivenScreenClosedReason.ServerClosed) {
sourceEntity.sendMessage("The server closed the teleport hub.");
} else {
sourceEntity.sendMessage("You closed the teleport hub.");
}
});
});
Closes the form if it is currently being shown to the player. Throws a FormVisibilityError if the form is not currently open.
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 { CustomForm, DataDrivenScreenClosedReason } from "@minecraft/server-ui";
// Run `/scriptevent example:timedoffer` in chat to open the form.
system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
if (id !== "example:timedoffer" || !(sourceEntity instanceof Player)) return;
const form = new CustomForm(sourceEntity, "Timed Offer");
form.label("This offer will close in 3 seconds.");
form.show().then((reason) => {
if (reason === DataDrivenScreenClosedReason.ServerClosed) {
sourceEntity.sendMessage("The server closed the timed offer.");
} else {
sourceEntity.sendMessage("You closed the timed offer.");
}
});
// Close the open form after 3 seconds (60 ticks).
system.runTimeout(() => {
if (form.isShowing()) {
form.close();
}
}, 60);
});
Adds a close button to the form at the bottom and as an 'X' in the corner. Returns the form instance to allow method chaining.
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 { CustomForm, DataDrivenScreenClosedReason } from "@minecraft/server-ui";
// Run `/scriptevent example:serverinfo` in chat to open the form.
system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
if (id !== "example:serverinfo" || !(sourceEntity instanceof Player)) return;
const form = new CustomForm(sourceEntity, "Server Info");
form.label("Welcome to the server! Explore custom biomes and quests.");
form.closeButton();
form.show().then((reason) => {
if (reason === DataDrivenScreenClosedReason.ServerClosed) {
sourceEntity.sendMessage("The server closed the server info.");
} else {
sourceEntity.sendMessage("You closed the server info.");
}
});
});
Optionaloptions: DividerOptions
Optional configuration for the divider, such as visibility.
Adds a horizontal divider line to the form layout. Useful for visually separating sections of the form. Returns the form instance to allow method chaining.
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 { CustomForm, DataDrivenScreenClosedReason } from "@minecraft/server-ui";
// Run `/scriptevent example:accountoverview` in chat to open the form.
system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
if (id !== "example:accountoverview" || !(sourceEntity instanceof Player)) return;
const form = new CustomForm(sourceEntity, "Account Overview");
form.label("Manage account settings.");
form.divider();
form.button("Log Out", () => {
sourceEntity.sendMessage("Logged out.");
});
form.show().then((reason) => {
if (reason === DataDrivenScreenClosedReason.ServerClosed) {
sourceEntity.sendMessage("The server closed the account overview.");
} else {
sourceEntity.sendMessage("You closed the account overview.");
}
});
});
The text label displayed around the dropdown.
An ObservableNumber that holds the index of the currently selected item.
The list of items to display in the dropdown.
Optionaloptions: DropdownOptions
Optional configuration for the dropdown, such as a description, disabled state, or visibility.
Adds a dropdown selection control to the form layout. The current selection is tracked via an ObservableNumber and will update when the player changes the selection. Returns the form instance to allow method chaining.
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 { CustomForm, DataDrivenScreenClosedReason, ObservableNumber } from "@minecraft/server-ui";
// Run `/scriptevent example:chooseheroclass` in chat to open the form.
system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
if (id !== "example:chooseheroclass" || !(sourceEntity instanceof Player)) return;
const classNames = ["Warrior", "Mage", "Rogue"];
const selectedClass = new ObservableNumber(0, { clientWritable: true });
selectedClass.subscribe((value) => {
const heroClass = classNames[value] ?? "Unknown";
sourceEntity.sendMessage(`Selected class: ${heroClass}.`);
});
const form = new CustomForm(sourceEntity, "Hero Class");
form.dropdown("Choose Class", selectedClass, [
{ label: "Warrior", value: 0 },
{ label: "Mage", value: 1 },
{ label: "Rogue", value: 2 },
]);
form.show().then((reason) => {
if (reason === DataDrivenScreenClosedReason.ServerClosed) {
sourceEntity.sendMessage("The server closed the hero class form.");
} else {
sourceEntity.sendMessage("You closed the hero class form.");
}
});
});
The header text to display.
Optionaloptions: TextOptions
Optional configuration for the header, such as visibility.
Adds a header text component to the form layout. Headers are displayed in a larger or bolder style than regular labels, and are suitable for section titles. Returns the form instance to allow method chaining.
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 { CustomForm, DataDrivenScreenClosedReason } from "@minecraft/server-ui";
// Run `/scriptevent example:servercontrols` in chat to open the form.
system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
if (id !== "example:servercontrols" || !(sourceEntity instanceof Player)) return;
const form = new CustomForm(sourceEntity, "Server Controls");
form.header("Gameplay Rules");
form.button("Toggle Fall Damage", () => {
sourceEntity.sendMessage("Updated fall damage setting.");
});
form.show().then((reason) => {
if (reason === DataDrivenScreenClosedReason.ServerClosed) {
sourceEntity.sendMessage("The server closed the controls form.");
} else {
sourceEntity.sendMessage("You closed the controls form.");
}
});
});
The image source path to display. Must be a relative path to an image file within the provided pack.
The resource pack identifier that contains the provided image source.
Optionaloptions: ImageOptions
Optional configuration for the image, such as visibility or width.
The form instance to allow method chaining.
Adds an image component to the form layout. Gifs are supported but are extremely slow to load - always try to have the gif as small as possible.
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 { CustomForm, DataDrivenScreenClosedReason } from "@minecraft/server-ui";
// Run `/scriptevent example:welcomebadge` in chat to open the form.
system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
if (id !== "example:welcomebadge" || !(sourceEntity instanceof Player)) return;
const form = new CustomForm(sourceEntity, "Welcome Badge");
form.image("textures/ui/World", "core", { width: 0.5 });
form.label("Welcome to the realm.");
form.show().then((reason) => {
if (reason === DataDrivenScreenClosedReason.ServerClosed) {
sourceEntity.sendMessage("The server closed the welcome badge.");
} else {
sourceEntity.sendMessage("You closed the welcome badge.");
}
});
});
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 { CustomForm, DataDrivenScreenClosedReason } from "@minecraft/server-ui";
// Run `/scriptevent example:closeafterthreeseconds` in chat to open the form.
system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
if (id !== "example:closeafterthreeseconds" || !(sourceEntity instanceof Player)) return;
const form = new CustomForm(sourceEntity, "Visibility Panel");
form.label("Monitoring form visibility state.");
form.show().then((reason) => {
if (reason === DataDrivenScreenClosedReason.ServerClosed) {
sourceEntity.sendMessage("The server closed the visibility panel.");
} else {
sourceEntity.sendMessage("You closed the visibility panel.");
}
});
// Check whether the form is still open before closing it.
system.runTimeout(() => {
if (form.isShowing()) {
sourceEntity.sendMessage("Form is open. Closing now.");
form.close();
}
}, 60);
});
The text to display in the label.
Optionaloptions: TextOptions
Optional configuration for the label, such as visibility.
Adds a read-only text label to the form layout. Returns the form instance to allow method chaining.
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 { CustomForm, DataDrivenScreenClosedReason } from "@minecraft/server-ui";
// Run `/scriptevent example:questguide` in chat to open the form.
system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
if (id !== "example:questguide" || !(sourceEntity instanceof Player)) return;
const form = new CustomForm(sourceEntity, "Quest Guidance");
form.label("Defeat 10 zombies in the mines to complete this bounty.");
form.show().then((reason) => {
if (reason === DataDrivenScreenClosedReason.ServerClosed) {
sourceEntity.sendMessage("The server closed the quest guide.");
} else {
sourceEntity.sendMessage("You closed the quest guide.");
}
});
});
Rc
The buttons to display in the row. Maximum Length: 3
Optionaloptions: MultiButtonRowOptions
Optional configuration for the row, such as visibility.
Adds a horizontal row of up to three clickable buttons to the form layout. Returns the form instance to allow method chaining.
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 { CustomForm, DataDrivenScreenClosedReason } from "@minecraft/server-ui";
// Run `/scriptevent example:acceptordecline` in chat to open the form.
system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
if (id !== "example:acceptordecline" || !(sourceEntity instanceof Player)) return;
const form = new CustomForm(sourceEntity, "Confirm Action");
form.label("Do you want to proceed with this purchase?");
form.multiButtonRow([
{ label: "Accept", onClick: () => sourceEntity.sendMessage("Accepted.") },
{ label: "Decline", onClick: () => sourceEntity.sendMessage("Declined.") },
]);
form.show().then((reason) => {
if (reason === DataDrivenScreenClosedReason.ServerClosed) {
sourceEntity.sendMessage("The server closed the confirmation form.");
} else {
sourceEntity.sendMessage("You closed the confirmation form.");
}
});
});
Shows the form to the player. Returns a promise that resolves with a DataDrivenScreenClosedReason indicating how the form was closed.
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 { CustomForm, DataDrivenScreenClosedReason } from "@minecraft/server-ui";
// Run `/scriptevent example:dailycheckin` in chat to open the form.
system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
if (id !== "example:dailycheckin" || !(sourceEntity instanceof Player)) return;
const form = new CustomForm(sourceEntity, "Daily Check-in");
form.label("Welcome back to another adventure day.");
form.show().then((closeReason) => {
if (closeReason === DataDrivenScreenClosedReason.ServerClosed) {
sourceEntity.sendMessage("The server closed the daily check-in.");
} else {
sourceEntity.sendMessage("You closed the daily check-in.");
}
});
});
The text label displayed around the slider.
An ObservableNumber that holds the current value of the slider.
The minimum value of the slider range.
The maximum value of the slider range.
Optionaloptions: SliderOptions
Optional configuration for the slider, such as step size, a description, disabled state, or visibility.
Adds a numeric slider control to the form layout. The current value is tracked via an ObservableNumber and will update as the player moves the slider. Returns the form instance to allow method chaining.
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 { CustomForm, DataDrivenScreenClosedReason, ObservableNumber } from "@minecraft/server-ui";
// Run `/scriptevent example:renderdistance` in chat to open the form.
system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
if (id !== "example:renderdistance" || !(sourceEntity instanceof Player)) return;
const renderDistance = new ObservableNumber(8, { clientWritable: true });
renderDistance.subscribe((newDistance) => {
sourceEntity.sendMessage(`Render distance set to ${newDistance} chunks.`);
});
const form = new CustomForm(sourceEntity, "Video Settings");
form.slider("Render Distance (Chunks)", renderDistance, 4, 16, { step: 2 });
form.show().then((reason) => {
if (reason === DataDrivenScreenClosedReason.ServerClosed) {
sourceEntity.sendMessage("The server closed the settings form.");
} else {
sourceEntity.sendMessage("You closed the settings form.");
}
});
});
Optionaloptions: SpacingOptions
Optional configuration for the spacer, such as visibility.
Adds a vertical spacer component to the form layout. Useful for adding empty space between form components. Returns the form instance to allow method chaining.
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 { CustomForm, DataDrivenScreenClosedReason } from "@minecraft/server-ui";
// Run `/scriptevent example:spacebeforebutton` in chat to open the form.
system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
if (id !== "example:spacebeforebutton" || !(sourceEntity instanceof Player)) return;
const form = new CustomForm(sourceEntity, "Layout Spacing");
form.header("Top Section");
form.spacer();
form.button("Continue", () => {
sourceEntity.sendMessage("Proceeding.");
});
form.show().then((reason) => {
if (reason === DataDrivenScreenClosedReason.ServerClosed) {
sourceEntity.sendMessage("The server closed the form.");
} else {
sourceEntity.sendMessage("You closed the form.");
}
});
});
The text label displayed around the text field.
An ObservableString that holds the current text value of the input field.
Optionaloptions: TextFieldOptions
Optional configuration for the text field, such as a description, disabled state, or visibility.
Adds a text input field to the form layout. The current text value is tracked via an ObservableString and will update as the player types. Returns the form instance to allow method chaining.
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 { CustomForm, DataDrivenScreenClosedReason, ObservableString } from "@minecraft/server-ui";
// Run `/scriptevent example:nameyourcharacter` in chat to open the form.
system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
if (id !== "example:nameyourcharacter" || !(sourceEntity instanceof Player)) return;
const playerNameInput = new ObservableString("", { clientWritable: true });
playerNameInput.subscribe((text) => {
sourceEntity.sendMessage(`Name updated to: ${text}`);
});
const form = new CustomForm(sourceEntity, "Character Setup");
form.textField("Character Name", playerNameInput);
form.show().then((reason) => {
if (reason === DataDrivenScreenClosedReason.ServerClosed) {
sourceEntity.sendMessage("The server closed character setup.");
} else {
sourceEntity.sendMessage("You closed character setup.");
}
});
});
The text label displayed next to the toggle.
An ObservableBoolean that holds the current on/off state of the toggle.
Optionaloptions: ToggleOptions
Optional configuration for the toggle, such as a description, disabled state, or visibility.
Adds a toggle (on/off switch) control to the form layout. The current state is tracked via an ObservableBoolean and will update when the player toggles it. Returns the form instance to allow method chaining.
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 { CustomForm, DataDrivenScreenClosedReason, ObservableBoolean } from "@minecraft/server-ui";
// Run `/scriptevent example:soundtoggle` in chat to open the form.
system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
if (id !== "example:soundtoggle" || !(sourceEntity instanceof Player)) return;
const soundEnabled = new ObservableBoolean(true, { clientWritable: true });
soundEnabled.subscribe((enabled) => {
sourceEntity.sendMessage(`Background music ${enabled ? "enabled" : "disabled"}.`);
});
const form = new CustomForm(sourceEntity, "Preferences");
form.toggle("Play Background Music", soundEnabled);
form.show().then((reason) => {
if (reason === DataDrivenScreenClosedReason.ServerClosed) {
sourceEntity.sendMessage("The server closed preferences.");
} else {
sourceEntity.sendMessage("You closed preferences.");
}
});
});
A customizable data driven (DDUI) form that lets you add buttons, labels, toggles, dropdowns, sliders, text fields, and more. The form layout is built by calling methods to add components before calling show(). Any Observable values bound to form components will automatically update the UI when their values change.
Example: demo.ts
Example: localizedText.ts
Example: realTimeEntityMonitor.ts
Example: settingsWithValidation.ts
Example: simpleActionMenu.ts
Source