react에서 swiperjs 쓰기

React 애플리케이션에서 SwiperJS를 사용하면 멋진 슬라이드 기능을 손쉽게 구현할 수 있습니다. SwiperJS는 가볍고 유연한 슬라이더 라이브러리로, 모바일 및 데스크탑 환경 모두에서 잘 작동하는 반응형 슬라이드를 구현할 수 있게 도와줍니다.

리액트나 웹페이지에서 슬라이드 효과를 줘야 한다거나 carousel 기능을 써야 할 때 유용합니다.

꽤 오래도록 사용이 되고 버전업이 되고 있는 carousel 라이브러리로 jquery가 한창 유행할때도 단골로 사용하기도 했습니다.

이번 글에서는 React 프로젝트에서 SwiperJS를 설치하고 설정하는 방법, 그리고 다양한 기능을 활용하는 방법에 대해 다룰 것입니다.

홈페이지 주소 :

https://swiperjs.com

리액트 관련 페이지 :

https://swiperjs.com/react#swiper-props

https://swiperjs.com/swiper-api#custom-build

React 프로젝트에 SwiperJS를 사용하려면 먼저 패키지를 설치해야 합니다. 아래 명령어를 통해 SwiperJS를 설치할 수 있습니다:

npm install swiper

설치가 완료되면, React 컴포넌트 내에서 SwiperJS를 사용할 준비가 됩니다. SwiperJS는 Swiper와 SwiperSlide라는 두 가지 주요 컴포넌트를 제공합니다.

SwiperJS를 React에서 사용하는 기본적인 설정은 매우 간단합니다. 아래는 기본적인 슬라이더를 구현하는 코드입니다.

import React from 'react';
import { Swiper, SwiperSlide } from 'swiper/react';
import 'swiper/swiper-bundle.min.css';

const MySlider = () => {
  return (
    
      슬라이드 1
      슬라이드 2
      슬라이드 3
      슬라이드 4
    
  );
}

export default MySlider;

SwiperJS는 많은 고급 기능들을 제공합니다.

예를 들어, 자동 슬라이드, 방향 전환, 반응형 설정 등을 쉽게 구현할 수 있습니다. 아래는 반응형 설정을 추가하는 예시입니다.

import React from 'react';
import { Swiper, SwiperSlide } from 'swiper/react';
import 'swiper/swiper-bundle.min.css';

const MyResponsiveSlider = () => {
  return (
    
      슬라이드 1
      슬라이드 2
      슬라이드 3
      슬라이드 4
    
  );
}

export default MyResponsiveSlider;

파라메터 :

