> For the complete documentation index, see [llms.txt](https://openjs.wiki.gd/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://openjs.wiki.gd/apis-and-tools/services/dialogapi.md).

# DialogApi

Services.get("DialogApi")

## Overview:

The `DialogApi` provides an interactive menu system using Paper’s modern Dialog API (requires Paper 1.21.6+). It allows you to create rich dialogs with text, inputs (text, range, boolean), item displays, and buttons. Dialogs can be closed by the player or your script, and events let you respond to button clicks, input changes, and closure.

```javascript
const Dialog = Services.get("DialogApi")
const dialog = Dialog.create(player)
    .title("My Dialog")
    .bodyMessage("info", "&aWelcome!")
    .show()
```

### Screenshot [<sup><sub>**(source code to the script here)**<sub></sup>](/example-scripts/skull-grabber-dialog-ui.md)

<figure><img src="https://1928206941-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FninfHRqxK6AQQSdjX6JX%2Fuploads%2F8GYTCJN0Y4HpQxcZTOCp%2Fimage.png?alt=media&amp;token=fb68cfda-6218-41db-a760-40990a2daa03" alt="" width="563"><figcaption></figcaption></figure>

### API Reference

**`Services.get("DialogApi")`**

Returns the DialogApi service object.

***

**`create(player)`**

Creates a new dialog for the given player.

| Parameter | Type     | Description                        |
| --------- | -------- | ---------------------------------- |
| `player`  | `Player` | The player who will see the dialog |

**Returns:** `Dialog` object

***

### Dialog Object

The dialog object returned by `create()` provides the following methods:

**`title(text)`**

Sets the dialog title.

| Parameter | Type     | Description                       |
| --------- | -------- | --------------------------------- |
| `text`    | `String` | Title text (supports color codes) |

**Returns:** `Dialog` (for chaining)

***

**`columns(cols)`**

Sets the number of columns for the button layout (default: 1).

| Parameter | Type     | Description                       |
| --------- | -------- | --------------------------------- |
| `cols`    | `Number` | Number of columns (e.g., 1, 2, 3) |

**Returns:** `Dialog`

***

**`canCloseWithEscape(value)`**

Allows the player to close the dialog by pressing Escape (default: true).

| Parameter | Type      | Description                         |
| --------- | --------- | ----------------------------------- |
| `value`   | `Boolean` | `true` to allow, `false` to disable |

**Returns:** `Dialog`

***

**`bodyMessage(id, text)`**

Adds a plain text message to the dialog body.

| Parameter | Type     | Description                         |
| --------- | -------- | ----------------------------------- |
| `id`      | `String` | Unique identifier for this message  |
| `text`    | `String` | Message text (supports color codes) |

**Returns:** `Dialog`

***

**`setBodyMessage(id, text)`**

Updates an existing body message.

| Parameter | Type     | Description                     |
| --------- | -------- | ------------------------------- |
| `id`      | `String` | The ID of the message to update |
| `text`    | `String` | New message text                |

**Returns:** `Dialog`

***

**`textInput(id, label, initial)`**

Adds a text input field.

| Parameter | Type     | Description                              |
| --------- | -------- | ---------------------------------------- |
| `id`      | `String` | Unique identifier for this input         |
| `label`   | `String` | Label displayed above the input          |
| `initial` | `String` | Initial value (optional, defaults to "") |

**Returns:** `Dialog`

***

**`rangeInput(id, label, initial, min, max, step)`**

Adds a numeric slider input.

| Parameter | Type     | Description                   |
| --------- | -------- | ----------------------------- |
| `id`      | `String` | Unique identifier             |
| `label`   | `String` | Label                         |
| `initial` | `Number` | Starting value                |
| `min`     | `Number` | Minimum value                 |
| `max`     | `Number` | Maximum value                 |
| `step`    | `Number` | Step increment (e.g., 1, 0.5) |

**Returns:** `Dialog`

***

**`boolInput(id, label, initial)`**

Adds a checkbox (boolean) input.

| Parameter | Type      | Description                                 |
| --------- | --------- | ------------------------------------------- |
| `id`      | `String`  | Unique identifier                           |
| `label`   | `String`  | Label                                       |
| `initial` | `Boolean` | Initial state (optional, defaults to false) |

**Returns:** `Dialog`

***

**`item(id, itemStack, description)`**

Displays an item in the dialog body.

| Parameter     | Type        | Description                                 |
| ------------- | ----------- | ------------------------------------------- |
| `id`          | `String`    | Unique identifier                           |
| `itemStack`   | `ItemStack` | The item to display                         |
| `description` | `String`    | Optional description (supports color codes) |

**Returns:** `Dialog`

***

**`setItem(id, itemStack, description)`**

Updates an existing item display.

| Parameter     | Type        | Description              |
| ------------- | ----------- | ------------------------ |
| `id`          | `String`    | ID of the item to update |
| `itemStack`   | `ItemStack` | New item                 |
| `description` | `String`    | Optional new description |

**Returns:** `Dialog`

***

**`baseButton(id, label)`**

Creates a button builder for a regular button.

| Parameter | Type     | Description                        |
| --------- | -------- | ---------------------------------- |
| `id`      | `String` | Unique identifier                  |
| `label`   | `String` | Button text (supports color codes) |

**Returns:** `ButtonBuilder` | `Dialog`

The `ButtonBuilder` has 2 methods:

* `width(pixels)`  sets the button width (default: 100). Returns the `Dialog` object.
* `tooltip(text)` sets the buttons tooltip (text that appears when mouse hovers over the button)

***

**`urlButton(id, label, url)`**

Creates a button that opens a URL when clicked.

| Parameter | Type     | Description              |
| --------- | -------- | ------------------------ |
| `id`      | `String` | Unique identifier        |
| `label`   | `String` | Button text              |
| `url`     | `String` | URL to open when clicked |

**Returns:** `ButtonBuilder` (same as above)

***

**`confirmButtons(yesId, yesLabel, noId, noLabel)`**

Adds two side-by-side buttons (Yes/No).

| Parameter  | Type     | Description                |
| ---------- | -------- | -------------------------- |
| `yesId`    | `String` | ID for the "yes" button    |
| `yesLabel` | `String` | Label for the "yes" button |
| `noId`     | `String` | ID for the "no" button     |
| `noLabel`  | `String` | Label for the "no" button  |

**Returns:** `Dialog`

***

**`exitButton(label)`**

Adds an exit button (closes the dialog when clicked). Only one exit button is allowed; calling this method again replaces the previous one.

| Parameter | Type     | Description  |
| --------- | -------- | ------------ |
| `label`   | `String` | Button label |

**Returns:** `ButtonBuilder` (same as above)

***

**`setButtonText(id, text)`**

Changes the text of an existing button.

| Parameter | Type     | Description     |
| --------- | -------- | --------------- |
| `id`      | `String` | Button ID       |
| `text`    | `String` | New button text |

**Returns:** `Dialog`

***

`setTooltip(id, text)`

Changes the tooltip of an existing button.

| Parameter | Type     | Description             |
| --------- | -------- | ----------------------- |
| `id`      | `String` | Button ID               |
| `text`    | `String` | New tooltip button text |

**Returns:** `Dialog`

***

**`get(id)`**

Retrieves the current value of an input field by its ID (only available after the dialog has been opened).

| Parameter | Type     | Description |
| --------- | -------- | ----------- |
| `id`      | `String` | Input ID    |

**Returns:** `*` current value (String, Number, Boolean, or null)

***

**`onEvent(handler)`**

Registers a callback that is fired for all dialog events (button clicks, input changes, closure).

| Parameter | Type       | Description               |
| --------- | ---------- | ------------------------- |
| `handler` | `Function` | `function(event) { ... }` |

**Returns:** `Dialog`

The `event` object passed to the handler has the following properties:

| Property         | Type       | Description                                                                                    |
| ---------------- | ---------- | ---------------------------------------------------------------------------------------------- |
| `type`           | `String`   | `"button"`, `"input"`, or `"closed"`                                                           |
| `id`             | `String`   | For `"button"` it's the button ID; for `"input"` it's the input ID; for `"closed"` it's `null` |
| `value`          | `*`        | For `"button"` it's the button ID; for `"input"` it's the new value                            |
| `read(key)`      | `Function` | Returns the current value of a given input (shortcut)                                          |
| `get(id)`        | `Function` | Alias for `read`                                                                               |
| `setCancelled()` | `Function` | Call to prevent default action (e.g., closing on exit button)                                  |
| `isCancelled()`  | `Function` | Returns whether the event was cancelled                                                        |

***

**`show()`**

Displays the dialog to the player.

**Returns:** `Dialog`

***

**`close()`**

Closes the dialog (fires a `"closed"` event). The dialog remains usable; you can `show()` it again.

**Returns:** `Dialog`

***

**`destroy()`**

Permanently destroys the dialog, freeing all resources. The dialog cannot be used afterwards.

**Returns:** `Dialog`

***

### Example

```javascript
const Dialog = Services.get("DialogApi")
const inventoryApi = Services.get("InventoryApi")

// Create a simple confirmation dialog
const dialog = Dialog.create(player)
    .title("&6&lConfirm")
    .bodyMessage("msg", "&7Do you want to delete your item?")
    .confirmButtons("yes", "&aYes", "no", "&cNo")
    .onEvent(event => {
        if (event.type === "button") {
            if (event.id === "yes") {
                player.getInventory().setItemInMainHand(null)
                player.sendMessage("§aItem deleted!")
            }
            dialog.close()
        }
    })
    .show()
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://openjs.wiki.gd/apis-and-tools/services/dialogapi.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.