Swiper slider가 안 움직일 때, wrapper와 slide 구조부터 확인하세요

홈페이지에서 메인 비주얼, 포트폴리오, 후기, 상품 카드 영역을 만들 때 Swiper slider를 사용하는 경우가 많습니다. 좌우로 넘기는 슬라이드, 모바일 카드 슬라이드, 페이지네이션 점, 이전·다음 버튼까지 비교적 깔끔하게 구성할 수 있기 때문입니다.

그런데 템플릿을 수정하다 보면 슬라이드가 갑자기 움직이지 않거나, 버튼은 보이는데 클릭해도 반응이 없거나, pagination 점은 있는데 현재 슬라이드가 바뀌지 않는 경우가 있습니다.

Swiper는 단순히 이미지를 여러 장 나열한다고 작동하는 방식이 아닙니다. 기본적으로 슬라이더 전체 영역, wrapper 영역, slide 영역이 정해진 구조로 들어가야 합니다.

디자인키트의 HTML 템플릿이나 웹디자인 소스를 수정할 때도 Swiper가 적용된 섹션을 만날 수 있습니다. 메인 슬라이드 이미지나 포트폴리오 카드를 바꾸다가 구조가 조금만 흐트러져도 슬라이더가 멈출 수 있기 때문에, 먼저 wrapper와 slide 구조를 보는 습관이 중요합니다.

Swiper slider는 왜 구조가 중요할까요?

Swiper는 슬라이드 영역을 계산해서 어느 방향으로 얼마나 이동할지 판단합니다. 이때 기준이 되는 요소가 swiper-wrapper이고, 실제 한 장씩 움직이는 항목이 swiper-slide입니다.

즉, Swiper가 정상적으로 움직이려면 아래 흐름이 맞아야 합니다.

구조가 맞지 않으면 CSS가 적용되어 화면은 비슷하게 보일 수 있어도 실제 슬라이드는 움직이지 않을 수 있습니다. 그래서 Swiper가 안 움직일 때는 “옵션이 틀렸나?”보다 “HTML 구조가 깨졌나?”를 먼저 확인하는 것이 좋습니다.

기본 구조는 어떻게 되어 있어야 할까요?

가장 기본적인 Swiper 구조는 아래와 같습니다.

<div class="swiper mainSwiper">
    <div class="swiper-wrapper">
        <div class="swiper-slide">슬라이드 1</div>
        <div class="swiper-slide">슬라이드 2</div>
        <div class="swiper-slide">슬라이드 3</div>
    </div>

    <div class="swiper-pagination"></div>

    <button type="button" class="swiper-button-prev">이전</button>
    <button type="button" class="swiper-button-next">다음</button>
</div>

여기서 중요한 것은 swiper-slide가 반드시 swiper-wrapper 안에 들어가야 한다는 점입니다.

아래처럼 wrapper 없이 slide만 나열하면 Swiper가 의도한 방식으로 슬라이드를 계산하기 어렵습니다.

<div class="swiper mainSwiper">
    <div class="swiper-slide">슬라이드 1</div>
    <div class="swiper-slide">슬라이드 2</div>
    <div class="swiper-slide">슬라이드 3</div>
</div>

화면상으로는 비슷하게 보일 수 있지만, Swiper 입장에서는 슬라이드 묶음이 제대로 잡히지 않은 상태입니다. 슬라이더가 멈췄다면 가장 먼저 wrapper가 빠지지 않았는지 확인해야 합니다.

초기화 코드가 실제 슬라이더를 찾고 있나요?

HTML 구조가 맞아도 JavaScript 초기화 코드가 해당 슬라이더를 제대로 찾지 못하면 Swiper는 작동하지 않습니다.

예를 들어 HTML에는 mainSwiper라는 클래스가 있는데, 스크립트에서는 다른 클래스를 찾고 있다면 아무 일도 일어나지 않습니다.

<script>
    const mainSwiper = new Swiper('.mainSwiper', {
        loop: true,
        pagination: {
            el: '.mainSwiper .swiper-pagination',
            clickable: true
        },
        navigation: {
            nextEl: '.mainSwiper .swiper-button-next',
            prevEl: '.mainSwiper .swiper-button-prev'
        }
    });
</script>

이때 확인할 부분은 세 가지입니다.

특히 템플릿을 복사해서 섹션을 하나 더 만들었을 때 문제가 자주 생깁니다. 같은 클래스명을 그대로 여러 곳에 사용하면 버튼이나 pagination이 다른 슬라이더와 엮일 수 있습니다.

CSS와 JS 파일 연결도 같이 확인해야 합니다

Swiper는 HTML 구조만으로 작동하지 않습니다. Swiper CSS와 JavaScript가 함께 연결되어야 합니다.

CSS가 없으면 슬라이드의 기본 배치나 크기가 어색하게 보일 수 있고, JavaScript가 없으면 슬라이드 기능 자체가 실행되지 않습니다.

점검할 부분은 아래와 같습니다.

템플릿 폴더를 옮기거나 파일명을 정리하는 과정에서 경로가 바뀌면 Swiper가 멈출 수 있습니다. 화면에서는 단순히 “슬라이드가 안 움직인다”로 보이지만, 실제 원인은 파일이 불러와지지 않는 문제일 때도 많습니다.

pagination과 navigation이 안 보일 때는 무엇을 봐야 할까요?

슬라이드는 움직이는데 pagination 점이 보이지 않거나, 이전·다음 버튼이 작동하지 않는 경우도 있습니다. 이때는 Swiper 자체보다 pagination과 navigation 요소가 제대로 연결되어 있는지 확인해야 합니다.

