Release date: February 7th, 2019
Current version: 5.3.10
Change log

AJAX-ZOOM thumbnail slider extension - axZmThumbSlider

Posted on 2019-02-20

The AJAX-ZOOM axZmThumbSlider thumbnails- and content slider is a component that extends the default functionality of the zoom-viewer. It is part of the download-package. The manual handling is the same as for most jQuery plugins. Within AJAX-ZOOM core, this component is used for vertical, horizontal and inline thumbnail galleries. The slider is also used in other AJAX-ZOOM extensions such as the hover on zoom extension. In this post, you can see some various implementations of the slider and find the complete documentation of the options and the API methods.

Starting from AJAX-ZOOM version 5.3.11, the demo and documentation for the axZmThumbSlider extension moved from the AJAX-ZOOM extensions directory of the core package to this page. If you have been redirected to this page, it is intended.

Extension version: 3.0
Extension date: 2019-02-19

Why another thumbnails slider?

Years ago, we used the "jCarousel" script for "external usage" for implementations outside of the core AJAX-ZOOM image-viewer. There was nothing much better back at that time. But, "jCarousel" outdated quickly and the first responsive release of "jCarousel" did not fulfill our expectations. Still does not. So did not any alternatives back then.

Compared to the main AJAX-ZOOM script, a "thumbnail slider" looked like a couple of lines. Thus, we decided to write our plugin from scratch to use it together with AJAX-ZOOM in general and without the need of forking a free code whenever there is a requirement for a new feature.

From the perspective of a template designer, the resulting axZmThumbSlider is quite easy to implement, and you can configure it easily via javascript and CSS. The script is responsive and has all required API and options available, which designers and coders commonly need for such an interactive element. You can also use it as "content scroller" and not just for the image thumbnails.

Today, this thumbnail extension is implemented into the native AJAX-ZOOM viewer, and we use it across several other AJAX-ZOOM extensions. All extensions that utilize this thumbnails slider have a dedicated option to pass through the options of the slider. You can also set the options of the slider for AJAX-ZOOM core viewer. Please see this post about setting the options for AJAX-ZOOM.

Within some of those extensions, it is also possible to disable this thumbnails slider and replace it with a different plugin, which applies the ul->li structure. However, such a replacement is rather a more difficult task and requires mapping the API methods or edit the source code of the extensions. Therefore, it may be easier to contact us with the request for a feature that you are missing.

The slider uses CSS3 transforms and falls back to left or top animations for browsers, which do not support the transforms or do not do well with them. CSS transitions are not used to animate the slider. It works equally well on desktops and mobile touch devices. It also idles quickly and makes sparing use of processor or GPU resources.

Thumbnails slider examples

Thumbnails slider external controls / some API showcase

  • Some thumb description 1
  • Some thumb description 2
External controlls
(replicate internal buttons)
scrollTo thumb [first] [4] [8 last] [8 middle] [8 first] [12] [last] [random]
scrollTo %: [20%] [50% last] [50% middle] [50% first] [80%]
scrollTo px: [200px first] [800px last] [800px middle] [800px first] [1400px]
scrollBy thumbs: [-1] [1]
scrollBy %: [20%] [-20%] [100%] [-100%]
scrollBy px: [200px] [-200px] [500px] [-500px]
Handle thumbs: prependThumb appendThumb removeThumb (last) removeThumb (first) insertThumbAfter (1) insertThumbBefore (3) removeAllThumbs

Horizontal slider with only a few thumbnails, centerNoScroll option enabled

If no height of the element is set, the plugin tries to determine it instantly and complains about that in browsers console if present.

Horizontal slider without buttons, a custom scrollbar and wraped by another design element

Thumbnails slider with mouseScroll option disabled and scrollBy: 2

Slider without button controls and mouseFlowMode option enabled

Responsive horizontal slider, fast pressScrollSpeed (20), mouseDrag disabled

Vertical sliders with fixed heigh, scrollbar left or right

Vertical sliders with fixed height and scroll buttons

contentMode option - vertical slider without thumbnails

HTML Ipsum Presents

Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo. Quisque sit amet est et sapien ullamcorper pharetra. Vestibulum erat wisi, condimentum sed, commodo vitae, ornare sit amet, wisi. Aenean fermentum, elit eget tincidunt condimentum, eros ipsum rutrum orci, sagittis tempus lacus enim ac dui. Donec non enim in turpis pulvinar facilisis. # Ut felis.

VoilĂ  - nested slider

