워드프레스에서 className을 직접 사용하면 안 되는 이유
Gutenberg 블록을 직접 개발하다 보면 React의 습관대로 <div className="my-block">처럼 클래스명을 하드코딩하고 싶은 순간이 생깁니다. 문법적으로는 전혀 문제가 없어 보이지만, 워드프레스 블록 에디터 환경에서는 이렇게 작성하면 여러 가지 예상치 못한 문제가 발생합니다. 이 글에서는 왜 className을 직접 다루면 안 되는지, 그리고 대신 어떻게 처리해야 하는지 정리합니다.
1. 워드프레스는 className을 “자동으로” 관리한다
Gutenberg는 일반 React 앱과 다르게, 블록의 className을 개발자가 아니라 에디터 자체가 관리하는 구조로 설계되어 있습니다. block.json의 supports 설정(정렬, 색상, 여백, 커스텀 클래스명 등)에 따라 워드프레스는 다음과 같은 클래스를 자동으로 블록에 부여합니다.
- 블록 고유 클래스:
wp-block-내블록이름 - 정렬 관련 클래스:
alignwide,alignfull등 - 색상/타이포그래피 지원 클래스:
has-text-color,has-background등 - 사용자가 에디터에서 “추가 CSS 클래스” 필드에 직접 입력한 값
edit.js나 save.js에서 className="my-custom-class"처럼 직접 문자열을 지정해버리면, 워드프레스가 자동으로 부여하려던 이 클래스들이 덮어씌워지거나 누락됩니다. 결과적으로 관리자가 에디터에서 정렬을 바꾸거나 색상을 지정해도 실제 화면에는 반영되지 않는 버그가 생깁니다.
2. 올바른 방법 – useBlockProps() 사용하기
WordPress 5.6 이후 블록 개발 표준은 useBlockProps() 훅을 사용하는 것입니다. 이 훅이 워드프레스가 자동으로 관리해야 하는 클래스와 속성들을 전부 병합해서 반환해줍니다.
잘못된 예시:
export default function Edit() {
return (
<div className="my-custom-block">
<p>내용</p>
</div>
);
}
올바른 예시:
import { useBlockProps } from '@wordpress/block-editor';
export default function Edit() {
const blockProps = useBlockProps({
className: 'my-custom-block',
});
return (
<div { ...blockProps }>
<p>내용</p>
</div>
);
}
useBlockProps()에 추가 클래스를 전달하면, 워드프레스가 자동으로 부여하는 클래스들과 병합되어 안전하게 처리됩니다. 직접 className을 지정할 때와 달리 기존 시스템 클래스가 사라지지 않습니다.
save.js에서도 마찬가지로 useBlockProps.save()를 사용해야 저장되는 마크업에 필요한 클래스가 정상적으로 포함됩니다.
import { useBlockProps } from '@wordpress/block-editor';
export default function save() {
const blockProps = useBlockProps.save({
className: 'my-custom-block',
});
return (
<div { ...blockProps }>
<p>내용</p>
</div>
);
}
3. 직접 className을 사용했을 때 실제로 발생하는 문제들
3-1. 정렬(Alignment) 기능이 깨짐
supports.align을 활성화해도, className을 직접 하드코딩하면 사용자가 “넓게” 또는 “전체 너비”를 선택해도 실제로는 적용되지 않습니다. 워드프레스가 정렬 클래스를 부여하려는 지점에 개발자의 고정 문자열이 이미 자리를 차지하고 있기 때문입니다.
3-2. 커스텀 CSS 클래스 필드가 무시됨
에디터 사이드바의 “고급(Advanced)” 패널에는 사용자가 직접 CSS 클래스를 추가할 수 있는 필드가 있습니다. className을 직접 관리하면 이 사용자 입력값이 반영되지 않거나, 반대로 개발자가 지정한 클래스가 사라지는 충돌이 생깁니다.
3-3. 블록 검증(Validation) 오류
블록을 저장할 때 워드프레스는 save.js가 생성한 마크업과 실제 게시물 콘텐츠에 저장된 HTML을 비교해 검증합니다. 클래스명이 예상과 다르면 “이 블록에 잘못된 콘텐츠가 포함되어 있습니다” 같은 **블록 검증 오류(invalid block)**가 발생해 편집이 막힐 수 있습니다.
3-4. 테마/플러그인 간 호환성 문제
많은 테마와 플러그인은 wp-block-* 형태의 표준 클래스명을 기준으로 스타일을 적용합니다. 표준 클래스가 빠지면 테마의 기본 스타일이 전혀 적용되지 않아, 사용자 입장에서는 “테마를 바꿨는데 블록 디자인이 깨졌다”는 문제로 이어집니다.
3-5. 향후 워드프레스 업데이트와의 충돌
워드프레스 코어는 계속해서 새로운 블록 지원 기능(예: 새로운 spacing, border 옵션 등)을 추가하며, 이 기능들은 모두 자동 클래스 부여 방식으로 구현됩니다. useBlockProps()를 쓰지 않고 직접 관리하던 블록은 새 기능이 추가될 때마다 수동으로 대응해야 하지만, useBlockProps()를 사용한 블록은 코어 업데이트만으로 자동으로 새 기능을 지원받게 됩니다.
4. 정리하면
className을 직접 지정하는 방식은 순수 React 컴포넌트를 만들 때는 아무 문제가 없지만, Gutenberg 블록은 워드프레스 에디터가 클래스명을 함께 관리하는 특수한 환경이라는 점이 다릅니다. 워드프레스가 자동으로 부여하려는 정렬, 색상, 커스텀 클래스 등의 정보와 개발자가 지정한 문자열이 충돌하면서 다양한 버그로 이어지기 때문에, 반드시 useBlockProps() (edit) / useBlockProps.save() (save)를 통해 클래스를 병합하는 방식으로 작성해야 합니다.
5. 체크리스트
블록을 개발하거나 리뷰할 때 아래 항목을 확인해보세요.
edit.js에서 최상위 요소에useBlockProps()를 사용하고 있는가?save.js에서 최상위 요소에useBlockProps.save()를 사용하고 있는가?- 추가 클래스가 필요하다면
className: '...'하드코딩이 아니라useBlockProps({ className: '...' })형태로 전달했는가? block.json의supports설정(align, color, spacing 등)이 실제 에디터에서 정상 동작하는지 테스트했는가?- 에디터 “고급” 패널의 커스텀 CSS 클래스 필드가 실제로 반영되는지 확인했는가?
이 몇 가지만 지켜도 정렬 오류, 블록 검증 오류, 테마 호환성 문제 같은 흔한 버그 대부분을 사전에 방지할 수 있습니다.