Skip to main content
api.ui.notify(spec) pops a toast in the top-right corner. Pass a table; only title is required. Returns a NotifyHandle you can update or dismiss. Any notifications you push are dismissed automatically when your script unloads.

​
Creation

api.ui.notify(spec: NotifySpec): NotifyHandle
FieldTypeWhat it does
titlestringRequired. Bold heading line.
subtextstring?Smaller line under the title.
iconstring?Image asset name shown on the left (resolved via getAsset).
durationnumber?Seconds before it auto-dismisses. Omit to keep it until you dismiss it yourself.
showProgressboolean?Show a progress bar you drive with Update.
progressnumber?Initial bar fill, 0 to 1 (only meaningful with showProgress).
timerboolean?Self-filling bar: fills 0 → 1 over duration with no manual updates. Implies a progress bar.
Spec type: NotifySpec.

​
Dismiss

handle:Dismiss(): ()
Remove the notification now (fades out).

​
Update

handle:Update(patch: { title: string?, subtext: string?, icon: string?, progress: number? }): ()
Patch fields live. Ignored on timer bars (those animate themselves).

​
GetId

handle:GetId(): string
The internal notification id.

​
NotifyHandle

handle:Dismiss()           -- remove it now
handle:Update(patch)       -- patch title / subtext / icon / progress
handle:GetId()             -- internal id
Handle type: NotifyHandle.

​
Examples

-- Simple toast that fades after 4s
api.ui.notify({ title = "Saved", subtext = "Config written", icon = "check", duration = 4 })

-- Self-filling 10s timer bar
api.ui.notify({ title = "Cooldown", duration = 10, timer = true })

-- Manual progress you drive yourself
local n = api.ui.notify({ title = "Downloading", showProgress = true, progress = 0 })
n:Update({ progress = 0.5 })
n:Update({ subtext = "Almost done", progress = 0.9 })
n:Dismiss()