# 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>](https://app.gitbook.com/s/HqXqB9FayGrV9U31bfmT/skull-grabber-dialog-ui)

<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&#x26;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 a single method:

* `width(pixels)`  sets the button width (default: 100). Returns the `Dialog` object.

***

**`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`

***

**`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()
```