> ## Documentation Index
> Fetch the complete documentation index at: https://bunnynet-cb9733c2-support-migration.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Smart Preloader
> Show a branded loading screen when your origin takes longer than expected to respond.
Smart Preloader monitors dynamic HTML requests and displays a customizable loading screen when your origin is slow to respond. Instead of leaving users staring at a blank page, they see your branding with a loading animation while the request completes in the background.
Smart Preloader is part of the [Bunny Optimizer](/optimizer) suite and
requires a DNS-accelerated Pull Zone.
## How it works
1. A user requests a page from your site
2. Bunny forwards the request to your origin immediately
3. If your origin responds within the trigger delay, the response is returned normally (no preloader shown)
4. If your origin exceeds the trigger delay, Bunny returns the preloader screen while keeping the original request alive
5. The preloader automatically reconnects to the original request and displays your content when ready
This approach adds near-zero overhead—the preloader only appears when your origin is already slow.
## Trigger conditions
The Smart Preloader only activates when all of these conditions are met:
The request must be for dynamic HTML content. Static assets (images, CSS,
JS) don't trigger the preloader.
Your origin must take longer than the configured trigger delay to respond.
The request must come from a browser expecting an HTML response.
## Configuration
### Trigger delay
Set the time threshold for when the preloader should appear. If your site typically responds in 700ms, set the trigger delay to 700ms—users only see the preloader when something is slower than usual.
### Custom HTML
You can replace the default preloader with your own HTML. Include the `{{preloader_script}}` tag in your HTML body to ensure the reconnection script is injected:
```html theme={null}
Loading...
Please wait...
{{preloader_script}}
```
Your custom HTML must not contain JavaScript or HTML errors that could prevent
the injected reconnection script from executing. If the script fails, the
request won't reconnect to your origin response.
## Technical details
The preloader returns HTTP status `529` to signal browsers not to cache the
temporary response.
Bunny may set cookies on preloader responses to reconnect users to their
original request. These are never used for tracking.
If your origin doesn't respond at all, users receive a standard `502` or
`504` error—not the preloader indefinitely.
Works alongside Perma-Cache, SafeHop, and Origin Shield with no conflicts.
## Performance impact
Smart Preloader is designed to add minimal overhead:
* When origin responds in time: **Zero overhead** (preloader never shown)
* When origin is slow: **\~150ms** additional load time in worst-case scenarios, primarily from the reconnection script
With Bunny's average global edge latency under 26ms, the reconnection process
is nearly instantaneous for most users.