Animate Scrolling in Scrollable Containers with jQuery - scrollToElement.js

scrollToElement.js is a tiny jQuery plugin that creates smooth scrolling animations to target elements inside scrollable containers. Unlike CSS `scroll-behavior: smooth`, this implementation gives you full control over animation duration and adds error handlers.

CSS smooth scrolling sets a fixed animation speed that scales with scroll distance. This means longer scrolls take more time, which can create inconsistent user experiences. This plugin solves this by letting you set exact animation durations.

The key benefit of scrollToElement.js lies in its customization. While CSS offers scroll-behavior: smooth, it provides limited control. You cannot adjust the duration of the animation, nor can you handle errors when no elements are found. This is where the plugin excels. You decide how long the scroll animation lasts, creating a pace that feels right for your content. 

However, it's important to acknowledge the simplicity of scroll-behavior: smooth. For basic, site-wide smooth scrolling where customization isn't critical, the CSS approach is lightweight and requires no JavaScript. The plugin adds a JavaScript dependency and a slight overhead. Choose scrollToElement.js when you need granular control over the animation. If a simple, browser-default smooth scroll across the entire page suffices, CSS might be your preferred route.

How to use it:

1. Download the jquery.scrollToElement.js file and load it after including the jQuery library in your HTML:

<script src="/path/to/cdn/jquery.min.js"></script>
<script src="/path/to/jquery.scrollToElement.js"></script>

2. Target the scrollable container element using its class or ID and initialize the plugin:

var $scrollableContainer = $('.scrollable-container').scrollToElement();

3. Create trigger elements like buttons to enable scrolling to specific elements. Notice the scroll-target class on the elements you want to scroll to and the data-element-id attribute to uniquely identify them.

<button id="trigger1">
  Scroll to Element 1
</button>
<button id="trigger2">
  Scroll to Element 2
</button>
...

<div class="scroll-container">
  <div class="scroll-target" data-element-id="1">
    Element 1
  </div>
  <div class="scroll-target" data-element-id="2">
    Element 2
  </div>
  ...
</div>

4. Use jQuery to attach click event listeners to your trigger buttons and call the scrollToElement method with the appropriate options:

• elementSelector: This option specifies the element to scroll to using a CSS selector. In this case, it targets the element with the data-element-id equal to "1".
• scrollDuration: Sets the animation duration to 1000 milliseconds.
• onElementNotFound: A function that executes if the plugin cannot find the specified element. Here, it displays an alert.

$('#trigger1').on('click', function() {
  $scrollContainer.scrollToElement({
    elementSelector: '[data-element-id="1"]',
    scrollDuration: 1000,
    onElementNotFound: function() {
      alert('Element not found.');
    }
  });
});

How It Works:

The JavaScript defines a jQuery plugin named scrollToElement. When you call this plugin on a container element, it stores the container. 

When a trigger event occurs, the plugin first checks if the target element exists within the container. If the element is found, it calculates the target element's position relative to the top of the scrollable container. 

It then uses jQuery's animate() function to smoothly adjust the container's scrollTop property over the specified duration. The stop(true) part ensures that any ongoing animation is stopped before starting a new one, preventing animation queues. 

If the target element is not found, it executes the onElementNotFound callback.

---

This awesome jQuery plugin is developed by saeedshabani. For more Advanced Usages, please check the demo page or visit the official website.