# esx_loadingscreen (/docs/core/esx_loadingscreen)

esx_loadingscreen is the loading screen players see while they connect to an
ESX Legacy server. It shows a logo, a progress bar driven by the game's real
load progress and rotating tips. It has no Lua config; you customize it by
editing the files in `web/`.

## Overview [#overview]

| | |
| --- | --- |
| Resource | `esx_loadingscreen` |
| Side | Client (loadscreen NUI) |
| Dependencies | None |
| Config | None, edit `web/script.js`, `web/style.css`, `web/logo.png` |
| Required | No, any loading screen resource works |

The manifest declares `loadscreen "web/index.html"` and
`loadscreen_manual_shutdown "yes"`. Manual shutdown means the game does not
close the loading screen on its own; a script has to call
`ShutdownLoadingScreenNui()`.

## How it works [#how-it-works]

<Steps>
<Step>
### Progress [#progress]

FiveM sends `loadProgress` messages with a `loadFraction` between 0 and 1 to the
page. The bar animates to that value and switches the status text through
"Connecting", "Handshaking", "Downloading resources", "Loading scripts",
"Spawning player" and "Finalizing".
</Step>
<Step>
### Completion [#completion]

When `loadFraction` reaches 1, the page posts the NUI callback
`loadingComplete`. The client script waits 2500 ms (`SHUTDOWN_DELAY`) and calls
`ShutdownLoadingScreenNui()`.
</Step>
<Step>
### Spawn [#spawn]

es_extended (without multicharacter) and esx_multicharacter also call
`ShutdownLoadingScreen()` and `ShutdownLoadingScreenNui()` when the player
spawns or the character selection opens, and fire the client event
`esx:loadingScreenOff`.
</Step>
</Steps>

## Customization [#customization]

| What | Where |
| --- | --- |
| Logo | Replace `web/logo.png` (keep the file name, it is listed in `fxmanifest.lua`) |
| Tips | `tips` array in `web/script.js` (rotates every 6000 ms) |
| Loading texts | `loadingTexts` array in `web/script.js` |
| Status labels | `statuses` array in `web/script.js` |
| Colors, layout | `web/style.css` |
| Font | Poppins from Google Fonts, linked in `web/index.html` |

```js title="web/script.js"
const tips = [
    "Read the rules at discord.gg/yourserver",
    "Press F1 to open the help menu",
    "Use /report to contact staff",
]
```

<Callout type="info">
The default tips mention features such as F1 menus and `/report` that ESX does
not ship. Replace them with tips that are true on your server.
</Callout>

If you add new files (a background video, extra images), add them to the
`files` list in `fxmanifest.lua`, otherwise the client never downloads them.

## Events [#events]

| Event | Side | Description |
| --- | --- | --- |
| `esx:loadingScreenOff` | Client (local, fired by es_extended / esx_multicharacter) | The loading screen was shut down. Use it to show your HUD. |

```lua title="client/main.lua"
AddEventHandler("esx:loadingScreenOff", function()
    -- show your HUD here
end)
```

## Common issues [#common-issues]

- **Two loading screens fight each other.** Only start one resource with a
  `loadscreen` entry.
- **Changes do not show up.** Loading screen files are cached by the client.
  Restart the server and clear the FiveM cache (`%localappdata%/FiveM/FiveM.app/data/cache`)
  to test.
- **Black screen after loading.** The loading screen closed but the player did
  not spawn. Check es_extended and esx_multicharacter errors in the F8 console.

## Related [#related]

- [Core resources overview](/docs/core)
- [esx_multicharacter](/docs/core/esx_multicharacter)
- [Client events](/docs/es_extended/events/client)
- [Troubleshooting](/docs/getting-started/troubleshooting)