0
# Vue Awesome Swiper
1

2
Vue Awesome Swiper is a Vue 3 wrapper component for the Swiper.js carousel/slider library. It serves as a bridge package that re-exports all functionality from the official `swiper/vue` implementation while providing a Vue plugin interface for easy global registration.
3

4
## Package Information
5

6
- **Package Name**: vue-awesome-swiper
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install swiper vue-awesome-swiper`
10

11
## Core Imports
12

13
**All swiper/vue exports available:**
14
```typescript
15
import { 
16
  Swiper, 
17
  SwiperSlide, 
18
  useSwiper, 
19
  useSwiperSlide 
20
} from "vue-awesome-swiper";
21

22
// Complete re-export: ALL swiper/vue functionality is available
23
import * as SwiperVue from "vue-awesome-swiper";
24
```
25

26
**Default import (plugin):**
27
```typescript
28
import VueAwesomeSwiper from "vue-awesome-swiper";
29
```
30

31
**CommonJS:**
32
```javascript
33
const { Swiper, SwiperSlide, useSwiper, useSwiperSlide } = require("vue-awesome-swiper");
34
```
35

36
**Important:** This package re-exports everything from `swiper/vue` via `export * from 'swiper/vue'`. Any API available in `swiper/vue` is also available from `vue-awesome-swiper`.
37

38
## Basic Usage
39

40
**Local Component Registration:**
41

42
```vue
43
<template>
44
  <swiper :modules="modules" :pagination="{ clickable: true }">
45
    <swiper-slide>Slide 1</swiper-slide>
46
    <swiper-slide>Slide 2</swiper-slide>
47
    <swiper-slide>Slide 3</swiper-slide>
48
  </swiper>
49
</template>
50

51
<script>
52
import SwiperClass, { Pagination } from 'swiper';
53
import { Swiper, SwiperSlide } from 'vue-awesome-swiper';
54

55
// Import Swiper styles
56
import 'swiper/css';
57
import 'swiper/css/pagination';
58

59
export default {
60
  components: {
61
    Swiper,
62
    SwiperSlide
63
  },
64
  setup() {
65
    return {
66
      modules: [Pagination]
67
    };
68
  }
69
};
70
</script>
71
```
72

73
**Global Plugin Registration:**
74

75
```javascript
76
import { createApp } from 'vue';
77
import VueAwesomeSwiper from 'vue-awesome-swiper';
78
import 'swiper/css';
79

80
const app = createApp();
81
app.use(VueAwesomeSwiper);
82
```
83

84
## Architecture
85

86
Vue Awesome Swiper is built around a simple bridge architecture:
87

88
- **Complete Re-export Layer**: Transparently re-exports **ALL** APIs from `swiper/vue` using `export * from 'swiper/vue'` - this includes components, composables, types, and utilities
89
- **Plugin Interface**: Provides a Vue plugin with `install` method for global component registration
90
- **Component Bridge**: Exposes `Swiper` and `SwiperSlide` components through both named and default exports
91
- **TypeScript Integration**: Full TypeScript support with type definitions matching the official Swiper Vue implementation
92
- **API Equivalence**: All imports from `vue-awesome-swiper` are functionally identical to imports from `swiper/vue`
93

94
## Complete API Re-export
95

96
This package provides complete access to the `swiper/vue` API through `export * from 'swiper/vue'`. This means:
97

98
```typescript { .api }
99
// These imports are functionally identical:
100
import { Swiper, SwiperSlide, useSwiper, useSwiperSlide } from "vue-awesome-swiper";
101
import { Swiper, SwiperSlide, useSwiper, useSwiperSlide } from "swiper/vue";
102

