A flexible, responsive, touch-friendly carousel for Vue.js
ashleysimpson and quinnlangille Updating outdated documentation (#317)
* add autoplay documentation

* update docs and vue-play demonstration

* fix up documentation and alphabetical ordering

* docs: remove package-lock.json

* docs: update documentation for previous 3 months of changes

* docs: remove documentation on npm usage
Latest commit c660170 Nov 14, 2018

README.md

Vue Carousel

Build Status Coverage Status Latest Stable Version

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

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 0 Listen for an external navigation request using this prop.
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.
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.
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
pageChange Number Carousel "pageChange" event emits the value of the current page
slideClick Object Slide "slideClick" event throws the dataset object of the selected element
transitionEnd Carousel "transitionEnd" event is thrown when the transition end is reached

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.