Native Dialog

Paper servers running Minecraft 1.21.6 or later support the Native Dialog API.

With EasyMenu 7, simply specifying dialog: true renders your menu as a native client dialog window for players on supported server versions.

---

Enabling Native Dialogs

Add dialog: true to your menu YAML:

plugins/EasyMenu/sub/shop.yml

menu-title: "&aShop"
dialog: true # Renders as a dialog where supported, chest UI otherwise

menu-items:
  - id: buy_diamond
    material: DIAMOND
    name: "Buy Diamond"
    lore:
      - "Price: $1,000"
    command: "shop buy diamond"

  - id: buy_gold
    material: GOLD_INGOT
    name: "Buy Gold"
    lore:
      - "Price: $500"
    command: "shop buy gold"

The dialog key behaves as follows:

Form	Result
dialog: true	Same as presentation.mode: native-preferred (falls back to the inventory GUI when dialogs are unsupported).
dialog: false	Forces the inventory display. Even when runtime.default-presentation in config.yml is auto or similar, this menu always opens as an inventory GUI.
Omitted	Follows runtime.default-presentation (default: inventory).
dialog together with presentation	presentation wins and dialog is ignored. A warning (dialog-key-ignored) is logged.

---

Element Translation on Dialogs

On Native Dialogs, elements are rendered as dialog buttons:

Menu Item Key	Rendered Dialog Representation
name	Button label text
lore	Hover tooltip on the button
material	Item appearance source (also used for button Sprite / Head icons where supported)

---

Customizing Dialog Layouts

Use presentation.native to customize button column counts, button widths, and escape key behaviors:

presentation:
  mode: native-preferred
  fallback: true

  native:
    columns: 3                   # Button columns (default: 3, range: 1-8)
    button-width: 150            # Button width (default: 150, range: 1-1024)
    can-close-with-escape: true  # Allow closing with Escape (default: true)
    pause: false                 # Pause flag in singleplayer (default: false)

Key	Default	Range / notes
columns	3	Clamped to 1-8. A value below 1 logs a warning and the default is used.
button-width	150	Clamped to 1-1024. A value below 1 logs a warning and the default is used.
can-close-with-escape	true	When false, Escape cannot close the dialog. Provide a button that closes it.
pause	false	Only meaningful in singleplayer (integrated server).

Behavior on Bedrock (Geyser)

columns and button-width are also used as layout hints for Bedrock forms, but the constraints differ from the Java Native Dialog. Bedrock Rich UI caps columns at 3 and rounds the button width into three tiers: 100 or less, 101-180, and 181 or more. See the Bedrock / Geyser / Rich UI Guide.

---

Graceful Fallback on Older Versions

On servers lacking the Dialog API (e.g. Minecraft 1.20.1 through 1.21.5), menus with dialog: true or mode: native-preferred automatically fall back to standard inventory GUIs.

Server administrators do not need to maintain separate menu versions for different Minecraft releases.