이름	타입	기본값	설명
a11y	any		a11y 파라미터를 포함하는 객체 또는 기본 설정으로 활성화하려면 boolean true.
allowSlideNext	boolean	true	슬라이드를 다음 방향(오른쪽 또는 아래)으로 전환할 수 없도록 하려면 false로 설정합니다.
allowSlidePrev	boolean	true	슬라이드를 이전 방향(왼쪽 또는 위)으로 전환할 수 없도록 하려면 false로 설정합니다.
allowTouchMove	boolean	true	false로 설정하면, 슬라이드를 변경하는 유일한 방법은 slidePrev 또는 slideNext와 같은 외부 API 기능을 사용하는 것입니다.
autoHeight	boolean	false	슬라이더 래퍼의 높이가 현재 활성 슬라이드의 높이에 맞게 조정되도록 true로 설정합니다.
autoplay	any		자동 재생 파라미터가 포함된 객체 또는 기본 설정으로 활성화하려면 boolean true.
breakpoints	object		화면 크기에 따라 서로 다른 파라미터를 설정할 수 있습니다. 모든 파라미터가 breakpoints에서 변경 가능한 것은 아니며, 레이아웃과 논리가 필요한 파라미터는 변경할 수 없습니다.
breakpointsBase	any	‘window’	기본값은 window입니다. container로 설정하면 브레이크포인트 키는 swiper 컨테이너의 너비를 기준으로 처리됩니다.
cardsEffect	any		카드 효과에 대한 파라미터 객체입니다.
centerInsufficientSlides	boolean	false	슬라이드가 slidesPerView보다 적으면 활성 슬라이드를 중앙에 배치합니다. 루프 모드 및 grid.rows와 함께 사용하지 않도록 권장됩니다.
centeredSlides	boolean	false	활성 슬라이드가 항상 왼쪽이 아닌 중앙에 배치되도록 설정합니다.
centeredSlidesBounds	boolean	false	활성 슬라이드를 중앙에 배치하지만 슬라이드의 시작과 끝에 여백을 추가하지 않도록 설정합니다. centeredSlides: true와 함께 사용해야 하며, 루프 또는 페이지네이션과 함께 사용하지 않도록 권장됩니다.
containerModifierClass	string	‘swiper-‘	슬라이더 컨테이너에 다양한 파라미터에 따라 추가될 수 있는 CSS 클래스의 시작 부분입니다.
controller	any		컨트롤러 파라미터가 포함된 객체 또는 기본 설정으로 활성화하려면 boolean true.
coverflowEffect	any		Coverflow 효과에 대한 파라미터 객체입니다.
createElements	boolean	false	활성화하면 Swiper는 슬라이드를 swiper-wrapper 요소로 자동으로 감싸고, 네비게이션, 페이지네이션, 스크롤바가 활성화되면 필요한 요소를 생성합니다.
creativeEffect	any		Creative 효과에 대한 파라미터 객체입니다.
cssMode	boolean	false	활성화하면 최신 CSS Scroll Snap API를 사용합니다. 이 경우 Swiper의 일부 기능이 지원되지 않으며 성능이 개선될 수 있습니다.
cubeEffect	any		Cube 효과에 대한 파라미터 객체입니다.
direction	‘horizontal’ \| ‘vertical’	‘horizontal’	‘horizontal’ 또는 ‘vertical’로 슬라이더 방향을 설정합니다.
edgeSwipeDetection	string \| boolean	false	앱에서 swipe-back 기능을 위해 Swiper 이벤트를 해제하려면 활성화합니다. ‘prevent’로 설정하면 시스템의 swipe-back 내비게이션을 방지합니다.
effect	string	‘slide’	전환 효과를 설정합니다. 가능한 값은 ‘slide’, ‘fade’, ‘cube’, ‘coverflow’, ‘flip’, ‘creative’ 또는 ‘cards’입니다.
enabled	boolean	true	Swiper가 초기화될 때 활성화됩니다. 비활성화되면 모든 네비게이션 요소가 숨겨지고 이벤트와 상호작용이 비활성화됩니다.
eventsPrefix	string	‘swiper’	Swiper 요소에서 발생하는 모든 DOM 이벤트의 접두사입니다.

메소드 & 속성