Header Level 2

  1. Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
  2. Aliquam tincidunt mauris eu risus.
  • Morbi in sem quis dui placerat ornare. Pellentesque odio nisi, euismod in, pharetra a, ultricies in, diam. Sed arcu. Cras consequat.
  • Praesent dapibus, neque id cursus faucibus, tortor neque egestas augue, eu vulputate magna eros eu erat. Aliquam erat volutpat. Nam dui mi, tincidunt quis, accumsan porttitor, facilisis luctus, metus.
  • Phasellus ultrices nulla quis nibh. Quisque a lectus. Donec consectetuer ligula vulputate sem tristique cursus. Nam nulla quam, gravida non, commodo a, sodales sit amet, nisi.
  • Pellentesque fermentum dolor. Aliquam quam lectus, facilisis auctor, ultrices ut, elementum vulputate, nunc.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus magna. Cras in mi at felis aliquet congue. Ut a est eget ligula molestie gravida. Curabitur massa. Donec eleifend, libero at sagittis mollis, tellus est malesuada tellus, at luctus turpis elit sit amet quam. Vivamus pretium ornare est.

Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo. Quisque sit amet est et sapien ullamcorper pharetra. Vestibulum erat wisi, condimentum sed, commodo vitae, ornare sit amet, wisi. Aenean fermentum, elit eget tincidunt condimentum, eros ipsum rutrum orci, sagittis tempus lacus enim ac dui. Donec non enim in turpis pulvinar facilisis. Ut felis. Praesent dapibus, neque id cursus faucibus, tortor neque egestas augue, eu vulputate magna eros eu erat. Aliquam erat volutpat. Nam dui mi, tincidunt quis, accumsan porttitor, facilisis luctus, metus

  • Morbi in sem quis dui placerat ornare. Pellentesque odio nisi, euismod in, pharetra a, ultricies in, diam. Sed arcu. Cras consequat.
  • Praesent dapibus, neque id cursus faucibus, tortor neque egestas augue, eu vulputate magna eros eu erat. Aliquam erat volutpat. Nam dui mi, tincidunt quis, accumsan porttitor, facilisis luctus, metus.
  • Phasellus ultrices nulla quis nibh. Quisque a lectus. Donec consectetuer ligula vulputate sem tristique cursus. Nam nulla quam, gravida non, commodo a, sodales sit amet, nisi.
  • Pellentesque fermentum dolor. Aliquam quam lectus, facilisis auctor, ultrices ut, elementum vulputate, nunc.
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.

If you add or remove content from the slider, it instantly adjusts the scrollbar and other functionalities. Nested sliders are supported.

Vertical sliders with multiple columns, width || height can be responsive

Todo: implement responsive grid system.

Options

The options are passed to the AJAX-ZOOM jQuery.fn.axZmThumbSlider extension as JavaScript object, e.g.:


		jQuery('#slider1').axZmThumbSlider({
			btnBwdObj: $('#extBwdButton_1'),
			btnFwdObj: $('#extFwdButton_1'),
			thumbLiStyle: {
				width: 90, 
				height: 120, 
				marginBottom: 7
			},
			wrapStyle: {backgroundColor: '#FFFFFF'},
			scrollbar: true,
			firstThumb: 1,
			firstThumbPos: 'middle',
			firstThumbTriggerClick: false,
			firstThumbHighlight: true 
		});
		
OptionDefaultDescription
orientation 'horizontal' Orientation value, horizontal or vertical.
multicolumn false If orientation is vertical, enable multiple columns with thumbs.
smoothMove 12 The smoothness of the scrolling.
pressScrollSpeed 6 Max speed of the movement while pressing on the buttons.
pressScrollSnap false Snap to thumbnails after pressing on the buttons.
pressScrollTime 250 Time in ms to start continuous stepless scrolling for the buttons.
contentMode false Enable a simple content scroller instead of thumbnails.
circularClickMode false Pressing on next or prev buttons results into scrolling to next element and triggering the click event on it instantly. It does not, however, support an endless visual loop. Instead, it focuses on the first thumb when the last is reached.
liImgAsBack false Images inside li tags (thumbs) are removed and put as a background of the li element.
randomize false Randomize order of thumbs on load, see also API methods for randomizing.
firstThumb 1 Thumb number to show on load. The numeration starts with one.
firstThumbPos 'middle' Default position within the slider (if possible), possible values: first, middle, last.
firstThumbTriggerClick false Trigger click on first selected thumbnails on load.
firstThumbHighlight false Highlight firstThumb if firstThumbTriggerClick is not enabled.
posOnClick 'middle' Scroll the thumb to selected position within the slider, possible values: false, 'first', 'middle', 'last'.
scrollBy 'auto -1'
  • Integer - number of slides scrolled when clicked on the backward / forward button
  • Can be also 'auto' or expression with auto and integer as string, e.g. 'auto -1'
  • String e.g. '50%' or '150px'
