Migration Guide - Tiny Slider

Overview

Tiny Slider v2 introduces significant improvements and optimizations. This guide helps you migrate from v1 to v2 and understand the breaking changes.

Current version: v2.9.4Previous versions: v1, v0

What’s New in v2

Performance Improvements

Percentage-based Widths

Uses % instead of px for slide widthsBenefit: No recalculation needed on window resize

/* v1: Fixed pixel widths */
.slide { width: 300px; }

/* v2: Percentage widths */
.slide { width: 33.33%; }

CSS Media Queries

Leverages native CSS media queries when supportedBenefit: Better performance and browser optimization

LocalStorage Caching

Browser capabilities saved to localStorageBenefit: No redundant feature detection on subsequent page loads

// Cached capabilities
// - tC: calc() support
// - tPL: Percentage Layout support
// - tMQ: Media Query support
// - tTf: Transform support
// - t3D: 3D Transform support
// - tTDu/tTDe: Transition Duration/Delay
// - tADu/tADe: Animation Duration/Delay
// - tTE/tAE: Transition/Animation End events

New Features

Enhanced Responsive Options (v2.1.0+)

More options available in the responsive object:

var slider = tns({
  container: '.my-slider',
  items: 1,
  responsive: {
    640: {
      items: 2,
      gutter: 20,
      edgePadding: 20,
      controls: true,
      nav: true,
      autoplay: true
      // Many more options now supported!
    }
  }
});

Center Option (v2.9.2+)

var slider = tns({
  container: '.my-slider',
  items: 3,
  center: true  // New: Center active slide
});

Breaking Changes

1. Controls and Nav Position

Breaking Change: Controls and navigation are now inserted before the slider instead of after.

HTML Structure Change

<!-- v1: Controls/nav after slider -->
<div class="slider-wrapper">
  <div class="my-slider">
    <!-- slides -->
  </div>
  <!-- Controls inserted here (after) -->
  <!-- Nav inserted here (after) -->
</div>

<!-- v2: Controls/nav before slider -->
<div class="slider-wrapper">
  <!-- Controls inserted here (before) -->
  <!-- Nav inserted here (before) -->
  <div class="my-slider">
    <!-- slides -->
  </div>
</div>

CSS Update Required

/* v1: Positioning for after slider */
.my-slider + .tns-controls {
  margin-top: 20px;
}

/* v2: Update for before slider */
.tns-controls {
  margin-bottom: 20px;  /* Changed from margin-top */
}

.tns-controls + .tns-outer {
  margin-top: 0;
}

Flexbox Layout Update

/* v1 */
.slider-wrapper {
  display: flex;
  flex-direction: column;
}

/* v2: Controls now come first */
.slider-wrapper {
  display: flex;
  flex-direction: column-reverse;  /* Or reorder children */
}

/* Alternative: Use order property */
.tns-controls { order: 2; }
.tns-outer { order: 1; }

Visual Comparison

<!-- v1 Structure -->
<wrapper>
  <slider/>
  <controls/>
  <nav/>
</wrapper>

<!-- v2 Structure -->
<wrapper>
  <controls/>
  <nav/>
  <slider/>
</wrapper>

2. Autoplay Button Position

Breaking Change: The autoplay button is no longer part of the nav container (v2.1.0+).

Structure Change

<!-- v1: Autoplay button inside nav -->
<div class="tns-nav">
  <button data-nav="0"></button>
  <button data-nav="1"></button>
  <button data-action="start">Start</button>  <!-- Inside nav -->
</div>

<!-- v2: Autoplay button separate -->
<button data-action="start">Start</button>  <!-- Separate -->
<div class="tns-nav">
  <button data-nav="0"></button>
  <button data-nav="1"></button>
</div>

CSS Update

/* v1: Target within nav */
.tns-nav [data-action] {
  margin-left: 10px;
}

/* v2: Target independently */
[data-action] {
  display: block;
  margin: 10px 0;
}

/* Position autoplay button */
[data-action] {
  position: absolute;
  top: 10px;
  right: 10px;
}

3. Selector Changes in SCSS

Breaking Change: CSS selectors have changed in tiny-slider.scss. Update your custom styles accordingly.

Key Selector Changes

// v1 selectors (approximate)
.slider { }
.slider__item { }

// v2 selectors (from tiny-slider.scss)
.tns-outer { }
.tns-slider { }
.tns-item { }
.tns-slide-active { }
.tns-slide-cloned { }

