[CSS/SCSS] React에서 Swiper 스타일이 안 먹힐 때 – .swiper 대신 :global(.swiper)를 써야 하는 이유

리액트에서 Swiper 라이브러리를 사용할 때, SCSS로 커스텀 스타일을 주려는데 스타일이 전혀 적용되지 않았던 경험, 혹시 있으신가요?

이 문제는 SCSS 모듈(CSS Modules) 때문에 발생합니다. 그 이유와 해결 방법에 대해서 알아봅시다.

문제의 원인: SCSS Modules의 클래스 네이밍 방식

SCSS 모듈을 사용하면 클래스명은 로컬 스코프(local scope)로 변환됩니다. 즉, 아래처럼 작성한 .swiper 클래스는 실제 HTML에선 swiper_xyz123처럼 바뀝니다.

하지만 Swiper 라이브러리는 HTML을 렌더링할 때 순수한 전역 클래스명인 .swiper를 사용합니다.
결과적으로, SCSS 모듈에서 정의한 스타일은 Swiper의 클래스에 적용되지 않는 거예요.

 

해결 방법: :global()을 사용하자

SCSS 모듈 안에서도 전역 클래스명을 그대로 적용하려면 :global()을 써야 합니다.

/* Swiper.module.scss */

:global(.swiper) {
  width: 100%;
  background: red;
}

 

 

이렇게 작성하면 Swiper가 렌더링하는 .swiper 요소에 스타일이 정확히 적용됩니다.

 

 

추가 팁: Swiper 내부 요소 커스터마이징

Swiper는 .swiper, .swiper-slide, .swiper-button-prev, .swiper-pagination 등 다양한 클래스명을 사용해요.
이런 클래스들에도 동일하게 :global을 적용하면 커스터마이징이 가능합니다.

 

:global(.swiper-slide) {
  padding: 10px;
}

:global(.swiper-button-prev),
:global(.swiper-button-next) {
  color: #000;
}

 

Swiper 커스터마이징 시 꼭 알아야 할 포인트

SCSS 모듈을 사용할 때 Swiper의 기본 클래스명인 .swiper, .swiper-slide 등에 스타일을 적용하려면 :global()을 반드시 사용해야 합니다. SCSS 모듈은 클래스명을 자동으로 고유화하기 때문에, 그냥 .swiper라고 작성하면 Swiper가 생성한 실제 DOM 클래스와 일치하지 않아 스타일이 적용되지 않습니다. 반면, 일반 SCSS 파일을 사용할 경우에는 이런 문제가 발생하지 않기 때문에 그대로 클래스명을 써도 무방합니다. Swiper를 커스터마이징할 때 어떤 방식으로 스타일을 관리하고 있는지에 따라, 적절히 :global()을 활용하는 것이 중요합니다.

 

 

이렇게 SCSS 모듈을 사용할 때 Swiper의 전역 클래스에 :global()을 꼭 써야 스타일이 제대로 적용되는 이유에 대해 알아보았습니다.

 

 

 

[Git] git rebase에서 충돌이 날 때 대처법 (feat. 커밋 메시지 수정)

 

[Javascript] e.target vs e.currentTarget : 웹 개발자가 알아야 할 이벤트 객체의 중요한 속성

 

[Utility] 구독 없이 바로 사용 가능한 무료 온라인 디자인 툴 : Photopea(포토피아)

 

[macOS] 화면 공간을 더 넓게 사용하는 방법은?

 

유용한 터미널 명령어