Skip to content
This repository has been archived by the owner on Feb 24, 2023. It is now read-only.

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@lukaszflorczak
lukaszflorczak committed Dec 8, 2021
1 parent ae5765a commit fa1b99a
Showing 1 changed file with 98 additions and 100 deletions.
198 changes: 98 additions & 100 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# vue-agile
# vue-agile

[![](https://img.shields.io/npm/v/vue-agile.svg?style=flat-square&logo=npm)](https://www.npmjs.com/package/vue-agile) [![](https://img.shields.io/npm/l/vue-agile.svg?style=flat-square&logo=github)](https://github.com/lukaszflorczak/vue-agile/blob/master/LICENSE) [![](https://img.shields.io/codacy/grade/509a536ebcf64a71a119e988bd888af2.svg?style=flat-square&logo=codacy)](https://app.codacy.com/project/lukaszflorczak/vue-agile/dashboard) [![](https://img.shields.io/npm/dm/vue-agile.svg?style=flat-square&logo=npm)](https://www.npmjs.com/package/vue-agile) [![](https://img.shields.io/badge/buy%20me%20a%20coffee-+3€-red.svg?style=flat-square&logo=ko-fi)](https://ko-fi.com/lukaszflorczak)

Expand All @@ -14,60 +14,53 @@ More demos and examples coming soon in [vue-agile CodePens collection](https://c

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

![](https://muuteam.com/vue-agile.png)

---

🔭 If you're looking for Vue 2 version, check **[legacy/vue-v2](https://github.com/lukaszflorczak/vue-agile/tree/legacy/vue-v2)** branch.

---

## Important – update from version `1.0.x`

#### Events
* `afterChange` => `after-change`
* `beforeChange` => `before-change`

#### Deprecated
Deprecated props (`arrows`, `prevArrow`, `nextArrow`, `show`) and classes (`.agile__arrow`, `.agile__arrow--prev`, `.agile__arrow--next`, `.agile__slide--cloned`) from versions < `1.0` are no longer available
![](https://florczak.dev/vue-agile/banner.png)

## Installation

```bash
npm install vue-agile
```

or
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/).
**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 Vue from 'vue'
import { createApp } from 'vue'
import App from './App.vue'
import VueAgile from 'vue-agile'

Vue.use(VueAgile)
createApp(App)
.use(VueAgile)
```

#### In component

```js
// YourComponent.vue
import { VueAgile } from 'vue-agile'

export default {
components: {
agile: VueAgile
}
export default {
components: {
agile: VueAgile
}
}
```

Expand All @@ -82,23 +75,24 @@ export default {

```vue
<template>
<agile>
<div class="slide">
<h3>slide 1</h3>
</div>
...
<div class="slide">
<h3>slide n</h3>
</div>
</agile>
<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](#asNavFor) | array | `[]` | Set the carousel to be the navigation of other carousels |
Expand Down Expand Up @@ -168,9 +162,10 @@ Every first-level child of `<agile>` is a new slide. You also can group them ins
```

```js
showCurrentSlide (event) {
console.log(event)
// Shows for example: { currentSlide: 1 }
showCurrentSlide(event)
{
console.log(event)
// Shows for example: { currentSlide: 1 }
}
```

Expand All @@ -185,34 +180,35 @@ To customize responsiveness, I recommend defining your desired breakpoints and p
```

```js
data () {
return {
myOptions: {
navButtons: false,

responsive: [
{
breakpoint: 600,
settings: {
dots: false
}
},

{
breakpoint: 900,
settings: {
navButtons: true,
dots: true,
infinite: false
}
}
]
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.
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

Expand All @@ -222,10 +218,10 @@ From version `1.0` the component use slots for custom navigation buttons. It mea

```vue
<agile>
... <!-- slides -->
<template slot="prevButton">prev</template>
<template slot="nextButton">next</template>
... <!-- slides -->
<template slot="prevButton">prev</template>
<template slot="nextButton">next</template>
</agile>
```

Expand All @@ -237,30 +233,30 @@ To display a static caption or such like within the gallery, you can use the `ca

```vue
<agile @after-change="e => currentSlide = e.currentSlide">
... <!-- slides -->
<template slot="caption">{{ captions[currentSlide] }}</template>
... <!-- slides -->
<template slot="caption">{{ captions[currentSlide] }}</template>
</agile>
<script>
export default {
export default {
data () {
return {
currentSlide: 0,
captions: [
'This is slide 1',
'This is the second slide',
'This is a third and final slide',
]
}
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.
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

Expand All @@ -274,11 +270,12 @@ This option is useful for example for creating a photo gallery with two related

## `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.
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
<button @click="isActive = !isActive">Toggle carousel</button>
Expand All @@ -288,7 +285,7 @@ It is also possible to use `v-show`, but you have to use the `reload()` method.
## 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
Expand All @@ -304,61 +301,62 @@ Vue.use(VueAgile)
// nuxt.config.js

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

build: {
transpile: ['vue-agile']
}
build: {
transpile: ['vue-agile']
}
}
```

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

```vue
<client-only placeholder="Loading...">
<agile>...</agile>
<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.
**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
overflow: hidden;
width: 0
}

.agile--ssr .agile__slides > *:first-child {
width: 100%
width: 100%
}
```

At this stage slides don't have `agile__slide` class yet, so I use `> *` instead of this.
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.
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%
.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
.agile--ssr
.agile__slides
> *:nth-child(1)
width: 0
> *:nth-child(2)
width: 100%
> *: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.
Expand Down

0 comments on commit fa1b99a

Please sign in to comment.