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

# UI Library

> One-line, zero-dependency UI calls — notify, progress, menus, dialogs, skill checks, radial, target — rendered on the bridge's own themed NUI.

The `Bridge` global ships a complete UI library. Every component is a **single line of Lua** — `Bridge.Notify(...)`, `Bridge.Progress(...)`, `Bridge.Menu.Open(...)` — that renders on the bridge's own NUI. No frontend to build, no extra resource to install, no markup to write.

```lua theme={null}
Bridge.Notify.Success('Garage', 'Vehicle stored.')
local ok = Bridge.Progress({ label = 'Reeling in…', duration = 4000, canCancel = true })
if Bridge.Confirm.Open({ title = 'Sell vehicle?', intent = 'danger' }) then sell() end
```

<Note>
  The bridge's own NUI is the **default** renderer. `ox_lib` is opt-in — set `atlas:ui "ox"` (and start ox\_lib) to swap every call site over to it. You write the same Lua either way.
</Note>

## Themed by the accent

Every component reads the live server accent color (`atlas:theme:color`) automatically — toggles, progress fills, confirm badges, the radial wheel, and skill-check zones all tint to match. When an admin changes the accent, the UI follows without a restart. You never pass a color.

## Provider selection

UI resolves to a provider **per call**, so a renderer that starts late is still picked up. The default is the bridge's own NUI.

```cfg theme={null}
# server.cfg — all optional
setr atlas:ui "auto"   # auto | own | ox | framework | custom
```

| Value             | Renderer                                                                                           |
| ----------------- | -------------------------------------------------------------------------------------------------- |
| `own` *(default)* | The bridge's own NUI — zero dependencies.                                                          |
| `ox`              | `ox_lib` (must be started).                                                                        |
| `framework`       | The framework's native notify (notifications only; everything else falls back to `own`).           |
| `auto`            | Detects in order: `ox_lib` started → `ox`; a non-default framework → `framework`; otherwise `own`. |
| `custom`          | Your own renderer — fill the stubs in `editable/ui.lua`.                                           |

<Warning>
  Anything a chosen provider does not implement falls back to the bridge's own NUI automatically, so a call never silently does nothing. `Radial` and `Interact` are **always** the bridge's own NUI regardless of provider.
</Warning>

### Per-subsystem overrides

Pin a single component to a different renderer without changing the rest. Each is a provider id; blank inherits `atlas:ui`.

```cfg theme={null}
setr atlas:ui:notify     "own"
setr atlas:ui:progress   "ox"
setr atlas:ui:menu       ""
setr atlas:ui:textui     ""
setr atlas:ui:context    ""
setr atlas:ui:input      ""
setr atlas:ui:skillcheck ""
setr atlas:ui:confirm    ""
```

<Note>
  `Bridge.Target` reads its own convar, `atlas:target` (`auto | ox | qb | own | custom`) — not `atlas:ui:target`. See [Target](/atlas-bridge/ui/target).
</Note>

## Components

