Migration Guide

Guide for upgrading between Slick Carousel versions

Overview

This guide helps you migrate between different versions of Slick Carousel, highlighting breaking changes and new features.

Always backup your code and test thoroughly when upgrading Slick Carousel versions.

Migrating to Slick 1.4+

Version 1.4 introduced significant changes to the API, particularly around callbacks and methods.

Breaking Change: Callbacks → Events

Major Breaking Change: Callback methods were deprecated in Slick 1.4 and replaced with events.

This is the most significant change when upgrading from pre-1.4 versions.

Before (< 1.4): Callback Methods

// ❌ Old way (deprecated)
$('.slider').slick({
  onAfterChange: function(slider, currentSlide) {
    console.log('Slide changed to:', currentSlide);
  },
  onBeforeChange: function(slider, currentSlide, nextSlide) {
    console.log('Changing from', currentSlide, 'to', nextSlide);
  },
  onInit: function(slider) {
    console.log('Slider initialized');
  }
});

After (1.4+): Event-Based System

// ✅ New way (current)
$('.slider')
  .on('init', function(event, slick) {
    console.log('Slider initialized');
  })
  .on('beforeChange', function(event, slick, currentSlide, nextSlide) {
    console.log('Changing from', currentSlide, 'to', nextSlide);
  })
  .on('afterChange', function(event, slick, currentSlide) {
    console.log('Slide changed to:', currentSlide);
  })
  .slick();

Important: Events must be bound before initializing Slick, especially for the init event.

Complete Callback → Event Mapping

All Event Conversions

Old Callback (< 1.4)	New Event (1.4+)	Parameters
onAfterChange	afterChange	event, slick, currentSlide
onBeforeChange	beforeChange	event, slick, currentSlide, nextSlide
onInit	init	event, slick
onReInit	reInit	event, slick
onSetPosition	setPosition	event, slick
onSwipe	swipe	event, slick, direction
onEdge	edge	event, slick, direction
onLazyLoaded	lazyLoaded	event, slick, image, imageSource
onLazyLoadError	lazyLoadError	event, slick, image, imageSource

New Events in 1.4+

Version 1.4+ introduced additional events not available as callbacks:

$('.slider')
  // Fires after a breakpoint is hit
  .on('breakpoint', function(event, slick, breakpoint) {
    console.log('Breakpoint triggered:', breakpoint);
  })
  // Fires when slider is destroyed
  .on('destroy', function(event, slick) {
    console.log('Slider destroyed');
  })
  .slick();

Method Syntax Change

In version 1.4+, the method calling syntax became more consistent:

Before (< 1.4)

// ❌ Inconsistent method access
var slider = $('.slider').slick();
slider.slickNext();

After (1.4+)

// ✅ Consistent method access
$('.slider').slick();
$('.slider').slick('slickNext');

// Access any internal method
$('.slider').slick('setPosition');

// Get current slide
var currentSlide = $('.slider').slick('slickCurrentSlide');

The new syntax allows you to call any internal Slick method, providing more flexibility.

Migrating to Slick 1.5+

Data Attribute Settings

Slick 1.5 introduced the ability to configure settings via data-slick attribute:

<div class="slider" data-slick='{"slidesToShow": 4, "slidesToScroll": 4}'>
  <div><h3>1</h3></div>
  <div><h3>2</h3></div>
  <div><h3>3</h3></div>
  <div><h3>4</h3></div>
</div>

<script>
// Still need to initialize
$('.slider').slick();
</script>

You still need to call $(element).slick() to initialize Slick, even when using data attributes.

Migrating to Slick 1.8+

Slick 1.8 is the current stable version with minor improvements and bug fixes.

What’s New in 1.8

• Improved accessibility features
• Better touch handling on mobile devices
• Various bug fixes and performance improvements
• Enhanced responsive behavior

Breaking Changes

No major breaking changes from 1.7 to 1.8. Most code should work without modifications.

Step-by-Step Migration Process

1. Audit Your Current Implementation

   Identify which callback methods you’re using:

   // Find these patterns in your code:
   // - onAfterChange
   // - onBeforeChange
   // - onInit
   // - Any other on* properties
   
