vue-directional-carousel
Version:
This is a Vue 3 component that allows you to set the direction of image movement not only vertically and horizontally but also in different directions (left, right, up, down).
199 lines (158 loc) • 7.62 kB
Markdown
This is a Vue 3 component that allows you to set the direction of image movement not only vertically and horizontally but also in different directions (left, right, up, down).
## Installation
You can install the `vue-directional-carousel` package via npm or yarn:
```bash
npm install vue-directional-carousel
```
or
```bash
yarn install vue-directional-carousel
```
## Usage
- Import the VueDirectionalCarousel component in your Vue.js project:
```javascript
import DirectionalCarousel from 'vue-directional-carousel'
```
- Register the VueDirectionalCarousel component locally in your component:
```javascript
// if use options api
export default {
components: {
DirectionalCarousel
}
}
```
- Use the vue-directional-carousel component in your template:
```html
<template>
<div>
<directional-carousel
:items="imageList"
:show-prev="true"
:show-next="true"
:interval="2000"
direction="down"
width="100%"
height="200px"
/>
</div>
</template>
<script setup>
import DirectionalCarousel from 'vue-directional-carousel'
// Define your carousel image here
const imageList = [
'src/assets/sample1.png',
'src/assets/sample2.png',
'src/assets/sample3.png',
'src/assets/sample4.png',
'src/assets/sample5.png',
...
]
</script>
```
| props | type | isRequired | default | description |
| -------------------- | ----------------------------------- | ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| items | string[] \| { src: string}[] | `Required` | | List of images to be used in the carousel. |
| width | string | Optional | '100%' | Width of the carousel. |
| height | string | Optional | '300px' | Height of the carousel. |
| direction | 'left' \| 'right' \| 'up' \| 'down' | Optional | 'right' | Direction in which the images flow. |
| duration | number | Optional | 1000 | Duration of each slide (shorter values make it faster). |
| interval | number | Optional | 0 | Auto slide interval for images (in ms). Set to 0 to disable auto sliding. |
| pauseAutoplayOnHover | boolean | Optional | false | When auto slide is enabled, pause the slide when the mouse is over an image. Resume auto slide when the mouse is moved outside the carousel area. |
| showPrev | boolean | Optional | true | Show previous button. |
| showNext | boolean | Optional | true | Show next button. |
| showDots | boolean | Optional | true | Show buttons indicating the current image sequence. Click to slide to the corresponding image. |
| currentIndex | number | Optional | 0 | Current visible slide index (0-based). Supports `v-model:currentIndex` for two-way binding so the carousel can be controlled from outside. |
## Props Validation Guidelines
For optimal usage, please ensure:
- `items` array contains at least one item
- `interval` is a non-negative number (0 or greater)
- `duration` is a positive number (greater than 0)
- `width` and `height` use valid CSS units (e.g., px, %, rem, em, vh, vw)
Example:
```vue
<DirectionalCarousel
:items="['image1.jpg', 'image2.jpg']"
width="100%"
height="300px"
:interval="2000"
:duration="1000"
/>
```
| event | payload | description |
| ---------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `update:currentIndex` | `number` | Fired whenever the visible slide changes (next/prev/dot click, autoplay, or programmatic update). Payload is the normalized index `0..items.length - 1`. Pairs with `v-model:currentIndex`. |
## Controlling the carousel from outside
You can drive the carousel from your own UI (e.g. a tab list above the slides) by binding `v-model:currentIndex`. The carousel exposes a normalized index, so the value is always within `[0, items.length - 1]` regardless of the internal infinite-loop transition.
```vue
<script setup>
import { ref } from 'vue'
import DirectionalCarousel from 'vue-directional-carousel'
const pages = [
{ title: 'Summary', src: '/reports/summary.png' },
{ title: 'Revenue', src: '/reports/revenue.png' },
{ title: 'Costs', src: '/reports/costs.png' },
{ title: 'Outlook', src: '/reports/outlook.png' }
]
const currentPage = ref(0)
</script>
<template>
<nav class="page-tabs">
<button
v-for="(page, i) in pages"
:key="i"
type="button"
:class="{ active: currentPage === i }"
@click="currentPage = i"
>
{{ page.title }}
</button>
</nav>
<DirectionalCarousel
v-model:currentIndex="currentPage"
:items="pages"
width="800px"
height="500px"
/>
</template>
```
Notes:
- If the parent does not bind `v-model:currentIndex`, the carousel manages its own state — existing usage keeps working with no changes.
- Setting an out-of-range or non-integer value is ignored and a warning is logged. The carousel stays on its current slide.
- While a transition is in flight, programmatic index changes are ignored to prevent jumpy state. The next change after the transition completes is honored.
Use Slot 'item' in your component:
```javascript
const items = ref([
{
title: "제목1",
url: "google.com",
}, {
title: "제목2",
url: "ahnlab.com",
},
]);
<DirectionalCarousel
:items="items"
direction="down"
height="50px"
width="400px"
:show-next="true"
:show-prev="true"
:interval="2000"
:pause-autoplay-on-hover="true"
>
<template
<div :style="{ backgroundColor: 'white', color: 'black', height: '100%', width: '100%' }">
{{ item.title }} / {{ item.url }}
</div>
</template>
</DirectionalCarousel>
```
MIT