1 2 3 4

Demos & Templates:

All demos & source code  (Release v2015.10.26)

jQuery Slider: the responsive thumbnail carousel, touch-enabled & mobile-friendly

jQuery is not required

The jQuery version is decommissioned since v.2014.6.14.

Now this jQuery Slider script is plain JavaScript. The jQuery library is not required anymore.

Main Features

Usage: Plug into page

Click the download button to download the source code, then upload the slider CSS and JavaScript files to your server. Link the two files (usually in the head section) in your page, and add the thumbnail slider HTML code into the body section.

<!DOCTYPE html> <html> <head> <title></title> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <link href="1/thumbnail-slider.css" rel="stylesheet" type="text/css" /> <script src="1/thumbnail-slider.js" type="text/javascript"></script> </head> <body> <div id="thumbnail-slider"> <div class="inner"> <ul> <li><a class="thumb" href="img/1.jpg"></a></li> <li><a class="thumb" href="img/2.jpg"></a></li> <li><a href="/"><img class="thumb" src="1.jpg" style="height:auto;" /></a></li> </ul> </div> </div> </body> </html>

Lazy load thumbnail images

You may have noticed that the thumbnail images are defined by the <a> tags in the markup. <a class="thumb" href="1.jpg">image description</a>

You can also use other alternative markup... more

The thumbnail images are usually defined in the format:<a class="thumb" href="1.jpg">image description</a>

The script thumbnail-slider.js will set its background with the image specified in the href attribute.

Benefits of using this format:
  • lazy load images
  • When the thumbnails are having different aspect ratios, it is easier to cutomize their styles by the CSS: .thumb { background-size:contain; /*or: cover*/ }

Alternative markup

Sometimes you may prefer to or have to use other markup for the thumbnails. For example, when you need to wrap the thumb with a link, you cannot use the above mentioned format as nested anchor tags are illegal.


<span class="thumb" style="background-image:url(1.jpg)"></span> or: <img class="thumb" src="1.jpg" style="height:auto;" /> or: Any HTML content. The slides(<li>) allow any HTML content, even plain text without any images.

Config Options

At the top of the thumbnail-slider.js is the thumbnailSliderOptions that you can customize:

var thumbnailSliderOptions = { sliderId: "imageSlider", orientation: "horizontal", thumbWidth: "140px", // or "xx%", or "auto" thumbHeight: "70px", // or "xx%", or "auto" showMode: 1, autoAdvance: true, selectable: true, slideInterval: 3000, // in seconds transitionSpeed: 300, // in seconds shuffle: false, startSlideIndex: 0, // 0-based pauseOnHover: true, initSliderByCallingInitFunc: false, rightGap: 0, // or 90, or "auto" keyboardNav: true, mousewheelNav: false, before: null, license: "yourlicensekey" }; var mcThumbnailSlider = new ThumbnailSlider(thumbnailSliderOptions); /* If you are building multiple Thumbnail Sliders in the same page, you can add codes here: var slider2Ops = {sliderId: "slider2", ...} var slider2 = new ThumbnailSlider(slider2Ops); */ /* The following code remains to be a single copy and untouched. */ /* Thumbnail Slider v2015.10.26. */ function ThumbnailSlider(myOptions) { ... }
Width of the thumbnails. It can be:
  • Pixel value, e.g. "140px". It does not have to be the actual width of the thumbnail. It can be any value that you desired.
  • Percentage, e.g. "100%"
  • "auto"

The script will apply this width to each <li> element of the slider.

Notice: For the thumbWidth and thumbHeight:

  • If one is in pixel and the other is "auto", the "auto" size will scale to the value that maintains the image aspect ratio;
  • If one is in percentage and the other is "auto", the size will be the percentage of the whole slider size (div#thumbnail-slider). The Demo #2 is an example of such setting.

Height of the thumbnails. It can be in pixels, or in percentage(e.g. "100%"), or "auto".

The script will apply this height to each <li> element of the slider.

An integer (1, 2, 3 or 4) specifying how the thumbnails are scrolled:
  • 1:   Move the thumbnails one by one. As soon as the last thumbnail has been visible in the viewport, the next scrolling will rewind to the beginning.
  • 2:   Highlight the thumbnails one by one; The thumbnails may not scroll unless the active thumbnail is not fully in view. It will rewind to the beginning after the last thumbnail has been highlighted.
    • This option is preferable for working with another image slider that gives a detailed view for each thumbnails. Examples: Demo 3, or Demo 4 of the Ninja Slider
    • This option will override the selectable setting to true
  • 3:   Highlight the thumbnails one by one. The highlighed thumbnail will always stay in the middle of the viewport. The sliding will loop continuously without rewinding.

    This option will override the selectable setting to true

  • 4:   Sliding with this option will move away all the thumbnails currently fully displayed in the viewport, and slide in the next group of thumbnails.

    It will rewind to the beginning when the last group of thumbnails has been displayed.

true or false indicating if auto scrolling the thumbnails.
If true:
  • The current active thumbnail will have the CSS class "active" so the active thumbnail can look different from others.
  • When a thumbnail is clicked, the slider will update the current active index, and switch the "active" thumbnail to it.

Notice: If the showMode is 2 or 3, this selectable will be overriden to true.

If it is not set to the default value, 0, the slider will re-organize the thumbnails so that the slider will start from the specified index of the thumbnails.

Note: the index value is 0-based.

true or false: pause advancing when mouse is over the slider.

Note: This function will be disabled with touch-enabled devices such as iPad, mobile phones.

true or false. If set to true, all slides at start will be randomized.

In the thumbnail-slider.js you will see this line of code:

var mcThumbnailSlider = new ThumbnailSlider(thumbnailSliderOptions);

It will init the slider and start the slider as soon as the page is ready (DOMContentLoaded event has been fired).

However there are times that the slider should start at a later time, such as building the slider markup dynamically. There are two ways to start it after the page load:

  • Option 1: Set this initSliderByCallingInitFunc option to true

    Then the slider won't be instantiated until you explicitly call the init function:

  • Option 2: Remove the line of code from the thumbnail-slider.js:

    var mcThumbnailSlider = new ThumbnailSlider(thumbnailSliderOptions);

    And add it to the place where it is the time to run it.

    Note: The option initSliderByCallingInitFunc must be false if taking this second approach.

The rightGap can be any integer value or the "default" string which specifies how much empty space allowed from the last thumb to the right border of the slider (or the bottom border if orientation: "vertical").

If showMode is not 3, when the last thumbnail scrolls into view, it has no following thumbs and may leave a blank area between the last thumb and the right border of the slider frame.

  • {rightGap: "default"} will leave the blank area as it is;
  • {rightGap: 0} will leave no blank area after the last thumb;
  • {rightGap: 100} will allows maximum 100px blank area after the last thumb.

If true, it allows the slider navigation by pressing the keyboard left and right arrow keys.

true or false. If set to true, users can scroll the thumbnails by the mousewheel while the mouse is hovering on the slider.
Callback function that runs at the beginning of each slide transition

Check out the Built-in event handlers and functions below for details.

Check out the License section for details.

Built-in event handlers and functions

If you need the API to further customize the jQuery slider:


The styles of the jQuery slider are mainly configured in the thumbnail-slider.css.

However, keep in mind that some styles are defined in the script thumbnail-slider.js, such as the orientation, thumbWidth, thumbHeight and rightBap in the Config Options section listed above, and some styles are built in the script such as the loading spinner which you will see when the image is too large or has an incorrect path.



Your Name
+ =  

Question Title

If your question is about troubleshooting, please first go through the checking list in Troubleshooting Request.