103
// ALL swiper/vue exports are available, including but not limited to:
104
// - Swiper component with all props, events, and slots
105
// - SwiperSlide component with reactive slot props  
106
// - useSwiper() composable for accessing Swiper instance
107
// - useSwiperSlide() composable for slide-specific data
108
// - All TypeScript types and interfaces from swiper/vue
109
// - Any additional utilities or helpers from swiper/vue
110
```
111

112
**API Coverage:** According to the original repository documentation, "All options and events of the original Swiper are supported" through this re-export mechanism.
113

114
## Capabilities
115

116
### Swiper Component
117

118
Main carousel container component with full Swiper.js functionality and Vue 3 integration.
119

120
```typescript { .api }
121
interface SwiperComponent {
122
  // Component props (all Swiper configuration options)
123
  modules?: SwiperModule[];
124
  allowTouchMove?: boolean;
125
  slidesPerView?: number | 'auto';
126
  autoplay?: AutoplayOptions | boolean;
127
  navigation?: NavigationOptions | boolean;
128
  pagination?: PaginationOptions | boolean;
129
  scrollbar?: ScrollbarOptions | boolean;
130
  // ... all other Swiper options
131

132
  // Component events
133
  onSwiper?: (swiper: SwiperInstance) => void;
134
  onSlideChange?: (swiper: SwiperInstance) => void;
135
  onTransitionStart?: (swiper: SwiperInstance) => void;
136
  onTransitionEnd?: (swiper: SwiperInstance) => void;
137
  // ... all other Swiper events
138
}
139

140
// Available slots
141
interface SwiperSlots {
142
  'container-start'?: () => VNode[];
143
  'wrapper-start'?: () => VNode[];
144
  default?: () => VNode[];
145
  'wrapper-end'?: () => VNode[];
146
  'container-end'?: () => VNode[];
147
}
148
```
149

150
### SwiperSlide Component
151

152
Individual slide component for carousel content with reactive slot props.
153

154
```typescript { .api }
155
interface SwiperSlideComponent {
156
  // Slot props available to slide content
157
  slotProps: {
158
    isActive: boolean;
159
    isVisible: boolean;
160
    isDuplicate: boolean;
161
    isPrev: boolean;
162
    isNext: boolean;
163
  };
164
}
165
```
166

167
### useSwiper Composable
168

169
Provides access to the Swiper instance within Swiper component context.
170

171
```typescript { .api }
172
/**
173
 * Access the Swiper instance from within a Swiper component
174
 * @returns Swiper instance or null if not within Swiper context
175
 */
176
function useSwiper(): SwiperInstance | null;
177
```
178

179
### useSwiperSlide Composable
180

181
Provides access to slide-specific data and state within SwiperSlide component context.
182

183
```typescript { .api }
184
/**
185
 * Access slide-specific data from within a SwiperSlide component
186
 * @returns Slide data object or null if not within SwiperSlide context
187
 */
188
function useSwiperSlide(): {
189
  isActive: Ref<boolean>;
190
  isVisible: Ref<boolean>;
191
  isDuplicate: Ref<boolean>;
192
  isPrev: Ref<boolean>;
193
  isNext: Ref<boolean>;
194
} | null;
195
```
196

197
### Plugin Installation
198

199
Vue plugin interface for global component registration.
200

201
```typescript { .api }
202
interface VueAwesomeSwiperPlugin {
203
  Swiper: typeof SwiperComponent;
204
  SwiperSlide: typeof SwiperSlideComponent;
205
  install(app: App): void;
206
}
207

208
/**
209
 * Install vue-awesome-swiper as a Vue plugin
210
 * Registers Swiper and SwiperSlide components globally
211
 * @param app - Vue application instance
212
 */
213
function install(app: App): void;
214
```
215

216
## Module System Integration
217

218
Vue Awesome Swiper works with Swiper's modular architecture. Modules must be imported from the `swiper` package and registered:
219

220
```typescript
221
import SwiperClass, { 
222
  Navigation, 
223
  Pagination, 
224
  Scrollbar, 
225
  Autoplay,
226
  EffectFade 
227
} from 'swiper';
228

