tessl/npm-vue-awesome-swiper

Vue 3 wrapper component for Swiper.js carousel library providing bridge to official swiper/vue implementation

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Vue Awesome Swiper

Name: tessl/npm-vue-awesome-swiper
Author: tessl

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.

Package Information

Package Name: vue-awesome-swiper
Package Type: npm
Language: JavaScript/TypeScript
Installation: npm install swiper vue-awesome-swiper

Core Imports

All swiper/vue exports available:

import { 
  Swiper, 
  SwiperSlide, 
  useSwiper, 
  useSwiperSlide 
} from "vue-awesome-swiper";

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

Default import (plugin):

import VueAwesomeSwiper from "vue-awesome-swiper";

CommonJS:

const { Swiper, SwiperSlide, useSwiper, useSwiperSlide } = require("vue-awesome-swiper");

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.

Basic Usage

Local Component Registration:

<template>
  <swiper :modules="modules" :pagination="{ clickable: true }">
    <swiper-slide>Slide 1</swiper-slide>
    <swiper-slide>Slide 2</swiper-slide>
    <swiper-slide>Slide 3</swiper-slide>
  </swiper>
</template>

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

// Import Swiper styles
import 'swiper/css';
import 'swiper/css/pagination';

export default {
  components: {
    Swiper,
    SwiperSlide
  },
  setup() {
    return {
      modules: [Pagination]
    };
  }
};
</script>

Global Plugin Registration:

import { createApp } from 'vue';
import VueAwesomeSwiper from 'vue-awesome-swiper';
import 'swiper/css';

const app = createApp();
app.use(VueAwesomeSwiper);

Architecture

Vue Awesome Swiper is built around a simple bridge architecture:

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

Complete API Re-export

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

// These imports are functionally identical:
import { Swiper, SwiperSlide, useSwiper, useSwiperSlide } from "vue-awesome-swiper";
import { Swiper, SwiperSlide, useSwiper, useSwiperSlide } from "swiper/vue";

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

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

Capabilities

Swiper Component

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

interface SwiperComponent {
  // Component props (all Swiper configuration options)
  modules?: SwiperModule[];
  allowTouchMove?: boolean;
  slidesPerView?: number | 'auto';
  autoplay?: AutoplayOptions | boolean;
  navigation?: NavigationOptions | boolean;
  pagination?: PaginationOptions | boolean;
  scrollbar?: ScrollbarOptions | boolean;
  // ... all other Swiper options

  // Component events
  onSwiper?: (swiper: SwiperInstance) => void;
  onSlideChange?: (swiper: SwiperInstance) => void;
  onTransitionStart?: (swiper: SwiperInstance) => void;
  onTransitionEnd?: (swiper: SwiperInstance) => void;
  // ... all other Swiper events
}

// Available slots
interface SwiperSlots {
  'container-start'?: () => VNode[];
  'wrapper-start'?: () => VNode[];
  default?: () => VNode[];
  'wrapper-end'?: () => VNode[];
  'container-end'?: () => VNode[];
}

SwiperSlide Component

Individual slide component for carousel content with reactive slot props.

interface SwiperSlideComponent {
  // Slot props available to slide content
  slotProps: {
    isActive: boolean;
    isVisible: boolean;
    isDuplicate: boolean;
    isPrev: boolean;
    isNext: boolean;
  };
}

useSwiper Composable

Provides access to the Swiper instance within Swiper component context.

/**
 * Access the Swiper instance from within a Swiper component
 * @returns Swiper instance or null if not within Swiper context
 */
function useSwiper(): SwiperInstance | null;

useSwiperSlide Composable

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

/**
 * Access slide-specific data from within a SwiperSlide component
 * @returns Slide data object or null if not within SwiperSlide context
 */
function useSwiperSlide(): {
  isActive: Ref<boolean>;
  isVisible: Ref<boolean>;
  isDuplicate: Ref<boolean>;
  isPrev: Ref<boolean>;
  isNext: Ref<boolean>;
} | null;

Plugin Installation

Vue plugin interface for global component registration.

interface VueAwesomeSwiperPlugin {
  Swiper: typeof SwiperComponent;
  SwiperSlide: typeof SwiperSlideComponent;
  install(app: App): void;
}

/**
 * Install vue-awesome-swiper as a Vue plugin
 * Registers Swiper and SwiperSlide components globally
 * @param app - Vue application instance
 */
function install(app: App): void;

Module System Integration

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

import SwiperClass, { 
  Navigation, 
  Pagination, 
  Scrollbar, 
  Autoplay,
  EffectFade 
} from 'swiper';

// Register modules
SwiperClass.use([Navigation, Pagination, Scrollbar, Autoplay, EffectFade]);

Available Modules:

Navigation - Previous/next buttons
Pagination - Dots/bullets/numbers pagination
Scrollbar - Scrollbar control
Autoplay - Automatic slide progression
EffectFade, EffectCube, EffectCoverflow, EffectFlip, EffectCards, EffectCreative - Transition effects
Lazy - Lazy loading for images
Zoom - Zoom functionality
Keyboard - Keyboard control
Mousewheel - Mouse wheel control
Virtual - Virtual slides
Controller - Multi-swiper synchronization
Thumbs - Thumbnail navigation
History - Browser history integration
HashNavigation - Hash navigation
Parallax - Parallax effects
Manipulation - Dynamic slide manipulation
FreeMode - Free mode scrolling

Types

interface SwiperInstance {
  // Core methods
  slideNext(speed?: number, runCallbacks?: boolean): void;
  slidePrev(speed?: number, runCallbacks?: boolean): void;
  slideTo(index: number, speed?: number, runCallbacks?: boolean): void;
  update(): void;
  destroy(deleteInstance?: boolean, cleanStyles?: boolean): void;

  // Properties
  activeIndex: number;
  realIndex: number;
  slides: HTMLElement[];
  isBeginning: boolean;
  isEnd: boolean;
  
  // Navigation
  allowSlideNext: boolean;
  allowSlidePrev: boolean;
  allowTouchMove: boolean;
}

interface AutoplayOptions {
  delay?: number;
  disableOnInteraction?: boolean;
  reverseDirection?: boolean;
  stopOnLastSlide?: boolean;
  waitForTransition?: boolean;
}

interface NavigationOptions {
  nextEl?: string | HTMLElement;
  prevEl?: string | HTMLElement;
  hideOnClick?: boolean;
  disabledClass?: string;
  hiddenClass?: string;
}

interface PaginationOptions {
  el?: string | HTMLElement;
  type?: 'bullets' | 'fraction' | 'progressbar' | 'custom';
  clickable?: boolean;
  dynamicBullets?: boolean;
  bulletClass?: string;
  bulletActiveClass?: string;
}

interface ScrollbarOptions {
  el?: string | HTMLElement;
  hide?: boolean;
  draggable?: boolean;
  snapOnRelease?: boolean;
}

type SwiperModule = typeof Navigation | typeof Pagination | typeof Scrollbar | typeof Autoplay;

CSS Requirements

Swiper requires CSS imports for styling:

// Core Swiper styles (required)
import 'swiper/css';

// Module-specific styles (as needed)
import 'swiper/css/navigation';
import 'swiper/css/pagination';
import 'swiper/css/scrollbar';
import 'swiper/css/autoplay';
import 'swiper/css/effect-fade';
// ... other module styles

Migration Notes

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

Error Handling

Common issues and solutions:

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

Workspace: tessl
Visibility: Public
Created: 7 months ago
Last updated: 3 months ago
Describes: pkg:npm/vue-awesome-swiper@5.0.x
Publish Source: CLI
Badge