Skip to main content
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 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: 
<!DOCTYPE html>
<html>
  <head>
    <title>Loading...</title>
  </head>
  <body>
    <div class="loader">
      <img src="https://example.com/logo.png" alt="Loading" />
      <p>Please wait...</p>
    </div>
    {{preloader_script}}
  </body>
</html>
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

Status code

The preloader returns HTTP status 529 to signal browsers not to cache the temporary response.

Cookies

Bunny may set cookies on preloader responses to reconnect users to their original request. These are never used for tracking.

Error handling

If your origin doesn’t respond at all, users receive a standard 502 or 504 error—not the preloader indefinitely.

Feature compatibility

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.