<CardGroup cols={2}>
  <Card title="Notifications" icon="https://mintcdn.com/atlasscripts/BwePy2Q7bMLnl0yQ/icons/box-filled.svg?fit=max&auto=format&n=BwePy2Q7bMLnl0yQ&q=85&s=c228a3b89453b292c0cedb29c252b3ab" href="/atlas-bridge/ui/notifications" width="24" height="24" data-path="icons/box-filled.svg">
    Toast feedback. The only UI callable from the **server** (targeted at a player).
  </Card>

  <Card title="Progress" icon="https://mintcdn.com/atlasscripts/BwePy2Q7bMLnl0yQ/icons/box-filled.svg?fit=max&auto=format&n=BwePy2Q7bMLnl0yQ&q=85&s=c228a3b89453b292c0cedb29c252b3ab" href="/atlas-bridge/ui/progress" width="24" height="24" data-path="icons/box-filled.svg">
    Blocking progress bar with optional prop + animation. Returns completed/cancelled.
  </Card>

  <Card title="Text UI" icon="https://mintcdn.com/atlasscripts/BwePy2Q7bMLnl0yQ/icons/box-filled.svg?fit=max&auto=format&n=BwePy2Q7bMLnl0yQ&q=85&s=c228a3b89453b292c0cedb29c252b3ab" href="/atlas-bridge/ui/text-ui" width="24" height="24" data-path="icons/box-filled.svg">
    A persistent help label (`[E] Open shop`). Show and hide.
  </Card>

  <Card title="Menus" icon="https://mintcdn.com/atlasscripts/BwePy2Q7bMLnl0yQ/icons/box-filled.svg?fit=max&auto=format&n=BwePy2Q7bMLnl0yQ&q=85&s=c228a3b89453b292c0cedb29c252b3ab" href="/atlas-bridge/ui/menus" width="24" height="24" data-path="icons/box-filled.svg">
    `Menu` (toggles/steppers, stays open) and `Context` (a simple action list).
  </Card>

  <Card title="Input & Confirm" icon="https://mintcdn.com/atlasscripts/BwePy2Q7bMLnl0yQ/icons/box-filled.svg?fit=max&auto=format&n=BwePy2Q7bMLnl0yQ&q=85&s=c228a3b89453b292c0cedb29c252b3ab" href="/atlas-bridge/ui/input" width="24" height="24" data-path="icons/box-filled.svg">
    Blocking forms (`Input`) and yes/no dialogs (`Confirm`).
  </Card>

  <Card title="Skill Check" icon="https://mintcdn.com/atlasscripts/BwePy2Q7bMLnl0yQ/icons/box-filled.svg?fit=max&auto=format&n=BwePy2Q7bMLnl0yQ&q=85&s=c228a3b89453b292c0cedb29c252b3ab" href="/atlas-bridge/ui/skill-check" width="24" height="24" data-path="icons/box-filled.svg">
    Blocking timing minigame — circle, bar, or key sequence.
  </Card>

  <Card title="Radial" icon="https://mintcdn.com/atlasscripts/BwePy2Q7bMLnl0yQ/icons/box-filled.svg?fit=max&auto=format&n=BwePy2Q7bMLnl0yQ&q=85&s=c228a3b89453b292c0cedb29c252b3ab" href="/atlas-bridge/ui/radial" width="24" height="24" data-path="icons/box-filled.svg">
    A radial action wheel with optional submenus.
  </Card>

  <Card title="Target" icon="https://mintcdn.com/atlasscripts/BwePy2Q7bMLnl0yQ/icons/box-filled.svg?fit=max&auto=format&n=BwePy2Q7bMLnl0yQ&q=85&s=c228a3b89453b292c0cedb29c252b3ab" href="/atlas-bridge/ui/target" width="24" height="24" data-path="icons/box-filled.svg">
    Entity/zone targeting — `ox_target` → `qb-target` → own.
  </Card>
</CardGroup>

## Server vs client availability

Almost all UI is **client-only** — it renders on a player's screen, so it lives in your client VM. The one exception is `Notify`, which you can call from the server to push a toast to a specific player.

| Component          | Client |                Server               |
| ------------------ | :----: | :---------------------------------: |
| `Notify`           |    ✓   | ✓ *(first arg is the player `src`)* |
| `Progress`         |    ✓   |                  —                  |
| `TextUI`           |    ✓   |                  —                  |
| `Menu` / `Context` |    ✓   |                  —                  |
| `Input`            |    ✓   |                  —                  |
| `Confirm`          |    ✓   |                  —                  |
| `SkillCheck`       |    ✓   |                  —                  |
| `Radial`           |    ✓   |                  —                  |
| `Interact`         |    ✓   |                  —                  |
| `Target`           |    ✓   |                  —                  |

<Warning>
  The blocking components — `Progress`, `Input`, `Confirm`, `SkillCheck` — yield until the player finishes. Always call them inside a `CreateThread`, command, or event callback, never at file top level.
</Warning>