Options

Overview

Tiny-slider provides a comprehensive set of options to customize slider behavior. Options are passed to the tns() function during initialization.

const slider = tns({
  container: '.my-slider',
  items: 3,
  slideBy: 'page',
  autoplay: true
});

Container & Layout

container

HTMLElement | Element | string

default:".slider"

The slider container element or selector.

container: '.my-slider'
// or
container: document.querySelector('.my-slider')

mode

'carousel' | 'gallery'

default:"carousel"

Controls animation behavior:

carousel: Slides move to the side
gallery: Uses fade animations, changes all slides at once

axis

'horizontal' | 'vertical'

default:"horizontal"

The axis of the slider.

edgePadding

number

default:"0"

Space on the outside (in pixels).

edgePadding: 20

center

boolean

default:"false"

Center the active slide in the viewport.

Available from v2.9.2+

Display & Items

items

number

default:"1"

Number of slides being displayed in the viewport.

If slides ≤ items, the slider won’t be initialized.

items: 3

gutter

number

default:"0"

Space between slides (in pixels).

gutter: 10

fixedWidth

number | false

default:"false"

Controls width attribute of the slides. When set, each slide will have this fixed width in pixels.

fixedWidth: 300

autoWidth

boolean

default:"false"

Sets the width of slides to auto. If true, the width of each slide will be its natural width as an inline-block box.

autoWidth: true

autoHeight

boolean

default:"false"

Height of slider container changes according to each slide’s height.

autoHeight: true

controls

boolean

default:"true"

Controls the display and functionalities of controls components (prev/next buttons). If true, display the controls and add all functionalities.

controlsText

string[]

default:"['prev', 'next']"

Text or markup in the prev/next buttons.

controlsText: ['←', '→']

controlsContainer

HTMLElement | Element | string | false

default:"false"

The container element/selector around the prev/next buttons.

controlsContainer must have at least 2 child elements.

prevButton

HTMLElement | string | false

default:"false"

Customized previous button.

This option will be ignored if controlsContainer is a Node element or a CSS selector.

nextButton

HTMLElement | string | false

default:"false"

Customized next button.

This option will be ignored if controlsContainer is a Node element or a CSS selector.

nav

boolean

default:"true"

Controls the display and functionalities of nav components (dots). If true, display the nav and add all functionalities.

navPosition

'top' | 'bottom'

default:"top"

Controls nav position.

navContainer

HTMLElement | Element | string | false

default:"false"

The container element/selector around the dots.

navContainer must have at least same number of children as the slides.

navAsThumbnails

boolean

default:"false"

Indicate if the dots are thumbnails. If true, they will always be visible even when more than 1 slide displayed in the viewport.

Autoplay

autoplay

boolean

default:"false"

Toggles the automatic change of slides.

autoplayTimeout

number

default:"5000"

Time between 2 autoplay slides change (in milliseconds).

autoplayTimeout: 3000 // 3 seconds

autoplayDirection

'forward' | 'backward'

default:"forward"

Direction of slide movement (ascending/descending the slide index).

autoplayText

string[]

default:"['start', 'stop']"

Text or markup in the autoplay start/stop button.

autoplayText: ['▶', '⏸']

autoplayHoverPause

boolean

default:"false"

Stops sliding on mouseover.

autoplayButton

HTMLElement | string | false

default:"false"

The customized autoplay start/stop button or selector.

autoplayButtonOutput

boolean

default:"true"

Output autoplayButton markup when autoplay is true but a customized autoplayButton is not provided.

autoplayResetOnVisibility

boolean

default:"true"

Pauses the sliding when the page is invisible and resumes it when the page becomes visible again (Page Visibility API).

Animation & Mode

speed

number

default:"300"

Speed of the slide animation (in milliseconds).

speed: 500

animateIn

string

default:"tns-fadeIn"

Name of intro animation class (for gallery mode).

animateOut

string

default:"tns-fadeOut"

Name of outro animation class (for gallery mode).

animateNormal

string

default:"tns-normal"

Name of default animation class.

animateDelay

number | false

default:"false"

Time between each gallery animation (in milliseconds).

loop

boolean

default:"true"

Moves throughout all the slides seamlessly.

rewind

boolean

default:"false"

