Thumbslider

What is this?

A responsive javascript carousel with thumbnails.

Features

Creates thumbnails from slide content
Carousel structure is responsive and scalable within container dimensions
Plain Javascript - no reliance on any framework (animation is pluggable)

Fantastic! How do I get it?

npm

npm install thumbslider --save

bower

bower install thumbslider --save

What's the Setup?

Add thumbslider resources to your html <head>.

<link href="../dist/thumbslider.min.css" rel="stylesheet" />
 
<script src=".../dist/thumbslider.min.js"></script>

Polyfills are available also (See Polyfilling section).

Next, you need to have a container element with some content

<div id="carousel_container" class="ts-theme-default">
  ...
</div>

Make sure the container is styled to have a width and height.

Finally, to create and render the carousel (with default options)

var carousel = thumbslider.create('carousel_container');
carousel.start(); // start rotation

Animation can be plugged into thumbslider.

For instance, if you have JQuery in your page, you can create the carousel like so:

var carousel = thumbslider.create('carousel_container', { animator: thumbslider.tweeners.jquery });

How Does It All Work?

To start, here's some example content:

<div id="carousel_container" class="ts-theme-default">
  <div>
    <h1>
      <span data-ts-thumb>Top Header</span>
    </h1>
    <p>Paragraph Content</p>
  </div>
  <div data-ts-name="sub-topic">
    <h2>Sub Header</h2>
  </div>
  More Content Here!
  <img src="http://www.server.com/path/to/some/image.png" />
</div>

thumbslider assumes that every top-level non-text child node of the container is a content item.

In the above example content, the content items would be the two top level <div> elements and the <img> element.

Each content item is given an identifier in the carousel. This name comes from its 'data-ts-name' attribute.

<div data-ts-name="sub-topic">
  ...
</div>

If no attribute is specified a random identifier is generated.

A thumbnail node for the content item is derived from the content itself. This node will be selected as

the first descendant of the content item found having a 'data-ts-thumb' attribute, or
the first non-text node in the content item, or
the content item itself

So, in the above example

the first <div> content item uses the <span> as its thumbnail item
the second <div> will have it's <h2> element as its thumbnail
and the <img> content item will also double as the thumbnail itself

The content item is always cloned and copied to the selector as a thumb element. You can instead have the thumb element moved from its current location by specifying 'remove' as the value of 'data-ts-thumb'.

<div>
  <h1>
    <span data-ts-thumb="remove">Top Header</span>
  </h1>
  ...
</div>

Here's a quick ref for the content attributes.

data-ts-name (optional: for top-level container child)
Gives the content item a name. A random name is generated if not specified.
data-ts-thumb (optional: for any descendant of a content item)
Identifies element to be used as thumbnail for the content item. Specify 'remove' as value for attribute to prevent cloning. The first non-text node in the content item or the content item itself is used if not specified.

Configuration Options

var config = { ... }
thumbslider.create('my_carousel_id', config);

