> ## 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.

# Theming

> One accent color drives every bridge UI. Set the server default with a convar, or let a player pick their own — the bridge persists it and live-pushes it to every UI.

`atlasBridge` has a single accent color that every bridge UI follows automatically — notifications, progress bars, menus, confirm dialogs, the radial wheel, skill-check zones, markers, and the world-anchored interaction prompts. You never pass a color to a component. They read the accent and tint themselves.

There are two layers:

1. **A server default** — the `atlas:theme:color` convar, applied to everyone.
2. **An optional per-player override** — a player can pick their own accent at runtime; the bridge persists it on their client and recolors all of their UIs instantly.

## The server default

Set the global accent with one convar. The default is `#F487F4`.

```cfg theme={null}
# server.cfg
setr atlas:theme:color "#F487F4"   # any valid hex
```

Internally, the accent is published to the NUI as the `--atlas-theme-color` CSS variable, and the lib's drawing helpers (`Bridge.Draw.Marker`, `Bridge.Draw.Outline`) default to it. Changing the convar and restarting the bridge recolors every UI — no per-component wiring.

<Note>
  This server color is what `Bridge.Theme.Get()` and `Bridge.Theme.Rgba(alpha)` return on the **server**, where there is no per-player HUD. Per-player theming is a client concern (below).
</Note>

## Per-player theming

Each player can have their own accent. The picker UI is **yours to build** — the bridge gives you the storage, validation, persistence, and live push. You call one export; the bridge handles the rest.

### The flow

<Steps>
  <Step title="Your script calls the export">
    A color-changer (a settings menu, an F-key picker, whatever you build) calls `exports.atlasBridge:SetTheme(hex)` — or, with the `Bridge` global loaded, `Bridge.Theme.Set(hex)`.
  </Step>

  <Step title="The bridge validates the hex">
    Invalid hex is rejected and the call returns `false`. A valid hex is accepted.
  </Step>

  <Step title="The bridge persists it to that client's KVP">
    The color is written to the player's local resource KVP, so it **survives a reconnect** on that machine. (This is on-client persistence, not a database — a different PC starts from the server default.)
  </Step>

  <Step title="The bridge fires atlasBridge:themeChanged">
    Every consumer that subscribed via `Bridge.Theme.OnChange` is notified with the new hex.
  </Step>

  <Step title="Every NUI recolors instantly">
    The new accent is pushed to all of the player's open UIs through the `--atlas-theme-color` variable, so they re-tint without a reload.
  </Step>
</Steps>

### Client API

<Tabs>
  <Tab title="Exports">
    ```lua theme={null}
    -- client
    local ok = exports.atlasBridge:SetTheme('#4f8ef7')   -- true if the hex was valid
    local hex = exports.atlasBridge:GetTheme()            -- the player's current accent
    exports.atlasBridge:ResetTheme()                      -- clear the override, back to the server default
    ```
  </Tab>

  <Tab title="Bridge facade">
    ```lua theme={null}
    -- client
    Bridge.Theme.Set('#4f8ef7')   -- validate + persist + push
    local hex = Bridge.Theme.Get() -- cached, frame-safe (safe to read in Draw loops)
    Bridge.Theme.Reset()           -- back to the server default
    Bridge.Theme.OnChange(function(hex)
        -- react to a color change (yours, or a Reset)
    end)
    ```
  </Tab>
</Tabs>

<ParamField path="Bridge.Theme.Set(hex)" type="string → boolean">
  Validate, persist to KVP, and live-push a new accent. Returns `false` if `hex` is not a valid color.
</ParamField>

<ParamField path="Bridge.Theme.Get()" type="→ string">
  The player's current accent hex. Cached, so it is safe to call every frame (e.g. inside a `Bridge.Draw` loop).
</ParamField>

<ParamField path="Bridge.Theme.Reset()" type="→ boolean">
  Clear the player's override and fall back to the server default (`atlas:theme:color`).
</ParamField>

<ParamField path="Bridge.Theme.OnChange(cb)" type="fun(hex: string)">
  Register a callback fired whenever the accent changes.
</ParamField>

### Worked example — a minimal picker

A picker only has to collect a hex and hand it to the bridge. Here it uses the bridge's own input dialog, but any UI works — the only line that matters is the `Bridge.Theme.Set` call.

```lua theme={null}
-- client
RegisterCommand('themepicker', function()
    local values = Bridge.Input.Open({
        title = 'Pick your accent',
        fields = {
            { type = 'text', label = 'Hex color', placeholder = '#4f8ef7', required = true },
        },
    })
    if not values then return end          -- cancelled

    local hex = values[1]
    if Bridge.Theme.Set(hex) then          -- bridge validates + persists + pushes
        Bridge.Notify.Success('Theme', 'Accent updated.')
    else
        Bridge.Notify.Error('Theme', 'That is not a valid hex color.')
    end
end, false)

RegisterCommand('themereset', function()
    Bridge.Theme.Reset()
    Bridge.Notify('Theme reset to the server default.')
end, false)
```

That is the whole integration. You build the UI; the bridge owns the color.

## Server-side reads

The server has no per-player HUD, so the server facade always returns the configured default — useful for any server-side color need (a Discord embed color, a blip tint computed server-side):

```lua theme={null}
-- server
local hex = Bridge.Theme.Get()           -- = atlas:theme:color
local r, g, b, a = Bridge.Theme.Rgba()   -- alpha defaults to the configured HUD alpha
```

<Tip>
  `Bridge.Color.ToRgba(hex)` returns `r, g, b` (no alpha). Use `Bridge.Theme.Rgba(a)` when you need an alpha channel.
</Tip>

## Related

<CardGroup cols={2}>
  <Card title="UI Library" icon="https://mintcdn.com/atlasscripts/BwePy2Q7bMLnl0yQ/icons/box-filled.svg?fit=max&auto=format&n=BwePy2Q7bMLnl0yQ&q=85&s=c228a3b89453b292c0cedb29c252b3ab" href="/atlas-bridge/ui/overview" width="24" height="24" data-path="icons/box-filled.svg">
    Every UI component follows the accent automatically.
  </Card>

  <Card title="Configuration" icon="https://mintcdn.com/atlasscripts/BwePy2Q7bMLnl0yQ/icons/wrench-filled.svg?fit=max&auto=format&n=BwePy2Q7bMLnl0yQ&q=85&s=2f07ced69c9d944e41df19ed19c921f6" href="/atlas-bridge/convars" width="24" height="24" data-path="icons/wrench-filled.svg">
    The `atlas:theme:color` convar and the rest of the bridge config.
  </Card>
</CardGroup>