1. swiper

swiper

슬라이더 라이브러리중 개인적으로 느끼기에는 가장 크고 다양하고 가이드도 잘 나와있는 라이브러리라고 생각됩니다.

기본적인 가이드나 예시가 너무나도 친절하게 나와있다보니 기본적인 상태로 사용하는데는 크게 어려움이 없는 라이브러리이지만

그래도 사용하면서 겪은 문제나 다양한 커스텀 방법을 작성해보겠습니다.

 

2. 라이브러리 사용하기

1. CDN 방식으로 사용하기

공식 가이드 문서 바로가기

다른 라이브러리들처럼 먼저 CDN 방식으로 사용하는 방법입니다. 어느 라이브러리던 해당 라이브러리의 js와 css를 연결해줘야 합니다.

<link  rel="stylesheet"  href="https://cdn.jsdelivr.net/npm/swiper@12/swiper-bundle.min.css"/>
<script src="https://cdn.jsdelivr.net/npm/swiper@12/swiper-bundle.min.js"></script>

2026.09.08 기준으로 공식 가이드 문서에는 12버전을 사용하고 있습니다. 

html 파일의 head 위치에 해당 코드를 추가해주면 swiper 준비는 끝납니다!

만약 해당 파일을 cdn 서버가 이닌 직접 프로젝트 폴더에 추가 후 작업을 원하는 경우 https://www.jsdelivr.com/package/npm/swiper

해당 링크에서도 다운로드가 가능합니다!

2. NPM 방식으로 사용하기

react 나 vue 같은 프레임워크를 사용한다면 조금 더 간단하게 사용할 수 있습니다.

npm install swiper

yarn add swiper

pnpm add swiper

이런식으로 먼저 라이브러리 설치를 진행합니다. 라이브러리 설치가 끝났다면 원하는 컴포넌트에서 아래와 같이 필요한 패키지를 import 시켜줍니다.

// 필수 코어 버전
import Swiper from 'swiper';

// 네비게이션, 페이지네이션 옵션
import { Navigation, Pagination } from 'swiper/modules';

// 필수 코어 스타일 시트
import 'swiper/css';

// 네이게이션 스타일 시트
import 'swiper/css/navigation';

// 페이지네이션 스타일 시트
import 'swiper/css/pagination';

스타일 코드의 경우 import 하지 않아도 슬라이더가 작동은 하지만 모든 스타일이 매우 요상하게 변하니 반드시 추가해주도록 합니다!

3. 기본 HTML 구조

다음으로는 슬라이드 생성을 위한 기본 HTML 구조를 확인 해보겠습니다.

<!-- swiper 스크립트 타겟 -->
<div class="swiper">
  <!-- 슬라이드 생성을 위한 추가 필수 요소 -->
  <div class="swiper-wrapper">
    <!-- 슬라이드 아이템 요소 -->
    <div class="swiper-slide">Slide 1</div>
    <div class="swiper-slide">Slide 2</div>
    <div class="swiper-slide">Slide 3</div>
    ...
  </div>
  <!-- 페이지네이션을 사용하는 경우 -->
  <div class="swiper-pagination"></div>

  <!-- 네이게이션을 사용하는 경우 -->
  <div class="swiper-button-prev"></div>
  <div class="swiper-button-next"></div>

  <!-- 스크롤바를 사용하는 경우 -->
  <div class="swiper-scrollbar"></div>
</div>

위와같이 기본적인 HTML틀을 작성해줍니다. 스크립트 타겟의 경우 원하는 class나 ID로 설정해도 되지만

바로 하위의 자식요소인 swiper-wrapper 은 필수요소이므로 기존 className을 반드시 사용해야 합니다.

4. 기본 js 구조

다음으로는 기본 javaScript 코드를 작성해주겠습니다.

const swiper = new Swiper('.swiper', {
  // 옵션을 추가할 파라미터 값
  loop: true,

  // 페이지네이션을 사용하는 경우
  pagination: {
    el: '.swiper-pagination',
  },

  // 네비게이션을 사용하는 경우
  navigation: {
    nextEl: '.swiper-button-next',
    prevEl: '.swiper-button-prev',
  },

  // 스크롤바를 사용하는 경우
  scrollbar: {
    el: '.swiper-scrollbar',
  },
});

 위와 같이 스크립트를 작성해주면 화면에 가장 기본적인 슬라이드가 표시됩니다.

 

See the Pen swiper default by 김기태 (@kkt9102) on CodePen.

5. 자주 쓰이는 옵션값

1. direction (string)

슬라이드 요소의 방향을 정하는 옵션값입니다. 옵션 파라미터를 추가하지 않으면 기본적으로 'horizontal' 상태로 슬라이드가 작동합니다.

만약 슬라이드를 세로방향으로 작동시기려면 direction 을 'vertical' 로 값을 주면 됩니다.

 

2. loop (boolean)

슬라이드를 반복시는 옵션값입니다. 옵션 파라미터를 추가하지 않을 경우 기본적으로 false 상태로 슬라이드가 작동합니다.

 

3. navigation (object)

슬라이드에 이전 과 다음 버튼을 추가하는 옵션값입니다. 해당 파라미터를 추가한 후 직접적으로 이전 과 다음 버튼이 될 요소를 지정해야 합니다.

해당 파라미터값을 작성하지 않은 경우 기본적으로 슬라이드 이동 버튼은 생성되지 않습니다.

오브젝트 형식으로 작성하며 파라미터값은 아래와 같이 추가합니다.

  navigation: {
      nextEl: '.swiper-button-next',
      prevEl: '.swiper-button-prev',
  }

 

4. pagination (object)

슬라이드에 n번째 슬라이드로 이동 또는 현재 몇번째 슬라이드인지 확인이 가능한 옵션값입니다. 해당 파라미터를 추가한 후 직접 pagination 을 생성할 요소를 지정해야 합니다.

해당 파라미터 값을 작성하지 않은 경우 기본적으로 슬라이드 pagination 은 생성되지 않습니다.

오브젝트 형식으로 작성하며 파라미터값은 아래와 같이 추가합니다.

pagination: {
    el: '.swiper-pagination',
}

 

5. spaceBetween (number)

슬라이드 요소들간의 간격을 주는 옵션입니다. 기본적으로 해당 값을 설정하지 않은 경우 각 슬라이드 요소들이 붙은 상태로 슬라이드가 진행됩니다.

해당값은 swiper-slide 요소들의 margin-right 로 추가되며 각 요소들의 inline-style로 선언됩니다.

css요소로 슬라이드 아이템간의 간격을 조절할 수는 있지만 최초로 로딩되는 슬라이드 요소에만 값이 정상적으로 들어가고 슬라이가 진행되면서 간격이 점점 더 틀어지게 되므로

슬라이드 요소간의 간격을 조절하는 경우 반드시 해당 옵션값으로 간격을 조절해야 합니다.

 

swiper 사용을 위한 가장 기본적인설명만 추가하였습니다.

포스트가 워낙 길어질 것 같으니 다음 포스트에서 추가적인 파라미터와 이것저것 다양한 스타일 수정과 자주사용했던 옵션에 관한 포스트를 추가하겠습니다.

잘못된 부분이나 조금 더 나은 개선점에대한 댓글은 언제나 환영합니다!