option	type	default	description
activeClass*	string	'active'	CSS class name to add to the current content item
animator	function	(default non-animating function)	Function for animation (See Animators section)
icons*	Object	(css triangles)	Class names for the nav icons (See Icon Controls section)
pauseOnMouseover*	boolean	true	Pause carousel rotation on mouseover?
responsive	object	{ xs: 480, sm: 768, md: 1024, lg: 1200 }	Responsive labels and thresholds (See Configuring Responsively section)
rotateDuration*	number	0.8	Seconds of carousel rotation animation
rotateEasing*	any	null	Library-specific easing value for carousel rotation
rotateInterval*	number	3	Seconds between each rotation
rotateIntermission*	number	3	Seconds to wait before restarting rotation after user interaction
selectorDisplay*	string	'visible'	Display as 'hidden', 'visible', 'transient', or 'overlay' (See Selector Display section)
selectorHideDelay*	number	0	number of seconds before hiding a displayed 'transient' selector. Set to `0` to disable
selectorPosition*	string	'bottom'	Position selector at 'top', 'bottom', 'left', or 'right'
selectorSize*	number	0.2	Size of selector (either height or width dependent upon selectorPosition) as percentage of container
showIconsOnHover*	boolean	true	Show controls on carousel mouse hovers? (Controls always shown for `false`)
showSelector*	boolean	true	Display 'transient' selector initially?
showThumbContent*	boolean	true	Display content for thumbnails?
shuffle*	boolean	false	Shuffle the carousel content items?
slideScaleType*	object	{ img: 'content-max', def: 'none' }	Slide scaling by tag or class name (See Content Scaling section)
slideTransition*	function	(default 'slide' function)	Content slide transition animation (See Slide Transitions section)
startAt*	string or number	(first content item)	Content item name or index to display when carousel loads
thumbScaleType*	object	{ img: 'content-max', def: 'viewer' }	Thumb scaling by tag or class name (See Content Scaling section)
thumbSize*	number	1.0	ratio of secondary to primary dimension (at `1.0` carousel tries to maintain square-shaped thumbs)
toggleDuration*	number	0.8	Seconds of 'transient' selector toggle
toggleEasing*	any	null	Library-specific easing value for 'transient' selector toggle
viewerOrientation*	string	'horizontal'	Direction of viewer scroll ('vertical' or 'horizontal')

* = option can be configured responsively

Animators

JQuery

{ animator: thumbslider.tweeners.jquery }

GreenSock (requires TweenMax and ScrollToPlugin)

{ animator: thumbslider.tweeners.gsap }

No animation (the default)

{ animator: thumbslider.tweeners.none }

Custom

{ animator: function(element, time, params) { ... } }

Animator Function Parameters

param	type	description
element	object	DOM Element to be animated
time	number	Animation duration in seconds
params	object	Additional animation parameters
params.after	function	function to execute when/after animation completes
params.attrs	object	element attributes to be animated
params.before	function	function to execute when/before animation begins
params.during	function	function to execute for each frame of animation
params.ease	any	easing value for animation
params.styles	object	element styles to be animated

Note that individual animation requests will generally include only a subset of params.

Icon Controls

There are four possible values for config.icons, and the defaults are

{
    icons:
    {
        top: 'deficon',
        left: 'deficon',
        bottom: 'deficon',
        right: 'deficon'
    }
}

The class name values are added directly to the <i> tag for the control.

<i class="deficon"></i>

The default 'deficon' class simply makes black css triangles for the nav controls.

To use actual icons you can use your favorite icon provider.

For instance, here is an example using Font Awesome.

{
    icons:
    {
        top: 'fa fa-chevron-up',
        left: 'fa fa-chevron-left',
        bottom: 'fa fa-chevron-down',
        right: 'fa fa-chevron-right',
    }
}

This uses the library's 'chevron' icons for nav controls. Don't forget to properly setup your icon provider in your html.

Selector Display

There are four possible values for config.selectorDisplay.

value	viewable	offsets viewer	details
hidden	never	no	Selector is hidden from view and not updated
visible	always	yes	Selector is part of content pane
transient	toggle	no	User can toggle selector display
overlay	always	no	Similar to 'transient' but without toggle

Note that the following config options have no effect unless selector display is 'transient'.

selectorHideDelay
showSelector
toggleDuration
toggleEasing

Content Scaling

HTML content can be scaled for either the slide or the thumbnail, and this scaling is specified by element tagname or css classname.

For instance, to scale all image content items to completely fill the thumbnail,

{ thumbScaleType: { img: 'content-max' } }

Or, to scale content items with a 'scale-me' class to fit in the slide,

{ slideScaleType: { 'scale-me': 'content-min' } }

There are four possible values for config.slideScaleType and config.thumbScaleType.