이름	타입	설명
swiper.a11y	any	접근성 관련 파라미터 객체 또는 활성화하려면 boolean true
swiper.activeIndex	number	현재 활성 슬라이드의 인덱스 번호
swiper.allowSlideNext	boolean	슬라이드를 다음 슬라이드로 전환할 수 있는 능력을 비활성화/활성화 (false/true)
swiper.allowSlidePrev	boolean	슬라이드를 이전 슬라이드로 전환할 수 있는 능력을 비활성화/활성화 (false/true)
swiper.allowTouchMove	boolean	슬라이드를 마우스로 끌거나 터치로 이동할 수 있는 능력을 비활성화/활성화 (false/true)
swiper.animating	boolean	슬라이더가 전환 중일 때 true
swiper.autoplay	any	자동 재생 설정
swiper.cardsEffect	any	카드 효과에 대한 설정
swiper.clickedIndex	number	마지막으로 클릭된 슬라이드의 인덱스 번호
swiper.clickedSlide	HTMLElement	마지막으로 클릭된 슬라이드의 HTML 요소
swiper.controller	any	컨트롤러 설정
swiper.coverflowEffect	any	Coverflow 효과에 대한 설정
swiper.creativeEffect	any	Creative 효과에 대한 설정
swiper.cubeEffect	any	Cube 효과에 대한 설정
swiper.defaults	any	기본 Swiper 설정
swiper.el	HTMLElement	슬라이더 컨테이너 HTML 요소
swiper.extendedDefaults	any	전역 Swiper 확장 옵션 객체
swiper.fadeEffect	any	Fade 효과에 대한 설정
swiper.flipEffect	any	Flip 효과에 대한 설정
swiper.freeMode	any	자유 모드 설정
swiper.hashNavigation	any	URL 해시 네비게이션 설정
swiper.height	number	컨테이너의 높이 (px)
swiper.history	any	슬라이드의 히스토리 상태 관리 설정
swiper.isBeginning	boolean	슬라이더가 “왼쪽”/”상단” 위치에 있을 경우 true
swiper.isEnd	boolean	슬라이더가 “오른쪽”/”하단” 위치에 있을 경우 true
swiper.isLocked	boolean	슬라이드가 “잠겨 있음” (watchOverflow에 의해) 상태일 경우 true
swiper.keyboard	any	키보드 네비게이션 설정
swiper.mousewheel	any	마우스 휠 네비게이션 설정
swiper.navigation	any	네비게이션 설정
swiper.originalParams	any	원본 초기화 파라미터 객체
swiper.pagination	any	페이지네이션 설정
swiper.parallax	any	패럴랙스 효과 설정
swiper.params	any	초기화 파라미터 객체
swiper.previousIndex	number	이전 활성 슬라이드의 인덱스 번호
swiper.progress	number	슬라이더의 현재 진행도 (0에서 1 사이)
swiper.realIndex	number	루프 모드에서 재배열된 슬라이드를 고려한 현재 활성 슬라이드의 인덱스 번호
swiper.scrollbar	any	스크롤바 설정
swiper.slides	HTMLElement[]	슬라이드 HTML 요소 배열
swiper.slidesEl	HTMLElement	슬라이드 래퍼 HTML 요소
swiper.slidesGrid	number[]	슬라이드 그리드 배열
swiper.slidesSizesGrid	number[]	슬라이드의 크기 배열
swiper.snapGrid	number[]	슬라이드 스냅 그리드
swiper.snapIndex	number	현재 스냅 그리드에서의 인덱스 번호
swiper.swipeDirection	‘prev’ \| ‘next’	슬라이드 방향
swiper.thumbs	any	썸네일 설정
swiper.touches	object	터치 이벤트 관련 속성들
swiper.translate	number	슬라이드 래퍼의 현재 translate 값
swiper.virtual	any	가상 슬라이드 설정
swiper.width	number	컨테이너의 너비 (px)
swiper.wrapperEl	HTMLElement	슬라이드 래퍼 HTML 요소
swiper.zoom	any	줌 설정

SwiperJS 이벤트

이름	설명
init	Swiper가 초기화될 때 발생하는 이벤트
slideChange	슬라이드가 변경될 때 발생하는 이벤트
slideChangeTransitionStart	슬라이드 전환이 시작될 때 발생하는 이벤트
slideChangeTransitionEnd	슬라이드 전환이 끝날 때 발생하는 이벤트
sliderMove	슬라이더가 이동하는 동안 발생하는 이벤트
transitionStart	슬라이더의 전환이 시작될 때 발생하는 이벤트
transitionEnd	슬라이더의 전환이 끝날 때 발생하는 이벤트
reachBeginning	슬라이더가 가장 첫 번째 슬라이드에 도달할 때 발생하는 이벤트
reachEnd	슬라이더가 가장 마지막 슬라이드에 도달할 때 발생하는 이벤트
fromEdge	슬라이더가 양 끝에서 벗어날 때 발생하는 이벤트
setTranslate	슬라이드의 위치를 설정할 때 발생하는 이벤트
setTransition	슬라이드의 전환을 설정할 때 발생하는 이벤트
resize	슬라이더 크기가 변경될 때 발생하는 이벤트
click	슬라이더 내에서 클릭 이벤트가 발생할 때
doubleClick	슬라이더 내에서 더블 클릭 이벤트가 발생할 때
touchStart	터치가 시작될 때 발생하는 이벤트
touchMove	터치가 이동할 때 발생하는 이벤트
touchEnd	터치가 종료될 때 발생하는 이벤트

SwiperJS 이벤트

