Fix: Element Plus Anchor Scroll Stutter On Rapid Clicks

Nov 29, 2025 by Alex Johnson 56 views

Element Plus Anchor Scroll Animation Stutter: A Deep Dive and Solution

Element Plus is a powerful and versatile UI library built for Vue.js. Among its many components, the el-anchor component provides an excellent way to create in-page navigation, allowing users to smoothly scroll to different sections of a webpage. However, a common issue arises when users rapidly click the same anchor link, leading to a frustrating stutter in the scroll animation. This article delves into the root cause of this problem, explains the observed behavior, and provides a clear solution.

The Problem: Rapid Clicks and Animation Interruptions

The core of the issue lies in how the el-anchor component handles multiple clicks on the same link during an ongoing scroll animation. When a user clicks an anchor link, the component initiates a smooth scroll to the target section. However, if the user quickly clicks the same link again before the animation completes, the component cancels the current animation and starts a new one. This behavior results in a jarring visual effect where the scroll repeatedly restarts, causing a stuttering motion instead of a smooth transition. This is not only visually unpleasant but also disrupts the user experience, making navigation feel clunky and unresponsive. The issue is especially noticeable when the duration prop of the el-anchor is set to a longer value (e.g., 1000ms), as the interruption becomes more pronounced.

Detailed Analysis of the Bug

Let's break down the scenario in detail. The el-anchor component, when a link is clicked, calculates the necessary scroll distance and initiates an animation to move the viewport to the target section. This animation typically involves updating the scrollTop property of the scrollable container (often the document.body or a specific div) over time. The problem arises because each click triggers a new animation. Therefore, the old animation is interrupted, and a new one starts. This constant interruption and restarting of animations is what causes the stuttering effect. The frequency and timing of the clicks directly correlate with the severity of the stutter. Rapid clicks mean more interruptions, leading to more pronounced stuttering.

Code Snippet: Reproduction and Demonstration

The following is an example demonstrating the behavior:

<template>
  <div>
    <div style="position: fixed; top: 0; left: 0; background: #000; color: #fff; padding: 10px;">Fixed Top Block</div>
    <div ref="containerRef" style="height: 300px; overflow-y: auto;">
      <div id="part1" style="height: 300px; background: rgba(255, 0, 0, 0.02); margin-top: 30px;">part1</div>
      <div id="part2" style="height: 300px; background: rgba(0, 255, 0, 0.02); margin-top: 30px;">part2</div>
      <div id="part3" style="height: 300px; background: rgba(0, 0, 255, 0.02); margin-top: 30px;">part3</div>
    </div>
    <div class="vp-row">
      <el-anchor
        :container="containerRef"
        direction="vertical"
        type="default"
        :offset="30"
        :duration="1000"
        @click="handleClick"
      >
        <el-anchor-link href="#part1" title="part1" />
        <el-anchor-link href="#part2" title="part2" />
        <el-anchor-link href="#part3" title="part3" />
      </el-anchor>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const containerRef = ref<HTMLElement | null>(null);

const handleClick = (e: MouseEvent) => {
  e.preventDefault();
}
</script>

In this example, the el-anchor component is used to navigate to different sections (part1, part2, part3) within a scrollable container. Setting duration="1000" makes the animation more noticeable. By rapidly clicking the same link (e.g., the link to part2) while the animation is in progress, the stuttering effect becomes evident.

The Solution: Preventing Animation Interruptions

The solution to this problem involves modifying the component's behavior to prevent the interruption of the ongoing scroll animation due to subsequent clicks on the same link. The core idea is to check if an animation is already in progress and, if so, ignore subsequent clicks on the same link until the animation is complete. A more robust solution might include debouncing the click events to prevent the rapid triggering of multiple animations.

Implementation of the Fix

The fix can be implemented by adding a check within the el-anchor component's click handler. This handler should first determine if a scroll animation is currently active. If an animation is running and the clicked link is the same as the one currently being scrolled to, then the click event should be ignored. The exact implementation details depend on how Element Plus manages its scroll animations internally. One approach could be to use a flag (e.g., isScrolling) to indicate whether an animation is in progress. This flag is set to true when the animation starts and set to false when it completes. The click handler will then check the value of this flag before initiating a new animation. If the isScrolling flag is true, and the clicked link is the same, then the handler does nothing.

// Pseudocode for the fix
let isScrolling = false;
let currentTarget = null;

function handleClick(target: string) {
  if (isScrolling && target === currentTarget) {
    return; // Ignore the click if already scrolling to the same target
  }
  //... existing scroll animation logic
  isScrolling = true;
  currentTarget = target;

  // After animation completes
  setTimeout(() => {
    isScrolling = false;
    currentTarget = null;
  }, duration); // duration is the animation time
}

Testing and Validation

After implementing the fix, it's crucial to thoroughly test it to ensure that the stuttering issue is resolved without introducing any regressions. Testing should involve the following:

Manual Testing: Test the component in various browsers and operating systems. Verify that rapidly clicking the same anchor link no longer causes stuttering. Instead, it should continue the animation smoothly.
Edge Cases: Test with different duration values to ensure the fix works correctly regardless of the animation speed. Test with different scrolling containers (e.g., document.body, custom div elements) to cover various use cases.
Regression Testing: Ensure that the fix does not negatively impact the component's other functionalities, such as scrolling to different links or handling different container types.

Benefits of the Fix

Implementing the fix offers significant improvements to the user experience:

Smoother Navigation: The primary benefit is the elimination of the stuttering effect, resulting in a seamless and more intuitive navigation experience.
Improved User Satisfaction: By removing the jarring visual effect, the fix enhances the overall usability of the website or application, leading to increased user satisfaction.
Enhanced Professionalism: A smooth and responsive UI reflects positively on the quality and professionalism of the website or application.

Conclusion

The stuttering anchor scroll animation in Element Plus, caused by rapid clicks on the same link, can significantly impact the user experience. By understanding the root cause and implementing the suggested fix, developers can ensure a smoother, more user-friendly navigation experience. This fix not only improves the aesthetics of the application but also contributes to better usability and overall user satisfaction. The described fix is a simple yet effective solution, which greatly improves the user's perception of the website or application. Implementing this fix is highly recommended for any project utilizing the el-anchor component in Element Plus.

For more information on Element Plus and its components, please visit the official documentation:

Element Plus Documentation