🚀 단순한 UI도 확장 가능하게: Compound Component 패턴 사용 후기

🔹 서론: 글을 작성한 이유

최근 프로젝트에서 "사용자 액션에 대한 결과를 보여주는 페이지"를 구현하게 되었다! 정말 간단한 UI였지만, 초기부터 여러 가지 것들을 고려해 만들어 보면 좋지 않을까 싶어서 컴포넌트화를 진행하기로 했다. 이번 글에서는 결론적으로 컴포넌트를 어떻게 구성했고, 그 과정에서 배운 점을 적어보려고 한다 😀

✅ 레이아웃은 일정하고 아이콘, 제목, 디스크립션만 달라지는 구조
✅ 향후 UI 변경 가능성 (ex. '메인으로 이동하기' 버튼 추가 등)
✅ 화면 구성 중 일부만 쓰이는 경우 (ex. 디스크립션 없이 아이콘과 제목만 쓰이는 경우)

위와 같은 요구사항 및 가능성을 고려했을 때, 다음과 같은 특징이 필요하다는 걸 알 수 있겠다.

⭕️ 레이아웃은 공통 + 내용만 달라지는 구조 필요
⭕️ 변경에 용이한 구조 필요
⭕️ 각 요소가 서로 의존성이 적은 구조 필요

결론적으로 나는 이런 조건을 충족하는 가장 효과적인 패턴이 💡 합성 컴포넌트라고 생각했고, 해당 패턴을 이용해서 UI를 개발하게 되었다.

🔹 합성 컴포넌트란?

프론트엔드에서 컴포넌트를 어떻게 구성할지 고민하다 보면, "어떻게 하면 더 유연하고 재사용하기 쉬운 컴포넌트를 만들 수 있을까?"라는 질문을 자주 하게 된다.
그 고민의 해결책 중 하나가 바로 합성(Composition)이다!

🔸 Composition vs Inheritance

React는 전통적인 클래스 기반 언어에서 많이 쓰이는 상속(Inheritance)보다는, 합성(Composition)을 더 선호한다. 합성은 "여러 컴포넌트를 조합해서 새로운 UI를 만들어내는 방식"으로, 컴포넌트 간의 결합도를 낮추고 더 유연한 구조를 만들 수 있게 해준다.

• 상속 : 기능을 상속받아 확장하는 방식. 컴포넌트 간 강한 의존이 생기고, 재사용이 어렵다.
• 합성 : 여러 컴포넌트를 조합해 새로운 기능을 구성하는 방식. 독립성과 확장성이 좋다.

React 공식 문서에서도 아래와 같이 말하고 있다 👀

"React는 강력한 합성 모델을 가지고 있으며, 상속 대신 합성을 사용하여 컴포넌트 간에 코드를 재사용하는 것이 좋습니다."

"Facebook에서는 수천 개의 React 컴포넌트를 사용하지만, 컴포넌트를 상속 계층 구조로 작성을 권장할만한 사례를 아직 찾지 못했습니다."

🔸 예시: children 기반 합성

가장 기본적인 합성 방식은 children을 통해 하위 요소를 주입받는 방식이다.

function Card({ children }: { children: React.ReactNode }) {
  return <div className="p-4 border rounded-md">{children}</div>;
}

<Card>
  <h2>공지사항</h2>
  <p>오늘은 오후 6시에 점검이 있습니다.</p>
</Card>

이 예제에서 Card는 내부 구조를 고정하지 않고, 부모가 넘긴 내용을 그대로 감싸서 보여준다. 이런 방식은 레이아웃, 모달, 툴팁 등 다양한 UI 요소에 쓸 수 있다.

🔸 React에서 자주 쓰이는 합성 패턴

React에서는 합성을 구현하는 방식이 꽤 다양하다. 그중 자주 쓰이는 대표적인 패턴은 아래와 같다.

1️⃣ Slot 패턴
컴포넌트 내부의 특정 영역에 내용을 명확하게 주입하고 싶을 때 쓰는 방식이다.
예를 들어 제목, 본문, 푸터를 각각 다른 슬롯으로 구성할 수 있다.

function Dialog({ title, body, footer }: Props) {
  return (
    <div className="dialog">
      <div className="dialog-title">{title}</div>
      <div className="dialog-body">{body}</div>
      <div className="dialog-footer">{footer}</div>
    </div>
  );
}

<Dialog
  title={<h2>회원가입</h2>}
  body={<SignUpForm />}
  footer={<Button>확인</Button>}
/>

2️⃣ Compound Component 패턴
하위 컴포넌트를 논리적으로 묶어서 사용하는 방식이다.
보통 Tabs, Accordion, Select 같은 구조에서 많이 쓴다.