Update Your CSS

/* v1: Old selectors */
.slider { }
.slider .item { }
.slider .item.active { }

/* v2: New selectors */
.tns-slider { }
.tns-slider .tns-item { }
.tns-slider .tns-slide-active { }

Import Updated SCSS

If you’re using SCSS:

// v1
@import 'path/to/v1/tiny-slider';

// v2: Update path and check for selector changes
@import 'path/to/v2/tiny-slider';

// Override with your custom styles
.tns-slider {
  // Your customizations
}

Migration Checklist

Update Package

# npm
npm install tiny-slider@latest

# bower
bower install tiny-slider

# CDN
# Update to latest version
# https://cdnjs.cloudflare.com/ajax/libs/tiny-slider/2.9.4/tiny-slider.css
# https://cdnjs.cloudflare.com/ajax/libs/tiny-slider/2.9.4/min/tiny-slider.js

Update Controls/Nav Styles

Adjust CSS for the new position of controls and navigation (now before slider).

/* Update margins, positioning, and flex order */
.tns-controls {
  margin-bottom: 20px;  /* Was margin-top */
}

Update Autoplay Button Styles

Move autoplay button styles out of nav context.

/* Remove .tns-nav prefix if present */
[data-action] {
  /* Standalone button styles */
}

Update Selector References

Search and replace old selectors in your CSS and JavaScript.

// v1
document.querySelector('.slider .item');

// v2
document.querySelector('.tns-slider .tns-item');

Test Responsive Behavior

Verify responsive options still work correctly with the new system.

Check LocalStorage

Clear localStorage if testing, as v2 uses it for caching.

// Clear tiny-slider cache
localStorage.removeItem('tnsApp');
localStorage.removeItem('tC');
localStorage.removeItem('tPL');
// ... etc

Step-by-Step Migration Example

Before (v1)

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="tiny-slider-v1.css">
  <style>
    .slider { max-width: 900px; margin: 0 auto; }
    .slider .item { padding: 10px; }
    .slider + .controls { margin-top: 20px; }
  </style>
</head>
<body>
  <div class="slider">
    <div class="item">Slide 1</div>
    <div class="item">Slide 2</div>
    <div class="item">Slide 3</div>
  </div>
  
  <script src="tiny-slider-v1.js"></script>
  <script>
    var slider = tns({
      container: '.slider',
      items: 3
    });
  </script>
</body>
</html>

After (v2)

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/tiny-slider/2.9.4/tiny-slider.css">
  <style>
    /* Update: tns-slider instead of slider */
    .my-slider { max-width: 900px; margin: 0 auto; }
    
    /* Update: tns-item instead of item */
    .my-slider .tns-item { padding: 10px; }
    
    /* Update: controls now BEFORE slider */
    .tns-controls { 
      margin-bottom: 20px;  /* Changed from margin-top */
      text-align: center;
    }
    
    /* Update: nav also before slider */
    .tns-nav { 
      margin-bottom: 20px;
      text-align: center;
    }
    
    /* Update: autoplay button is separate */
    [data-action] {
      display: block;
      margin: 10px auto;
    }
  </style>
</head>
<body>
  <div class="my-slider">
    <div>Slide 1</div>
    <div>Slide 2</div>
    <div>Slide 3</div>
  </div>
  
  <script src="https://cdnjs.cloudflare.com/ajax/libs/tiny-slider/2.9.2/min/tiny-slider.js"></script>
  <script>
    var slider = tns({
      container: '.my-slider',
      items: 3
    });
  </script>
</body>
</html>

Common Migration Issues

Issue 1: Controls Not Visible

Solution

Problem: Controls appear in unexpected location or are hidden.Solution: Update positioning CSS

/* Fix absolute positioning */
.slider-wrapper {
  position: relative;
}

.tns-controls {
  position: absolute;
  top: 50%;  /* Adjust as needed */
  width: 100%;
  /* Remove bottom: 0 if you had it */
}

.tns-controls button[data-controls="prev"] {
  left: 10px;
}

.tns-controls button[data-controls="next"] {
  right: 10px;
}

Issue 2: JavaScript Selector Errors

Solution

Problem: Custom JavaScript can’t find slider elements.Solution: Update selectors

// v1
var slides = document.querySelectorAll('.slider .item');
var activeSlide = document.querySelector('.slider .item.active');

