Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lukaszflorczak/vue-agile
🎠 A carousel component for Vue.js
https://github.com/lukaszflorczak/vue-agile
carousel carousel-component javascript js slick slide vue vue-agile vue-component vuejs
Last synced: about 2 months ago
JSON representation
🎠 A carousel component for Vue.js
- Host: GitHub
- URL: https://github.com/lukaszflorczak/vue-agile
- Owner: lukaszflorczak
- License: mit
- Archived: true
- Created: 2017-05-29T06:30:50.000Z (over 7 years ago)
- Default Branch: main
- Last Pushed: 2023-01-07T15:45:31.000Z (almost 2 years ago)
- Last Synced: 2024-09-22T05:32:28.021Z (about 2 months ago)
- Topics: carousel, carousel-component, javascript, js, slick, slide, vue, vue-agile, vue-component, vuejs
- Language: JavaScript
- Homepage: https://lukaszflorczak.github.io/vue-agile/
- Size: 8.91 MB
- Stars: 1,489
- Watchers: 46
- Forks: 167
- Open Issues: 56
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# vue-agile
[](https://www.npmjs.com/package/vue-agile) [](https://github.com/lukaszflorczak/vue-agile/blob/master/LICENSE) [](https://app.codacy.com/project/lukaszflorczak/vue-agile/dashboard) [](https://www.npmjs.com/package/vue-agile) [](http://ko-fi.com/lukaszflorczak)
> A carousel component for Vue.js inspired by [Slick](https://github.com/kenwheeler/slick/).
> Powerful, responsive, touch-friendly, with Nuxt.js SSR support, without a jQuery dependency.
**[Demo & examples](https://lukaszflorczak.github.io/vue-agile/)**
More demos and examples coming soon in [vue-agile CodePens collection](https://codepen.io/collection/AdRzJW/).
---
If you like the component remember to **star it** ⭐️. If you appreciate my work you can also **[buy me a coffee](https://ko-fi.com/lukaszflorczak)** ☕️ 😉
---
🔭 If you're looking for Vue 2 version, check **[legacy/vue-v2](https://github.com/lukaszflorczak/vue-agile/tree/legacy/vue-v2)** branch.
## Installation
```bash
npm install vue-agile
```
or
```bash
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](https://codepen.io/collection/AdRzJW/).
## Importing
#### Global
```js
// main.js
import { createApp } from 'vue'
import App from './App.vue'
import VueAgile from 'vue-agile'
createApp(App)
.use(VueAgile)
```
#### In component
```js
// YourComponent.vue
import { VueAgile } from 'vue-agile'
export default {
components: {
agile: VueAgile
}
}
```
#### Via ``
```html
<script src="https://unpkg.com/vue-agile">
```
## Usage
```vue
...
```
Every first-level child of `` is a new slide. You also can group them inside `...` tags.
## Options / Props
| Parameter | Type | Default | Description |
| --- | :---: | :---: | --- |
| [asNavFor](#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](#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
```vue
...
```
**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
```vue
...
My custom 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
```vue
...
```
```js
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
```vue
...
```
```js
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
```vue
...
prev
next
```
## Caption
To display a static caption or such like within the gallery, you can use the `caption` slot.
#### Example
```vue
currentSlide = e.currentSlide">
...
{{ captions[currentSlide] }}
export default {
data () {
return {
currentSlide: 0,
captions: [
'This is slide 1',
'This is the second slide',
'This is a third and final slide',
]
}
}
}
```
## 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
```vue
...
...
```
**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
```vue
Toggle carousel
...
```
## 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
```js
// plugins/vue-agile.js
import Vue from 'vue'
import VueAgile from 'vue-agile'
Vue.use(VueAgile)
```
```js
// nuxt.config.js
export default {
plugins: ['~/plugins/vue-agile'],
build: {
transpile: ['vue-agile']
}
}
```
To use component without SSR use the `client-only` component:
```vue
...
```
**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.
```css
.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"`
```sass
.agile--ssr
.agile__slides
> *:nth-child(1),
> *:nth-child(2)
width: 50%
```
#### Example for `:initialSlide="1"`
(Slides index starts at `0`)
```sass
.agile--ssr
.agile__slides
> *:nth-child(1)
width: 0
> *:nth-child(2)
width: 100%
```
You can also check [nuxt-agile](https://github.com/lukaszflorczak/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: `...` (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](https://cli.vuejs.org/guide/browser-compatibility.html#browserslist) or just use my config for [babel](https://github.com/lukaszflorczak/vue-agile/blob/master/babel.config.js)).