none
No content scaling is performed.
content-max
The content element is scaled up or down so that its smallest dimension fits in the slide or thumbnail. The content is then centered for the opposite dimension.
content-min
The content element is scaled up or down so that its largest dimension fits in the slide or thumbnail. The content is then centered for the opposite dimension.
viewer
The content container (ts-slide-content or ts-thumb-content) has its size increased to the size of the viewer area to allow content to flow and then (css transform) scaled back down by 50%. This is obviously more useful for thumbnails.

Slide Transitions

You can specify the transition for slide rotation in the configuration.

{ slideTransition: thumbslider.transitions.xxx }

Replace 'xxx' in the above with one of the following:

fade
Fades in the next slide while fading out the current one.
slide
Slides in the next slide while sliding out the current one.
stack
Slides the next slide onto the current one.
unstack
Slides the current slide off to reveal the next one.

Configuring Responsively

The default responsive setup is

{ responsive: { xs: 480, sm: 768, md: 1024, lg: 1200 } }

Use responsive labels ('xs', 'sm', etc.) inside other config options to have those values change responsively.

{
    selectorDisplay: { xs: 'hidden', def: 'transient' },
    selectorSize: { sm: 0.2, lg: 0.24, def: 0.3 }
}

Remember that/to

responsiveness is based on carousel container width, not window width.
the responsive label whose value is greater than or equal to the current container width will be in effect.
always specify a default (def) value in a config option to catch width values beyond the defined responsive configuration.
if a config option does not specify a value for the responsive label currently in effect the next level label (or def) will be used.

Generated Carousel HTML

<div class="ts-carousel">
  <div class="ts-viewer">
    <div class="ts-control ts-prev">
      <i class=""></i>
    </div>
    <div class="ts-view">
      <div class="ts-slides">
        <div class="ts-slide" data-ts-name="[CONTENT_NAME]">
          <div class="ts-slide-content">
            < content element >
          </div>
        </div>
        ... (repeated slide elements)
      </div>
    </div>
    <div class="ts-control ts-next">
      <i class=""></i>
    </div>
  </div>
  <div class="ts-selector">
    <div class="ts-select">
      <div class="ts-thumbs">
        <div class="ts-focus"></div>
        <div class="ts-thumb" data-ts-name="[CONTENT_NAME]">
          <div class="ts-thumb-overlay">
            <div class="ts-thumb-content">
              < content element >
            </div>
          </div>
        </div>
        ... (repeated thumb elements)
      </div>
    </div>
    <div class="ts-toggle"></div>
  </div>
</div>

Note that above HTML will replace original container contents.

Contextually Applied CSS Classes

For 'ts-content' element:
- 'ts-selector-xxx'
  Applied with 'xxx' as the current config.selectorDisplay value
- 'ts-selector-xxx'
  Applied with 'xxx' as the current config.selectorPosition value. This is not applied if config.selectorDisplay is 'hidden'.
- 'ts-selector-xxx'
  Applied with 'xxx' as the current orientation of the selector ('horizontal' or 'vertical'). This is not applied if config.selectorDisplay is 'hidden'.
For 'ts-slide' and 'ts-thumb' elements:
- config.activeClass
  Applied as these content items become current via selection or rotation.

Theming/Styling Guidelines

Remember that the carousel container must have height and width set.

When applying CSS styles to the generated HTML elements know that

properties
top, left, bottom, right, position	should not be changed
z-index, overflow	can be set as necessary but not recommended
height, width	are ignored (values calculated and set inline)

In general, you should use pixel measurements (px) for styling your carousel.

There are a few themes available in /dist/themes that you can use outright or as a starting point for your own theme.

Thumbslider API

Module Functions

The following functions are available on the thumbslider module.

