ssense / vue-carousel

A flexible, responsive, touch-friendly carousel for Vue.js

Vue Carousel

WARNING: vue-carousel is at pre-alpha stage of development and may undergo significant changes.

Feel free to submit issues and feature requests here.

Full documentation and examples

Table of Contents

• Installation
• Usage
• Development
• License

Installation

npm install vue-carousel

or if you prefer yarn

yarn add vue-carousel

Usage

Global

You may install Vue Carousel globally:

import Vue from 'vue';
import VueCarousel from 'vue-carousel';

Vue.use(VueCarousel);

This will make <carousel> and <slide> available to all components within your Vue app.

Local

Include the carousel directly into your component using import:

import { Carousel, Slide } from 'vue-carousel';

export default {
  ...
  components: {
    Carousel,
    Slide
  }
  ...
};

Configuration

Property	Type	Default	Description
adjustableHeight	Boolean	false	Adjust the height of the carousel for the current slide.
adjustableHeightEasing	String		Slide transition easing for adjustableHeight. Any valid CSS transition easing accepted.
autoplay	Boolean	false	Flag to enable autoplay.
autoplayDirection	String	forward	Sets the autoplay direction for the carousel during autoplay. By default it is forward but can also be set to backward. If an incorrect string is supplied it will default to forward.
autoplayHoverPause	Boolean	true	Flag to pause autoplay on hover.
autoplayTimeout	Number	2000	Time elapsed before advancing slide in autoplay.
centerMode	Boolean	false	Center images when the size is less than the container width.
easing	String	ease	Slide transition easing. Any valid CSS transition easing accepted.
loop	Boolean	false	Flag to make the carousel loop around when it reaches the end.
minSwipeDistance	Number	8	Minimum distance for the swipe to trigger a slide advance.
mouseDrag	Boolean	true	Flag to toggle mouse dragging.
navigateTo	Number, Array	0	Listen for an external navigation request using this prop. When the supplied prop is of type Number the slide with the matching index is animated into view, however you can disable this animation by supplying an Array consisting of exactly two element: the new slide index and a boolean indication whether the change should be animated or not (eg. [3, false] would mean "go to the slide with index 3 without animation").
navigationClickTargetSize	Number	8	Amount of padding to apply around the label in pixels.
navigationEnabled	Boolean	false	Flag to render the navigation component (next/prev buttons).
navigationNextLabel	String	▶	Text content of the navigation next button.
navigationPrevLabel	String	◀	Text content of the navigation prev button.
paginationActiveColor	String	#000000	The fill color of the active pagination dot. Any valid CSS color is accepted.
paginationColor	String	#efefef	The fill color of pagination dots. Any valid CSS color is accepted.
paginationPosition	String	bottom	The position of pagination dots. Possible values are bottom, bottom-overlay, top and top-overlay. The overlay values place the pagination component over the images.
paginationEnabled	Boolean	true	Flag to render pagination component.
paginationPadding	Number	10	The padding inside each pagination dot. Pixel values are accepted.
paginationSize	Number	10	The size of each pagination dot. Pixel values are accepted.
perPage	Number	2	Maximum number of slides displayed on each page.
perPageCustom	Array		Configure the number of visible slides with a particular browser width. This will be an array of arrays, ex. [[320, 2], [1199, 4]]. Formatted as [x, y] where x=browser width, and y=number of slides displayed. Ex. [1199, 4] means if (window >= 1199) then show 4 slides per page.
resistanceCoef	Number	20	Resistance coefficient to dragging on the edge of the carousel. This dictates the effect of the pull as you move towards the boundaries.
scrollPerPage	Boolean	true	Scroll per page, not per item.
spacePadding	Number	0	Stage padding option adds left and right padding style (in pixels) onto VueCarousel-inner.
spacePaddingMaxOffsetFactor	Number	0	Specify by how much should the space padding value be multiplied of, to re-arange the final slide padding.
speed	Number	500	Slide transition speed. Number of milliseconds accepted.
tagName	String	slide	Name (tag) of slide component. Overwrite with coponent name when extending slide component.
touchDrag	Boolean	true	Flag to toggle touch dragging.
value	Number		Support for v-model functionality. Setting this value will change the current page to the number inputted (if between 0 and pageCount).