2. Create Event Handlers

   Convert each callback to an event handler:

   // Before
   $('.slider').slick({
     onAfterChange: function(slider, currentSlide) {
       updateCounter(currentSlide);
     }
   });
   
   // After
   $('.slider')
     .on('afterChange', function(event, slick, currentSlide) {
       updateCounter(currentSlide);
     })
     .slick();
   
3. Update Method Calls

   Update any method calls to use the new syntax:

   // Before
   var slider = $('.slider').slick();
   slider.slickGoTo(2);
   
   // After
   $('.slider').slick();
   $('.slider').slick('slickGoTo', 2);
   
4. Test Thoroughly

   Test all carousel functionality:

   • Slide navigation
   • Autoplay
   • Responsive breakpoints
   • Event handlers
   • Dynamic content updates
5. Update Dependencies

   Ensure jQuery version compatibility:

   <!-- For IE8+ support -->
   <script src="https://code.jquery.com/jquery-1.12.4.min.js"></script>
   
   <!-- For modern browsers only -->
   <script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
   

Common Migration Issues

Events not firing

Problem: Event handlers don’t execute.

Solution: Ensure events are bound before calling .slick():

// ❌ Wrong - event bound after init
$('.slider').slick();
$('.slider').on('afterChange', handler);

// ✅ Correct - event bound before init
$('.slider').on('afterChange', handler);
$('.slider').slick();

Init event not triggering

Problem: The init event doesn’t fire.

Solution: Bind the init event before initialization:

$('.slider')
  .on('init', function(event, slick) {
    console.log('Initialized!');
  })
  .slick();  // Must be after binding

Method calls failing

Problem: Method calls return undefined or throw errors.

Solution: Use the correct 1.4+ method syntax:

// ❌ Wrong
var slide = $('.slider').slickCurrentSlide();

// ✅ Correct
var slide = $('.slider').slick('slickCurrentSlide');

Parameter order confusion

Problem: Event parameters are different from callback parameters.

Solution: Note that events include the event object as the first parameter:

// Callback (old)
onAfterChange: function(slick, currentSlide) {
  // slick is first parameter
}

// Event (new)
.on('afterChange', function(event, slick, currentSlide) {
  // event is first, then slick
})

Migration Checklist

Pre-Migration Checklist

• Backup current implementation
• Document all custom callbacks
• Identify all method calls
• Check jQuery version compatibility
• Review custom CSS modifications
• Note any third-party integrations

Post-Migration Checklist

• All events fire correctly
• Method calls work as expected
• Responsive breakpoints function properly
• Autoplay works correctly
• Keyboard navigation works
• Touch/swipe gestures work on mobile
• Custom styling still applies
• Performance is acceptable
• Cross-browser testing complete

Example: Complete Migration

Before (Pre-1.4)

$('.slider').slick({
  slidesToShow: 3,
  slidesToScroll: 1,
  autoplay: true,
  onInit: function(slider) {
    console.log('Slider ready');
    updateNavigation(slider);
  },
  onBeforeChange: function(slider, currentSlide, nextSlide) {
    console.log('Changing slides');
  },
  onAfterChange: function(slider, currentSlide) {
    updateCounter(currentSlide);
    trackAnalytics(currentSlide);
  }
});

// Method calls
var slider = $('.slider').slick();
slider.slickNext();

After (1.4+)

$('.slider')
  .on('init', function(event, slick) {
    console.log('Slider ready');
    updateNavigation(slick);
  })
  .on('beforeChange', function(event, slick, currentSlide, nextSlide) {
    console.log('Changing slides');
  })
  .on('afterChange', function(event, slick, currentSlide) {
    updateCounter(currentSlide);
    trackAnalytics(currentSlide);
  })
  .slick({
    slidesToShow: 3,
    slidesToScroll: 1,
    autoplay: true
  });

// Method calls
$('.slider').slick('slickNext');

Getting Help

If you encounter issues during migration:

Troubleshooting

Common issues and solutions

Community Support

Ask questions on Stack Overflow