CustomForm Class

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.

Methods

• constructor
• button
• close
• closeButton
• divider
• dropdown
• header
• isShowing
• label
• show
• slider
• spacer
• textField
• toggle

constructor

new CustomForm(player: minecraftserver.Player, title: ObservableString | ObservableUIRawMessage | string | UIRawMessage)

Creates a new CustomForm for the specified player with the given title.

Parameters

• player: @minecraft/server.Player

  The player to show this form to.

• title: ObservableString | ObservableUIRawMessage | string | UIRawMessage

  The title text to display at the top of the form.

Returns CustomForm

Notes:

• This function can throw errors.
  • Throws @minecraft/server.InvalidEntityError

button

button(label: ObservableString | ObservableUIRawMessage | string | UIRawMessage, onClick: () => void, options?: ButtonOptions): CustomForm

Adds a clickable button to the form layout. Returns the form instance to allow method chaining.

Parameters

• label: ObservableString | ObservableUIRawMessage | string | UIRawMessage

  The text label to display on the button.

• onClick: () => void

  A callback function that is invoked when the player clicks the button.

• options?: ButtonOptions = null

  Optional configuration for the button, such as a tooltip, disabled state, or visibility.

Returns CustomForm

Notes:

• This function can't be called in restricted-execution mode.
• This function can throw errors.
  • Throws InvalidFormModificationError

close

close(): void

Closes the form if it is currently being shown to the player. Throws a FormVisibilityError if the form is not currently open.

Notes:

• This function can't be called in restricted-execution mode.
• This function can throw errors.
  • Throws @minecraft/common.EngineError, FormVisibilityError, @minecraft/server.InvalidEntityError

closeButton

closeButton(): CustomForm

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.

Returns CustomForm

Notes:

• This function can't be called in restricted-execution mode.
• This function can throw errors.
  • Throws InvalidFormModificationError

divider

divider(options?: DividerOptions): CustomForm

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.

Parameters

• options?: DividerOptions = null

  Optional configuration for the divider, such as visibility.

Returns CustomForm

Notes:

• This function can't be called in restricted-execution mode.
• This function can throw errors.
  • Throws InvalidFormModificationError

dropdown

dropdown(label: ObservableString | ObservableUIRawMessage | string | UIRawMessage, value: ObservableNumber, items: DropdownItemData[], options?: DropdownOptions): CustomForm

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.

Parameters

• label: ObservableString | ObservableUIRawMessage | string | UIRawMessage

  The text label displayed around the dropdown.

• value: ObservableNumber

  An ObservableNumber that holds the index of the currently selected item.

• items: DropdownItemData[]

  The list of items to display in the dropdown.

• options?: DropdownOptions = null

  Optional configuration for the dropdown, such as a description, disabled state, or visibility.

Returns CustomForm

Notes:

• This function can't be called in restricted-execution mode.
• This function can throw errors.
  • Throws InvalidFormModificationError, InvalidObservableError

header

header(text: ObservableString | ObservableUIRawMessage | string | UIRawMessage, options?: TextOptions): CustomForm

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.

Parameters

• text: ObservableString | ObservableUIRawMessage | string | UIRawMessage

  The header text to display.

• options?: TextOptions = null

  Optional configuration for the header, such as visibility.

Returns CustomForm

Notes:

• This function can't be called in restricted-execution mode.
• This function can throw errors.
  • Throws InvalidFormModificationError

isShowing

isShowing(): boolean

Returns true if the form is currently being shown to the player, false otherwise.

Returns boolean

Notes:

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

label

label(text: ObservableString | ObservableUIRawMessage | string | UIRawMessage, options?: TextOptions): CustomForm

Adds a read-only text label to the form layout. Returns the form instance to allow method chaining.

Parameters

• text: ObservableString | ObservableUIRawMessage | string | UIRawMessage

  The text to display in the label.

• options?: TextOptions = null

  Optional configuration for the label, such as visibility.

Returns CustomForm

Notes:

• This function can't be called in restricted-execution mode.
• This function can throw errors.
  • Throws InvalidFormModificationError

show

show(): Promise<DataDrivenScreenClosedReason>

Shows the form to the player. Returns a promise that resolves with a DataDrivenScreenClosedReason indicating how the form was closed.

Returns Promise<DataDrivenScreenClosedReason>

Notes:

• This function can't be called in restricted-execution mode.
• This function can throw errors.
  • Throws @minecraft/common.EngineError, FormVisibilityError, @minecraft/server.InvalidEntityError

slider

slider(label: ObservableString | ObservableUIRawMessage | string | UIRawMessage, value: ObservableNumber, min: number | ObservableNumber, max: number | ObservableNumber, options?: SliderOptions): CustomForm

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.

Parameters

• label: ObservableString | ObservableUIRawMessage | string | UIRawMessage

  The text label displayed around the slider.

• value: ObservableNumber

  An ObservableNumber that holds the current value of the slider.

• min: number | ObservableNumber

  The minimum value of the slider range.

• max: number | ObservableNumber

  The maximum value of the slider range.

• options?: SliderOptions = null

  Optional configuration for the slider, such as step size, a description, disabled state, or visibility.

Returns CustomForm

Notes:

• This function can't be called in restricted-execution mode.
• This function can throw errors.
  • Throws InvalidFormModificationError, InvalidObservableError

spacer

spacer(options?: SpacingOptions): CustomForm

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.

Parameters

• options?: SpacingOptions = null

  Optional configuration for the spacer, such as visibility.

Returns CustomForm

Notes:

• This function can't be called in restricted-execution mode.
• This function can throw errors.
  • Throws InvalidFormModificationError

textField

textField(label: ObservableString | ObservableUIRawMessage | string | UIRawMessage, text: ObservableString, options?: TextFieldOptions): CustomForm

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.

Parameters

• label: ObservableString | ObservableUIRawMessage | string | UIRawMessage

  The text label displayed around the text field.

• text: ObservableString

  An ObservableString that holds the current text value of the input field.

• options?: TextFieldOptions = null

  Optional configuration for the text field, such as a description, disabled state, or visibility.

Returns CustomForm

Notes:

• This function can't be called in restricted-execution mode.
• This function can throw errors.
  • Throws InvalidFormModificationError, InvalidObservableError

toggle

toggle(label: ObservableString | ObservableUIRawMessage | string | UIRawMessage, toggled: ObservableBoolean, options?: ToggleOptions): CustomForm

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.

Parameters

• label: ObservableString | ObservableUIRawMessage | string | UIRawMessage

  The text label displayed next to the toggle.

• toggled: ObservableBoolean

  An ObservableBoolean that holds the current on/off state of the toggle.

• options?: ToggleOptions = null

  Optional configuration for the toggle, such as a description, disabled state, or visibility.

Returns CustomForm

Notes:

• This function can't be called in restricted-execution mode.
• This function can throw errors.
  • Throws InvalidFormModificationError, InvalidObservableError