How to Fix WordPress Site List Scroll Jumping on Delete: A Complete Guide

Understanding the Scroll Reset Issue in WordPress Site Lists

Managing multiple sites in WordPress often involves navigating long lists. A persistent issue has frustrated users: every time a site is deleted, the list scrolls back to the top, forcing users to manually scroll down to continue their work. This behavior also occurred during drag-and-drop reordering, thumbnail fetching, category deletion, tag deletion, and after maintenance completion.

Root Cause: The Missing keepScroll Argument

The fetchSites() function in WordPress includes a parameter called keepScroll. When set to true, this parameter prevents the list from resetting its scroll position. However, in the original implementation, this argument was omitted across six critical call sites, causing the default behavior of scrolling to the top to activate every time the list was refreshed.

The logic for scroll preservation was already in place, but its effectiveness was nullified by the absence of the keepScroll argument in the function calls. As a result, users experienced an unintended scroll reset after every operation that triggered a list refresh.

Implementing the Fix

The solution involved updating the SiteList component to include the keepScroll prop wherever it was rendered. This change was applied across six distinct call sites, including the Admin Dashboard, Project Settings, User Management, Analytics Overview, Bulk-Edit Modal, and Search Results page. The implementation ensured that the scroll position remained unchanged after operations like deletion or reordering.

To maintain backward compatibility, the keepScroll parameter was defined as an optional boolean with a default value of false. This allowed existing callers to continue functioning without modification while enabling scroll preservation where needed.

Code Example: Before and After

Before: The SiteList component was called without the keepScroll prop, leading to scroll resets.

<SiteList sites={sites} onDelete={handleDelete} />

After: The keepScroll prop was added to preserve the scroll position.

<SiteList
  sites={sites}
  onDelete={handleDelete}
  keepScroll={true}
/>

Impact of the Fix

The implementation of the keepScroll argument delivered significant improvements:

• Enhanced User Experience: Users no longer experience abrupt scroll resets, allowing for smoother navigation through long lists. This is particularly beneficial for environments managing 100+ sites, where manual scrolling would otherwise disrupt workflows.
• Performance: The fix introduced no additional re-renders. The component simply reused the existing scroll container, ensuring optimal performance.
• Backward Compatibility: Existing callers that did not require scroll preservation continued to work seamlessly, as the keepScroll parameter defaulted to false.

Verification and Testing

To confirm the fix, users can follow these steps:

1. Run the WordPress UI locally using npm start or yarn dev.
2. Navigate to a page that renders the site list, such as Admin → Sites.
3. Scroll down to a lower section of the list.
4. Delete a site and observe that the scroll position remains unchanged.

For custom implementations where scroll resets are desired, the keepScroll prop can be omitted or explicitly set to false.

Additional Resources

For further reading, refer to the following resources:

• GitHub PR #9876: Details the changes made to the six call sites, including updated typings and new tests.
• Issue #4523: The original bug report highlighting the scroll reset issue, complete with screenshots and a demonstration video.
• Release Notes – v2.3.1: Lists the fix under the “Bug fixes → UI/UX” section.
• Component Documentation: Updated to include usage examples and guidelines for the keepScroll prop.

Key Takeaway: The scroll reset issue in WordPress site lists was resolved by implementing the keepScroll argument across all relevant call sites. This simple yet effective change significantly improved user experience and workflow efficiency.