[React - Swiper.js] 옵션 정리

📌 Swiper.js 설정 옵션 가이드

🔗Swiperjs - api

📍 Swiper 옵션 정보

📗 많이 사용하는 기본  옵션

옵션	타입	기본값
initialSlide	number	0	초기 활성화될 슬라이드 인덱스
direction	"horizontal" / "vertical"	horizontal	슬라이드 방향
loop	boolean	false	슬라이드 무한 루프
speed	number	300	슬라이드 전환 속도
slidesPerView	number / "auto"	1	한 번에 보여줄 슬라이드 개수
spaceBetween	number	0	슬라이드 간 간격(px)
centeredSlides	boolean	false	현재 슬라이드를 가운데 정렬
slidesPerGroup	number	1	그룹당 표시할 슬라이드 개수
loopFillGroupWithBlank	boolean	false	루프 모드에서, 그룹의 마지막에 빈 슬라이드를 채울지 여부
grabCursor	boolean	false	마우스를 올렸을 때 손 모양의 커서 표시

 

📗 네비게이션 & 페이지네이션

- navigation: 이전/다음 버튼 설정

- pagination: 페이지네이션(점 또는 숫자) 설정

- scrollbar: 스크롤바 설

옵션	타입	기본값
navigation	boolean / { nextEl, prevEl }	false	화살표 네비게이션 활성화
pagination	boolean / { el, clickable }	false	하단 페이지네이션(인디케이터) 설정
scrollbar	boolean / { el, draggable }	false	스크롤바 설정

 

import { Navigation, Pagination, Scrollbar } from 'swiper/modules';
import 'swiper/css/navigation';
import 'swiper/css/pagination';
import 'swiper/css/scrollbar';

// 📍 navigation
navigation: {
  nextEl: '.swiper-button-next', // 다음 버튼 요소 지정
  prevEl: '.swiper-button-prev', // 이전 버튼 요소 지정 
  disabledClass: 'swiper-button-disabled', // 비활성화 상태일 때 적용될 클래스
  hiddenClass: 'swiper-button-hidden' // 숨겨졌을 때 적용될 CSS 클래스
}

// 📍 pagination
pagination: {
  el: '.swiper-pagination', // 요소 지정
  type: 'bullets', // 'bullets', 'fraction', 'progressbar', 'custom' 스타일 설정
  clickable: true, // 클릭 설정
  dynamicBullets: false, //동일한 크기를 유지 / 활성 index와 거리에따라 bullets 크기가 동적으로 
  renderBullet: function (index, className) { // bullet이 렌더링되는 방식을 결정하는 함수
    return '<span class="' + className + '">' + (index + 1) + '</span>';
  }
}

// 📍 scrollbar
scrollbar: {
  el: '.swiper-scrollbar', //  요소 지정
  draggable: true, // 스크롤바를 드래그 가능하게 만들지 설정
  hide: false // 스크롤바를 자동으로 숨길지 설정
}

// Import Swiper React components
import { Swiper, SwiperSlide } from 'swiper/react';
// Import Swiper modules
import { Navigation, Pagination, Scrollbar } from 'swiper/modules';
// Import Swiper styles
import 'swiper/css';
import 'swiper/css/navigation';
import 'swiper/css/pagination';
import 'swiper/css/scrollbar';

export const SwiperTest = () => {
  return(
    <Swiper
      spaceBetween={10}
      slidesPerView={3}
      modules={[Navigation, Pagination, Scrollbar]}
      navigation={{
        nextEl: '.swiper-button-next',
        prevEl: '.swiper-button-prev',
        disabledClass: 'swiper-button-disabled',
        hiddenClass: 'swiper-button-hidden'
      }}
      pagination={{
        el: '.swiper-pagination',
        type: 'bullets',
        clickable: true,
        dynamicBullets: false,
        renderBullet: function (index:number, className:string) {
          return '<span class="' + className + '">' + (index + 1) + '</span>';
        }
      }}
      scrollbar={{
        el: '.swiper-scrollbar',
        draggable: true,
        hide: false
      }}
    >
      <SwiperSlide><div className="box">1</div></SwiperSlide>
      <SwiperSlide><div className="box">2</div></SwiperSlide>
      <SwiperSlide><div className="box">3</div></SwiperSlide>
      <SwiperSlide><div className="box">4</div></SwiperSlide>
      <SwiperSlide><div className="box">5</div></SwiperSlide>
      <SwiperSlide><div className="box">6</div></SwiperSlide>
      <div>
        <button className="swiper-button-next"></button>
        <button className="swiper-button-prev"></button>
      </div>
      <div className="swiper-pagination"></div>
      <div className="swiper-scrollbar"></div>
    </Swiper>
  );
};

 

 

