Repository files navigation

A carousel component for Vue.js inspired bySlick.
Powerful, responsive, touch-friendly, with Nuxt.js SSR support, without a jQuery dependency.

Demo & examples

More demos and examples coming soon invue-agile CodePens collection.

If you like the component remember tostar it ⭐️. If you appreciate my work you can alsobuy me a coffee ☕️ 😉

🔭 If you're looking for Vue 2 version, checklegacy/vue-v2 branch.

npm install vue-agile

or

yarn add vue-agile

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 youwant, feel free to use styles fromCodePen demos.

// main.jsimport{createApp}from'vue'importAppfrom'./App.vue'importVueAgilefrom'vue-agile'createApp(App).use(VueAgile)

// YourComponent.vueimport{VueAgile}from'vue-agile'exportdefault{components:{agile:VueAgile}}

<scriptsrc="https://unpkg.com/vue-agile"></script><linkrel="stylesheet"href="https://unpkg.com/vue-agile/dist/VueAgile.css">

<template>  <agile>    <divclass="slide">      <h3>slide 1</h3>    </div>    ...    <divclass="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.

<agile :dots="false" :infinite="false" :autoplay-speed="5000">...</agile>

Important! If you use props inline, convert props names fromcamelCase tokebab-case.

<agile ref="carousel">...</agile><button @click="$refs.carousel.goToNext()">My custom button</button>

<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 insideoptions.

<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, thatnavButtons: false option will be used on screens from 0 to 600 px width (+ all default carousel options). On screens from 600 to 900 pxdots: false will beadded to options from breakpoint before. And on screens over 900 px widthnavButtons anddots options will be overwritten andinfinite: false will be added.

From version1.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 thecaption slot.

<agile @after-change="e=>currentSlide=e.currentSlide">  ... <!-- slides -->  <template slot="caption">{{ captions[currentSlide] }}</template></agile><script>exportdefault {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, usev-if to show the carousel after the slides are ready. Usingv-if is also recommended in other situations if you want to hide/show the slideshow.

It is also possible to usev-show, but you have to use thereload() method.

<button @click="isActive=!isActive">Toggle carousel</button><agilev-if="isActive">...</agile>

The component uses browser specific attributes (likewindow anddocument). However, you can try to render the first view on server side.

// plugins/vue-agile.jsimportVuefrom'vue'importVueAgilefrom'vue-agile'Vue.use(VueAgile)

// nuxt.config.jsexportdefault{plugins:['~/plugins/vue-agile'],build:{transpile:['vue-agile']}}

To use component without SSR use theclient-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 haveagile__slide class yet, so I use> * instead of this.

If you would like to connect this with paramsslidesToShow orinitialSlide you have to add some custom styles withnth-child param.

.agile--ssr.agile__slides    >*:nth-child(1),    >*:nth-child(2)width:50%

(Slides index starts at0)

.agile--ssr.agile__slides    >*:nth-child(1)width:0    >*:nth-child(2)width:100%

You can also checknuxt-agile repository and check working demo of vue-agile with Nuxt and SSR.

If content changes, you have to usereload or in some cases, you can usekey property:<agile :key="mySlides.length">...</agile> (it'll rebuild the carousel after each change ofmySlides 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 invue documentation or just use my config forbabel).