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

# Notify

> Toast notifications and pill toasts you pop from a script.

`api.ui.notify(spec)` pops a toast in the top-right corner. Pass a table; only `title` is required. Returns a [NotifyHandle](#notifyhandle) you can update or dismiss.

Any notifications you push are dismissed automatically when your script unloads.

## Creation

```luau theme={null}
api.ui.notify(spec: NotifySpec): NotifyHandle
```

| Field          | Type       | What it does                                                                                      |
| -------------- | ---------- | ------------------------------------------------------------------------------------------------- |
| `title`        | `string`   | **Required.** Bold heading line.                                                                  |
| `subtext`      | `string?`  | Smaller line under the title.                                                                     |
| `icon`         | `string?`  | Image asset name shown on the left (resolved via [getAsset](/utility/get-asset)).                 |
| `duration`     | `number?`  | Seconds before it auto-dismisses. Omit to keep it until you dismiss it yourself.                  |
| `showProgress` | `boolean?` | Show a progress bar you drive with `Update`.                                                      |
| `progress`     | `number?`  | Initial bar fill, `0` to `1` (only meaningful with `showProgress`).                               |
| `timer`        | `boolean?` | Self-filling bar: fills `0` → `1` over `duration` with no manual updates. Implies a progress bar. |

Spec type: [NotifySpec](/reference/types#notifyspec).

***

## Dismiss

```luau theme={null}
handle:Dismiss(): ()
```

Remove the notification now (fades out).

***

## Update

```luau theme={null}
handle:Update(patch: { title: string?, subtext: string?, icon: string?, progress: number? }): ()
```

Patch fields live. Ignored on `timer` bars (those animate themselves).

***

## GetId

```luau theme={null}
handle:GetId(): string
```

The internal notification id.

## NotifyHandle

```luau theme={null}
handle:Dismiss()           -- remove it now
handle:Update(patch)       -- patch title / subtext / icon / progress
handle:GetId()             -- internal id
```

Handle type: [NotifyHandle](/reference/types#notifyhandle).

## Examples

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

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

```luau theme={null}
-- 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()
```

***

## Pill toasts

```luau theme={null}
api.ui.toast(spec: ToastSpec | string): ToastHandle
```

`api.ui.toast(spec)` pushes a compact one-line pill into the same feed the hit logs use. Pass a table, or just a string as shorthand for `{ text = ... }`.

| Field      | Type      | What it does                                                                    |
| ---------- | --------- | ------------------------------------------------------------------------------- |
| `text`     | `string`  | **Required.** The pill's text.                                                  |
| `accent`   | `Color3?` | Accent color of the pill. Theme color when omitted.                             |
| `duration` | `number?` | Seconds before it fades. Default `4`. Pass `0` to keep it until you dismiss it. |

Returns a handle with `Dismiss()` and `GetId()`. Your toasts are dismissed automatically when your script unloads.

```luau theme={null}
api.ui.toast("Round started")
local pill = api.ui.toast({ text = "Tracking...", accent = Color3.fromRGB(70, 220, 176), duration = 0 })
pill:Dismiss()
```