> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shdevelopment.org/llms.txt
> Use this file to discover all available pages before exploring further.

# sh-notify: In-Game Toast Notifications for FiveM

> sh-notify provides stacked, auto-dismissing toast notifications in three styles. Call it from any script via a single Lua export.

sh-notify renders clean, stacked toast notifications in the top-right corner of the screen, giving players immediate visual feedback for in-game events. Each notification plays a short UI sound on appearance, displays for a configurable duration, and then auto-dismisses without any additional code on your end. Because the resource exposes a single Lua export, you can trigger notifications from any client-side script on your server — including your own custom resources and other SH Development scripts that support it.

## Installation

<Steps>
  <Step title="Add the resource to your server">
    Place the `sh-notify` folder inside your server's `resources` directory.

    ```
    resources/
    └── sh-notify/
        ├── fxmanifest.lua
        ├── client/
        └── html/
    ```
  </Step>

  <Step title="Start sh-notify before dependent scripts">
    Open `server.cfg` and ensure `sh-notify` is listed **before** any resource that calls its export. FiveM resolves exports at runtime, but starting it first avoids race conditions on server boot.

    ```cfg server.cfg theme={null}
    ensure sh-notify
    # ... your other resources below
    ensure my-other-script
    ```
  </Step>
</Steps>

<Note>
  Many SH Development scripts use sh-notify as their default notification handler. Set `Config.Notify = 'sh'` inside those scripts' config files to route their alerts through sh-notify automatically.
</Note>

## Export Reference

Trigger a notification from any client-side Lua script using the `shnotif` export:

```lua theme={null}
exports['sh-notify']:shnotif(icon, title, text, type, length)
```

### Parameters

<ParamField path="icon" type="string" required>
  A Font Awesome 5 class string that determines the icon displayed on the left side of the notification. Use the full class string as it appears in Font Awesome's documentation.

  Example: `'fas fa-check-circle'`
</ParamField>

<ParamField path="title" type="string" required>
  The bold heading displayed above the horizontal divider inside the notification card.

  Example: `'Vehicle Spawned'`
</ParamField>

<ParamField path="text" type="string" required>
  The body text displayed below the divider. Use this to provide detail or context for the notification.

  Example: `'Your vehicle has been delivered to the garage.'`
</ParamField>

<ParamField path="type" type="string" required>
  Controls the color theme of the notification card. Must be one of the three values below.

  | Value     | Appearance                        |
  | --------- | --------------------------------- |
  | `success` | Semi-transparent green background |
  | `primary` | Semi-transparent blue background  |
  | `error`   | Semi-transparent red background   |
</ParamField>

<ParamField path="length" type="number" required>
  How long the notification stays on screen, in **milliseconds**. After this duration the card fades out and is removed from the stack automatically.

  Example: `5000` (5 seconds)
</ParamField>

## Usage Examples

The following examples demonstrate all three notification types. Copy the relevant line into your client-side script and adjust the text to suit your use case.

<Tabs>
  <Tab title="Success">
    Use `success` to confirm that an action completed without errors.

    ```lua theme={null}
    exports['sh-notify']:shnotif('fas fa-check-circle', 'Success', 'Vehicle spawned', 'success', 5000)
    ```
  </Tab>

  <Tab title="Primary (Info)">
    Use `primary` for neutral status updates or informational messages.

    ```lua theme={null}
    exports['sh-notify']:shnotif('fas fa-info-circle', 'Info', 'Loading zone...', 'primary', 5000)
    ```
  </Tab>

  <Tab title="Error">
    Use `error` to inform players of failures, denied actions, or warnings.

    ```lua theme={null}
    exports['sh-notify']:shnotif('fas fa-times-circle', 'Error', 'No permission', 'error', 5000)
    ```
  </Tab>
</Tabs>

## Notification Stacking

When multiple notifications are triggered in quick succession, sh-notify stacks them vertically in the top-right corner of the screen. Each card is independent — it starts its own dismiss timer when it appears, so earlier notifications expire first regardless of how many are queued behind them.

<Tip>
  Browse the full Font Awesome 5 free icon library at [fontawesome.com/icons](https://fontawesome.com/icons) to find icon class strings. Only the **free** tier icons are available in NUI without additional setup.
</Tip>