Events

Event	Type	Emitter	Description
navigation-click		Carousel	Emits when the a navigation button is clicked, with the current direction (backward or forward)
pagination-click		Carousel	Emits when a pagination button is clicked, with the current pageNumber
page-change	Number	Carousel	Emits with the current page number.
slide-click	Object	Slide	Emits with the dataset object of the selected element ··
transition-start		Carousel	Emits when the transition end is reached
transition-end		Carousel	Emits when the transition start is reached ·

Lowercase versions of the above events are also emitted, namely—pagechange, slideclick, transitionstart and transitionend.

HTML Structure

Once the Carousel and Slide components are installed globally or imported, they can be used in templates in the following manner:

  <carousel :per-page="1" :navigate-to="someLocalProperty" :mouse-drag="false">
    <slide>
      Slide 1 Content
    </slide>
    <slide>
      Slide 2 Content
    </slide>
  </carousel>

To listen for the 'slideclick' event you can do the following:

  <carousel>
    <slide
        data-index="0"
        data-name="MySlideName"
        @slideclick="handleSlideClick">
      Slide 1 Content
    </slide>
    ...
  </carousel>

  handleSlideClick (dataset) => {
    console.log(dataset.index, dataset.name)
  }

Development

A sandboxed dev environment is provided by vue-play. Changes made to the component files will appear in real time in the sandbox.

To begin development, run:

yarn install
yarn dev

then navigate to http://localhost:5000

To modify and add sandbox scenarios, edit play/index.js

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

vue-carousel's Issues

Test issue

Foobar

Question: Displaying a popup is hidden by overflow property

I am probably doing something wrong - I am really new to the front-end world.

I am trying to display a div using v-if. The ViewCarousel-Wrapper class specifies overflow: hidden; - which typically cuts off most of my popup.

Is there a recommended / suggested way to deal with this?

Buffering

Does vue-carousel support buffering? I can potentially have hundreds of slides but would like to only render a limited number - say 5 - at a time

Disable dragging function

Please add a property for disable dragging function. Thanks

Feature request: Use style classes instead of inline styles

There're a few component options regarding styles such as paginationActiveColor, paginationPadding, etc. Since they are rendered as inline styles, it is hard to override them with CSS classes. It's better to set CSS classed for these elements. What do you think?

Feature Request: Create prop to add margin between elements

I'm increasing horizontal margin on VueCarousel-slide, but the carousel is being cut off.

I can set flex-basis manually but it doesn't get updated with resolution changes.

  <carousel :perPage="5" :navigationEnabled="true" :paginationEnabled="false">
    <slide>
      <img src="http://via.placeholder.com/300">
    </slide>
    <slide>
      <img src="http://via.placeholder.com/300">
    </slide>
    <slide>
      <img src="http://via.placeholder.com/300">
    </slide>
    <slide>
      <img src="http://via.placeholder.com/300">
    </slide>
    <slide>
      <img src="http://via.placeholder.com/300">
    </slide>
    <slide>
      <img src="http://via.placeholder.com/300">
    </slide>
    <slide>
      <img src="http://via.placeholder.com/300">
    </slide>
    <slide>
      <img src="http://via.placeholder.com/300">
    </slide>
  </carousel>
</template>

<script>
import { Carousel, Slide } from 'vue-carousel';

export default {
  components: {
    Carousel,
    Slide,
  },
};
</script>

<style lang="scss">
  $margin: .5%;
  $padding: 1%;

  .VueCarousel-inner {
    /*flex-basis: 327px !important;*/
  }

  .VueCarousel-slide {
    margin: 0 $margin 0 $margin;
    padding: $padding $padding $padding $padding;
    border: 2px solid #0e5a7e;

    img {
      width: 100%;
    }
  }

  .VueCarousel-navigation-button {
    color: inherit !important;
  }
</style>

Feature request: Custom navigation buttons

How can I change the prev/next buttons with a custom ones?

