swiper 옵션

a11y (접근성)

타입: object 또는 boolean

true로 설정하면 기본 접근성 설정이 활성화
객체로 접근성 관련 메시지 등 세부 옵션을 직접 설정

const swiper = new Swiper('.swiper', {
  a11y: {
    prevSlideMessage: '이전 슬라이드',  // 이전 슬라이드 버튼에 대한 설명
    nextSlideMessage: '다음 슬라이드',  // 다음 슬라이드 버튼에 대한 설명
  },
});

allowSlideNext

타입: boolean
기본값: true

false로 설정하면 사용자가 다음 슬라이드 방향(오른쪽 또는 아래)으로 스와이프하는 것이 불가능

allowTouchMove

타입: boolean
기본값: true

false로 설정하면 사용자의 터치 또는 드래그로 슬라이드를 이동할 수 없으며,
슬라이드 변경은 오직 외부 API 함수(slidePrev(), slideNext())로만 가능

autoHeight

타입: boolean
기본값: false

true로 설정하면 현재 활성화된 슬라이드의 높이에 맞춰 슬라이더 래퍼의 높이가 자동으로 조절

breakpoints (반응형 설정)

타입: object

화면 크기별로 다른 옵션을 설정
단, 레이아웃과 로직에 크게 영향을 주는 옵션들(예: loop, effect)은 사용할 수 없음
slidesPerView, spaceBetween, grid.rows 등은 가능

breakpointsBase

타입: any
기본값: 'window'

breakpoints의 기준이 되는 대상을 설정
'window' (기본값): 브라우저 창 너비 기준으로 동작
'container': Swiper 컨테이너(부모 요소)의 너비 기준으로 동작

window면 전체 창 크기에 따라 반응형이 바뀌고
container면 swiper가 담긴 요소 크기에 따라 반응형이 적용

cardsEffect

타입: object

카드 스타일의 효과를 위한 세부 설정을 담는 객체
Swiper를 effect: 'cards'로 설정했을 때 사용

centerInsufficientSlides

타입: boolean
기본값: false

slidesPerView보다 슬라이드 개수가 적을 때 슬라이드를 가운데 정렬함
다만 loop 모드와 grid.rows 옵션과 함께 사용하면 안 됨

centeredSlides

타입: boolean
기본값: false

true로 설정하면 활성 슬라이드(active slide)를 가운데 정렬

centeredSlidesBounds

타입: boolean
기본값: false

centeredSlides가 true일 때 활성 슬라이드를 가운데 정렬하면서
슬라이더의 시작과 끝 부분에 빈 공간(간격)이 추가되지 않도록 함
loop 모드나 페이지네이션과는 함께 사용하지 않는 것이 좋음

containerModifierClass

타입: string
기본값: 'swiper-'

Swiper 컨테이너에 추가되는 CSS 클래스의 접두사(prefix)
다양한 옵션에 따라 컨테이너에 붙는 클래스 이름이 이 값을 기반으로 생성

coverflowEffect

타입: object

Coverflow 효과에 대한 세부 옵션을 담는 객체
Swiper를 effect: 'coverflow'로 설정했을 때 사용.

createElements

타입: boolean
기본값: false

이 옵션을 켜면 Swiper가 자동으로 슬라이드를 swiper-wrapper 요소로 감싸고,
내비게이션, 페이지네이션, 스크롤바 요소도 필요할 때 자동으로 생성
(해당 기능들을 활성화할 때 관련 파라미터가 있거나 true로 설정한 경우)

creativeEffect

타입: object

Swiper의 창의적인(creative) 효과를 위한 세부 옵션
effect: 'creative' 와 함께 사용합니다.

cssMode

타입: boolean
기본값: false

true로 설정하면 최신 CSS Scroll Snap API를 사용해 슬라이더를 구현
이 모드는 Swiper의 모든 기능을 지원하지는 않지만, 간단한 설정에서는 성능이 훨씬 좋음

cssMode 활성화 시 미지원 기능:
Cube 효과
speed 파라미터가 동작하지 않을 수 있음
모든 transition 시작/끝 관련 이벤트 (대신 slideChange 이벤트 사용)
slidesPerGroup 제한적 지원
simulateTouch 효과 없음, 마우스 드래그 불가
resistance 동작하지 않음
allowSlidePrev/Next 무시
swipeHandler 무시

direction

타입: 'horizontal' | 'vertical'
기본값: 'horizontal'

