Skip to content

Latest commit

 

History

History
372 lines (269 loc) · 10.8 KB

README.md

File metadata and controls

372 lines (269 loc) · 10.8 KB
Raw

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

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

Installation

npm install vue-agile

or

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.

Importing

Global

// main.js
import { createApp } from 'vue'
import App from './App.vue'
import VueAgile from 'vue-agile'

createApp(App)
  .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 { currentSlide } Fires after slide change
before-change { currentSlide, nextSlide } 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).