Feature request: Infinite loop

Slider Full Screen Image Carousel

How do i create a full screen image carousel?

Modal Functionality

I'm not sure if any Modal-like functionality is planned for the future of this project, but thought I'd try and discuss here. Much of the time I use image carousel functionality, I also want to use the same carousel to prompt a modal, with content of the image, and anything else in the <slot>. Not dissimilar to viewing a photo on Facebook.

The modal could be prompted by:

• "Selecting" or clicking the image
• "Selecting" an expand icon, or similar
• etc...

Is this something that may be planned for a the project?

Are there specific avenues you'd like to take in order to implement something like this?

If it is planned, would a PR be welcomed?

How to get the current slide/ page number?

Hello, i am trying to get the this.currentPage variable outside of the Carousel so that i can set another variable.

How can i do this?

Feature Request: Add support for lazy load images

Question: Can styles be customized?

Thanks for the plugin!
Where can we change the CSS-Styles? I tried to set custom styles, but they doesn't work.

Feature request: auto start

Love this slider so far and it would be even better with an API option to auto cycle through the slides by specifying the interval per slide. An option to loop infinitely or not would be nice as well.

Feature request: emit event when currentPage changes

related: #25

I want to handle navigation from outside the Carousel. I am using Vuex, so it would be handy to have an event emitted when the currentPage changes. I could do it, add a watcher on currentPage that emits an event, and create a pull request, if you want.

I tried this, but it does not work, would be nice though:

watch: {
  '$refs.carousel.currentPage' () {
    if (this.currentPage !== this.$refs.carousel.currentPage) {
      store.dispatch('carousel/currentPageChanged', this.$refs.carousel.currentPage)
    }
  }
}

The rest should work like this (did not test):

computed: {
  ...mapGetters('carousel', [
    'currentPage'
  ])
},
watch: {
  currentPage () {
    if (this.currentPage !== this.$refs.carousel.currentPage) {
      this.$refs.carousel.goToPage(this.currentPage)
    }
  }
}

Thank you!

Feature request: navigation handle within Carousel

Can we add a prop that make the navigation handles locate inside the carousel div?

It might be just add a prop that changes .VueCarousel-navigation-* class left or right value.

Thanks

Bug: Doesn't run with vue-webpack-boilerplate

Running:

node v6.8.1
npm v4.0.5

Setup a vue boilerplate with vue-cli:

npm install -g vue-cli
vue init webpack test
cd test
npm install
npm install -S @ssense/vue-carousel

Added to main.js:

import VueCarousel from '@ssense/vue-carousel'
Vue.use(VueCarousel)

However I always get this error when I run with npm run dev:

Uncaught SyntaxError: Unexpected token import
at Object. (app.js:642)
at webpack_require (app.js:556)
at fn (app.js:87)
at eval (eval at (app.js:660), :11:20)
at Object. (app.js:660)
at webpack_require (app.js:556)
at fn (app.js:87)
at Object. (app.js:587)
at webpack_require (app.js:556)
at app.js:579

(app.js:642)

eval("import Carousel from './Carousel.vue';\nimport Slide from './Slide.vue';\n\nconst install = (Vue) => {\n  Vue.component('carousel', Carousel);\n  Vue.component('slide', Slide);\n};\n\nexport default install;\n\nexport {\n  Carousel,\n  Slide,\n};\n\n//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbIndlYnBhY2s6Ly8vLi9+L0Bzc2Vuc2UvdnVlLWNhcm91c2VsL3NyYy9pbmRleC5qcz8wNTY4Il0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBO0FBQ0E7O0FBRUE7QUFDQTtBQUNBO0FBQ0E7O0FBRUE7O0FBRUE7QUFDQTtBQUNBO0FBQ0EiLCJmaWxlIjoiOS5qcyIsInNvdXJjZXNDb250ZW50IjpbImltcG9ydCBDYXJvdXNlbCBmcm9tICcuL0Nhcm91c2VsLnZ1ZSc7XG5pbXBvcnQgU2xpZGUgZnJvbSAnLi9TbGlkZS52dWUnO1xuXG5jb25zdCBpbnN0YWxsID0gKFZ1ZSkgPT4ge1xuICBWdWUuY29tcG9uZW50KCdjYXJvdXNlbCcsIENhcm91c2VsKTtcbiAgVnVlLmNvbXBvbmVudCgnc2xpZGUnLCBTbGlkZSk7XG59O1xuXG5leHBvcnQgZGVmYXVsdCBpbnN0YWxsO1xuXG5leHBvcnQge1xuICBDYXJvdXNlbCxcbiAgU2xpZGUsXG59O1xuXG5cblxuLy8vLy8vLy8vLy8vLy8vLy8vXG4vLyBXRUJQQUNLIEZPT1RFUlxuLy8gLi9+L0Bzc2Vuc2UvdnVlLWNhcm91c2VsL3NyYy9pbmRleC5qc1xuLy8gbW9kdWxlIGlkID0gOVxuLy8gbW9kdWxlIGNodW5rcyA9IDAiXSwic291cmNlUm9vdCI6IiJ9");

