Swiper_캐러셀_적용과_프로젝트_마무리

작성자:

1. Swiper란?

Swiper(스와이퍼)는 터치 슬라이드/캐러셀(Carousel, 회전목마형 슬라이드)을 쉽게 만들어주는 라이브러리이다. 넷플릭스, 유튜브, 쿠팡 같은 서비스에서 콘텐츠를 좌우로 넘기는 UI가 바로 이것이다.

이번 편에서는 6편에서 만든 Section.jsx의 그리드 레이아웃을 Swiper 캐러셀로 업그레이드한다.

순서 만들 기능 핵심 개념
1단계 Swiper 기본 적용 Swiper, SwiperSlide, 모듈 import
2단계 반응형 설정 breakpoints
3단계 자동 재생 Autoplay 모듈

2. Swiper 설치 확인

1편에서 이미 설치했지만, 혹시 빠뜨렸다면 아래 명령어를 실행한다.

npm install swiper

3. 1단계 — Swiper 기본 적용

src/components/Section.jsx 파일을 열고 전체를 아래로 교체한다.

먼저 import 부분부터 작성한다.

import Card from "./Card";
import { Swiper, SwiperSlide } from 'swiper/react';
import { Navigation, Pagination } from 'swiper/modules';
import 'swiper/css';
import 'swiper/css/navigation';
import 'swiper/css/pagination';
줄 설명
2 Swiper(컨테이너)와 SwiperSlide(각 슬라이드)를 가져온다.
3 Navigation(좌우 화살표)과 Pagination(하단 점) 모듈을 가져온다. Swiper는 필요한 기능만 모듈로 불러오는 방식을 쓴다.
4-6 Swiper CSS와 각 모듈 전용 CSS를 불러온다. 이것이 없으면 레이아웃이 깨진다.

이어서 컴포넌트 본체를 작성한다.

export default function Section({ title, items }) {
  return (
    <section className="bg-black py-10 px-4">
      <div className="container mx-auto">
        <h2 className="text-[32px] font-bold mb-6">{title}</h2>
        <Swiper
          modules={[Navigation, Pagination]}
          spaceBetween={16}
          slidesPerView={1}
          navigation
          pagination={{ clickable: true }}
        >
          {items.map((m) => (
            <SwiperSlide key={m.id}>
              <Card movie={m} />
            </SwiperSlide>
          ))}
        </Swiper>
      </div>
    </section>
  );
}
줄 설명
7 modules에 사용할 모듈을 배열로 전달한다.
8 spaceBetween={16}은 슬라이드 간 간격을 16px로 설정한다.
9 slidesPerView={1}은 한 번에 1개의 슬라이드를 보여준다.
10 navigation은 좌우 화살표 버튼을 활성화한다.
11 pagination={{ clickable: true }}는 하단에 클릭 가능한 점 인디케이터를 표시한다.
13-16 영화 배열을 순회하며 각 영화를 SwiperSlide로 감싸고, 그 안에 Card를 넣는다.

여기까지 저장하면 슬라이드가 1개씩 보이는 기본 캐러셀이 완성된다.

4. 2단계 — 반응형 설정

모바일에서는 1개, 태블릿에서는 3개, 데스크톱에서는 4개의 카드가 보이게 breakpoints를 추가한다. Swiper 태그 안에 속성을 추가한다.

        <Swiper
          modules={[Navigation, Pagination]}
          spaceBetween={16}
          slidesPerView={1}
          navigation
          pagination={{ clickable: true }}
          breakpoints={{
            640:  { slidesPerView: 2 },
            768:  { slidesPerView: 3 },
            1024: { slidesPerView: 4 },
          }}
        >

breakpoints는 화면 너비에 따라 보이는 슬라이드 수를 조절한다.

화면 너비 보이는 카드 수 해당 기기
0 ~ 639px 1개 스마트폰
640 ~ 767px 2개 큰 스마트폰 / 작은 태블릿
768 ~ 1023px 3개 태블릿
1024px 이상 4개 노트북 / 데스크톱

Tip: 숫자는 프로젝트에 맞게 자유롭게 조절할 수 있다. slidesPerView: 5로 바꾸면 한 번에 5개 카드가 보인다.

5. 3단계 — 자동 재생 추가

슬라이드가 자동으로 넘어가게 하려면 Autoplay 모듈을 추가한다.

import에 Autoplay를 추가한다.

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

그리고 Swiper 태그에 Autoplay 모듈과 옵션을 추가한다.

        <Swiper
          modules={[Navigation, Pagination, Autoplay]}
          spaceBetween={16}
          slidesPerView={1}
          navigation
          pagination={{ clickable: true }}
          autoplay={{ delay: 3000, disableOnInteraction: false }}
          loop={true}
          breakpoints={{
            640:  { slidesPerView: 2 },
            768:  { slidesPerView: 3 },
            1024: { slidesPerView: 4 },
          }}
        >
옵션 설명
delay: 3000 3초(3000ms)마다 다음 슬라이드로 넘긴다.
disableOnInteraction: false 사용자가 수동으로 넘긴 뒤에도 자동 재생을 계속한다.
loop={true} 마지막 슬라이드 다음에 처음으로 무한 반복한다.

6. 자주 쓰는 Swiper 옵션 모음