슬라이더 방향을 설정
가로(horizontal) 또는 세로(vertical) 슬라이더로 지정 가능

edgeSwipeDetection

타입: string | boolean
기본값: false

앱 내에서 스와이프 백(뒤로가기) 제스처를 인식하도록 Swiper 이벤트를 활성화
'prevent'로 설정하면 시스템의 뒤로가기 네비게이션을 막음
이 기능은 터치 이벤트(touch)에서만 동작하며, iOS/안드로이드에서는 작동하지만
Windows 터치 기기에서는 동작 안 함

edgeSwipeThreshold

타입: number
기본값: 20

앱에서 스와이프 백(뒤로가기) 제스처를 인식하는 영역의 너비(px)
화면 왼쪽 가장자리에서부터 이 값만큼 떨어진 영역 내에서 터치 이벤트가 활성화

effect

타입: 'slide' | 'fade' | 'cube' | 'coverflow' | 'flip' | 'creative' | 'cards'
기본값: 'slide'

슬라이더 전환 효과를 설정
선택 가능한 효과: 슬라이드, 페이드, 큐브, 커버플로우, 플립, 크리에이티브, 카드

fadeEffect

타입: object

페이드 효과 설정 객체

flipEffect

타입: object

플립 효과 설정 객체

focusableElements

타입: string
기본값: 'input, select, option, textarea, button, video, label'

포커스 가능한 요소들의 CSS 선택자
해당 요소가 포커스 되었을 때 스와이핑이 비활성화

followFinger

타입: boolean
기본값: true

이 옵션을 끄면 손가락으로 누르고 있는 동안 슬라이더가 움직이지 않고, 손을 뗄 때만 애니메이션됨

freeMode

타입: boolean 또는 object

자유 모드 활성화 여부 및 설정
true로 간단히 활성화하거나, 객체로 상세 설정 가능

const swiper = new Swiper('.swiper', {
  freeMode: true,
});

const swiper = new Swiper('.swiper', {
  freeMode: {
    enabled: true,
    sticky: true, // 스크롤 멈춤 효과 등 추가 옵션
  },
});

grabCursor

타입: boolean
기본값: false

데스크탑 환경에서 마우스 커서를 잡는 모양으로 바꿔서 사용자 경험을 향상
true일 때 슬라이더 위에 마우스가 있을 경우 커서가 ‘손 모양’으로 변경

grid

타입: object

여러 줄로 된 슬라이더를 활성화하는 설정
예: 2줄짜리 슬라이더

hashNavigation

타입: object 또는 boolean

URL 해시 기반 내비게이션 활성화 옵션
true면 기본 설정으로 활성화 객체로 상세 설정 가능

height

타입: null 또는 number
기본값: null

Swiper 컨테이너 높이(px)를 강제로 설정
보통 숨겨진 상태에서 초기화하거나 서버 사이드 렌더링(SSR) 환경에서 사용
이 옵션을 사용하면 반응형이 되지 않음

history

타입: object 또는 boolean

히스토리 API를 사용해 슬라이드별로 고유 URL을 가짐
data-history 속성을 이용해 각 슬라이드 URL 지정
기본 설정은 true로 활성화

const swiper = new Swiper('.swiper', {
  history: {
    replaceState: true,
  },
});

init

타입: boolean
기본값: true

Swiper가 생성 시 자동으로 초기화될지 여부
false로 하면 수동으로 swiper.init() 호출 필요

initialSlide

타입: number
기본값: 0

초기 활성 슬라이드 인덱스 지정

injectStyles

타입: string[]

Swiper Element (웹 컴포넌트)에서 쉐도우 DOM에 텍스트 스타일 주입

injectStylesUrls

타입: string[]

Swiper Element에서 쉐도우 DOM에 스타일 태그 주입.

keyboard

타입: object 또는 boolean

키보드로 슬라이드 조작 활성화
true면 기본 설정 활성화

const swiper = new Swiper('.swiper', {
  keyboard: {
    enabled: true,
    onlyInViewport: false,
  },
});

lazyPreloadPrevNext

타입: number

Lazy Load 시 미리 불러올 이전/다음 슬라이드의 개수를 설정
(예: 2이면 이전 1개, 다음 1개를 미리 로드)

lazyPreloaderClass

타입: string

Lazy 로딩 프리로더에 사용할 CSS 클래스 이름

longSwipes

타입: boolean

