# Alert

<figure><img src="/files/0PdzH0OJhaBgwTjNtaVO" alt=""><figcaption></figcaption></figure>

This resource provides a synchronous (blocking) Alert Dialog system. It utilizes `Citizen.Await` to pause code execution until the user interacts with the alert, making logic flows linear and easy to write.

### ⚙️ Exports

You can access these functions from any other resource using the `exports` handler.

#### `ShowAlert`

Opens a customizable alert dialog and awaits a user response.

```lua
local result = exports['ak47_lib']:ShowAlert(data)
```

Parameters (`data` table):

| **Property** | **Type**  | **Default** | **Description**                                                                                     |
| ------------ | --------- | ----------- | --------------------------------------------------------------------------------------------------- |
| `header`     | `string`  | `nil`       | The title text of the alert.                                                                        |
| `content`    | `string`  | `nil`       | The body text. Supports `\n` for new lines and Markdown (e.g., `**bold**`).                         |
| `centered`   | `boolean` | `false`     | If `true`, centers the text within the dialog.                                                      |
| `cancel`     | `boolean` | `false`     | If `true`, displays a "Cancel" button alongside the confirm button.                                 |
| `size`       | `string`  | `config`    | The width of the dialog. Options usually include `'sm'`, `'md'`, `'lg'`.                            |
| `labels`     | `table`   | `nil`       | Custom text for buttons. See [Label Object](https://www.google.com/search?q=%23label-object) below. |
| `colors`     | `table`   | `config`    | Custom Hex colors. See [Color Object](https://www.google.com/search?q=%23color-object) below.       |
| `borders`    | `table`   | `config`    | Array of border positions (e.g., `{'bottom'}`).                                                     |

Return Value:

* `'confirm'`: User clicked the confirm button.
* `'cancel'`: User clicked cancel, the alert was overwritten, or the UI was forcibly closed.

> Note: If an alert is already active when `ShowAlert` is called, the new function call will immediately return `'cancel'` to prevent overlapping UIs.

***

#### `HideAlert`

Forcibly closes the currently active alert (if any) and resolves its promise as `'cancel'`.

```lua
exports['ak47_lib']:HideAlert()
```

***

### 🧩 Data Objects

#### Label Object

Used inside the `labels` parameter to change button text.

```lua
{
    confirm = "Yes, Do it", -- Text for the primary button
    cancel = "No, Go back"  -- Text for the secondary button (if cancel = true)
}
```

#### Color Object

Used inside the `colors` parameter to override default styling.

```lua
{
    colorPrimary = '#1F1F1F',   -- Background color
    colorSecondary = '#FF5555', -- Accent/Button color
    colorText = '#FFFFFF'       -- Text color
}
```

***

### 💡 Examples

#### Example 1: Basic Information

A simple notification that pauses the script until acknowledged.

```lua
local result = exports['ak47_lib']:ShowAlert({
    header = 'Welcome',
    content = 'Welcome to the server! Please read the rules.',
    centered = true,
    size = 'sm'
})

print('User acknowledged the alert.')
```

#### Example 2: Confirmation Logic

Using the return value to determine the next step.

```lua
local choice = exports['ak47_lib']:ShowAlert({
    header = 'Purchase Vehicle',
    content = 'Are you sure you want to buy this vehicle for **$50,000**?',
    cancel = true, -- Enable cancel button
    labels = {
        confirm = 'Purchase',
        cancel = 'Walk Away'
    }
})

if choice == 'confirm' then
    TriggerServerEvent('buyVehicle')
    print('Vehicle purchased')
else
    print('Purchase cancelled')
end
```

#### Example 3: Danger/Warning Style

Customizing colors to indicate a dangerous action (red styling).

```lua
local confirmation = exports['ak47_lib']:ShowAlert({
    header = 'DELETE CHARACTER',
    content = 'This action is **irreversible**.\nAre you sure?',
    centered = true,
    cancel = true,
    size = 'md',
    colors = {
        colorPrimary = '#360000', -- Dark Red Background
        colorSecondary = '#FF0000', -- Bright Red Buttons
        colorText = '#FFFFFF'
    },
    borders = {'bottom', 'top'},
    labels = { confirm = 'PERMANENTLY DELETE', cancel = 'Cancel' }
})

if confirmation == 'confirm' then
    -- Delete logic here
end
```

#### Example 4: Handling Overlaps

Since the function returns immediately if another alert is open, you can handle that edge case.

```lua
local status = exports['ak47_lib']:ShowAlert({ header = 'Test' })

if status == 'cancel' then
    -- Note: This could mean the user clicked cancel OR 
    -- simply that the UI was already open.
    print('Alert closed or could not open.')
end
```


---

# 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.menanak47.com/plugins/ak47_lib/interface/alert.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.