Any help would be appreciated :)

basic demo not working with vue-cli basic app

Hi,
Using:
"vue": "^2.2.6",
"vue-carousel": "^0.6.4"

I made a made a basic "vue init webpack" app
did an npm install of the carousel lib
added the import and use code to src/main.js
and added the <carousel> and <slide> elements in the index.html

and I just get the plain old text "Slide 1 Content Slide 2 Content" - no carousel features

Option to auto-slide

I'd like to suggest to have an option to make the carousel auto-slide.
Something like this:

<carousel :options="{'auto-slide': true}">
    <slide>...</slide>
    <slide>...</slide>

One of the situations this package could use is for customer testimonials on the page.
It could be nice if the visitors have a peek on the few satisfaction feedback from our loyal customers.

Feature request: a way to customize navigation arrows

Is there a way to customize a color or position of navigation arrows?

navigationNextLabel usage

Hi

Not sure I'm using the navigationNextLabel correctly, but the code below, gives me an error:

Property or method "Next" is not defined on the instance but referenced during render.

<carousel :perPage="1" :navigationEnabled="false" :navigationNextLabel="Next">
    <slide>
        Slide 1 Content
    </slide>
    <slide>
        Slide 2 Content
    </slide>
</carousel>

Bug: extra blank page

I'm trying to copy from one of the example fiddle, however I'm encountering an issue where the pagination and carousel showing extra blank page(s).

here's the fiddle
https://jsfiddle.net/irhamkim/dqwbjkre/1/

Feature: Add class 'active' to set the active slide

Question: is there any attribute to remove navigation dots?

I want remove just the navigation dots and use only the next and prev buttons.

Feature request: Carousel direction

Hi,

Can we have a setting to define direction to slide like horizontal as well as vertical?

Expected Number, got String

I am using code from your own example.

<carousel :perPage="1" paginationActiveColor="#42b983" paginationColor="#b2ebd1" paginationSize="5" easing="linear" speed="300">

I got to errors with paginationSize and speed!

Feature request: Add class to active pagination item

Hello, it will be perfect to add some class to active element.
User will be able to easy customize it.

trying to style custom elements but not seeming to work...

trying to style the 'carousel' and 'slide' custom elements that vue-carousel exposes but it does not seem to be working very well...dunno what I'm doing wrong here... I imported the component globally then added it to my app component, then in the styles section of the app component i added carousel and slide selectors and gave them bg colors to test, but the colors are not showing up at all...not sure what to do next at this point.

Please help, if possible, thank you :-)

Feature request: fade transition

Hi, nice work on this Carousel. I really like it!
I was wondering, will you be adding more transition effects in the future, i.e. fade?
Thanks!

Bug: `pageChange` event isn't triggered in in-dom template.

Currently, camel case named event is not triggered in in-dom template.
Maybe we need to change the event name like page-change or trigger both events.

Refer vuejs/vue#4044

Bug: Slides with inputs lose focus immediately when clicked

Hello

I tried this carousel and I think it´s great. It´s easy and nice to use.

