or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-vue-awesome-swiper

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/vue-awesome-swiper@5.0.x

To install, run

npx @tessl/cli install tessl/npm-vue-awesome-swiper@5.0.0

index.mddocs/

Vue Awesome Swiper

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