# Modal

<figure><img src="/files/5kT2EI9bQF1u2zuSS35F" 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.


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.boii.dev/fivem-free-resources/bduk/components/modal.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.