이벤트 이름	인수	설명
activeIndexChange	(swiper)	활성 인덱스가 변경될 때 발생
afterInit	(swiper)	초기화 직후에 발생
beforeDestroy	(swiper)	Swiper가 파괴되기 직전에 발생
beforeInit	(swiper)	초기화 직전에 발생
beforeLoopFix	(swiper)	“loop fix” 직전에 발생
beforeResize	(swiper)	리사이즈 처리 직전에 발생
beforeSlideChangeStart	(swiper)	슬라이드 전환이 시작되기 직전에 발생
beforeTransitionStart	(swiper, speed, internal)	전환 시작 직전에 발생
breakpoint	(swiper, breakpointParams)	브레이크포인트가 변경될 때 발생
changeDirection	(swiper)	방향이 변경될 때 발생
click	(swiper, event)	사용자가 Swiper를 클릭/탭할 때 발생. pointerup 이벤트가 인수로 전달됨
destroy	(swiper)	Swiper가 파괴될 때 발생
doubleClick	(swiper, event)	사용자가 Swiper를 더블 클릭/탭할 때 발생
doubleTap	(swiper, event)	사용자가 Swiper의 컨테이너를 더블 탭할 때 발생. pointerup 이벤트가 인수로 전달됨
fromEdge	(swiper)	Swiper가 시작 위치 또는 끝 위치를 벗어날 때 발생
init	(swiper)	Swiper가 초기화된 직후 발생
lock	(swiper)	Swiper가 잠겨 있을 때 발생 (watchOverflow 활성화 시)
loopFix	(swiper)	“loop fix” 이후에 발생
momentumBounce	(swiper)	모멘텀 바운스가 발생할 때 발생
observerUpdate	(swiper)	observer가 활성화되어 DOM 변화를 감지할 때 발생
orientationchange	(swiper)	화면 회전 (예: 가로 → 세로) 시 발생
progress	(swiper, progress)	Swiper의 진행도가 변경될 때 발생. progress 값이 0에서 1 사이로 전달됨
reachBeginning	(swiper)	Swiper가 시작 위치에 도달할 때 발생
reachEnd	(swiper)	Swiper가 마지막 슬라이드에 도달할 때 발생
realIndexChange	(swiper)	실제 인덱스가 변경될 때 발생
resize	(swiper)	윈도우 크기 변경 직전에 발생
setTransition	(swiper, transition)	애니메이션이 시작될 때마다 발생. 현재 전환 지속시간 (ms)이 인수로 전달됨
setTranslate	(swiper, translate)	슬라이더의 래퍼가 위치를 변경할 때 발생. 현재 translate 값이 인수로 전달됨
slideChange	(swiper)	현재 활성 슬라이드가 변경될 때 발생
slideChangeTransitionEnd	(swiper)	슬라이드 전환 애니메이션이 끝날 때 발생
slideChangeTransitionStart	(swiper)	슬라이드 전환 애니메이션이 시작될 때 발생
slideNextTransitionEnd	(swiper)	“forward” 방향으로 슬라이드가 전환 끝날 때 발생
slideNextTransitionStart	(swiper)	“forward” 방향으로 슬라이드가 전환 시작될 때 발생
slidePrevTransitionEnd	(swiper)	“backward” 방향으로 슬라이드가 전환 끝날 때 발생
slidePrevTransitionStart	(swiper)	“backward” 방향으로 슬라이드가 전환 시작될 때 발생
slideResetTransitionEnd	(swiper)	현재 슬라이드로 리셋될 때 애니메이션이 끝날 때 발생
slideResetTransitionStart	(swiper)	현재 슬라이드로 리셋될 때 애니메이션이 시작될 때 발생
sliderFirstMove	(swiper, event)	첫 번째 터치/드래그 이동 시 발생
sliderMove	(swiper, event)	사용자가 Swiper를 터치하고 이동할 때 발생. pointermove 이벤트가 인수로 전달됨
slidesGridLengthChange	(swiper)	슬라이드 그리드가 변경될 때 발생
slidesLengthChange	(swiper)	슬라이드 수가 변경될 때 발생
slidesUpdated	(swiper)	슬라이드와 크기가 계산되고 업데이트된 후 발생
snapGridLengthChange	(swiper)	스냅 그리드가 변경될 때 발생
snapIndexChange	(swiper)	스냅 인덱스가 변경될 때 발생
tap	(swiper, event)	사용자가 Swiper를 클릭/탭할 때 발생. pointerup 이벤트가 인수로 전달됨
toEdge	(swiper)	Swiper가 시작 또는 끝 위치로 이동할 때 발생
touchEnd	(swiper, event)	사용자가 Swiper를 놓을 때 발생. pointerup 이벤트가 인수로 전달됨
touchMove	(swiper, event)	사용자가 Swiper를 터치하고 이동할 때 발생. pointermove 이벤트가 인수로 전달됨
touchMoveOpposite	(swiper, event)