Moves to the opposite edge when reaching the first or last slide.

slideBy

number | 'page'

default:"1"

Number of slides going on one “click”.

slideBy: 1        // Move one slide at a time
slideBy: 'page'   // Move one page at a time

startIndex

number

default:"0"

The initial index of the slider.

startIndex: 2 // Start at third slide

Interaction

touch

boolean

default:"true"

Activates input detection for touch devices.

mouseDrag

boolean

default:"false"

Changing slides by dragging them with mouse.

arrowKeys

boolean

default:"false"

Allows using arrow keys to switch slides.

swipeAngle

number | boolean

default:"15"

Swipe or drag will not be triggered if the angle is not inside the range when set.

swipeAngle: 15  // Degrees

preventActionWhenRunning

boolean

default:"false"

Prevent next transition while slider is transforming.

Available from v2.9.1+

preventScrollOnTouch

'auto' | 'force' | false

default:"false"

Prevent page from scrolling on touchmove:

auto: Check if touch direction matches slider axis first
force: Always prevent page scrolling
false: Don’t prevent scrolling

Available from v2.9.1+

Responsive

responsive

ResponsiveOptions | false

default:"false"

Defines options for different viewport widths. Breakpoints behave like (min-width: breakpoint) in CSS.

responsive: {
  640: {
    edgePadding: 20,
    gutter: 20,
    items: 2
  },
  900: {
    items: 3
  }
}

See Responsive Options for available options.

Advanced

lazyload

boolean

default:"false"

Enables lazyloading images that are currently not viewed, thus saving bandwidth.Requires:

Class matching lazyloadSelector on images
data-src attribute with real image src
width attribute for autoWidth slider

lazyloadSelector

string

default:".tns-lazy-img"

The CSS selector for lazyload images.

Available from v2.9.1+

nested

'inner' | 'outer' | false

default:"false"

Define the relationship between nested sliders.

Make sure you run the inner slider first, otherwise the height of the inner slider container will be wrong.

freezable

boolean

default:"true"

Indicate whether the slider will be frozen (controls, nav, autoplay and other functions will stop work) when all slides can be displayed in one page.

disable

boolean

default:"false"

Disable slider.

useLocalStorage

boolean

default:"true"

Save browser capability variables to localStorage and without detecting them every time the slider runs.

nonce

string | false

default:"false"

Nonce attribute for inline style tag to allow slider usage without unsafe-inline Content Security Policy source.

onInit

() => void | false

default:"false"

Callback to be run on initialization.

onInit: () => {
  console.log('Slider initialized!');
}

Responsive Options Interface

The following options can be redefined in the responsive field:

Option	Type	Description
`startIndex`	number	Initial slide index
`items`	number	Number of visible slides
`slideBy`	number \| ‘page’	Slides to move per action
`speed`	number	Animation speed
`autoHeight`	boolean	Dynamic container height
`fixedWidth`	number \| false	Fixed slide width
`edgePadding`	number	Outside spacing
`gutter`	number	Space between slides
`center`	boolean	Center active slide
`controls`	boolean	Show/hide controls
`controlsText`	string[]	Control button text
`nav`	boolean	Show/hide nav dots
`autoplay`	boolean	Enable/disable autoplay
`autoplayHoverPause`	boolean	Pause on hover
`autoplayResetOnVisibility`	boolean	Reset on visibility change
`autoplayText`	string[]	Autoplay button text
`autoplayTimeout`	number	Time between slides
`touch`	boolean	Touch input detection
`mouseDrag`	boolean	Mouse drag support
`arrowKeys`	boolean	Arrow key navigation
`disable`	boolean	Disable slider

Responsive Behavior

The breakpoints behave like (min-width: breakpoint) in CSS, so an undefined option will be inherited from previous small breakpoints.

const slider = tns({
  container: '.my-slider',
  items: 1,          // Default: 1 item
  gutter: 0,
  responsive: {
    640: {
      items: 2,        // >= 640px: 2 items
      gutter: 20       // >= 640px: 20px gutter
    },
    768: {
      gutter: 30       // >= 768px: still 2 items, but 30px gutter
    },
    1024: {
      items: 3         // >= 1024px: 3 items, 30px gutter (inherited)
    }
  }
});

Complete Options Table

