A carousel component for Vue.js inspired by Slick

vue-agile

Powerful, responsive, touch-friendly, and written in Vue and Vanilla JS (without a jQuery dependency).

Important – update from version < 1.0

Depreciated props => new props/option

• arrows => navButtons
• prevArrow => prevButton slot
• nextArrow => nextButton slot
• show => reload() method

Depreciated classes => new classes

• .agile__arrow => .agile__nav-button
• .agile__arrow--prev => .agile__nav-button--prev
• .agile__arrow--next => .agile__nav-button--next
• .agile__slide--cloned => cloned slides are grouped in .agile__slides--cloned container now

Structure

• Nav buttons and dots are grouped in .agile__actions container now

Installation

yarn add vue-agile

or

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

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

Example

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

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

Events

Example

<agile @afterChange="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 a 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>

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>

SSR Support

The component uses browser specific attributes (like window and document). Unfortunately, it is necessary -- so as of now, the only option is to run vue-agile solely on the client-side.

Full support for Nuxt.js is a known issue that will be addressed in a next version.

Example

// plugins/vue-agile.js

import Vue from 'vue'
import VueAgile from 'vue-agile'

Vue.use(VueAgile)

// nuxt.config.js

module.exports = {
    plugins: [
        { src: '~/plugins/vue-agile', ssr: false }
    ]
}

<client-only placeholder="Loading...">
    <agile>...</agile>
</client-only>

Contributing

? Thanks to Maciej Wach for inventing the name and to all Contributors for your development.

# project setup
yarn install
 
# compiles and hot-reloads for development
yarn serve
 
# compiles and minifies for production
yarn build-bundle

# lint and fixes files
yarn run lint

GitHub