const Tabs = ({ children }) => <div>{children}</div>;
Tabs.TabList = ({ children }) => <div className="tab-list">{children}</div>;
Tabs.TabPanel = ({ children }) => <div className="tab-panel">{children}</div>;

<Tabs>
  <Tabs.TabList>
    <button>탭 1</button>
    <button>탭 2</button>
  </Tabs.TabList>
  <Tabs.TabPanel>
    <p>탭 1의 내용</p>
  </Tabs.TabPanel>
</Tabs>

이런 방식은 컴포넌트를 더 작은 단위로 쪼개고, 각 부분에 대한 책임을 분리할 수 있게 해준다. 동시에 개발자가 사용 시점에서 어떤 구조로 사용할지 더 명확하게 제안할 수도 있다.

두 패턴을 표로 비교하자면 다음과 같다.

항목	Slot 패턴	Compound Component 패턴
구성 방식	명시적인 prop으로 영역별 내용을 전달함	하위 컴포넌트를 논리적으로 조합하여 구성
컴포넌트 구조 제어 방식	상위 컴포넌트에서 구조 제어	상위 컴포넌트가 하위 컴포넌트 집합을 제공
유연성	prop 구조를 따라야 하므로 다소 고정적	children 조합으로 유연한 구성 가능
확장성	새로운 슬롯을 추가하려면 props 수정 필요	컴포넌트만 추가하면 되므로 확장에 유리함
실제 사용 예	Dialog, Modal, Card 등 구성 요소가 명확히 구분되는 컴포넌트	Tabs, Accordion, Select, Menu 등 복잡한 구성의 UI 컴포넌트

그러므로 나는 앞서 얘기했던 "변경에 용이한 구조", "서로 의존성이 적은 구조"라는 조건을 충족하려면, Slot 패턴보다는 Compound Component 패턴이 보다 적합할 거라고 판단했고, 해당 패턴에 맞춰 구현을 진행하기로 했다 😀

🔹 Compound Component 패턴으로 구현

🔸 구조화

구조화는 다음과 같이 진행했다. 여기에 추가로 Icon은 자유도가 높기보다는, 상황에 맞는 아이콘이 명시적으로 사용될 가능성이 더 높기 때문에, Result.Image 부분에서는 type을 좀 더 활용해 보기로 했다.

최종 코드는 아래와 같다.

🔸 구현부

import Image from "next/image";

import { RESULT_IMG_MAP } from "@/constants/result/resultImg";

export type ImgKind = "letter";

function ResultImage({ kind }: { kind: ImgKind }) {
  return (
    <Image
      src={RESULT_IMG_MAP[kind]}
      alt="결과 이미지"
      width={80}
      height={80}
    />
  );
}

function ResultTitle({ children }: { children: React.ReactNode }) {
  return <h1 className="mt-6 text-2xl font-bold text-gray-900">{children}</h1>;
}

function ResultDescription({ children }: { children: React.ReactNode }) {
  return (
    <p className="mt-2 whitespace-pre font-medium text-gray-400">{children}</p>
  );
}

function ResultMain({ children }: { children: React.ReactNode }) {
  return (
    <div className="flex flex-col items-center justify-center text-center">
      {children}
    </div>
  );
}

export const Result = Object.assign(ResultMain, {
  Image: ResultImage,
  Title: ResultTitle,
  Description: ResultDescription,
});

구현부에서는 각 하위 컴포넌트를 만들어주고, Object.assign()을 이용해 컴포넌트를 조합하는 방식으로 구현된 Result 컴포넌트이다. Object.assign()은 "출처 객체들의 모든 열거 가능한 속성을 복사해 대상 객체에 붙여넣는" 메소드인데, 이 과정이 필요한 이유는 합성 컴포넌트 패턴으로 사용하려면 "하위 컴포넌트들을 상위 컴포넌트에 속성으로 붙여야 하기 때문"이다. ReactMain에 하위 컴포넌트들을 붙여 합성 컴포넌트로 사용하기 위해 동적으로 속성을 부여하는 과정이다.

TypeScript에서는 아래와 같이 명시적으로 지정할 수도 있다.

type ResultComponent = typeof ResultMain & {
  Image: typeof ResultImage;
  Title: typeof ResultTitle;
  Description: typeof ResultDescription;
};

const Result = ResultMain as ResultComponent;
Result.Image = ResultImage;
Result.Title = ResultTitle;
Result.Description = ResultDescription;

Object.assign() 방식이 좀 더 코드가 짧아지고 직관적이라 해당 메소드를 사용하는 걸 권장한닷...!!

+) 아주 중요한 부분은 아니지만 참고로 RESULT_IMG_MAP은 아이콘 종류별로 어떤 이미지를 쓸 건지 지정해놓은 상수이다.

🔸 사용부

import { Result } from "@/ui/Result";