Option	Type	Default	Description
`container`	HTMLElement \| Element \| string	`.slider`	Slider container
`mode`	`carousel` \| `gallery`	`carousel`	Animation mode
`axis`	`horizontal` \| `vertical`	`horizontal`	Slider axis
`items`	number	`1`	Visible slides
`gutter`	number	`0`	Space between slides (px)
`edgePadding`	number	`0`	Outside space (px)
`fixedWidth`	number \| false	`false`	Fixed slide width
`autoWidth`	boolean	`false`	Auto slide width
`autoHeight`	boolean	`false`	Dynamic height
`center`	boolean	`false`	Center active slide
`controls`	boolean	`true`	Show controls
`controlsText`	string[]	`['prev', 'next']`	Control text
`controlsContainer`	HTMLElement \| string \| false	`false`	Custom controls container
`prevButton`	HTMLElement \| string \| false	`false`	Custom prev button
`nextButton`	HTMLElement \| string \| false	`false`	Custom next button
`nav`	boolean	`true`	Show navigation dots
`navPosition`	`top` \| `bottom`	`top`	Nav position
`navContainer`	HTMLElement \| string \| false	`false`	Custom nav container
`navAsThumbnails`	boolean	`false`	Use thumbnails
`arrowKeys`	boolean	`false`	Arrow key navigation
`speed`	number	`300`	Animation speed (ms)
`autoplay`	boolean	`false`	Auto slide change
`autoplayTimeout`	number	`5000`	Autoplay interval (ms)
`autoplayDirection`	`forward` \| `backward`	`forward`	Autoplay direction
`autoplayText`	string[]	`['start', 'stop']`	Autoplay button text
`autoplayHoverPause`	boolean	`false`	Pause on hover
`autoplayButton`	HTMLElement \| string \| false	`false`	Custom autoplay button
`autoplayButtonOutput`	boolean	`true`	Output autoplay button
`autoplayResetOnVisibility`	boolean	`true`	Reset on visibility
`animateIn`	string	`tns-fadeIn`	Intro animation class
`animateOut`	string	`tns-fadeOut`	Outro animation class
`animateNormal`	string	`tns-normal`	Default animation class
`animateDelay`	number \| false	`false`	Gallery animation delay (ms)
`loop`	boolean	`true`	Seamless loop
`rewind`	boolean	`false`	Rewind at edges
`slideBy`	number \| `page`	`1`	Slides per action
`startIndex`	number	`0`	Initial slide
`responsive`	ResponsiveOptions \| false	`false`	Responsive config
`lazyload`	boolean	`false`	Enable lazy loading
`lazyloadSelector`	string	`.tns-lazy-img`	Lazy load selector
`touch`	boolean	`true`	Touch detection
`mouseDrag`	boolean	`false`	Mouse drag support
`swipeAngle`	number \| boolean	`15`	Swipe angle threshold
`preventActionWhenRunning`	boolean	`false`	Prevent actions during transition
`preventScrollOnTouch`	`auto` \| `force` \| false	`false`	Prevent page scroll
`nested`	`inner` \| `outer` \| false	`false`	Nested slider mode
`freezable`	boolean	`true`	Freeze when all visible
`disable`	boolean	`false`	Disable slider
`useLocalStorage`	boolean	`true`	Cache capabilities
`nonce`	string \| false	`false`	CSP nonce
`onInit`	Function \| false	`false`	Init callback

API

Options Reference

Overview

Option Categories

Container & Layout

Display & Items

Navigation Controls

Navigation Dots

Autoplay

Animation & Mode

Interaction

Responsive

Advanced

Responsive Options Interface

Responsive Behavior

Complete Options Table

Build docs developers (and LLMs) love

API

Options Reference

​Overview

​Option Categories

​Container & Layout

​Display & Items

​Navigation Controls

​Navigation Dots

​Autoplay

​Animation & Mode

​Interaction

​Responsive

​Advanced

​Responsive Options Interface

​Responsive Behavior

​Complete Options Table

Build docs developers (and LLMs) love

Overview

Option Categories

Container & Layout

Display & Items

Navigation Controls

Navigation Dots

Autoplay

Animation & Mode

Interaction

Responsive

Advanced

Responsive Options Interface

Responsive Behavior

Complete Options Table