Headless WordPress-NextJS Preloader

A WordPress plugin that provides admin-configurable preloader settings for headless WordPress + Next.js websites. Control preloader type, logo, colors, and animations directly from your WordPress admin dashboard.

Author: High6-Gio
Website: https://high6.com/
Version: 2.1.0

What's New in v2.1.0

• ✅ Fixed: Settings Now Apply Immediately - Switched from 1-hour cache to cache: 'no-store' so WordPress admin changes appear on the next page load (no more stale defaults)
• ✅ localStorage Caching - Returning visitors instantly see the configured preloader (no flash of fallback)
• ✅ Smart Progress Bar - Creeps to 90% while page loads, then accelerates to 100% only when window.load fires (no more "completed" bar before page is ready)
• ✅ Logo Preloading - Logo image is preloaded via new Image() with fetchPriority="high" so it appears immediately
• ✅ Hydration-Safe - Deterministic initial state to prevent React hydration mismatches
• ✅ Cleaner First-Visit UX - Shows opaque background only (no fallback spinner) before settings load, eliminating the "double spinner" flash
• ✅ Children Rendered Underneath - Page is now revealed naturally by the exit animation instead of being hidden with opacity-0

What's New in v2.0.0

• ✅ Integration Guide Tab - Complete step-by-step instructions with copy-paste code
• ✅ Fixed Toggle Switch - Proper styling without checkbox display issue
• ✅ Better UI/UX - Improved admin interface with clear visual hierarchy
• ✅ Copy-to-Clipboard - One-click copying for all code snippets
• ✅ Auto-generated API URL - Environment variable code automatically includes your WordPress URL

Features

• Toggle Enable/Disable - Easily turn the preloader on or off
• Preloader Types - Choose between Spinner or Progress Bar
• Custom Background Color - Set any background color using hex code
• Logo Upload - Display your brand logo in the preloader
• 9 Exit Animations - Choose how the preloader transitions away:
  • Fade Out
  • Slide Up
  • Slide Down
  • Scale Down
  • Curtain Split (Horizontal)
  • Curtain Split (Vertical)
  • Diagonal Wipe
  • Circle Reveal
  • Dissolve / Pixelate

Installation

1. Download the headless-wp-nextjs-preloader folder
2. Upload to your WordPress site's wp-content/plugins/ directory
3. Activate the plugin through the 'Plugins' menu in WordPress
4. Navigate to Preloader in the WordPress admin menu

Alternative: Install from GitHub

cd wp-content/plugins/
git clone https://github.com/High6-Gio/headless-wp-nextjs-preloader.git

Configuration

Accessing Settings

After activation, you'll find a new menu item called "Preloader" in your WordPress admin sidebar (with a visibility icon).

Settings Overview

1. Enable Preloader - Toggle switch to enable/disable the preloader
2. Preloader Type - Choose between:
   • Spinner - Rotating circle animation
   • Progress Bar - Loading bar with percentage
3. Background Color - Hex color picker for the preloader background
4. Logo Image - Upload a logo to display (optional)
5. Exit Animation - Dropdown to select the exit animation style

REST API

The plugin exposes a public REST API endpoint that the Next.js frontend uses to fetch preloader settings:

GET /wp-json/headless-wp-preloader/v1/preloader-settings

Response Example

{
  "enabled": 1,
  "type": "spinner",
  "background_color": "#ffffff",
  "logo": 123,
  "logo_url": "https://example.com/wp-content/uploads/logo.png",
  "exit_animation": "fade-out"
}

API Fields

• enabled (integer) - 1 for enabled, 0 for disabled
• type (string) - "spinner" or "progress"
• background_color (string) - Hex color code
• logo (integer) - WordPress attachment ID
• logo_url (string) - Full URL to the logo image
• exit_animation (string) - Animation identifier

Frontend Integration

The Next.js frontend automatically fetches settings from this API and renders the preloader accordingly. The integration is already set up in:

• app/components/shared/Preloader.tsx - Main preloader component
• app/layout.tsx - Preloader wraps all page content
• app/globals.css - Exit animation CSS styles

Environment Variable

Make sure your Next.js .env file includes:

NEXT_PUBLIC_WORDPRESS_API_URL=https://your-wordpress-site.com

Caching

The frontend uses a two-layer caching strategy for the best balance of freshness and performance:

• cache: 'no-store' on the network fetch — every page load gets the latest settings from WordPress, so admin changes appear immediately
• localStorage cache of the last-known settings — returning visitors render the configured preloader instantly (before the network request completes), then the cache is refreshed in the background

This means changes you make in WordPress admin appear on the very next page load, while returning visitors still get a near-instant preloader.

Troubleshooting

Preloader not showing

1. Check if the preloader is enabled in WordPress admin
2. Verify the NEXT_PUBLIC_WORDPRESS_API_URL is correctly set in .env
3. Check browser console for API errors
4. Ensure the WordPress REST API is accessible

Logo not displaying

1. Make sure you've uploaded a logo using the media uploader
2. Check that the image URL is accessible
3. Recommended logo size: 200px width or less

Animations not working smoothly

1. Check browser compatibility for CSS animations
2. Reduce animation duration in globals.css if needed
3. Test on different devices for performance

Customization

Adding New Animations

1. Add the animation option in apir-tayo-preloader.php (line ~250)
2. Create the CSS keyframes in app/globals.css
3. Update the animation handler in Preloader.tsx

Changing Minimum Display Time

The preloader holds the final state briefly before the exit animation. Edit these values in Preloader.tsx:

// Inside the exit-trigger useEffect
const holdMs = isProgressType ? 300 : 500; // ms to hold before exit

Support

For issues or feature requests, please contact the development team.

License

GPL v2 or later

Version

2.1.0

Changelog

v2.1.0 (Current)

• Fixed: Settings now apply immediately (switched from 1h revalidation to no-store)
• Added localStorage caching so returning visitors see configured preloader instantly
• Smarter progress bar that waits for actual window.load event (caps at 90% until then)
• Logo image preloaded with fetchPriority="high", loading="eager", decoding="sync"
• Hydration-safe initial state to avoid SSR mismatch
• First-visit fallback shows only an opaque background (no flash of fallback spinner)
• Page content now rendered underneath the overlay for natural reveal on exit

v2.0.0

• Added Integration Guide tab with step-by-step instructions
• Fixed toggle switch display issue (checkbox no longer visible)
• Improved admin UI with better visual hierarchy
• Added one-click copy buttons for all code snippets
• Auto-generates environment variable with correct WordPress URL

v1.0.0

• Initial release
• Preloader settings admin page
• 9 exit animations
• REST API endpoint
• Logo upload support
• Color picker for background