jQuery thumbnail scroller

A thumbnail/image scroller that can be used as standalone or alongside lightboxes, gallery scripts etc. Features include: scrolling by cursor movement, buttons and/or touch, vertical and/or horizontal scrolling, customization via CSS and option parameters, methods for triggering events like scroll-to, update, destroy etc., user-defined callbacks functions and more.

Current version 2.0.3 (Changelog) – Version 1.x.x (no longer actively maintained)

• Get started
• Configuration
• Methods
• Styling
• Callbacks

How to use it

HTML

Get plugin files. Extract and upload jquery.mThumbnailScroller.min.js and jquery.mThumbnailScroller.css to your web server (more info)

Include jquery.mThumbnailScroller.css in the head tag your html document

<link rel="stylesheet" href="/path/to/jquery.mThumbnailScroller.css">

Include jQuery library (if your project doesn’t use it already) and jquery.mThumbnailScroller.min.js in your document’s head or body tag

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
<script src="/path/to/jquery.mThumbnailScroller.min.js"></script>

Create the markup with your images, links, etc. which is basically an element (e.g. a div) holding an unordered list (ul)

<div id="my-thumbs-list">
  <ul>
    <li><a href="image-1-link"><img src="/path/to/image-1-file" /></a></li>
    <li><a href="image-2-link"><img src="/path/to/image-2-file" /></a></li>
    <li><a href="image-3-link"><img src="/path/to/image-3-file" /></a></li>
    <li><a href="image-4-link"><img src="/path/to/image-4-file" /></a></li>
    <!-- and so on... -->
  </ul>
</div>

CSS

Give your element (in the example above #my-thumbs-list) a width and/or height value and a CSS overflow value of auto or hidden. For example:

#my-thumbs-list{
  overflow: auto;
  width: 800px;
  height: auto;
}

If you’re creating a vertical scroller, you’ll need to set a height (or max-height) value

#my-thumbs-list{
  overflow: auto;
  width: 300px;
  height: 500px;
}

Initialization

Initialize via javascript

Create a script and call mThumbnailScroller function on your element selector along with the option parameters you want

<script>
    (function($){
        $(window).load(function(){
            $("#my-thumbs-list").mThumbnailScroller({
              axis:"x" //change to "y" for vertical scroller
            });
        });
    })(jQuery);
</script>

more info

$(".myClass").mThumbnailScroller();

$(".myClass, #my-thumbs-list").mThumbnailScroller();

$(".myClass").mThumbnailScroller({
    type:"hover-precise"
});
$("#my-thumbs-list").mThumbnailScroller({
    axis:"y",
    type:"click-70"
});

Initialize via HTML

If you prefer to initialize the plugin without a script, you can simply give your element the class mThumbnailScroller and optionally set its orientation via the HTML data attribute data-mts-axis ("x" for horizontal and "y" for vertical). For example:

<div id="my-thumbs-list" class="mThumbnailScroller" data-mts-axis="x">
  <ul>
    <!-- your content -->
  </ul>
</div>

See code examples on Github

Basic configuration & option parameters

The 2 basic options are axis which defines the scroller orientation and type which defines how the user interacts with the scroller.

axis

The default scroller orientation is horizontal, so if you don’t set an axis option value, it defaults to "x"

$("#my-thumbs-list").mThumbnailScroller({ axis:"x" });

To create a vertical scroller, set axis option to "y"

$("#my-thumbs-list").mThumbnailScroller({ axis:"y" });

or use data-mts-axis="y" if you’re initializing the plugin via HTML

type

You can set the type of scroller via javascript, for example:

$("#my-thumbs-list").mThumbnailScroller({ type:"hover-50" });

or using the HTML data attribute data-mts-type, e.g.:

<div class="mThumbnailScroller" data-mts-type="hover-50">...</div>

There are 4 basic scroller types:

1. "hover-[number]" (e.g. "hover-33", "hover-80" etc.)

   Scrolling content in linear mode by hovering the cursor over the scroller edges. The edges are defined by the type name, where [number] indicates the percentage of the scroller area in which scrolling is idle. For example, setting "hover-50" (default value) on a 600 pixels wide horizontal scroller, means that scrolling will be triggered only when the cursor is over the first 150 pixels from the left or right edge. And when cursor is over the 50% of the scroller width (300 pixels), scrolling will be idle or stopped.

2. hover-precise

   Scrolling content with animation easing (non-linear mode) by hovering the cursor over the scroller. The scrolling speed and direction is directly affected by the cursor movement and position within the scroller.

3. "click-[number]" (e.g. "click-50", "click-90" etc.)

   Scrolling content by clicking buttons. The scrolling amount is defined by type name, where [number] indicates a percentage of the scroller area. For example, setting "click-50" on a 800 pixels wide horizontal scroller, means that each time you click the left or right arrow buttons, the content will scroll by 400 pixels (50% of 800px) to the left or right.

4. click-thumb

   Scrolling each image/thumbnail at a time by clicking buttons.

Configuration

You can configure your scroller(s) using the following option parameters when calling mThumbnailScroller function
Usage $(selector).mThumbnailScroller({ option: value });

Plugin methods

Methods are ways to execute various scroller actions programmatically from within your script(s).

update

Usage $(selector).mThumbnailScroller("update");

Call the update method to manually update existing scrollers to accomodate new content or resized element(s). This method is by default called automatically by the script (via updateOnContentResize option) when the element itself and/or its content size changes.

scrollTo

Usage $(selector).mThumbnailScroller("scrollTo", position, {options});

Call the scrollTo method to scroll content to the position parameter. Position parameter can be a string (e.g. "#element-id", "bottom", "left" etc.), an integer indicating number of pixels (e.g. 100), an array for y/x axis (e.g. [100,100]), a js/jQuery object, a function etc. method demo