📗 Autoplay : 자동 재생

옵션	타입	기본값
autoplay	boolean / { delay, disableOnInteraction }	false	자동 재생 활성화
autoplay.delay	number	3000	자동 재생 간격(ms)
autoplay.disableOnInteraction	boolean	true	상호작용(클릭, 드래그 등) 할 때 자동 재생을 완전히 비활성화할지를 결정
pauseOnMouseEnter	boolean	false	마우스를 슬라이드 위에 올렸을 때 자동 재생을 일시 중지할지 여부를 결정
stopOnLastSlide	boolean	false	마지막 슬라이드에서 자동 재생을 멈출지 여부를 결정합
reverseDirection	boolean	false	자동 재생의 방향을 반대로 할지 여부를 결정합니다. (true로 설정 시 슬라이드가 반대 방향으로 자동 재생)

 

📗 breakpoints  : 반응형 설정

- 화면 크기에 따라 슬라이드 설정

<Swiper
  breakpoints={{
    320: {
      slidesPerView: 1,
      spaceBetween: 10
    },
    768: {
      slidesPerView: 2,
      spaceBetween: 20
    },
    1024: {
      slidesPerView: 3,
      spaceBetween: 30
    }
  }}
>

</Swiper>

 

📗 update 

Swiper의 상태나 슬라이드 변경 시 슬라이드 재 렌더링, 레이아웃 재계산하여 update 진행 메서드

옵션	타입	기본값	설	사용법
update()	() => void		Swiper 상태와 레이아웃을 강제로 재계산하고 업데이트	swiper.update()를 호출하여 Swiper를 강제로 업데이트

 const swiperRef = useRef<SwiperClass | null>(null);

const handleUpdateSwiper = () => {
  if (swiperRef.current) {
    swiperRef.current.update();
  }
};

 

📗 observer

Swiper의 변경을 자동으로 감지하여 Swiper을 업데이트하는 기능

옵션	타입	기본값
observer	boolean	false	DOM 변경 감시를 활성화하여, Swiper가 자동으로 업데이트
observeParents	boolean	false	부모 요소의 DOM 변경을 감지하여 Swiper가 업데이트
observeSlideChildren	boolean	false	슬라이드 내 자식 요소의 DOM 변경을 감지하여 Swiper가 업데이트

<Swiper
  observer={true}
  observeParents={true}
  observeSlideChildren={false}
>...</Swiper>

 

📗 A11y : 접근성 (Accessibility)

import 'swiper/css/a11y'

 

// Import Swiper modules
import { A11y } from 'swiper/modules';
// Import Swiper styles
import 'swiper/css/a11y'

<Swiper
  // modules - A11y 추가
  modules={[A11y]}
  // 접근성 
  a11y={{
    enabled: true, // 접근성 사용
    // 👇 스크린 리더가 읽는 메시지
    prevSlideMessage: '이전 슬라이드 버튼에 포커스가 갔을 때',
    nextSlideMessage: '다음 슬라이드 버튼에 포커스가 갔을 때',
    firstSlideMessage: '첫 번째 슬라이드에 도달했을 때',
    lastSlideMessage: '마지막 슬라이드에 도달했을 때',
  }}
 >...</Swiper>

 

✅ aria 추가 확인 !

 

 

 

 

✍️ 기록

 

감사합니다. 😁