Notification

Advanced Notification System for RedM

Introduction

cas-notification is a modern NUI-based notification system for RedM. It uses a React + TypeScript frontend and a lightweight Lua client to display stylish, animated notifications with:

• Success, error and info styles

• Optional sound effects

• Progress bar support

• Sticky (no-timeout) notifications

• Click-to-dismiss behavior

• Alignment and position options

It is framework-agnostic and can be used with any framework or no framework at all.

---

Features

• Clean, RDR2-styled notification design (success, error, info skins)

• Configurable alignment (left or right side of the screen)

• Top or bottom stacking position

• Per-notification options:

  • Custom title and message

  • Type: success, error, info

  • Custom timeout duration

  • Sticky (no auto-dismiss)

  • Progress bar display

  • Click-to-dismiss toggle

  • Sound enable/disable

  • Custom sound volume

  • Meta data (arbitrary Lua table)

• Default timeouts per type:

  • success: 4000–5000 ms

  • error: 6000–7000 ms

  • info: 5000–6000 ms

• Concurrency limiting: keeps up to 4 notifications on screen at once

• Built-in client event for triggering notifications from other resources

• Export-based API

• Test command that demonstrates multiple notification configurations

---

Requirements

• Any framework (or none)

---

Installation

1. Place the resource in your server’s resources folder as:

   cas-notification

2. Add it to your server.cfg:

   ensure cas-notification

There is no server-side Lua logic for this resource; everything is client-side and NUI.

---

Configuration

Configuration is entirely client-side in the config folder.

Client Config

File: config/client_config.lua

Config = {
    align = "left",
    testCommand = "Notifications",
    enableTestCommand = true,
}

• align Default horizontal alignment for notifications. Accepts "left" or "right". Each notification can override this per payload.

• testCommand The name of the test command registered if enableTestCommand is true. Default: /Notifications

• enableTestCommand When true, registers the test command that showcases several sample notifications.

The React frontend also reads config.position if present, but by default only align is defined in this config. You can safely extend the Config table if needed; it is passed to NUI through cas_notify:getLocaleAndConfig.

Icons

Icons are taken from the react-icons Font Awesome 6 set. Browse icons on the React Icons website and use their exact component names (e.g. FaSmoking, FaHammer) as the icon value.

https://react-icons.github.io/react-icons/icons/fa6/

---

Locale

File: config/locale.lua

Locale = "en"

Locales = {
    ["en"] = {
        ["success"] = "Success",
        ["error"] = "Error",
        ["info"] = "Info",
    },
    ["fr"] = {
        ["success"] = "Succès",
        ["error"] = "Erreur",
        ["info"] = "Info",
    }
}

function _L(key)
    if Locales[Locale] == nil then
        return "Locale not found"
    end

    if Locales[Locale][key] == nil then
        return "Key not found"
    end

    return Locales[Locale][key]
end

• Locale Current active language: "en", "fr", etc.

• Locales[...] Strings for notification type labels.

You can add new languages by extending Locales and changing Locale.

---

Notification Payload Structure

On the frontend side, the notification interface looks like:

interface NuiNotificationPayload {
  id?: number
  message: string
  type?: "success" | "error" | "info"
  timeout?: number
  title?: string
  icon?: string
  sticky?: boolean
  playSound?: boolean
  soundVolume?: number
  progressBar?: boolean
  allowClickDismiss?: boolean
  align?: "left" | "right"
  position?: "top" | "bottom"
  meta?: any
}

On the Lua side, normalizePayload fills defaults:

• type defaults to "info"

• timeout defaults based on type if not specified

• id is auto-generated if not provided

Important fields:

• message The main text content.

• type "success", "error", or "info".

• title Short title displayed at the top of the notification.

• timeout Duration in milliseconds before auto-dismiss. If not set, defaults are:

  • success: 4000–5000 ms

  • error: 6000–7000 ms

  • info: 5000–6000 ms

• sticky true makes the notification not auto-dismiss (or treats timeout <= 0 as sticky).

• playSound If false, no sound is played. Default is sound on.

• soundVolume Float between 0 and 1. Default is 0.1.

• progressBar If false, hides the small progress bar at the bottom. Default is enabled.

• allowClickDismiss If false, disables dismissing the notification by clicking on it. Default is enabled.

• align "left" or "right". If not present, falls back to Config.align.

