vue-agile

# vue-agile [](https://github.com/lukaszflorczak/vue-agile/blob/master/LICENSE) [](https://app.codacy.com/project/lukaszflorczak/vue-agile/dashboard) [](https://www.npmjs.com/package/vue-agile) [](http://ko-fi.com/lukaszflorczak) > A carousel component for Vue.js inspired by [Slick](https://github.com/kenwheeler/slick/).
> Powerful, responsive, touch-friendly, with Nuxt.js SSR support, without a jQuery dependency. **[Demo & examples](https://lukaszflorczak.github.io/vue-agile/)** More demos and examples coming soon in [vue-agile CodePens collection](https://codepen.io/collection/AdRzJW/). --- If you like the component remember to **star it** ⭐️. If you appreciate my work you can also **[buy me a coffee](https://ko-fi.com/lukaszflorczak)** ☕️ --- If you're looking for Vue 2 version, check **[legacy/vue-v2](https://github.com/lukaszflorczak/vue-agile/tree/legacy/vue-v2)** branch. ## Installation ```bash npm install vue-agile ``` or ```bash yarn add vue-agile ``` ## Styles **The component is delivered without styles for the appearance of the navigation elements** (like dots color and shape, arrows position, etc.). I think most people use their own styles and default styles are completely redundant. If you want, feel free to use styles from [CodePen demos](https://codepen.io/collection/AdRzJW/). ## Importing #### Global ```js // main.js import { createApp } from 'vue' import App from './App.vue' import VueAgile from 'vue-agile' createApp(App) .use(VueAgile) ``` #### In component ```js // YourComponent.vue import { VueAgile } from 'vue-agile' export default { components: { agile: VueAgile } } ``` #### Via ` ``` ## Usage ```vue ... ``` Every first-level child of `` is a new slide. You also can group them inside `...` tags. ## Options / Props | Parameter | Type | Default | Description | | --- | :---: | :---: | --- | | [asNavFor](#asNavFor) | array | `[]` | Set the carousel to be the navigation of other carousels | | autoplay | boolean | `false` | Enable autoplay | | autoplaySpeed | integer (ms) | `3000` | Autoplay interval in milliseconds | | centerMode | boolean | `false` | Enable centered view when `slidesToShow` > `1` | | changeDelay | integer (ms) | `0` | Insert a delay when switching slides. Useful for `fade`: `true` | | dots | boolean | `true` | Enable dot indicators/pagination | | fade | boolean | `false` | Enable fade effect | | infinite | boolean | `true` | Infinite loop sliding | | initialSlide | integer | `0` | Index of slide to start on | | mobileFirst | boolean | `true` | Enable mobile first calculation for responsive settings | | navButtons | boolean | `true` | Enable prev/next navigation buttons | | options | object | `null` | All settings as one object | | pauseOnDotsHover | boolean | `false` | Pause autoplay when a dot is hovered | | pauseOnHover | boolean | `true` | Pause autoplay when a slide is hovered | | [responsive](#Responsive) | object | `null` | Object containing breakpoints and settings objects | | rtl | boolean | `false` | Enable right-to-left mode | | slidesToShow | integer | `1` | Number of slides to show | | speed | integer (ms) | `300` | Slide animation speed in milliseconds | | swipeDistance | integer (px) | `50` | Distance to swipe the next slide | | throttleDelay | integer (ms) | `500` | Throttle delay for actions | | timing | string | `ease` | Transition timing function
(`linear`/`ease`/`ease-in`/`ease-out`/`ease-in-out`) | | unagile | boolean | `false` | Disable Agile carousel | #### Example ```vue ... ``` **Important!** If you use props inline, convert props names from `camelCase` to `kebab-case`. ## Methods | Name | Description | | --- | --- | | `getCurrentBreakpoint()` | Returns current breakpoint (can returns `0` in mobile first for the smallest breakpoint and `null` for desktop first for the largest) | | `getCurrentSettings()` | Returns settings object for current breakpoint – useful for debugging | | `getCurrentSlide()` | Returns index of current slide | | `getInitialSettings()` | Returns full settings object with all options – useful for debugging | | `goTo()` | Navigates to a slide by index | | `goToNext()` | Navigates to next slide | | `goToPrev()` | Navigate to previous slide | | `reload()` | Reload carousel & slides settings, classes and inline styles | #### Example ```vue ... My custom button ``` ## Events | Name | Value | Description | | --- | --- | --- | | after-change | `{ currentSlide }` | Fires after slide change | | before-change | `{ currentSlide, nextSlide }` | Fires before slide change | | breakpoint | `{ breakpoint } ` | Fires after breakpoint change | #### Example ```vue ... ``` ```js showCurrentSlide(event) { console.log(event) // Shows for example: { currentSlide: 1 } } ``` ## Responsive To customize responsiveness, I recommend defining your desired breakpoints and passing settings object with your modification options inside **options**. #### Example ```vue ... ``` ```js data() { return { myOptions: { navButtons: false, responsive: [ { breakpoint: 600, settings: { dots: false } }, { breakpoint: 900, settings: { navButtons: true, dots: true, infinite: false } } ] } } } ``` How does it work? Mobile first mode is used by default. It means, that `navButtons: false` option will be used on screens from 0 to 600 px width (+ all default carousel options). On screens from 600 to 900 px `dots: false` will be added to options from breakpoint before. And on screens over 900 px width `navButtons` and `dots` options will be overwritten and `infinite: false` will be added. ## Custom arrows / nav buttons From version `1.0` the component use slots for custom navigation buttons. It means you can put inside whatever you want – any HTML with text, image, icon etc. #### Example ```vue ... prev next ``` ## Caption To display a static caption or such like within the gallery, you can use the `caption` slot. #### Example ```vue ... {{ captions[currentSlide] }} ``` ## asNavFor This option is useful for example for creating a photo gallery with two related slider – one big with only one slide in view and second for navigation with thumbnails. #### Example ```vue ... ... ``` **Important!** If you want to use the autoplay mode use it only in one of the related carousels. ## `v-if` & `v-show` If you have slides being dynamically loaded, use `v-if` to show the carousel after the slides are ready. Using `v-if` is also recommended in other situations if you want to hide/show the slideshow. It is also possible to use `v-show`, but you have to use the `reload()` method. #### Example ```vue Toggle carousel ... ``` ## Nuxt.js && SSR Support The component uses browser specific attributes (like `window` and `document`). However, you can try to render the first view on server side. #### Example ```js // plugins/vue-agile.js import Vue from 'vue' import VueAgile from 'vue-agile' Vue.use(VueAgile) ``` ```js // nuxt.config.js export default { plugins: ['~/plugins/vue-agile'], build: { transpile: ['vue-agile'] } } ``` To use component without SSR use the `client-only` component: ```vue ... ``` **Important!** Component rendered on server side has additional CSS class: `agile--ssr`, so you can use it to add some additional styles or manipulations. For example, I have limited options for setting the first appearance of the slides. By default, the server renders the view and styles, where only the first slide is visible. ```css .agile--ssr .agile__slides > * { overflow: hidden; width: 0 } .agile--ssr .agile__slides > *:first-child { width: 100% } ``` At this stage slides don't have `agile__slide` class yet, so I use `> *` instead of this. If you would like to connect this with params `slidesToShow` or `initialSlide` you have to add some custom styles with `nth-child` param. #### Example for `:slidesToShow="2"` ```sass .agile--ssr .agile__slides > *:nth-child(1), > *:nth-child(2) width: 50% ``` #### Example for `:initialSlide="1"` (Slides index starts at `0`) ```sass .agile--ssr .agile__slides > *:nth-child(1) width: 0 > *:nth-child(2) width: 100% ``` You can also check [nuxt-agile](https://github.com/lukaszflorczak/nuxt-agile) repository and check working demo of vue-agile with Nuxt and SSR. ## FAQ #### 1. Using component with dynamic content If content changes, you have to use `reload` or in some cases, you can use `key` property: `...` (it'll rebuild the carousel after each change of `mySlides` length). #### 2. Support for IE11 Yes, the UMD bundle is built with support for IE11. If you build your app with vue-agile as a dependency yourself be sure you configured babel properly (read more in [vue documentation](https://cli.vuejs.org/guide/browser-compatibility.html#browserslist) or just use my config for [babel](https://github.com/lukaszflorczak/vue-agile/blob/master/babel.config.js)).