But I wanted to use it with some form components and other elements different that only images. When I click on the inputs, they just lose focus immediately. I don´t want to think that this component is only mean to use for images. It could be good idea that any component could be used.

Well, if you have a solution for my situation, I would really thank you.

Again, nice component

JS function to navigate the page manually

Can we navigate the pages left and right by calling a simple function manually instead of using button clicks?

Bug: Incorrect pagination dot count

Reproduction Code

        <carousel :perPage="1" autoplay scrollPerPage easing="ease-in-out">
            <slide>a</slide>
         
            <slide>b</slide>

        </carousel>

What is expected?

Must show 2 pagination dots and will not slide on a blankpage

What happened?

Question: How can I use the carousel with server side rendering?

Please suggest how to use with Vue SSR.
I am trying to integrate this with VueJS's framework Nuxt.js

import Vue from 'vue'
if(process.BROWSER_BUILD) {
    const VueCarousel = require('vue-carousel');
    VueCarousel.default.install(Vue)
}

I am getting this

vue.runtime.common.js:521 [Vue warn]: The client-side rendered virtual DOM tree is not matching server-rendered content. This is likely caused by incorrect HTML markup, for example nesting block-level elements inside

, or missing . Bailing hydration and performing full client-side render.

Although I am able to make it work in dev mode, regardless of the warning.
On production mode vue-carousel doesn't work and doesn't show images at all.

Please suggest.

:navigationNextLabel='something' doesn't work

Hello ,

This parameter seems doesn't work :

:navigationNextLabel='test'

Any issue or I use it in the wrong way ? I also declare :navigationEnabled to True.

Thank you.

Feature request: set starting slide index

Great slider - thank you very much!

I was wondering if we could be allowed to set the first slide index? I would like to start my slider on the very last slide in the list. Or maybe there's already a way to do this that I have missed?

Thanks!

Feature: Create carousel component

https://ssense.atlassian.net/browse/ELON-770

Bug: Dynamic slides not working with slide in child template

I must say, this is a very nice carousel.

It works absolutely great when I use in combination with Laravel and add slides server side using the Blade template engine. However, I want to add these slides dynamically using Vue.

When using a Vue component that encapsulates slides instead of actual slides, dynamic slides do not work. Even when slides are directly added without the encapsulating component, they don't work.

The problem is that the first page is initialized but navigation is impossible (nor with buttons nor using the autoplay function). The rendered HTML clearly shows that there are more slides than the first page is able to contain. The template I'm using is:

<template>
  <div>
      <carousel :pagination-enabled=true :navigation-enabled=true
      :per-page=5 :scroll-per-page=true :click-target-size=20
      :autoplay="true" :autoplay-timeout="5000">
        <list-item v-for="item in items" :key="item['id']"></list-item>
      </carousel>
  </div>
</template>

The child component list-item has the following template:

<template>
  <slide class="itemType">
    <div @click="itemClick">
        ....
    </div>
  </slide>
</template>

So both contain nothing fancy.

I'm using version 0.6.4 of the carousel.

Doesn't work properly with 1 element per page.

I was trying to use the plugin with only 1 element per page but when I change from the first image to the second the new image is mounted over the first, looks like this:

Bug: Issue when perPage not defined, but breakpointSlidesPerPage is

Hey there,