긴 스와이프 동작을 활성화할지 여부를 설정
false로 설정하면 긴 스와이프가 무시

longSwipesMs

타입: number

긴 스와이프로 인식되기 위한 최소 시간(ms)

longSwipesRatio

타입: number

긴 스와이프로 인식되기 위한 슬라이드 너비의 비율

loop

타입: boolean

슬라이드를 무한 루프 형태로 전환
사용 조건에 맞지 않으면 빈 슬라이드를 추가해야 함

loopAddBlankSlides

타입: boolean

loop 조건을 만족하지 않을 경우 자동으로 빈 슬라이드를 추가

loopAdditionalSlides

타입: number

루프 시 추가로 복제할 슬라이드 개수를 설정

loopPreventsSliding

타입: boolean

슬라이드 전환 중일 때 중복 전환을 방지

maxBackfaceHiddenSlides

타입: number

슬라이드 개수가 이 수보다 작으면 Safari에서 시각적 깜빡임을 줄이기 위해
backface-visibility: hidden을 자동 적용

슬라이드가 많은 경우 이 옵션을 활성화하면 성능이 저하될 수 있으므로 권장x

modules

타입: any[]
사용할 Swiper 모듈을 배열로 지정

import Swiper from 'swiper';
import { Navigation, Pagination } from 'swiper/modules';

const swiper = new Swiper('.swiper', {
  modules: [ Navigation, Pagination ],
});

mousewheel

타입: object 또는 boolean
마우스 휠을 사용해 슬라이드 이동을 가능하게 함
기본 설정으로 활성화하려면 true로 지정

const swiper = new Swiper('.swiper', {
  mousewheel: {
    invert: true,
  },
});

navigation

타입: object 또는 boolean
이전/다음 버튼을 사용한 슬라이드 내비게이션 기능을 활성화

const swiper = new Swiper('.swiper', {
  navigation: {
    nextEl: '.swiper-button-next',
    prevEl: '.swiper-button-prev',
  },
});

nested

타입: boolean
기본값: false

부모 Swiper와 동일한 방향을 사용하는 내부 Swiper의 터치 이벤트 처리를 위해 활성화

noSwiping

타입: boolean
기본값: true

특정 요소에서 스와이프(슬라이드 이동)를 막고 싶을 때 사용
noSwipingClass로 지정된 클래스의 요소에 적용

noSwipingClass

타입: string
기본값: 'swiper-no-swiping'

스와이프를 막을 요소에 지정할 클래스 이름

noSwipingSelector

타입: string

noSwipingClass 대신 사용할 수 있는 CSS 셀렉터
예를 들어 'input'을 지정하면 모든 <input> 요소에서 스와이프가 비활성화

normalizeSlideIndex

타입: boolean
기본값: true

슬라이드 인덱스를 자동으로 정규화

observeParents

타입: boolean
기본값: false

Swiper의 부모 요소의 변경 사항을 감지하려면 true로 설정

observeSlideChildren

타입: boolean
기본값: false

슬라이드 내부 자식 요소의 변경 사항을 감지하려면 true로 설정

observer

타입: boolean
기본값: false

Swiper 및 자식 요소에 MutationObserver를 활성화
슬라이드 요소를 추가/삭제하거나 Swiper 스타일을 변경할 경우 자동으로 업데이트

on

타입: object
설명: 이벤트 핸들러를 등록할 수 있음

const swiper = new Swiper('.swiper', {
  on: {
    slideChange: () => {
      console.log('슬라이드 변경됨');
    },
  },
});

onAny

타입: function(handler)
모든 이벤트 발생 시 호출되는 이벤트 리스너를 추가
이벤트 이름과 전달된 인자들을 함께 확인할 수 있음

 const swiper = new Swiper('.swiper', {
  onAny(eventName, ...args) {
    console.log('이벤트 이름:', eventName);
    console.log('이벤트 데이터:', args);
  },
});

oneWayMovement

타입: boolean
기본값: false

true로 설정 시, 스와이프 방향에 관계없이 슬라이드가 항상 앞으로만 이동

pagination

타입: object 또는 boolean
페이지네이션(슬라이드 인디케이터)을 활성화
true를 설정하면 기본 설정으로 적용되고, 객체를 통해 커스터마이징

const swiper = new Swiper('.swiper', {
  pagination: {
    el: '.swiper-pagination', // 페이지네이션 요소 선택자
    type: 'bullets', // bullet, fraction, progressbar 등 사용 가능
  },
});