예를 들어 HTML에는 버튼이 있는데 옵션에서 해당 버튼을 지정하지 않았거나, 선택자가 다른 영역을 가리키고 있으면 버튼이 작동하지 않을 수 있습니다.

<div class="swiper portfolioSwiper">
    <div class="swiper-wrapper">
        <div class="swiper-slide">포트폴리오 1</div>
        <div class="swiper-slide">포트폴리오 2</div>
    </div>

    <div class="swiper-pagination"></div>
    <button type="button" class="swiper-button-prev">이전</button>
    <button type="button" class="swiper-button-next">다음</button>
</div>

<script>
    const portfolioSwiper = new Swiper('.portfolioSwiper', {
        pagination: {
            el: '.portfolioSwiper .swiper-pagination',
            clickable: true
        },
        navigation: {
            nextEl: '.portfolioSwiper .swiper-button-next',
            prevEl: '.portfolioSwiper .swiper-button-prev'
        }
    });
</script>

여러 개의 Swiper를 한 페이지에서 사용할 때는 특히 범위를 좁혀주는 것이 좋습니다. .swiper-button-next처럼 전체 페이지에서 같은 클래스를 찾게 하면 다른 슬라이더의 버튼과 연결될 수 있습니다.

슬라이드가 여러 개인데 한 장만 보이는 경우

Swiper가 움직이기는 하는데 슬라이드 개수가 의도와 다르게 보일 때도 있습니다. 이때는 slidesPerView, spaceBetween, breakpoints 옵션을 확인해야 합니다.

예를 들어 PC에서는 3개 카드가 보이고, 모바일에서는 1개 카드만 보이게 하려면 반응형 옵션을 따로 잡을 수 있습니다.

<script>
    const cardSwiper = new Swiper('.cardSwiper', {
        slidesPerView: 1,
        spaceBetween: 16,
        breakpoints: {
            768: {
                slidesPerView: 2,
                spaceBetween: 20
            },
            1024: {
                slidesPerView: 3,
                spaceBetween: 24
            }
        }
    });
</script>

모바일에서 슬라이드가 너무 작게 보이거나, PC에서 카드가 한 장만 보인다면 구조보다 옵션 문제일 수 있습니다. 하지만 이 경우에도 wrapper와 slide 구조가 먼저 맞아야 옵션이 정상적으로 적용됩니다.

숨김 영역 안에 있는 Swiper는 따로 확인해야 합니다

탭 메뉴, 팝업, 아코디언, display none 상태의 영역 안에 Swiper가 들어가 있으면 처음부터 정상적으로 크기를 계산하지 못할 수 있습니다.

예를 들어 두 번째 탭 안에 슬라이더가 있는데 페이지 로딩 시점에는 그 탭이 숨겨져 있다면, Swiper가 슬라이드 너비를 0처럼 잘못 계산할 수 있습니다. 그래서 탭을 열었을 때 슬라이드가 찌그러지거나 움직이지 않는 것처럼 보일 수 있습니다.

이런 경우에는 숨겨진 영역이 열린 뒤 Swiper를 업데이트해야 할 수 있습니다.

<script>
    cardSwiper.update();
</script>

다만 업데이트 코드를 아무 곳에나 반복해서 넣는 것은 좋지 않습니다. 탭이 실제로 열리는 시점, 팝업이 표시되는 시점처럼 화면 구조가 바뀌는 순간에 맞춰 실행하는 것이 안정적입니다.

디자인키트 템플릿 수정 시 자주 생기는 상황

디자인키트의 HTML 템플릿이나 웹디자인 소스를 수정할 때 Swiper가 멈추는 상황은 대체로 비슷합니다.

이미지를 바꾸는 과정에서 slide 요소를 지우거나, 카드 개수를 늘리면서 wrapper 바깥에 새 항목을 추가하거나, 버튼 위치를 옮기면서 선택자가 맞지 않게 되는 경우가 많습니다.

특히 아래 상황을 조심하는 것이 좋습니다.

Swiper는 구조가 분명한 라이브러리입니다. 그래서 오류가 생겼을 때도 감으로 수정하기보다 구조, 파일, 초기화, 옵션 순서로 보면 원인을 더 빠르게 찾을 수 있습니다.

Swiper slider 점검 순서

이 순서대로 보면 불필요하게 코드를 많이 바꾸지 않아도 됩니다. Swiper 문제는 대부분 구조, 선택자, 파일 연결, 초기화 순서에서 시작되는 경우가 많습니다.

자주 묻는 질문

Swiper는 옵션보다 구조를 먼저 봐야 합니다

Swiper slider가 안 움직일 때는 옵션을 계속 바꾸기보다 구조를 먼저 확인해야 합니다. 슬라이더 전체 영역, wrapper, slide가 올바르게 들어가 있는지 보는 것이 우선입니다.

그다음 CSS와 JS 파일 연결, 초기화 코드, pagination과 navigation 선택자, 반응형 옵션을 차례대로 점검하면 문제를 더 쉽게 찾을 수 있습니다.

디자인키트의 HTML 템플릿이나 웹디자인 소스를 수정할 때도 Swiper는 메인 비주얼, 포트폴리오, 후기, 카드형 콘텐츠에서 자주 쓰일 수 있습니다. 이미지를 바꾸거나 슬라이드 개수를 늘릴 때 구조를 함께 확인하면, 템플릿을 수정한 뒤 슬라이더가 멈추는 문제를 줄일 수 있습니다.

결국 Swiper의 핵심은 많은 옵션을 아는 것보다 기본 구조를 정확히 유지하는 데 있습니다. wrapper와 slide 구조가 안정적으로 잡혀 있어야 pagination, navigation, 반응형 옵션도 의도한 대로 작동합니다.