function NotifyResultPage() {
  return (
    <div className="flex h-screen w-full items-center justify-center">
      <Result>
        <Result.Image kind="letter" />
        <Result.Title>매칭 신청이 완료됐어요!</Result.Title>
        <Result.Description>
          {`매칭이 성사되면\n카톡으로 알려드릴게요`}
        </Result.Description>
      </Result>
    </div>
  );
}

export default NotifyResultPage;

사용부에서는 이런 식으로 조합해서 사용해주면 된다! 👍

🔸 Compound Component 패턴으로 구현하지 않았다면?

import Image from "next/image";
import { RESULT_IMG_MAP } from "@/constants/result/resultImg";

export type ImgKind = "letter";

interface ResultProps {
  kind: ImgKind;
  title: React.ReactNode;
  description: React.ReactNode;
}

export function Result({ kind, title, description }: ResultProps) {
  return (
    <div className="flex flex-col items-center justify-center text-center">
      <Image
        src={RESULT_IMG_MAP[kind]}
        alt="완료 이미지"
        width={80}
        height={80}
      />
      <h1 className="mt-6 text-2xl font-bold text-gray-900">{title}</h1>
      <p className="mt-2 whitespace-pre font-medium text-gray-400">{description}</p>
    </div>
  );
}

이러한 방식은 코드가 더 짧아질 순 있겠지만, 보다 비직관적이고 컨텐츠의 위치가 고정적이라서 유연성이 떨어진다는 단점이 있을 것 같다.

🔹 합성 컴포넌트, 항상 좋을까?

당연히 그렇진 않다고 생각한다. 실제로 액션 결과 페이지를 합성 컴포넌트로 구현하겠다는 테크스펙을 작성했을 때, 팀원분께서 지금 시점에서는 오버스펙일 수도 있겠다는 피드백을 주셨고, 나도 이에 어느 정도는 공감하고 있다🙃 최종적으로 합성 컴포넌트로 구현할 수 있었던 이유는, 시간 여유가 조금 있는 상태이기도 했고, 해당 페이지가 앞으로 많은 곳에서 이용될 페이지라고 생각되어서였다.

🔸 단순한 UI에서는 오히려 과설계일 수 있다

예를 들어 단순한 버튼이나 라벨, 레이아웃이 거의 고정된 팝업 등은 children이나 여러 하위 컴포넌트를 통한 합성 구조를 만들기보다는 단순한 prop 기반 컴포넌트로 설계하는 것이 더 나은 선택지가 될 수 있다.

❌ 안 좋은 예시

<Button.Root>
  <Button.Label>확인</Button.Label>
  <Button.Icon src="check.svg" />
</Button.Root>

→ 실제로는 그냥 <Button icon="check.svg">확인</Button>으로도 충분한 경우가 많다.

불필요한 합성 구조는 코드량을 늘리고, 팀원들이 해당 구조를 학습해야 하는 부담도 함께 생긴다 👀

🔸 그럼 어떨 때 사용하는 게 좋을까?

1. 컴포넌트가 다양한 내부 구조를 가질 수 있을 때

ex) Dialog, Form, Card처럼 본문, 제목, 푸터 등을 유동적으로 조합하고 싶은 경우
ex) 컴포넌트 구성 중 일부만 쓰이는 경우도 존재할 때

2. 협업하는 개발자에게 명확한 구조를 제안하고 싶을 때

ex) Tabs.TabList, Tabs.TabPanel처럼 사용자가 직관적으로 어떤 컴포넌트를 써야 하는지 알 수 있음

3. 복잡한 UI 로직을 Context를 통해 공유할 필요가 있을 때

ex) 탭 전환, 선택 상태 등 여러 하위 컴포넌트가 동일한 상태를 공유할 경우

즉, 합성 컴포넌트는 (1) UI 구조의 유연성이 필요하고 (2) 하위 컴포넌트들이 논리적으로 연결되어 있을 때(또는 상태를 공유할 때) 유용한 패턴이라고 생각한다!

🔹 마무리

예전에 인턴할 때에는 합성 컴포넌트로 UI를 구성해 본 적 있느냐는 사수님의 질문에 해 본 적이 없다고 대답했었는데 이제는 있다고 대답할 수 있는 사람이 되었다(ㅎㅎ) 도입 전후로 합성 컴포넌트에 대해 자세히 공부해 보았는데, 단순하면서도 강력한 패턴이라는 생각이 든다. 컴포넌트화를 할 때 앞으로 고려할 옵션이 하나 더 늘어난 것 같다! 재사용성 좋은 컴포넌트에 대해 더 고민하고 발전하는 프론트엔드 개발자가 되어야겠다 🫠 읽어주셔서 감사합니다!

피드백은 언제나 환영합니다 🤗

🔹 참고 문서

• 합성 컴포넌트로 재사용성 극대화하기
• 합성(Composition) vs 상속(Inheritance)