A WordPress plugin that improves page navigation by intelligently managing scroll position restoration. The plugin waits for dynamic elements to load before restoring scroll position, preventing layout shift and improving user experience.
- Intelligent Scroll Restoration: Waits for dynamic elements (like ads, lazy-loaded content) to load before restoring scroll position
- Safelist Support: Define elements that, when present, allow immediate scroll restoration
- BFCache Compatible: Uses modern browser APIs (
pagehide,visibilitychange) for proper Back-Forward Cache support - Performance Optimized: Minimal impact on Core Web Vitals (INP, CLS)
- Flexible Configuration: Control timing, selectors, and page targeting from WordPress admin
- PHP: 8.1 or higher
- WordPress: 6.3 or higher
- Compatible with WordPress VIP coding standards
- Upload the
delayed-scroll-restorationfolder to/wp-content/plugins/ - Activate the plugin through the 'Plugins' menu in WordPress
- Configure settings at Settings → Delayed Scroll Restoration
Navigate to Settings → Delayed Scroll Restoration in your WordPress admin to configure:
CSS selectors that, when found on page load, allow immediate scroll restoration. This is useful for elements that are always present and indicate the page is ready.
Examples:
#header
.nav-menu
[data-loaded="true"]
CSS selectors for elements that are injected dynamically (ads, lazy-loaded content). The plugin waits for any of these to appear before restoring scroll.
Examples:
#ad-container
.lazy-loaded
[data-ad-slot]
.content-loader
Note: When this field is empty, the script will not output at all.
Time in milliseconds to wait after the dynamic element appears before scrolling. Default: 100
Maximum time in milliseconds the MutationObserver will watch before disconnecting and restoring scroll anyway. Default: 10000
When enabled, delayed scroll restoration only applies to single post pages. When disabled, it applies to all pages.
- On Page Load: The plugin disables the browser's automatic scroll restoration and resets scroll to top
- Priority Check: Checks if any safelist selectors are present
- If found: Restores scroll immediately (after configured delay)
- If not found: Proceeds to observe for dynamic selectors
- Dynamic Observation: Uses MutationObserver to watch for dynamically injected elements
- Scroll Restoration: Once a dynamic element appears (or timeout occurs), waits for the configured delay, then smoothly restores scroll position
- On Navigation: Saves scroll position to sessionStorage using BFCache-compatible events
- Storage: Uses
sessionStoragewith page URL as key - Selectors: Combines multiple selectors using
:is()syntax for optimal performance - Events: Uses
pagehidefor BFCache compatibility withvisibilitychangefallback - Smooth Scrolling: Provides smooth scroll behavior with fallbacks for older browsers
- Anchor Links: Handles hash fragments when no saved scroll position exists
- Auto-cleanup: Observer automatically disconnects after finding elements or reaching timeout
- Inline script in
<head>for immediate execution - No external HTTP requests
- Optimized DOM checking using combined selectors
- Early exit patterns in mutation observer
- Automatic cleanup via observer disconnection
- Minimal impact on Interaction to Next Paint (INP)
- Modern browsers with MutationObserver support
- BFCache-compatible browsers (Chrome 96+, Firefox 86+, Safari 10.1+)
- Graceful degradation for older browsers
For issues, feature requests, or contributions, visit XWP
See LICENSE file for details.
Developed by XWP