# esx_notify (/docs/core/esx_notify)

esx_notify is the default notification UI of ESX Legacy. It draws small toast
notifications with a type (success, error, info, warning), an optional title
and a configurable screen position. You rarely call it directly:
`ESX.ShowNotification` on the client and `xPlayer.showNotification` on the
server both end up in this resource.

## Overview [#overview]

| | |
| --- | --- |
| Resource | `esx_notify` |
| Side | Client only (server code uses events or `xPlayer`) |
| Dependencies | `es_extended` (loads `@es_extended/imports.lua`) |
| UI | NUI page (`nui/index.html`), jQuery, Material Symbols icons |
| Required | Yes, `ESX.ShowNotification` errors when it is missing |

## Configuration [#configuration]

`Config.lua` has two keys.

| Key | Default | Description |
| --- | --- | --- |
| `Config.notificationSoundEnabled` | `true` | Plays a short generated tone per notification. The pitch depends on the type. |
| `Config.position` | `"middle-right"` | Default position when a call passes no valid position. |

Valid positions: `top-right`, `top-left`, `top-middle`, `bottom-right`,
`bottom-left`, `bottom-middle`, `middle-left`, `middle-right`. Any other value
falls back to `Config.position`.

## Notification types [#notification-types]

| Type | Icon |
| --- | --- |
| `success` | check circle |
| `error` | error |
| `info` | info (also used for unknown types) |
| `warning` | warning triangle |

## Functions [#functions]

### ESX.ShowNotification [#esxshownotification]

Client wrapper in es_extended. This is the call you use in almost every script.

```lua
ESX.ShowNotification(message, notifyType, length, title, position)
```

| Name | Type | Description |
| --- | --- | --- |
| `message` | `string` | Text to show. Supports color codes and `~br~`. |
| `notifyType` | `string?` | `success`, `error`, `info` or `warning`. Default `"info"`. |
| `length` | `number?` | Duration in milliseconds. Default `5000`. |
| `title` | `string?` | Bold title above the message. Default `"New Notification"`. |
| `position` | `string?` | One of the positions above. Default `Config.position`. |

```lua title="client/main.lua"
ESX.ShowNotification("You bought a ~g~water bottle~s~.", "success", 3000, "Shop")

ESX.ShowNotification("Inventory full!~br~Some items were dropped.", "warning", 4000, "Inventory", "bottom-left")
```

### xPlayer.showNotification [#xplayershownotification]

Server side, the `xPlayer` object has the same signature. It triggers the
client event `esx:showNotification`, which calls `ESX.ShowNotification`.

```lua title="server/main.lua"
local xPlayer = ESX.GetPlayerFromId(source)
if xPlayer then
    xPlayer.showNotification("Your paycheck has arrived.", "info", 5000, "Bank")
end
```

### Notify export [#notify-export]

The raw export. Note the different argument order: type and length come first.

```lua
exports["esx_notify"]:Notify(notifyType, length, message, title, position)
```

| Name | Type | Description |
| --- | --- | --- |
| `notifyType` | `string` | Notification type. Non-string values become `"info"`. |
| `length` | `number` | Duration in ms. Invalid values (negative, `NaN`, infinite, non-number) become `3000`. |
| `message` | `any` | Converted with `tostring`. `~br~` becomes a line break. |
| `title` | `string?` | Optional title. |
| `position` | `string?` | Optional position. |

```lua title="client/main.lua"
exports["esx_notify"]:Notify("error", 4000, "You don't have enough money!", "Transaction failed")
```

## Events [#events]

| Event | Side | Arguments |
| --- | --- | --- |
| `esx:showNotification` | Client (net, registered by es_extended) | `message, type, length, title, position` |
| `ESX:Notify` | Client (net, registered by esx_notify) | `type, length, message, title, position` |

Trigger them from the server when you have no `xPlayer` at hand:

```lua title="server/main.lua"
TriggerClientEvent("esx:showNotification", playerId, "Server restart in 5 minutes", "warning", 10000, "Server")
```

## Formatting [#formatting]

The NUI escapes HTML, so you cannot inject markup. Two formatting helpers exist:

- `~br~` (or a literal `<br>`) inserts a line break.
- Color codes: `~r~` red, `~b~` blue, `~g~` green, `~y~` yellow, `~p~` purple,
  `~c~` grey, `~m~` dark grey, `~u~` black, `~o~` orange.

<Callout type="warn" title="~s~ does not reset the color">
In 1.16.4 the NUI script removes every `~s~` before it applies colors. A color
code therefore colors the rest of the message, not just the next word. Put the
colored part at the end of the message, or split the information into title and
message.
</Callout>

## Debug commands [#debug-commands]

When `Config.EnableDebug` is `true` in es_extended, esx_notify registers test
commands: `/oldnotify`, `/notify`, `/notify1`, `/notify2`, `/notify3` and
`/notify4`. They are not available on a normal server.

## Common issues [#common-issues]

- **Nothing shows up.** Check that `esx_notify` is started after `es_extended`
  and that no other resource overrides `ESX.ShowNotification`.
- **Wrong text in the title or a number as the message.** You passed the
  `ESX.ShowNotification` argument order to the export, or the other way around.
- **Replacing esx_notify with another UI.** Keep a resource named `esx_notify`
  or edit `es_extended/client/modules/ui/notifications.lua`; es_extended only
  checks for this resource name.

## Related [#related]

- [Core resources overview](/docs/core)
- [Client functions](/docs/es_extended/client/functions)
- [xPlayer](/docs/es_extended/server/xplayer)
- [esx_textui](/docs/core/esx_textui)
- [esx_progressbar](/docs/core/esx_progressbar)