| 옵션 | 값 예시 | 설명 |
| :– | :– | :– |
| `slidesPerView` | `4` | 한 번에 보이는 슬라이드 수 |
| `spaceBetween` | `16` | 슬라이드 간 간격 (px) |
| `navigation` | `true` | 좌우 화살표 표시 |
| `pagination` | `{ clickable: true }` | 하단 점 인디케이터 표시 |
| `loop` | `true` | 무한 반복 |
| `grabCursor` | `true` | 마우스 커서가 잡기(grab) 모양으로 바뀐다 |

| 옵션 | 값 예시 | 설명 |
| :– | :– | :– |
| `delay` | `3000` | 자동 넘김 간격 (ms) |
| `disableOnInteraction` | `false` | 수동 조작 후에도 자동 재생 유지 |
| `pauseOnMouseEnter` | `true` | 마우스를 올리면 일시정지 |
| `reverseDirection` | `true` | 역방향으로 자동 넘김 |

Swiper 기본 화살표 대신 직접 디자인한 화살표를 사용할 수도 있다.

import { useRef } from "react";

export default function Section({ title, items }) {
  const prevRef = useRef(null);
  const nextRef = useRef(null);

  return (
    <section className="bg-black py-10 px-4">
      <div className="container mx-auto relative">
        <h2 className="text-[32px] font-bold mb-6">{title}</h2>
        <button ref={prevRef} className="absolute left-0 top-1/2 z-10 text-white text-2xl">◀</button>
        <button ref={nextRef} className="absolute right-0 top-1/2 z-10 text-white text-2xl">▶</button>
        <Swiper
          modules={[Navigation]}
          navigation={{ prevEl: prevRef.current, nextEl: nextRef.current }}
          onBeforeInit={(swiper) => {
            swiper.params.navigation.prevEl = prevRef.current;
            swiper.params.navigation.nextEl = nextRef.current;
          }}
          slidesPerView={4}
          spaceBetween={16}
        >
          {items.map((m) => (
            <SwiperSlide key={m.id}>
              <Card movie={m} />
            </SwiperSlide>
          ))}
        </Swiper>
      </div>
    </section>
  );
}

useRef(유즈레프)로 버튼의 DOM 참조를 만들고, navigation의 prevEl/nextEl에 연결한다. onBeforeInit은 Swiper 초기화 직전에 참조를 다시 설정하는 안전장치이다.

7. 자주 발생하는 에러


Swiper가 설치되지 않았을 가능성이 높다. `npm install swiper`를 실행한 뒤 개발 서버를 재시작한다.

`import ‘swiper/css/navigation’;`을 빠뜨리지 않았는지 확인한다. `modules={[Navigation]}`에 Navigation이 포함되어 있어야 한다.

`.env` 파일의 API 키를 확인한다. 수정 후 반드시 개발 서버를 재시작한다.

무료 호스팅(Render)은 사용하지 않으면 슬립(Sleep) 상태가 된다. 첫 요청 시 30초~1분 기다리면 서버가 깨어난다.

8. 빌드와 배포

개발이 완료되면 프로덕션(Production, 운영) 빌드를 생성한다.

npm run build
줄 설명
1 Vite가 코드를 최적화하고 dist 폴더에 배포용 파일을 생성한다. Vercel(버셀), Netlify(넷틀리파이) 같은 호스팅 서비스에 업로드하면 된다.

빌드 결과물을 로컬에서 미리 확인하려면 아래 명령어를 실행한다.

npm run preview

9. 전체 프로젝트 파일 최종 점검

설정 파일

파일 역할 작성 편
vite.config.js Vite + React + Tailwind 설정 1편
src/index.css Tailwind 진입점 + 챗봇 CSS 1편, 9편
.env TMDB API 키 저장 1편

핵심 파일

파일 역할 작성 편
src/main.jsx React 앱 진입점 + 라우터 설정 2편
src/api/axios.js Axios 인스턴스 (TMDB, 챗봇) 3편
src/App.jsx 전체 레이아웃 + 데이터 로딩 + 헤더 + 플로팅 챗봇 4편, 8편

컴포넌트 파일

파일 역할 작성 편
src/components/Home.jsx 메인 페이지 (히어로 + 섹션) 5편
src/components/Section.jsx 영화 목록 섹션 (Swiper) 6편, 10편
src/components/Card.jsx 영화 카드 6편
src/components/MovieDetail.jsx 영화 상세 페이지 7편
src/components/Chatbot.jsx AI 챗봇 대화 UI 9편

10. 시리즈 전체 요약

편 핵심 내용
1편 프로젝트 생성, 패키지 설치, 환경 설정
2편 React 진입점, React Router 라우팅
3편 Axios 인스턴스, API 키 환경 변수
4편 App.jsx 레이아웃, useEffect 데이터 로딩
5편 Home 메인 페이지, 히어로 영상, useOutletContext
6편 Section/Card 컴포넌트, map(), Props 전달
7편 MovieDetail 상세 페이지, useParams, 조건부 렌더링
8편 플로팅 챗봇 버튼, 모달, 이벤트 버블링
9편 Chatbot 채팅 기능, fetch POST, 스프레드 연산자
10편 Swiper 캐러셀, 반응형 슬라이드, 프로젝트 마무리

이 시리즈를 완료하면 React의 핵심 개념(컴포넌트, Props, State, Hook, 라우팅)과 실전 API 연동, 외부 라이브러리 활용까지 경험한 것이다. 이제 이 GOFLIX 프로젝트를 기반으로 기능을 추가하거나, 자신만의 프로젝트를 시작해 보자.

댓글 남기기