I encountered a bug and was only able to create a workaround as I am too inexperienced to fix it. It's about the following code in Carousel.vue:
breakpointSlidesPerPage() { if (!this.perPageCustom) { return this.perPage } const breakpointArray = this.perPageCustom const width = this.browserWidth const breakpoints = breakpointArray.sort((a, b) => ((a[0] > b[0]) ? -1 : 1)) // Reduce the breakpoints to entries where the width is in range // The breakpoint arrays are formatted as [widthToMatch, numberOfSlides] const matches = breakpoints.filter(breakpoint => width >= breakpoint[0]) // If there is a match, the result should return only // the slide count from the first matching breakpoint const match = matches[0] && matches[0][1] return match || this.perPage },

What's wrong is, that, if I define a carousel like such:
<carousel class="ProjectSlider" :perPageCustom="[[480, 1],[768, 2]]" :navigationEnabled="true">

For devices with width > 480, 1 slide will be shown, for width > 768, 2 slides will be shown and for < 480, match will be undefined (I debugged that) and if perPage is not defined, the view will be buggy. I just set perPage to 1 to circumvent that bug, but this behaviour is not the behaviour described in the documentation.

Bug: pagination dots count error

just this simple example: i got four dots, it's ok if i use template in Vue constructor

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
    <script src="../dep/vue.js"></script>
    <script src="../dep/vue-carousel.min.js"></script>
</head>
<body>
<div id="example">
    <carousel :perPage="1">
        <slide>1</slide>
        <slide>2</slide>
        <slide>3</slide>
    </carousel>
</div>
<script>
    new Vue({
        el: '#example',
        components: {
            'carousel': VueCarousel.Carousel,
            'slide': VueCarousel.Slide
        },
    });
</script>
</body>
</html>

Doesn't work properly with 1 element per page.

I was trying to use the plugin with only 1 element per page but when I change from the first image to the second the new image is mounted over the first, looks like this:

Compile library

I'm trying to recompile the library in order to change some functionality, and these are the commands I ran:

npm install
npm run build

But I get this message:

> [email protected] build ...\node_modules\vue-carousel
> webpack --config config/webpack.min.conf.js && npm run updateDocAssets

Hash: 418ca0cfdee1742e1365
Version: webpack 1.15.0
Time: 58ms
              Asset     Size  Chunks             Chunk Names
vue-carousel.min.js  2.12 kB       0  [emitted]  main
    + 1 hidden modules

ERROR in vue-carousel.min.js from UglifyJs
SyntaxError: Unexpected token: name (Carousel) [vue-carousel.min.js:62,8]

It seems it doesn't compile .vue files. Is there a way to achieve that?

Thanks

:navigationEnabled="true" not working

I can enable navigation. Adding :navigationEnabled="true" to carousel doesn't effect anything.
Using with blank webpack starter.

Feature Request: Support variable slide widths

Hi there.
Thanks for providing this slider in the first place 🙌🏻.
But I have the following problem:
I have a slider with images with variable widths (when height is matched).
Lets imagine that the first image is about 70% width of the screen, and the second is just next to it.
So first I want to display the first image and 30% should already be filled by the second image.
If it slides 1 slide, I want it to stop as soon as the left edge of the second image is at the left edge of the slider wrapper.
I see that I can adjust the perPage setting, but this would sometimes mess up my slides (I get empty slides at the end) or some images are never displayed. And most of all: so far all my slides have the same width...

Maybe you can give me a hint how to get this done.
cheers

I have made some visualization what I am looking for:

Feature request: Dynamic slides with automatic updates

Hello,

First of all, thanks for this awesome component.
I have a carousel which contains a list of elements. This list is updated so sometimes, the number of items in the carousel changes.

Is there a way to trigger an update of the carousel ?

For example, now, if I switch from 1 item to 20 items, the pagination doesn't update and all the elements are on the same page.

I tried to call recomputeCarouselWidth without success.

Thanks!

Bug: Project license mismatch

The license reads MIT in the website footer but is specified as ISC in package.json

#speed or size?

from the doc

#speed
Size of each pagination dot. Pixel values are accepted.

Is it a speed or a size !?

How has been looping

Thank you want to and I said as soon as possible

Inline templates ignore the carousel tag attributes

First, good effort, we need a good vue carousel 👍

I've noticed an issue with the rendering when using an inline template... took me a while to work out what was happening.

I've made a copy of one of the example fiddles and replace the JS template with an inline template:

https://jsfiddle.net/doginthehat/h8uq5d0p/

The carousel works in that it's correctly laid out.

However, it seems to completely ignore any of the attributes passed to the tag.

So in this instance, the number of slides and the carousel isn't responsive. It just show 2 items no matter what you give it.

<carousel :perPage="4" :perPageCustom="[[480, 2], [768, 3]]">

Haven't been able to dig in the code to find the problem but you might have some idea.

Thanks