Page Load Progress
Locks the screen and displays a loading spinner when users submit forms that trigger time-consuming tasks, preventing accidental double-clicks and improving user experience.
page_load_progress
Install
composer require 'drupal/page_load_progress:^2.0'
Overview
Page Load Progress is a user interface enhancement module that provides visual feedback during page loads and form submissions. When a user clicks a submit button or navigates via internal links, the module can display a full-screen overlay with a spinning throbber to clearly indicate that a task is being processed.
This behavior helps prevent users from clicking multiple times while waiting for a response, which can cause duplicate submissions or task execution failures, especially when working with web services or complex operations. The screen lock ensures users understand their action is being processed and prevents them from inadvertently triggering additional actions.
The module offers granular control over when and where the throbber appears through visibility conditions based on URL paths, configurable delays before showing the spinner, and the option to enable ESC key dismissal for manual unlocking.
Features
- Displays a full-screen overlay with animated spinner during form submissions and page loads
- Configurable delay before showing the throbber (immediately, 1 second, 3 seconds, or 5 seconds)
- Path-based visibility conditions to show or hide the throbber on specific pages using wildcard patterns
- Optional support for internal link navigation in addition to form submissions
- ESC key support to allow users to manually dismiss the throbber if needed
- Automatic exclusion of Ajax-based forms and elements to prevent conflicts with modals and dynamic content
- Smart detection to avoid locking when links are opened in new tabs, within modals, or have Ajax handlers
Use Cases
Long-running form submissions
When users submit forms that trigger time-consuming operations such as sending emails, processing payments, generating reports, or syncing with external services, the throbber prevents confusion and double-submissions by clearly indicating the action is in progress.
Content management operations
During content creation or editing that involves complex processing like image manipulation, taxonomy updates, or workflow transitions, the loading indicator reassures content editors that their changes are being saved.
Import/export operations
When running data imports, exports, or migrations through the admin interface, the screen lock prevents administrators from navigating away or triggering duplicate operations while the process completes.
E-commerce checkout flows
During checkout processes where payment processing occurs, the throbber prevents customers from clicking submit multiple times, which could result in duplicate charges or order creation failures.
Integration with external APIs
When forms interact with external web services that may have variable response times, the loading indicator sets appropriate user expectations and prevents timeout-related user errors.
Tips
- Grant the 'Use Page Load Progress' permission only to roles that will benefit from the feature, such as authenticated users or administrators
- Use the 3-5 second delay option to avoid showing the throbber for quick page loads, providing a smoother experience
- Configure path visibility to exclude pages with many Ajax interactions or modal dialogs
- Keep the ESC key option enabled to give users an escape route if something goes wrong
- The module automatically excludes Views UI pages (/admin/structure/views/) to prevent conflicts with the Views preview functionality
- When using the internal links option, be aware that external links and links with target attributes are automatically excluded
- Custom themes can override the CSS to customize the overlay appearance and spinner animation
Technical Details
Admin Pages 1
/admin/config/user-interface/page-load-progress
Configure the behavior of the Page Load Progress module, including when the loading throbber appears, visibility conditions by path, and user escape options.
Permissions 2
Hooks 2
hook_page_attachments
Used to attach the page_load_progress library and Drupal settings to pages where the user has the 'use page load progress' permission and the visibility conditions are met.
template_preprocess_input
Adds the 'page-load-progress-submit' CSS class to submit buttons that are not Ajax-enabled, allowing the JavaScript to identify which elements should trigger the throbber.
Troubleshooting 5
Verify that the user role has the 'Use Page Load Progress' permission. Check that the form is not using Ajax (the module automatically excludes Ajax forms). Ensure the page path is not excluded by visibility conditions.
Enable the ESC key option to allow users to dismiss the overlay manually. This can occur if there are JavaScript errors preventing the page from reloading or if the server response is delayed.
The module attempts to avoid modal conflicts, but if issues persist, use the visibility conditions to exclude pages with modal functionality or ensure modal links have appropriate classes that distinguish them from regular links.
Ensure that Ajax-enabled links have the 'use-ajax' or 'webform-ajax-link' class. The module checks for these classes and excludes them from triggering the throbber.
The module only triggers on links starting with '/'. However, some absolute internal URLs might be treated differently. Consider using relative paths or adding specific class-based exclusions.
Security Notes 3
- The module respects Drupal's permission system - only users with the 'use page load progress' permission will see the loading indicator
- The 'administer page load progress' permission should be granted carefully as it allows modification of the module behavior site-wide
- The CSS selector configuration (page_load_progress_elements) can only be modified via configuration management override, not through the UI, preventing potential injection issues