• position "top" or "bottom". If not present and config.position === "bottom", it uses bottom; otherwise top.

• meta Custom metadata you want to attach (for debugging or tooling).

---

Lua API

Exports

All API is client-side.

1) addNotification

exports["cas-notification"]:addNotification(message, notifType, duration, opts)

• message (string or table) If a table, it can be the full payload. If a string, notifType, duration, and opts are used to enrich it.

• notifType (string, optional) "success", "error", "info".

• duration (number, optional) Timeout in milliseconds.

• opts (table, optional) Extra notification payload fields (title, sticky, align, position, etc.).

Examples:

exports["cas-notification"]:addNotification("Saved successfully", "success", 3000)

exports["cas-notification"]:addNotification({
    message = "Bank robbery failed",
    type = "error",
    title = "Robbery",
    timeout = 7000,
    sticky = false,
    playSound = true,
    progressBar = true,
    align = "right",
    position = "top"
})

2) successNotification

exports["cas-notification"]:successNotification("Operation successful", 4000)

A shorthand for notifying with type "success".

3) errorNotification

exports["cas-notification"]:errorNotification("Something went wrong", 5000)

A shorthand with type "error".

4) infoNotification

exports["cas-notification"]:infoNotification("Just so you know", 4000)

A shorthand with type "info".

---

Client Event

You can also trigger notifications via event instead of exports:

TriggerEvent("cas-notification:client:addNotification", message, notifType, duration, opts)

Equivalent to calling exports["cas-notification"]:addNotification(...).

Example:

TriggerEvent("cas-notification:client:addNotification", "You have new mail", "info", 5000, {
    title = "Mail",
    playSound = true,
    allowClickDismiss = true
})

---

Test Command

The test command is controlled by Config.enableTestCommand and Config.testCommand.

If enableTestCommand = true, a command is registered:

RegisterCommand(Config.testCommand, function()
    local testQueue = {
        {
            message = "Test notification for success!",
            type = "success",
            timeout = 4000,
            title = "Bank",
            sticky = false,
            playSound = true,
            soundVolume = 0.15,
            progressBar = true,
            allowClickDismiss = true
        },
        {
            message = "Test notification for error!",
            type = "error",
            timeout = 6000,
            title = "Error",
            sticky = false,
            playSound = true,
            progressBar = true,
            allowClickDismiss = true
        },
        {
            message = "Persistent info notification (sticky).",
            type = "info",
            timeout = 2000,
            title = "Info",
            sticky = false,
            playSound = false,
            progressBar = false,
            allowClickDismiss = true,
            meta = { source = "testCommand" }
        }
    }

    Citizen.CreateThread(function()
        for _, payload in ipairs(testQueue) do
            Notifications:Add(payload)
            Citizen.Wait(2500)
        end
    end)
end, false)

So by default, you can run:

/Notifications

and see a sequence of different styled notifications.

You can rename this command by changing Config.testCommand.

---

Usage Examples

Basic success notification

exports["cas-notification"]:successNotification("Payment completed", 4000)

Error notification with title and bottom-right alignment

exports["cas-notification"]:addNotification("You do not have enough money", "error", 5000, {
    title = "Store",
    align = "right",
    position = "bottom",
    playSound = true
})

Info notification without progress bar and click-to-dismiss disabled

exports["cas-notification"]:addNotification("Server restart in 5 minutes", "info", 10000, {
    title = "System",
    progressBar = false,
    allowClickDismiss = false,
    sticky = false
})

Sticky notification (no timeout)

exports["cas-notification"]:addNotification({
    message = "You are in admin mode",
    type = "info",
    title = "Admin",
    timeout = 0,
    sticky = true,
    playSound = false,
    progressBar = false
})

---

Troubleshooting

Notifications not showing

• Make sure the resource is started:

  • ensure cas-notification

• Ensure web/build/index.html and assets exist.

• Check for NUI errors in the F8 console.

• Make sure no other NUI resource is blocking or overriding focus.

Wrong alignment or position

• Check Config.align in client_config.lua.

• Ensure payloads do not override align and position unexpectedly.

Sound not playing

• Confirm your client has sound enabled.

• Make sure playSound is not set to false in payload.

• Check soundVolume is not set to 0.

---

Credits

• Script name: cas-notification

• Author: CAS

• Frontend: React + TypeScript + Framer Motion

• Assets: Custom success, error, info containers and heat textures

• Platforms: RedM