# Modal

<figure><img src="https://3046942752-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHfd391cB6wDC8S3yHcie%2Fuploads%2FFkeFhwpmgpcacNf1PgDr%2Fimage.png?alt=media&#x26;token=c812175e-3bad-4f1c-b5b9-f36a9f09979a" alt=""><figcaption></figcaption></figure>

A popup window that shows a title, input fields, and action buttons.\
Modals can appear when you press a key, hover over a card, or click a button.

***

## Structure

```lua
modal = {
    title = "Edit Item",
    options = {
        { id = "item_name", label = "Item Name", type = "text" },
        { id = "amount", label = "Amount", type = "number", min = 1, max = 100 }
    },
    buttons = {
        {
            id = "save_item",
            label = "Save",
            on_action = function(data)
                -- do something with data.dataset.item_name, data.dataset.amount
            end,
            dataset = { -- additional data if required
                source = "inventory",
                item_id = "some_id"
            }
        },
        {
            id = "cancel",
            label = "Cancel"
            -- No action needed — this will auto-close the modal
        }
    }
}
```

***

## Modal Options

| Key       | Description                                                  |
| --------- | ------------------------------------------------------------ |
| `title`   | Title text shown at the top of the modal.                    |
| `options` | A list of inputs to show inside the modal (see Input Types). |
| `buttons` | Buttons shown at the bottom — use `on_action` or `action`.   |

***

## Input Types

| Type       | Description                                                      |
| ---------- | ---------------------------------------------------------------- |
| `text`     | A single-line text input.                                        |
| `number`   | A number input. You can include `min` and `max`.                 |
| `textarea` | A larger, multiline input.                                       |
| `select`   | A dropdown menu — include `options = { { label, value }, ... }`. |

## Each input requires:

| Key     | Description                        |
| ------- | ---------------------------------- |
| `id`    | Unique field name.                 |
| `label` | Label displayed next to the input. |

***

## Button Options

| Key         | Description                                                           |
| ----------- | --------------------------------------------------------------------- |
| `id`        | Unique button ID.                                                     |
| `label`     | Button text.                                                          |
| `on_action` | Custom handler function that receives `{ input = {}, dataset = {} }`. |
| `action`    | Optional named action (e.g., `"close_builder"`).                      |
| `dataset`   | Optional values passed alongside the input data.                      |
| *(none)*    | If no `on_action` or `action` is given, the button closes the modal.  |

***

## Notes

* Modal input values are **automatically collected** when a button is clicked.
* Values are passed to your handler function or action as `data.input`.
* You can show one modal per interaction or button — they do not conflict.
* Use `on_action = function(data)` for fully custom behavior.
* Use `action = "close_builder"` to safely close the UI entirely.
* Simply leave out the action on any button to close the modal.