모듈 : swiperjs 네비게이션

이름	타입	기본값	설명
disabledClass	string	‘swiper-button-disabled’	네비게이션 버튼이 비활성화되면 추가되는 CSS 클래스 이름
enabled	boolean		브레이크포인트에서 네비게이션을 활성화하거나 비활성화할 때 사용하는 boolean 속성
hiddenClass	string	‘swiper-button-hidden’	네비게이션 버튼이 숨겨지면 추가되는 CSS 클래스 이름
hideOnClick	boolean	false	슬라이더의 컨테이너를 클릭한 후 네비게이션 버튼의 가시성을 토글할지 여부
lockClass	string	‘swiper-button-lock’	네비게이션 버튼이 잠겨 있으면 추가되는 CSS 클래스 이름
navigationDisabledClass	string	‘swiper-navigation-disabled’	브레이크포인트에서 네비게이션이 비활성화될 때, swiper 컨테이너에 추가되는 CSS 클래스 이름
nextEl	any	null	“next” 버튼처럼 작동할 요소의 CSS 선택자나 HTML 요소
prevEl	any	null	“prev” 버튼처럼 작동할 요소의 CSS 선택자나 HTML 요소

SwiperJS 네비게이션 메소드 및 이벤트

네비게이션 속성

이름	타입	설명
swiper.nextEl	HTMLElement	“next” 네비게이션 버튼의 HTML 요소
swiper.prevEl	HTMLElement	“previous” 네비게이션 버튼의 HTML 요소

네비게이션 메소드

이름	설명
swiper.destroy()	네비게이션을 파괴합니다.
swiper.init()	네비게이션을 초기화합니다.
swiper.update()	네비게이션 버튼의 상태(활성화/비활성화)를 업데이트합니다.

네비게이션 이벤트

이벤트 이름	인수	설명
navigationHide	(swiper)	네비게이션이 숨겨졌을 때 발생하는 이벤트
navigationNext	(swiper)	“next” 버튼 클릭 시 발생하는 이벤트
navigationPrev	(swiper)	“previous” 버튼 클릭 시 발생하는 이벤트
navigationShow	(swiper)	네비게이션이 표시될 때 발생하는 이벤트

SwiperJS 네비게이션 CSS 커스텀 속성

속성 이름	설명
–swiper-navigation-size	네비게이션 버튼의 크기 설정. 기본값은 44px
–swiper-navigation-top-offset	네비게이션 버튼의 상단 오프셋 설정. 기본값은 50%
–swiper-navigation-sides-offset	네비게이션 버튼의 측면 오프셋 설정. 기본값은 10px
–swiper-navigation-color	네비게이션 버튼의 색상 설정. 기본값은 var(–swiper-theme-color)

그 이외에도 그리드, 프리모드등이 있는데 이는 api페이지를 살펴보시면 됩니다.

https://swiperjs.com/swiper-api#custom-build

이벤트 사용 방법

Swiper의 이벤트는 두 가지 방법으로 사용할 수 있습니다:

1. Swiper 초기화 시 on 파라미터 사용

const swiper = new Swiper('.swiper', {
  // ...
  on: {
    init: function () {
      console.log('swiper initialized');
    },
  },
});

2. 초기화 후 on 메소드 사용

const swiper = new Swiper('.swiper', {
  // ...
});
swiper.on('slideChange', function () {
  console.log('slide changed');
});

참고: 이벤트 핸들러 내에서 this는 항상 Swiper 인스턴스를 가리킵니다.

SwiperJS는 React에서 빠르게 슬라이더를 구현할 수 있는 유용한 라이브러리입니다.

이번 글에서는 SwiperJS의 기본적인 설치 방법과 사용법, 그리고 고급 기능 활용 예시까지 살펴보았습니다.

다양한 설정을 활용해 멋진 슬라이드를 구현할 수 있으며, 반응형 웹사이트에서도 잘 작동합니다. 필요에 따라 SwiperJS를 커스터마이징하여 자신만의 슬라이드를 만들어 보세요.