README.markdown

   1 slick
   2 -------
   3
   4 [1]: <https://github.com/kenwheeler/slick>
   5
   6 _the last carousel you'll ever need_
   7
   8 #### Demo
   9
  10 [http://kenwheeler.github.io/slick](http://kenwheeler.github.io/slick/)
  11
  12 #### CDN
  13
  14 To start working with Slick right away, there's a couple of CDN choices availabile
  15 to serve the files as close, and fast as possible to your users:
  16
  17 - https://cdnjs.com/libraries/slick-carousel
  18 - https://www.jsdelivr.com/projects/jquery.slick
  19
  20 #####Example using jsDelivr
  21
  22 Just add a link to the css file in your `<head>`:
  23 ```html
  24 <link rel="stylesheet" type="text/css" href="//cdn.jsdelivr.net/jquery.slick/1.6.0/slick.css"/>
  25 <!-- Add the slick-theme.css if you want default styling -->
  26 <link rel="stylesheet" type="text/css" href="//cdn.jsdelivr.net/jquery.slick/1.6.0/slick-theme.css"/>
  27 ```
  28
  29 Then, before your closing ```<body>``` tag add:
  30
  31 ```html
  32 <script type="text/javascript" src="//cdn.jsdelivr.net/jquery.slick/1.6.0/slick.min.js"></script>
  33 ```
  34
  35 #### Package Managers
  36
  37 ```sh
  38 # Bower
  39 bower install --save slick-carousel
  40
  41 # NPM
  42 npm install slick-carousel
  43 ```
  44
  45 #### Contributing
  46
  47 PLEASE review CONTRIBUTING.markdown prior to requesting a feature, filing a pull request or filing an issue.
  48
  49 ### Data Attribute Settings
  50
  51 In slick 1.5 you can now add settings using the data-slick attribute. You still need to call $(element).slick() to initialize slick on the element.
  52
  53 Example:
  54
  55 ```html
  56 <div data-slick='{"slidesToShow": 4, "slidesToScroll": 4}'>
  57   <div><h3>1</h3></div>
  58   <div><h3>2</h3></div>
  59   <div><h3>3</h3></div>
  60   <div><h3>4</h3></div>
  61   <div><h3>5</h3></div>
  62   <div><h3>6</h3></div>
  63 </div>
  64 ```
  65
  66 ### Settings
  67
  68 Option | Type | Default | Description
  69 ------ | ---- | ------- | -----------
  70 accessibility | boolean | true | Enables tabbing and arrow key navigation
  71 adaptiveHeight | boolean | false | Adapts slider height to the current slide
  72 autoplay | boolean | false | Enables auto play of slides
  73 autoplaySpeed | int  | 3000 | Auto play change interval
  74 centerMode | boolean | false | Enables centered view with partial prev/next slides. Use with odd numbered slidesToShow counts.
  75 centerPadding | string | '50px' | Side padding when in center mode. (px or %)
  76 cssEase | string |  'ease' | CSS3 easing
  77 customPaging | function | n/a | Custom paging templates. See source for use example.
  78 dots | boolean | false | Current slide indicator dots
  79 dotsClass | string | 'slick-dots' | Class for slide indicator dots container
  80 draggable | boolean | true | Enables desktop dragging
  81 easing | string |  'linear' | animate() fallback easing
  82 edgeFriction | integer | 0.15 | Resistance when swiping edges of non-infinite carousels
  83 fade | boolean | false | Enables fade
  84 arrows | boolean | true | Enable Next/Prev arrows
  85 appendArrows | string | $(element) | Change where the navigation arrows are attached (Selector, htmlString, Array, Element, jQuery object)
  86 appendDots | string | $(element) | Change where the navigation dots are attached (Selector, htmlString, Array, Element, jQuery object)
  87 mobileFirst | boolean | false | Responsive settings use mobile first calculation
  88 prevArrow | string (html \| jQuery selector) \| object (DOM node \| jQuery object) | `<button type="button" class="slick-prev">Previous</button>` | Allows you to select a node or customize the HTML for the "Previous" arrow.
  89 nextArrow | string (html \| jQuery selector) \| object (DOM node \| jQuery object) | `<button type="button" class="slick-next">Next</button>` | Allows you to select a node or customize the HTML for the "Next" arrow.
  90 infinite | boolean | true | Infinite looping
  91 initialSlide | integer | 0 | Slide to start on
  92 lazyLoad | string | 'ondemand' | Accepts 'ondemand' or 'progressive' for lazy load technique. 'ondemand' will load the image as soon as you slide to it, 'progressive' loads one image after the other when the page loads.
  93 pauseOnFocus | boolean | true | Pauses autoplay when slider is focussed
  94 pauseOnHover | boolean | true | Pauses autoplay on hover
  95 pauseOnDotsHover | boolean | false | Pauses autoplay when a dot is hovered
  96 respondTo | string | 'window' | Width that responsive object responds to. Can be 'window', 'slider' or 'min' (the smaller of the two).
  97 responsive | array | null | Array of objects [containing breakpoints and settings objects (see example)](#responsive-option-example). Enables settings at given `breakpoint`. Set `settings` to "unslick" instead of an object to disable slick at a given breakpoint.
  98 rows | int | 1 | Setting this to more than 1 initializes grid mode. Use slidesPerRow to set how many slides should be in each row.
  99 slide | string | '' | Slide element query
 100 slidesPerRow | int | 1 | With grid mode initialized via the rows option, this sets how many slides are in each grid row.
 101 slidesToShow | int | 1 | # of slides to show at a time
 102 slidesToScroll | int | 1 | # of slides to scroll at a time
 103 speed | int | 300 | Transition speed
 104 swipe | boolean | true | Enables touch swipe
 105 swipeToSlide | boolean | false | Swipe to slide irrespective of slidesToScroll
 106 touchMove | boolean | true | Enables slide moving with touch
 107 touchThreshold | int | 5 | To advance slides, the user must swipe a length of (1/touchThreshold) * the width of the slider.
 108 useCSS | boolean | true | Enable/Disable CSS Transitions
 109 useTransform | boolean | true | Enable/Disable CSS Transforms
 110 variableWidth | boolean | false | Disables automatic slide width calculation
 111 vertical | boolean | false | Vertical slide direction
 112 verticalSwiping | boolean | false | Changes swipe direction to vertical
 113 rtl | boolean | false | Change the slider's direction to become right-to-left
 114 waitForAnimate | boolean | true | Ignores requests to advance the slide while animating
 115 zIndex | number | 1000 | Set the zIndex values for slides, useful for IE9 and lower
 116
 117 ##### Responsive Option Example
 118 The responsive option, and value, is quite unique and powerful.
 119 You can use it like so:
 120
 121 ```javascript
 122 $(".slider").slick({
 123
 124   // normal options...
 125   infinite: false,
 126
 127   // the magic
 128   responsive: [{
 129
 130       breakpoint: 1024,
 131       settings: {
 132         slidesToShow: 3,
 133         infinite: true
 134       }
 135
 136     }, {
 137
 138       breakpoint: 600,
 139       settings: {
 140         slidesToShow: 2,
 141         dots: true
 142       }
 143
 144     }, {
 145
 146       breakpoint: 300,
 147       settings: "unslick" // destroys slick
 148
 149     }]
 150 });
 151 ```
 152
 153
 154
 155
 156 ### Events
 157
 158 In slick 1.4, callback methods were deprecated and replaced with events. Use them before the initialization of slick as shown below:
 159
 160 ```javascript
 161 // On swipe event
 162 $('.your-element').on('swipe', function(event, slick, direction){
 163   console.log(direction);
 164   // left
 165 });
 166
 167 // On edge hit
 168 $('.your-element').on('edge', function(event, slick, direction){
 169   console.log('edge was hit')
 170 });
 171
 172 // On before slide change
 173 $('.your-element').on('beforeChange', function(event, slick, currentSlide, nextSlide){
 174   console.log(nextSlide);
 175 });
 176 ```
 177
 178 Event | Params | Description
 179 ------ | -------- | -----------
 180 afterChange | event, slick, currentSlide | After slide change callback
 181 beforeChange | event, slick, currentSlide, nextSlide | Before slide change callback
 182 breakpoint | event, slick, breakpoint | Fires after a breakpoint is hit
 183 destroy | event, slick | When slider is destroyed, or unslicked.
 184 edge | event, slick, direction | Fires when an edge is overscrolled in non-infinite mode.
 185 init | event, slick | When Slick initializes for the first time callback. Note that this event should be defined before initializing the slider.
 186 reInit | event, slick | Every time Slick (re-)initializes callback
 187 setPosition | event, slick | Every time Slick recalculates position
 188 swipe | event, slick, direction | Fires after swipe/drag
 189 lazyLoaded | event, slick, image, imageSource | Fires after image loads lazily
 190 lazyLoadError | event, slick, image, imageSource | Fires after image fails to load
 191
 192
 193 #### Methods
 194
 195 Methods are called on slick instances through the slick method itself in version 1.4, see below:
 196
 197 ```javascript
 198 // Add a slide
 199 $('.your-element').slick('slickAdd',"<div></div>");
 200
 201 // Get the current slide
 202 var currentSlide = $('.your-element').slick('slickCurrentSlide');
 203 ```
 204
 205 This new syntax allows you to call any internal slick method as well:
 206
 207 ```javascript
 208 // Manually refresh positioning of slick
 209 $('.your-element').slick('setPosition');
 210 ```
 211
 212
 213 Method | Argument | Description
 214 ------ | -------- | -----------
 215 `slick` | options : object | Initializes Slick
 216 `unslick` |  | Destroys Slick
 217 `slickNext` |  |  Triggers next slide
 218 `slickPrev` | | Triggers previous slide
 219 `slickPause` | | Pause Autoplay
 220 `slickPlay` | | Start Autoplay (_will also set `autoplay` option to `true`_)
 221 `slickGoTo` | index : int, dontAnimate : bool | Goes to slide by index, skipping animation if second parameter is set to true
 222 `slickCurrentSlide` |  |  Returns the current slide index
 223 `slickAdd` | element : html or DOM object, index: int, addBefore: bool | Add a slide. If an index is provided, will add at that index, or before if addBefore is set. If no index is provided, add to the end or to the beginning if addBefore is set. Accepts HTML String || Object
 224 `slickRemove` | index: int, removeBefore: bool | Remove slide by index. If removeBefore is set true, remove slide preceding index, or the first slide if no index is specified. If removeBefore is set to false, remove the slide following index, or the last slide if no index is set.
 225 `slickFilter` | filter : selector or function | Filters slides using jQuery .filter syntax
 226 `slickUnfilter` | | Removes applied filter
 227 `slickGetOption` | option : string(option name) | Gets an option value.
 228 `slickSetOption` | change an option, `refresh` is always `boolean` and will update UI changes...
 229  | `option, value, refresh` | change a [single `option`](https://github.com/kenwheeler/slick#settings) to given `value`; `refresh` is optional.
 230  | `"responsive", [{ breakpoint: n, settings: {} }, ... ], refresh` | change or add [whole sets of responsive options](#responsive-option-example)
 231  | `{ option: value, option: value, ... }, refresh` | change  [multiple `option`s](https://github.com/kenwheeler/slick#settings) to corresponding `value`s.
 232
 233
 234 #### Example
 235
 236 Initialize with:
 237
 238 ```javascript
 239 $(element).slick({
 240   dots: true,
 241   speed: 500
 242 });
 243  ```
 244
 245 Change the speed with:
 246
 247 ```javascript
 248 $(element).slick('slickSetOption', 'speed', 5000, true);
 249 ```
 250
 251 Destroy with:
 252
 253 ```javascript
 254 $(element).slick('unslick');
 255 ```
 256
 257
 258 #### Sass Variables
 259
 260 Variable | Type | Default | Description
 261 ------ | ---- | ------- | -----------
 262 $slick-font-path | string | "./fonts/" | Directory path for the slick icon font
 263 $slick-font-family | string | "slick" | Font-family for slick icon font
 264 $slick-loader-path | string | "./" | Directory path for the loader image
 265 $slick-arrow-color | color | white | Color of the left/right arrow icons
 266 $slick-dot-color | color | black | Color of the navigation dots
 267 $slick-dot-color-active | color | $slick-dot-color | Color of the active navigation dot
 268 $slick-prev-character | string | '\2190' | Unicode character code for the previous arrow icon
 269 $slick-next-character | string | '\2192' | Unicode character code for the next arrow icon
 270 $slick-dot-character | string | '\2022' | Unicode character code for the navigation dot icon
 271 $slick-dot-size | pixels | 6px | Size of the navigation dots
 272
 273 #### Browser support
 274
 275 Slick works on IE8+ in addition to other modern browsers such as Chrome, Firefox, and Safari.
 276
 277 #### Dependencies
 278
 279 jQuery 1.7
 280
 281 #### License
 282
 283 Copyright (c) 2014 Ken Wheeler
 284
 285 Licensed under the MIT license.
 286
 287 Free as in Bacon.