create(name:string, options:object):Carousel
Creates a new carousel instance.
get(name:string):Carousel
Returns a given carousel instance or null if not found.
names():array
Returns a list of all carousel names.
options(name:string):object
Returns a copy of the configuration options used to create a given carousel instance or null if not found.
update(name:string, options:object):Carousel
Resets the given carousel with the specified configuration changes (i.e., these changes are merged with the carousel's original configuration)

Carousel Interface

There are a few methods that can be called on a thumbslider carousel instance.

currentIndex():number
Returns the index of the current content item.
getName():string
Returns the name (container id) of the carousel instance.
getSlide(id:string|number):node
Returns the DOM element for the content slide by index or name.
getThumb(id:string|number):node
Returns the DOM element for the content thumbnail by index or name.
itemCount():number
The number of content items in the carousel.
remodel():this
Recalculates the display of the carousel. Call this if you make style or other display changes to the carousel.
start():this
Starts carousel rotation.
stop():this
Stops carousel rotation.

Also see Carousel Events below for event registration methods available on the carousel interface.

Carousel Events

thumbslider uses event-mixer for event emission.

Event registration methods are mixed into the carousel interface using the below event names.

event name	data params	default preventable?	details
rotate	`nextIndex:number`	yes	occurs just before the next content item is displayed
toggle	`shown:boolean` `willShow:boolean`	yes	occurs just before a transient selector is hidden/shown. This can be fired even if `shown == willShow`

Anything Else I Should Know?

Polyfilling

The polyfill-candidate language features needed by thumbslider include

    Array.isArray
    Array.prototype.filter
    Array.prototype.find
    Array.prototype.forEach
    Array.prototype.indexOf
    Array.prototype.map
    Array.prototype.reduce
    document.querySelector
    Element.prototype.classList
    getComputedStyle
    Object.assign
    Object.keys
    Symbol

You can use these by including 'thumbslider.poly.js' rather than 'thumbslider.js'.

<script type="text/javascript" src="../dist/thumbslider.poly.min.js"></script>

This makes the thumbslider export a function. Pass this function a callback that will get executed once the polyfills are loaded.

thumbslider(function(ts)
{
    // Create carousel instances here
    ts.create( ... );
});

The first call to this function adds script tag to <head> that grabs the necessary polyfills from the Polyfill.io CDN. Subsequent calls are queued or executed immediately if the features are already loaded.

Links

{ distrib } { updates } { feedback } { license } { versioning }

Please be sure to check 'updates' link when upgrading to a new version.

Examples

There are a few thumbslider examples in the /examples folder. These will be posted online somewhere soon.

Tests

thumbslider uses Jasmine for testing and Istanbul for coverage analysis.

Test coverage is imcomplete at this time.

npm test

In browsers thumbslider works as intended in the latest versions of Firefox, Chrome, Safari, and Opera. It works well in Edge also. There are some issues with IE for now.

Finally

Happy Carouselling!

thumbslider

Thumbslider

What is this?

Features

Fantastic! How do I get it?

npm

bower

What's the Setup?

How Does It All Work?

Configuration Options

Animators

Icon Controls

Selector Display

Content Scaling

Slide Transitions

Configuring Responsively

Generated Carousel HTML

Contextually Applied CSS Classes

Theming/Styling Guidelines

Thumbslider API

Module Functions

Carousel Interface

Carousel Events

Anything Else I Should Know?

Polyfilling

Links

Examples

Tests

Finally

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

Weekly Downloads

Version

License

Last publish

Collaborators

thumbslider

Thumbslider

What is this?

Features

Fantastic! How do I get it?

npm

bower

What's the Setup?

How Does It All Work?

Configuration Options

Animators

Icon Controls

Selector Display

Content Scaling

Slide Transitions

Configuring Responsively

Generated Carousel HTML

Contextually Applied CSS Classes

Theming/Styling Guidelines

Thumbslider API

Module Functions

Carousel Interface

Carousel Events

Anything Else I Should Know?

Polyfilling

Links

Examples

Tests

Finally

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Last publish

Collaborators

Weekly Downloads