vue3-agile v0.2.0

vue3-agile

This is a fork of vue-agile by Łukasz Florczak. Since he abandoned his project in February of 2023 I decided to publish my own version with some improvements (SSR Support and Vue3 only)

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

Demo & examples

If you like the component remember to star it ⭐️.

Installation

npm install vue3-agile

or

yarn add vue3-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 'vue3-agile'

createApp(App)
  .use(VueAgile)

Component

<template>
  <Agile>
    ...
  </Agile>
</template>

<script setup>
import { Agile } from 'vue3-agile'
<script>

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

The component uses 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 setup>
  import { ref } from 'vue';

  const currentSlide = ref(0);
  const 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/vue3-agile.js

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

Vue.use(VueAgile)

// nuxt.config.js

export default {
  plugins: ['~/plugins/vue3-agile'],

  build: {
    transpile: ['vue3-agile']
  }
}

To use component without SSR use the client-only component:

<ClientOnly placeholder="Loading...">
  <agile>...</agile>
</ClientOnly>

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%

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