// v2: Use getInfo() method instead
var slider = tns({ container: '.my-slider' });
var info = slider.getInfo();
var slides = info.slideItems;
var activeIndex = info.index;
var activeSlide = slides[activeIndex];

Issue 3: Flexbox Layout Broken

Solution

Problem: Flex layout doesn’t account for controls-first order.Solution: Use flex order or reverse direction

/* Option 1: Flex order */
.slider-wrapper {
  display: flex;
  flex-direction: column;
}

.tns-controls { order: 2; }
.tns-nav { order: 3; }
.tns-outer { order: 1; }

/* Option 2: Reverse direction */
.slider-wrapper {
  display: flex;
  flex-direction: column-reverse;
}

/* Option 3: Grid layout */
.slider-wrapper {
  display: grid;
  grid-template-areas:
    "slider"
    "controls"
    "nav";
}

.tns-outer { grid-area: slider; }
.tns-controls { grid-area: controls; }
.tns-nav { grid-area: nav; }

Issue 4: Custom Nav Styling Broken

Solution

Problem: Nav styles targeting autoplay button no longer work.Solution: Separate autoplay button styles

/* v1: Autoplay button in nav */
.tns-nav button:last-child {
  /* This was the autoplay button */
}

/* v2: Target separately */
[data-action] {
  /* Autoplay button styles */
}

.tns-nav button {
  /* Nav dot styles (no autoplay button here) */
}

Testing After Migration

Visual Inspection

Controls and navigation are positioned correctly
Autoplay button appears in expected location
Slides display properly at all breakpoints

Functional Testing

Click controls to navigate
Click navigation dots
Test keyboard navigation (if enabled)
Verify autoplay and pause

Responsive Testing

Test all breakpoints defined in responsive options
Verify layout doesn’t break at any size

Browser Testing

Test in target browsers
Verify localStorage caching works
Check console for errors

Getting Help

If you encounter migration issues:

GitHub Issues

Report bugs and ask questions

Changelog

Review all version changes

Demos

See v2 in action

Source Code

Examine implementation details

Version Comparison

| Feature | v1 | v2 | |---------|----|----|| | Slide Width Units | px | % | | CSS Media Queries | Limited | Full support | | LocalStorage Caching | No | Yes | | Controls Position | After slider | Before slider | | Autoplay Button | In nav | Separate | | Responsive Options | Basic | Extended | | Center Option | No | Yes (v2.9.2+) | | Performance | Good | Excellent |

Next Steps

Configuration

Learn v2 configuration options

API Reference

Complete v2 API documentation

Examples

View v2 implementation examples

Quickstart

Get started with v2

Get Started

Core Concepts

Guides

​Overview

​What’s New in v2

​Performance Improvements

​New Features

​Enhanced Responsive Options (v2.1.0+)

​Center Option (v2.9.2+)

​Breaking Changes

​1. Controls and Nav Position

​HTML Structure Change

​CSS Update Required

​Flexbox Layout Update

​2. Autoplay Button Position

​Structure Change

​CSS Update

​3. Selector Changes in SCSS

​Key Selector Changes

​Update Your CSS

​Import Updated SCSS

​Migration Checklist

​Step-by-Step Migration Example

​Before (v1)

​After (v2)

​Common Migration Issues

​Issue 1: Controls Not Visible

​Issue 2: JavaScript Selector Errors

​Issue 3: Flexbox Layout Broken

​Issue 4: Custom Nav Styling Broken

​Testing After Migration

​Getting Help

GitHub Issues

Changelog

Demos

Source Code

​Version Comparison

​Next Steps

Configuration

API Reference

Examples

Quickstart

Build docs developers (and LLMs) love

Overview

What’s New in v2

Performance Improvements

New Features

Enhanced Responsive Options (v2.1.0+)

Center Option (v2.9.2+)

Breaking Changes

1. Controls and Nav Position

HTML Structure Change

CSS Update Required

Flexbox Layout Update

2. Autoplay Button Position

Structure Change

CSS Update

3. Selector Changes in SCSS

Key Selector Changes

Update Your CSS

Import Updated SCSS

Migration Checklist

Step-by-Step Migration Example

Before (v1)

After (v2)

Common Migration Issues

Issue 1: Controls Not Visible

Issue 2: JavaScript Selector Errors

Issue 3: Flexbox Layout Broken

Issue 4: Custom Nav Styling Broken

Testing After Migration

Getting Help

Version Comparison

Next Steps