mouseWheelScrollBy '20%' Use mousewheel for scrolling, requires Brandon Aaron's mousewheel.js; integer - number thumbs; string - px or % value, e.g. '50px' or '20%'
debugNumbers false Add numbers to the thumbs, CSS .axZmThumbSlider div.debugNumbers.
mouseFlowMode false The scroll position of the slider depends on the position of the mouse cursor above the slider.
mouseFlowMargin 25 Margin from left/right or top/bottom where mouse position for mouseFlowMode is not captured.
mouseDrag true Drag with the mouse as you would do it on touch devices.
thumbLiStyle {} Quickly overwrite thumb CSS style (e.g., width and height) without changing the CSS file or write inline styles.
thumbImgStyle {} Same as above. You can apply this option when liImgAsBack is disabled.
thumbLiSubClass{mousehover: 'mousehover', selected: 'selected', first: 'first', last: 'last'} This is an array-like object that represents thumbnail subclasses. You can disable it by setting a preperty value to false.
ulClass 'axZmThumbSlider' Main class prefix for the ul element.
wrapClass 'axZmThumbSlider_wrap' The CSS class for elements that wraps the thumbnails.
contentClass 'axZmThumbSlider_content' The CSS class for the wrapping element when contentMode option is enabled.
contentStyle {} Inline CSS style for the wrapper when contentMode is enabled.
wrapStyle {} Quickly override styles for the main wrapping element.
outerWrapPosition 'absolute' If the parent container has padding, setting this value to 'relative' will preserve the CSS position.
centerNoScroll true Center thumbnails in the slider when there is nothing to scroll.
btn true Enable slider element buttons.
btnOver false Place buttons not outside but over the thumbnails.
btnHidden false Hide a button if it is disabled (nothing to scroll or reaches the end).
btnClass 'axZmThumbSlider_button' The main CSS class prefix for buttons.
btnMargin null Distance from a button to the scrolling area. You can also set this margin via CSS.
btnBwdStyle null Quickly override CSS values of the backword button instead of changing the CSS class values.
btnFwdStyle null Quickly override CSS values of forward button instead of changing the CSS class values.
btnLeftText '«' Text for backword button (horizontal orientation)
btnRightText '»' Text for forward button (horizontal orientation)
btnBwdObj null Define the external backword button jQuery element via selector.
btnFwdObj null Define the external forward button jQuery element via selector.
scrollbar false Enable / disable the scrollbar.
scrollBarIndicator false If true, no actions will be attached to track area or scrollbar.
scrollbarMinDim 20 Minimal scrollbar width for horizontal / height for the vertical orientated slider.
scrollbarMaxDim null Maximal scrollbar width for horizontal / height for vertical orientated slider.
scrollbarClass 'axZmThumbSlider_scrollbar' Scrollbar CSS class.
scrollbarMargin null Distance, which shrinks the length of the scrollbar. Can be also set via CSS as well.
scrollbarOffset null Offset of the scrollbar. Can be set via CSS as well.
scrollbarStyle {} Quickly overwrite position of the scrollbar by applying CSS inline styles.
scrollbarContainerStyle {} Quickly set the margins of slider to adjust the buttons by applying CSS inline styles.
scrollbarBarStyle {} Quickly set bar style (color, height, margin).
scrollbarTrackStyle {} Quickly set slidebar track style (color, height/width, margin) by applying CSS inline styles.
scrollbarOpacity 0.85 Opacity of the scrollbar while interacting with the slider.
scrollbarIdleOpacity 0.35 Opacity of the scrollbar in idle state.
scrollbarIdleTimeout 350 If scrollbarIdleOpacity option is not set to 1, apply the opacity after this ms value.
scrollBarIdleFadeoutT 200 Fadeout time of the scrollbar in ms.
scrollBarMouseShowBindTo 'both' Bind mouseenter opacity handling functions to scrollbar itself or container, possible values are: 'scrollBar', 'container', 'both' or false.
scrollBarVerticalCenterThumbs true Center thumbnails when vertical scrollbar is enabled and is not visible because there is nothing to scroll.
scrollBarHorizontalMiddleThumbs true Center thumbnails when horizontal scrollbar is enabled and is not visible because there is nothing to scroll.
accVelocity 45 Acceleration velocity for touch devices or when dragging with the mouse.
touchOpt {smoothMove: 12, pressScrollSpeed: 6} Override any options for touch enabled devices, e.g. touchOpt: {btn: false, scrollBarIndicator: true, scrollbarIdleOpacity: 0}

API Methods

jQuery(selector).axZmThumbSlider(method, [arguments]); e.g.:


		$('#slider1').axZmThumbSlider('scrollBy', '50px');
		

You can chain all methods except getters. Some methods like appendThumb have also callbacks, and the arguments reference e.g. the thumb, which was added to the slider.