view examples

$(selector).mThumbnailScroller("scrollTo", "right");

$(selector).mThumbnailScroller("scrollTo", "last");

var to="#myID";
$(selector).mThumbnailScroller("scrollTo", to);

$(selector).mThumbnailScroller("scrollTo", "-=200"); //scroll forward
$(selector).mThumbnailScroller("scrollTo", "+=200"); //scroll backward

scrollTo position parameter

Position parameter can be:

• "string"
  • Element selector
    For example, scroll to element with id “element-id”:
    

    $(selector).mThumbnailScroller("scrollTo","#element-id");

  • Special pre-defined position
    For example, scroll to right:
    

    $(selector).mThumbnailScroller("scrollTo","right");

    Pre-defined position strings:

    • "bottom" – scroll to bottom
    • "top" – scroll to top
    • "right" – scroll to right
    • "left" – scroll to left
    • "first" – scroll to the position of the first element within content
    • "last" – scroll to the position of the last element within content

  • Number of pixels less/more: (e.g. "-=100"/"+=100")
    For example, scroll by 100 pixels right:
    

    $(selector).mThumbnailScroller("scrollTo","-=100");

• integer
  • Number of pixels (from left and/or top)
    For example, scroll to 100 pixels:
    

    $(selector).mThumbnailScroller("scrollTo",100);

• [array]
  • Different y/x position
    For example, scroll to 100 pixels from top and 50 pixels from left:
    

    $(selector).mThumbnailScroller("scrollTo",[100,50]);

• object/function
  • jQuery object
    For example, scroll to element with id “element-id”:
    

    $(selector).mThumbnailScroller("scrollTo",$("#element-id"));

  • js object
    For example, scroll to element with id “element-id”:
    

    $(selector).mThumbnailScroller("scrollTo",document.getelementbyid("element-id"));

  • function
    For example, scroll to 100 pixels:
    

    $(selector).mThumbnailScroller("scrollTo",function(){ return 100 });

scrollTo method options

stop

Usage $(selector).mThumbnailScroller("stop");

Stops running scrolling animations. Usefull when you wish to interrupt a previously scrollTo call.

disable

Usage $(selector).mThumbnailScroller("disable");

Calling disable method will temporarily disable the scroller(s). Disabled scrollers can be re-enabled by calling the update method.

To disable a scroller and reset its content position, call the method by setting its reset parameter to true:

$(selector).mThumbnailScroller("disable", true);

method demo

destroy

Usage $(selector).mThumbnailScroller("destroy");

Calling destroy method will completely remove the scroller and return the element to its original state.

method demo

Scroller styling & themes

You can style your scroller(s) using jquery.mThumbnailScroller.css which contains the basic/default styling and few ready-to-use themes.

You can modify the default styling or an existing scroller theme directly, clone a theme and change it to your needs or overwrite the CSS in another stylesheet. If you wish to maintain compatibility with future plugin versions (that may include an updated version of jquery.mThumbnailScroller.css), I recommend using your own custom (or cloned) theme (creating your own custom theme), or overwriting the CSS. This way you can always upgrade jquery.mThumbnailScroller.css without having to redo your changes.

Themes

Plugin’s CSS includes a number of ready-to-use themes for quickly applying a basic styling to your scroller(s). To apply a theme, use theme option parameter:

$(selector).mThumbnailScroller({
    theme: "theme-name"
});

or the HTML data attribute data-mts-theme in your markup:

<div class="mThumbnailScroller" data-mts-theme="theme-name">...</div>

themes list

$(selector).mThumbnailScroller({
    type:"click-50",
    theme:"buttons-in"
});

#my-thumbs-list{
  position: relative;
  padding: 0 55px;
}

$("#my-thumbs-list").mThumbnailScroller({
    type:"click-thumb",
    theme:"buttons-out"
});

$(selector).mThumbnailScroller({
    theme:"hover-full"
});

$(selector).mThumbnailScroller({
    theme:"hover-classic"
});

creating your own custom theme

$(selector).mThumbnailScroller({
    theme:"my-theme"
});

.mTS-my-theme{ padding: 10px; }
.mTS-my-theme .mTSThumbContainer{ margin: 0 5px; } 
/* and so on... */

User-defined callbacks

You can trigger your own js function(s) by using plugin’s callbacks option parameter (see all availbale callbacks in configuration section). Some examples:

$(selector).mThumbnailScroller({
    callbacks:{
        onScroll: function(){ /* do something */ }
    }
});

$(selector).mThumbnailScroller({
    callbacks:{
        onTotalScroll: function(){ myFunction(); }
    }
});

function myFunction(){
   /* do something */
}

The plugin returns a number of values and objects that can be used inside the callbacks

• this – the scroller element
• this.mts.content – the scrollable element containing the content (e.g. the ul element) as jquery object
• this.mts.top – content’s top position (pixels)
• this.mts.left – content’s left position (pixels)
• this.mts.topPct – content vertical scrolling percentage
• this.mts.leftPct – content horizontal scrolling percentage
• this.mts.direction – content’s scrolling direction (returns "x" or "y")

view code examples

$(selector).mThumbnailScroller({
    callbacks:{
        whileScrolling: function(){
          var result=this.mts.leftPct;
          console.log(result+"%");
        }
    }
});

$(selector).mThumbnailScroller({
    callbacks:{
        onTotalScroll: function(){
          appendData(this.mts.content);
        }
    }
});

function appendData(el){
   el.append("<li>new data</li>");
}

Plugin dependencies & requirements

• jQuery version 1.6.0 or higher

License

This work is released under the MIT License.
You are free to use, study, improve and modify it wherever and however you like.
https://opensource.org/licenses/MIT

Donating helps greatly in developing and updating free software and running this blog 🙂