# [[Compound Components Pattern]]

## 📌 Brief Summary
Compound Components 패턴은 암시적으로 상태를 공유하고 특정 부모 내에서만 작동하는 일련의 관련 컴포넌트들을 노출하여 선언적이고 가독성 높은 API를 구성하는 React 컴포넌트 설계 방식이다 [1]. 모든 기능을 수십 개의 prop으로 단일 컴포넌트에 쑤셔넣는 대신, 여러 협력 컴포넌트에 책임을 분산시켜 복잡한 요구사항을 처리한다 [2]. 이는 HTML의 `<select>`와 `<option>` 요소처럼 개별적인 책임을 유지하면서도 응집력 있는 단위로 함께 작동하여, 재사용 가능하고 유연한 UI를 구축하는 데 핵심적인 역할을 한다 [1, 3].

## 📖 Core Content
* **작동 원리 및 상태 관리:** 이 패턴은 React Context를 내부 계약(Internal Contract)으로 사용하여 prop drilling 없이 컴포넌트 간에 상태를 공유한다 [1, 4, 5]. 최상위(Root) 컴포넌트인 Provider는 전역 상태를 소유 및 관리하며, 하위 컴포넌트(Header, Body 등)는 전체 상태를 알 필요 없이 자신에게 필요한 좁은 범위의 상태만 소비하도록 설계된다 [6-8].
* **주요 장점:** 
  * 컴포넌트의 레이아웃과 구성을 소비자가 자유롭게 결정할 수 있는 높은 유연성을 제공한다 [3, 9].
  * 복잡한 기능을 구현할 때 수많은 설정 prop으로 인해 발생하는 'Prop Soup(프롭 수프)' 문제와 내부 로직이 숨겨지는 '블랙 박스' 문제를 해결하여 명확한 API를 유지할 수 있다 [10-12].
  * 디자인 시스템 구축 시 확장성이 뛰어나며, `aria-controls`와 같은 접근성(A11y) 속성을 수동으로 전달할 필요 없이 내부적으로 자동 연결하여 관리를 단순화할 수 있다 [13].
* **단점 및 주의사항:** 
  * 초기 작성해야 하는 보일러플레이트 코드량이 많고, 로직이 Context나 Hook에 분산되어 있어 단순 prop 기반 컴포넌트보다 버그 추적 및 디버깅이 어려울 수 있다 [13, 14].
  * 컴포넌트의 순서를 바꾸거나 생략할 수 있는 등 소비자에게 주어지는 자유도가 너무 높으면 오히려 UX나 접근성 일관성이 깨질 위험이 있어 명확한 문서화가 필수적이다 [14, 15].
* **적용 시기:** 레이아웃이 다양하게 변하거나, 소비자가 구성을 자유롭게 조합해야 할 때, 혹은 확장 가능한 공유 UI 라이브러리를 구축할 때 매우 적합하다 [15]. 하지만 Button, Icon, Badge처럼 단일하고 고정된 레이아웃을 가진 단순한 컴포넌트에는 불필요한 추상화를 초래하므로 피해야 한다 [16].

## 🔗 Knowledge Connections
- **Related Topics:** [[React Context API]], [[Headless Components]], [[Render Props]], [[Atomic Design]]
- **Projects/Contexts:** [[Radix UI]], [[Headless UI]], [[React Design Systems]]
- **Contradictions/Notes:** Compound Components는 구성의 유연성을 제공하여 재사용성을 높이지만, 너무 많은 자유도를 제공하면 일관성을 해치고 접근성을 손상시킬 수 있으므로 디자인 시스템 차원에서 "안전한 구성 경계(safe composition boundaries)"를 명확히 정의하고 문서화해야 한다 [14, 15]. 또한 모든 컴포넌트에 이 패턴을 남용하는 것은 가장 흔한 실수이며, 레이아웃이 고정된 단순 컴포넌트는 일반적인 Prop 기반 접근이 더 안전하고 단순하다고 조언한다 [16].

---
*Last updated: 2026-04-26*