229
// Register modules
230
SwiperClass.use([Navigation, Pagination, Scrollbar, Autoplay, EffectFade]);
231
```
232

233
**Available Modules:**
234
- `Navigation` - Previous/next buttons
235
- `Pagination` - Dots/bullets/numbers pagination
236
- `Scrollbar` - Scrollbar control
237
- `Autoplay` - Automatic slide progression
238
- `EffectFade`, `EffectCube`, `EffectCoverflow`, `EffectFlip`, `EffectCards`, `EffectCreative` - Transition effects
239
- `Lazy` - Lazy loading for images
240
- `Zoom` - Zoom functionality
241
- `Keyboard` - Keyboard control
242
- `Mousewheel` - Mouse wheel control
243
- `Virtual` - Virtual slides
244
- `Controller` - Multi-swiper synchronization
245
- `Thumbs` - Thumbnail navigation
246
- `History` - Browser history integration
247
- `HashNavigation` - Hash navigation
248
- `Parallax` - Parallax effects
249
- `Manipulation` - Dynamic slide manipulation
250
- `FreeMode` - Free mode scrolling
251

252
## Types
253

254
```typescript { .api }
255
interface SwiperInstance {
256
  // Core methods
257
  slideNext(speed?: number, runCallbacks?: boolean): void;
258
  slidePrev(speed?: number, runCallbacks?: boolean): void;
259
  slideTo(index: number, speed?: number, runCallbacks?: boolean): void;
260
  update(): void;
261
  destroy(deleteInstance?: boolean, cleanStyles?: boolean): void;
262

263
  // Properties
264
  activeIndex: number;
265
  realIndex: number;
266
  slides: HTMLElement[];
267
  isBeginning: boolean;
268
  isEnd: boolean;
269
  
270
  // Navigation
271
  allowSlideNext: boolean;
272
  allowSlidePrev: boolean;
273
  allowTouchMove: boolean;
274
}
275

276
interface AutoplayOptions {
277
  delay?: number;
278
  disableOnInteraction?: boolean;
279
  reverseDirection?: boolean;
280
  stopOnLastSlide?: boolean;
281
  waitForTransition?: boolean;
282
}
283

284
interface NavigationOptions {
285
  nextEl?: string | HTMLElement;
286
  prevEl?: string | HTMLElement;
287
  hideOnClick?: boolean;
288
  disabledClass?: string;
289
  hiddenClass?: string;
290
}
291

292
interface PaginationOptions {
293
  el?: string | HTMLElement;
294
  type?: 'bullets' | 'fraction' | 'progressbar' | 'custom';
295
  clickable?: boolean;
296
  dynamicBullets?: boolean;
297
  bulletClass?: string;
298
  bulletActiveClass?: string;
299
}
300

301
interface ScrollbarOptions {
302
  el?: string | HTMLElement;
303
  hide?: boolean;
304
  draggable?: boolean;
305
  snapOnRelease?: boolean;
306
}
307

308
type SwiperModule = typeof Navigation | typeof Pagination | typeof Scrollbar | typeof Autoplay;
309
```
310

311
## CSS Requirements
312

313
Swiper requires CSS imports for styling:
314

315
```typescript
316
// Core Swiper styles (required)
317
import 'swiper/css';
318

319
// Module-specific styles (as needed)
320
import 'swiper/css/navigation';
321
import 'swiper/css/pagination';
322
import 'swiper/css/scrollbar';
323
import 'swiper/css/autoplay';
324
import 'swiper/css/effect-fade';
325
// ... other module styles
326
```
327

328
## Migration Notes
329

330
- **Deprecated Package**: Vue Awesome Swiper is deprecated in favor of the official `swiper/vue` implementation
331
- **Breaking Changes**: Version 5.x is not compatible with previous versions (1.x-4.x)
332
- **Vue 3 Only**: Current version only supports Vue 3
333
- **Complete API Equivalence**: ALL APIs are identical to `swiper/vue` through `export * from 'swiper/vue'` - this package is a completely transparent bridge
334
- **Migration Path**: Replace `vue-awesome-swiper` imports with `swiper/vue` imports directly with no code changes required
335
- **Functional Equivalence**: As stated in the original documentation: imports from `vue-awesome-swiper` are "exactly equivalent to" imports from `swiper/vue`
336

337
## Error Handling
338

339
Common issues and solutions:
340

341
- **Module Registration**: Ensure Swiper modules are imported from `swiper` package and registered with `SwiperClass.use()`
342
- **CSS Missing**: Import required Swiper CSS files for proper styling
343
- **TypeScript Errors**: Ensure both `swiper` and `vue-awesome-swiper` are installed as dependencies
344
- **Vue Version**: Package requires Vue 3.x - use legacy versions for Vue 2 support