MethodDescriptionArguments
stop Stop initialized plugin -
run Run initialized plugin -
destroy Restore element to initial state -
rebuild Destroy and rebuild plugin -
scrollBy Scroll by a specified amount of pixels or prc String, px or % value, e.g. '20px' or '50%'
scrollTo Scroll to specified thumb or position
  1. Options object:
    • thumb: integer or string; integer e.g. 3 will scroll to third thumb; string e.g. '120px' or '50%' will scroll to this specified location
    • thumbPos: string; if thumb is integer (scroll to some thumb), the target position within visible area, possible values: first, middle or last
    • noAnm: bool; if true scrollTo position will be reached immediately without any animation
    • triggerClick: bool; trigger click on the thumb
    • highlight: bool; only highlight thumb
If agrument is not an options object, then it will be interpreted as thumb, e.g.
$('#slider1').axZmThumbSlider('scrollTo', {thumb: 7});
is the same as
$('#slider1').axZmThumbSlider('scrollTo', 7);
appendContent Append content if in contentMode.
  1. Well formated html as string
  2. Callback function
prependContent Prepend content if in contentMode.
  1. Well formated html as string
  2. Callback function
removeAllThumbsRemove all thumbs
  1. Callback function
removeThumbRemove thumb
  1. Thumb number or selector, see also isThumb
  2. Callback function
appendThumbAppend thumb
  1. Thumb image path as tring, object or formated html as string.
  2. Optional click function
  3. Optional callback function with first argument as jQuery reference to the appended element (thumb) and the second argument as thumb number e.g.
    
    							$('#slider1').axZmThumbSlider(
    								'appendThumb', 
    								'/pic/slider_demo_images/image_01.jpg', 
    								function(){
    									// Click event
    									alert('123');
    								}, 
    								function(el, no){
    									// Callback, after thumb added slide to it
    									$('#slider1').axZmThumbSlider('scrollTo', no);
    								}
    							); 
    							
prependThumbPrepend Thumb
  1. Thumb image path as tring, object or formated html as string
  2. Optional click function
  3. Optional callback function with first argument as jQuery reference to the prepended element (thumb) and the second argument as thumb number
insertThumbAfterInsert Thumb after some other thumb
  1. Thumb image path as tring, object or formated html as string
  2. Optional click function
  3. After as thumb number, selector, ...
  4. Optional callback function with first argument as jQuery reference to the inserted element (thumb) and the second argument as thumb number
insertThumbBeforeInsert Thumb before some other thumb
  1. Thumb image path as tring, object or formated html as string
  2. Optional click function
  3. Before as thumb number, selector, ...
  4. Optional callback function with first argument as jQuery reference to the inserted element (thumb) and the second argument as thumb number
changeThumbSizeDynamically change size of the thumbnails
  1. li: CSS style for li element
  2. img: CSS style for image
  3. size: Size of the container element (width or height); if 'auto' the size will be instantly determined
  4. scrollTo: Specify if it should be scrolled to current selected thumb e.g.
    
    							$('#slider1').axZmThumbSlider('changeThumbSize', {
    								li: {width: 150, height: 150}, 
    								img: {maxHeight: '140px', maxHeight: '140px', height: '', width: ''}, 
    								size: 'auto',
    								scrollTo: true,
    								clb: null
    							});
    							
  5. clb: callback function
unselectRemove "selected" class from all thumbs -
selectSelect specified thumb
  1. Thumb number or selector, see also isThumb
  2. Bool - trigger click
getNumberThumbsReturns number of currently loaded thumbs -
isThumbReturns n - (thumb number) from passed argument;
  1. Argument can be just number to confirm it is there, selector or object
getVisibleThumbReturns number of thumb which is visible first
  1. If true returns thumb from right / bottom
randomize Shuffle thumbs within loader element -
getUlEll Returns scrolling content jQuery element (ul or div in contentMode) -
sortMapReorder thumbs in the slider upon data attribute value
  1. Object which maps the order, e.g. {1:3,2:1} which would mean, that at first place there will be thumb with specified data attribute equals to three, at second place thumb with data attribute equals to one
  2. String: name of data attribute, e.g. data-number
  3. Optional callback function
sortByDataSort thumbnails by some data value
  1. Data name
  2. Callback function
triggerClickTrigger click on an thumbnail
  1. Thumbnail

Callbacks

The usage is same as with options.

Callback / OptionDefaultDescription
onPull null Function to execute after reached end or beginning of the slider, e.g. make a call to add other thumbs (see methods below)
holdPullPx 50 Min pixel to pull in either direction to trigger onPull
holdPullTime 750 Min time to pull in either direction to trigger onPull
onInit null Callback when plugin is created

Comments (0)

Leave a Comment

Looking for a place to add a personal image? Visit www.gravatar.com to get Your own gravatar, a globally-recognized avatar. After you're all setup, your personal image will be attached every time you comment.

To use live-support-chat, you need to have Skype installed on your device. In case live support over Skype is not available immediately, please leave us a message or send an email by using the contact form.

We answer every inquiry or question that relates to the AJAX-ZOOM software!

Live-Support-Chat