# Alert

<figure><img src="https://2088945756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkHcyR2RbVMcj5NHJ2HEa%2Fuploads%2F8dvTahRAj6InIkL5Yez8%2F3zUgw2p0ma.png?alt=media&#x26;token=2f2b9467-b02d-49a1-969f-535f3b575af1" 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
```