A carousel component for Vue.js inspired by Slick.
Powerful, responsive, touch-friendly, with Nuxt.js SSR support, without a jQuery dependency.
More demos and examples coming soon in vue-agile CodePens collection.
If you like the component remember to star it ⭐️. If you appreciate my work you can also buy me a coffee ☕️ 😉
🔭 If you're looking for Vue 2 version, check legacy/vue-v2 branch.
npm install vue-agileor
yarn add vue-agileThe 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.
// main.js
import { createApp } from 'vue'
import App from './App.vue'
import VueAgile from 'vue-agile'
createApp(App)
.use(VueAgile)// YourComponent.vue
import { VueAgile } from 'vue-agile'
export default {
components: {
agile: VueAgile
}
}<script src="https://unpkg.com/vue-agile"></script>
<link rel="stylesheet" href="https://unpkg.com/vue-agile/dist/VueAgile.css"><template>
<agile>
<div class="slide">
<h3>slide 1</h3>
</div>
...
<div class="slide">
<h3>slide n</h3>
</div>
</agile>
</template>Every first-level child of <agile> is a new slide. You also can group them inside <template v-slot:default>...</template> tags.
| Parameter | Type | Default | Description |
|---|---|---|---|
| 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 | 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 |
<agile :dots="false" :infinite="false" :autoplay-speed="5000">...</agile>Important! If you use props inline, convert props names from camelCase to kebab-case.
| 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 |
<agile ref="carousel">...</agile>
<button @click="$refs.carousel.goToNext()">My custom button</button>| Name | Value | Description |
|---|---|---|
| after-change | { currentSlide } |
Fires after slide change |
| before-change | { currentSlide, nextSlide } |
Fires before slide change |
| breakpoint | { breakpoint } |
Fires after breakpoint change |
<agile @after-change="showCurrentSlide($event)">...</agile>showCurrentSlide(event)
{
console.log(event)
// Shows for example: { currentSlide: 1 }
}To customize responsiveness, I recommend defining your desired breakpoints and passing settings object with your modification options inside options.
<agile :options="myOptions">...</agile>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.
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.
<agile>
... <!-- slides -->
<template slot="prevButton">prev</template>
<template slot="nextButton">next</template>
</agile>To display a static caption or such like within the gallery, you can use the caption slot.
<agile @after-change="e => currentSlide = e.currentSlide">
... <!-- slides -->
<template slot="caption">{{ captions[currentSlide] }}</template>
</agile>
<script>
export default {
data () {
return {
currentSlide: 0,
captions: [
'This is slide 1',
'This is the second slide',
'This is a third and final slide',
]
}
}
}
</script>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.
<agile ref="main" :fade="true">...</agile>
<agile ref="thumbnails" :as-nav-for="[$refs.main]" :slides-to-show="4" autoplay>...</agile>Important! If you want to use the autoplay mode use it only in one of the related carousels.
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.
<button @click="isActive = !isActive">Toggle carousel</button>
<agile v-if="isActive">...</agile>The component uses browser specific attributes (like window and document). However, you can try to render the first view on server side.
// plugins/vue-agile.js
import Vue from 'vue'
import VueAgile from 'vue-agile'
Vue.use(VueAgile)// nuxt.config.js
export default {
plugins: ['~/plugins/vue-agile'],
build: {
transpile: ['vue-agile']
}
}To use component without SSR use the client-only component:
<client-only placeholder="Loading...">
<agile>...</agile>
</client-only>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.
.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.
.agile--ssr
.agile__slides
> *:nth-child(1),
> *:nth-child(2)
width: 50%(Slides index starts at 0)
.agile--ssr
.agile__slides
> *:nth-child(1)
width: 0
> *:nth-child(2)
width: 100%You can also check nuxt-agile repository and check working demo of vue-agile with Nuxt and SSR.
If content changes, you have to use reload or in some cases, you can use key property: <agile :key="mySlides.length">...</agile> (it'll rebuild the carousel after each change of mySlides length).
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 or just use my config for babel).
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent