vue-agile

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

Demo & examples

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 ☕️ 😉

🎉 I'm happy and excited to inform, that new v1.1 version is available now! More information and a changelog you can find here.

Important – update from version `1.0.x`

Events

afterChange => after-change
beforeChange => before-change

Deprecated

Deprecated props (arrows, prevArrow, nextArrow, show) and classes (.agile__arrow, .agile__arrow--prev, .agile__arrow--next, .agile__slide--cloned) from versions < 1.0 are no longer available

Installation

yarn add vue-agile

npm install 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.

Importing

Global

// main.js
import Vue from 'vue'
import VueAgile from 'vue-agile'

Vue.use(VueAgile)

In component

// YourComponent.vue
import { VueAgile } from 'vue-agile'

export default { 
    components: {
        agile: VueAgile 
    }
}

Via `<script>`

<script src="https://unpkg.com/vue-agile"></script>
<link rel="stylesheet" href="https://unpkg.com/vue-agile/dist/VueAgile.css">

Usage

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

Options / Props

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

Example

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

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

<agile ref="carousel">...</agile>

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

Events

Name	Value	Description
after-change	`{ slideCurrent }`	Fires after slide change
before-change	`{ slideCurrent, slideNext }`	Fires before slide change
breakpoint	`{ breakpoint }`	Fires after breakpoint change

Example

<agile @after-change="showCurrentSlide($event)">...</agile>

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

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

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

<agile>
    ... <!-- slides -->
    
    <template slot="prevButton">prev</template>
    <template slot="nextButton">next</template>
</agile>

Caption

To display a static caption or such like within the gallery, you can use the caption slot.

Example

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

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

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

`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

<button @click="isActive = !isActive">Toggle carousel</button>

<agile v-if="isActive">...</agile>

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

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

Example for `:slidesToShow="2"`

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

Example for `:initialSlide="1"`

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

FAQ

1. Using component with dynamic content

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

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 or just use my config for babel).

occupant/vue-agile

vue-agile

Important – update from version 1.0.x

Events

Deprecated

Installation

Styles

Importing

Global

In component

Via <script>

Usage

Options / Props

Example

Methods

Example

Events

Example

Responsive

Example

Custom arrows / nav buttons

Example

Caption

Example

asNavFor

Example

v-if & v-show

Example

Nuxt.js && SSR Support

Example

Example for :slidesToShow="2"

Example for :initialSlide="1"

FAQ

1. Using component with dynamic content

2. Support for IE11

Important – update from version `1.0.x`

Via `<script>`

`v-if` & `v-show`

Example for `:slidesToShow="2"`

Example for `:initialSlide="1"`