# [[Component API Design|Component API Design]]

## 📌 Brief Summary
컴포넌트 API 디자인(Component API Design)은 개발자가 UI 컴포넌트를 사용하고 구성하는 방식에 대한 구조적 설계와 인터페이스 정의를 의미합니다[1-3]. 잘 설계된 컴포넌트 API는 과도한 Prop 설정에 의존하는 대신 합성(Composition)을 활용하여 소비자가 유연하게 UI를 조립할 수 있도록 돕습니다[2, 4]. 이는 확장 가능하고 유지보수가 쉬운 재사용 가능한 React 컴포넌트 라이브러리를 구축하는 데 핵심적인 역할을 합니다[1, 5, 6].

## 📖 Core Content
* **Prop-Driven API의 한계**: 컴포넌트의 레이아웃과 동작을 오직 수많은 Prop(예: 다수의 불리언 플래그)으로만 제어하려 하면, 각 Prop이 결합되어 내부 로직이 복잡해지는 '블랙박스'가 형성됩니다[4, 7, 8]. 이는 예기치 않은 동작을 유발하고, 사소한 변경에도 시스템이 쉽게 깨지는 원인이 됩니다[4, 7].
* **명확한 계약(Explicit Contracts) 및 Prop 설계**: 좋은 컴포넌트 API는 직관적이고 오용하기 어려워야 합니다[3]. 구현 방식이 아닌 사용 목적(intent)에 따라 Prop 이름을 짓고, Prop의 수를 최소화하여 지나치게 복잡한 설정(Prop Soup)을 피해야 합니다[3, 9]. 또한 초기 사용을 위해 합리적인 기본값(Sensible Defaults)을 제공해야 합니다[3, 10].
* **합성 기반(Composition-Driven) 사고의 전환**: "컴포넌트가 어떻게 보여야 하는지"를 지시하는 대신, 상태와 규칙만 제공하고 "레이아웃은 소비자가 조립"하도록 구성하는 멘탈 모델로의 전환이 필요합니다[2]. 
* **확장 가능한 주요 API 패턴**:
  * **복합 컴포넌트 ([[Compound Components|Compound Components]])**: `Accordion`, `Accordion.Item` 등과 같이 여러 하위 컴포넌트가 [[React Context|React Context]]를 통해 암시적으로 상태를 공유하는 패턴입니다[5, 11, 12]. 이 패턴은 Prop 드릴링을 방지하고 선언적이며 읽기 쉬운 구조를 제공합니다[5, 11].
  * **[[Render Props|Render Props]]**: 사용자에게 특정 UI 렌더링에 대한 완전한 제어권을 넘겨주는 '탈출구(escape hatch)' 역할을 하며, 기존 API를 해치지 않으면서 고급 사용자에게 유연성을 제공합니다[13, 14].
  * **오버라이드 패턴 ([[Overrides Pattern|Overrides Pattern]])**: Uber의 Base Web 등에서 활용되는 방식으로, `overrides` prop을 통해 컴포넌트 내부의 특정 하위 요소에 접근하여 속성, 스타일, 또는 렌더링 방식 전체를 대체할 수 있게 해줍니다[9, 15-17]. 이를 통해 모든 엣지 케이스를 위한 새로운 Prop을 추가할 필요가 없어집니다[17].
  * **헤드리스 컴포넌트 ([[Headless Components|Headless Components]]) 및 슬롯 (Slots)**: UI 스타일링 없이 상태와 동작 로직만 제공하거나(Headless), 소비자가 자체 콘텐츠를 삽입할 수 있는 의도된 영역(Slots)을 제공하여 API의 복잡성을 낮추는 패턴입니다[8, 18].

## 🔗 Knowledge Connections
- **Related Topics:** [[Compound Components|Compound Components]], Headless Components, Overrides Pattern, [[Prop Drilling|Prop Drilling]], [[Atomic Design|Atomic Design]]
- **Projects/Contexts:** [[Uber Base Web|Uber Base Web]], Radix UI, [[Shopify Polaris|Shopify Polaris]]
- **Contradictions/Notes:** 복합 컴포넌트(Compound Components) 패턴은 강력한 구성의 자유도를 제공하지만, 지나친 자유로움으로 인해 사용자가 하위 컴포넌트의 순서를 임의로 변경하여 UX나 접근성의 일관성을 해칠 위험이 있습니다[19, 20]. 따라서 버튼이나 아이콘같이 단순하고 구조가 고정된 컴포넌트에서는 불필요한 추상화가 되므로 일반적인 Prop-Driven 방식이 더 안전하고 적합합니다[20, 21].

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