모달이 10개가 넘어가면 생기는 일

코인니스 웹에는 모달이 많다. 비밀번호 변경, 프로필 이미지 변경, 신고, 차단, 포인트 내역... 이런 모달들이 페이지마다 흩어져 있었는데, 문제는 모달마다 구현 방식이 다 달랐다는 거다.

어떤 모달은 useState로 open/close를 관리하고, 어떤 모달은 커스텀 훅으로, 어떤 모달은 컴포넌트 내부에 직접 상태를 들고 있었다. 오버레이 클릭 시 닫힘 처리도 제각각이고, body 스크롤 잠금도 되는 곳 있고 안 되는 곳 있고. 새 모달 하나 만들 때마다 기존 모달 코드를 복사해서 약간 고치는 식이었다.

기존에 TabModal이라는 공용 컴포넌트가 있긴 했다. 근데 이게 탭 이름(name)과 탭 컴포넌트(component)만 받을 수 있어서, 모달 하단 버튼을 커스텀하려면 결국 각 모달 내부에서 따로 버튼을 만들어야 했다. 공용이라고 해놓고 확장이 안 되니까 점점 안 쓰게 되는 패턴.

이걸 한번에 정리하고 싶었다.

Radix UI Dialog를 뜯어보다

Compound Component 패턴의 가장 유명한 구현체가 Radix UI다. Radix의 Dialog를 써보면 이런 식이다:

<Dialog.Root>
  <Dialog.Trigger>열기</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay />
    <Dialog.Content>
      <Dialog.Title>제목</Dialog.Title>
      <Dialog.Description>내용</Dialog.Description>
      <Dialog.Close>닫기</Dialog.Close>
    </Dialog.Content>
  </Dialog.Portal>
</Dialog.Root>

각 하위 컴포넌트가 역할이 명확하다. Root는 상태를 들고, Trigger는 열고, Portal은 DOM 트리 밖에 렌더링하고, Overlay는 배경 딤을 깔고, Content는 본문을 담고, Close는 닫는다.

이 구조의 핵심은 Root가 Context Provider 역할을 한다는 점이다. open/close 상태를 Context로 공유하니까, 하위 컴포넌트들이 props 없이도 모달 상태에 접근할 수 있다.

그대로 가져다 쓰지 않은 이유

Radix UI를 그대로 설치해서 쓸 수도 있었다. 근데 몇 가지 맞지 않는 부분이 있었다.

코인니스는 styled-components 기반이라, Radix의 스타일링 방식과 맞춰야 하는 수고가 있었다
우리 디자인 시스템의 모달 스펙(560px 고정 너비, 특정 패딩, 버튼 영역 레이아웃)에 맞추려면 어차피 래핑이 필요했다
43개 모달을 점진적으로 마이그레이션해야 하니까, 기존 인터페이스와 호환되는 중간 레이어가 필요했다

그래서 Radix의 설계를 참고하되 직접 만들기로 했다.

핵심 — ModalRoot와 Context

가장 먼저 만든 건 ModalRoot다. 모든 하위 컴포넌트가 공유할 open/close 상태를 Context로 내려준다.

// ModalRoot.tsx
interface ModalContextState {
  modalOpenState: boolean;
  setModalOpenState: React.Dispatch<React.SetStateAction<boolean>>;
}

export const ModalContext = createContext<ModalContextState | undefined>(undefined);

export default function ModalRoot({
  open: openStateFromExternal,
  onOpenChange: setOpenStateFromExternal,
  children,
  defaultOpen,
}: ModalRootProps) {
  const [open, setOpen] = useState(defaultOpen ? true : false);
  const { lockScroll } = useBodyScrollLock();

  // 외부에서 open/onOpenChange를 넘기면 controlled, 안 넘기면 uncontrolled
  const modalOpenState = openStateFromExternal ?? open;
  const setModalOpenState = setOpenStateFromExternal ?? setOpen;

  useEffect(() => {
    if (modalOpenState) {
      lockScroll();
    }
  }, [lockScroll, modalOpenState]);

  return (
    <ModalContext.Provider value={{ modalOpenState, setModalOpenState }}>
      {children}
    </ModalContext.Provider>
  );
}

export function useModalContxt() {
  const context = useContext(ModalContext);
  if (!context) throw new Error('useModalContxt hook must be used within ModalRoot Component');
  return context;
}

여기서 신경 쓴 부분은 Controlled / Uncontrolled 모두 지원하는 것이다. 부모 컴포넌트에서 open과 onOpenChange를 넘기면 외부 상태를 그대로 쓰고, 안 넘기면 내부 useState를 쓴다. 이렇게 해둬야 기존 코드에서 이미 useModal 훅으로 상태를 관리하고 있는 경우에도 자연스럽게 연결할 수 있다.

asChild 패턴 — 스타일 자유도 확보

Trigger와 Close 컴포넌트에서 asChild 패턴을 구현했다. 이게 뭐냐면, 모달을 여는 버튼이 우리가 미리 정한 <button>이 아니라 외부에서 넘긴 어떤 요소든 될 수 있게 하는 것이다.

// ModalTrigger.tsx
export default function ModalTrigger({ children, asChild, optionClickHandler, ... }) {
  const { setModalOpenState } = useModalContxt();
  const { lockScroll } = useBodyScrollLock();

  const openModal = () => {
    lockScroll();
    setModalOpenState(true);
  };

  // asChild일 때: children의 onClick을 가로채서 모달 열기 로직을 붙인다
  if (asChild) {
    const reactElement = children as React.ReactElement;
    const nativeClickEvent = reactElement.props.onClick;

    const handleClick = (e: any) => {
      e.stopPropagation();
      openModal();
      nativeClickEvent?.();
    };

    return React.cloneElement(reactElement, { onClick: handleClick });
  }

  // asChild가 아닐 때: 기본 button으로 렌더링
  return (
    <button onClick={handleClick}>
      {children ?? 'Button'}
    </button>
  );
}

React.cloneElement로 children에 onClick을 주입하는 방식이다. 이러면 <Modal.Trigger asChild><StyledButton>열기</StyledButton></Modal.Trigger> 처럼, 이미 스타일이 입혀진 커스텀 버튼을 그대로 트리거로 쓸 수 있다.

Portal과 Overlay

ModalPortal은 createPortal로 #modal div에 모달을 렌더링한다. index.html에 <div id="modal"></div>을 #root 위에 하나 추가했다.

// ModalPortal.tsx
const portalElement = document.getElementById('modal') as HTMLElement;

export default function ModalPortal({ children }: { children: ReactNode }) {
  const { modalOpenState } = useModalContxt();
  return modalOpenState ? createPortal(children, portalElement) : null;
}

ModalOverlay는 배경 딤 처리 + 클릭 시 모달 닫기를 담당한다:

// ModalOverlay.tsx
export default function ModalOverlay({ children, className }) {
  const { modalOpenState, setModalOpenState } = useModalContxt();
  const { openScroll } = useBodyScrollLock();

  const closeModal = () => {
    openScroll();
    setModalOpenState(false);
  };

  return modalOpenState ? (
    <OverLay className={className} onClick={closeModal}>
      {children}
    </OverLay>
  ) : null;
}

Object.assign으로 하위 컴포넌트 합성

각 컴포넌트를 따로 만들고, modal-main.ts에서 Object.assign으로 묶었다.

// modal-main.ts
import ModalRoot from 'components/dialog/ModalRoot';
import ModalPortal from 'components/dialog/ModalPortal';
import ModalTrigger from 'components/dialog/ModalTrigger';
import ModalOverlay from 'components/dialog/ModalOverlay';
import ModalClose from 'components/dialog/ModalClose';
import ModalTitle, { ModalContent, ModalDescription } from 'components/dialog/ModalContents';
import ModalButtonGroup, { ModalButton } from 'components/dialog/ModalButtonGroup';

const Modal = Object.assign({}, {
  Root: ModalRoot,
  Trigger: ModalTrigger,
  Portal: ModalPortal,
  Overlay: ModalOverlay,
  Content: ModalContent,
  Title: ModalTitle,
  Description: ModalDescription,
  Close: ModalClose,
  ButtonGroup: ModalButtonGroup,
  Button: ModalButton,
});

export default Modal;

이렇게 하면 사용하는 쪽에서 Modal.Root, Modal.Trigger 형태로 쓸 수 있다. 개별 컴포넌트도 따로 export 해서, styled-components로 스타일을 오버라이드해야 할 때 styled(ModalContent) 같은 식으로 쓸 수 있게 했다.

RootModal — 실사용 래핑 컴포넌트

위의 primitive 컴포넌트들만으로도 모달을 만들 수 있지만, 매번 Portal → Overlay → Content → Title → ButtonGroup을 조립하는 건 번거롭다. 그래서 이걸 한번 감싼 RootModal을 만들었다.

// RootModal.tsx
export default function RootModal({
  modalTrigger,
  modalTitle,
  children,
  onConfirmBtn,
  onCancelBtn,
  open,
  onOpenChange,
  isFlexible,
  ...props
}: BaseModalProps) {
  const isAnyButton = !!(onCancelBtn || onConfirmBtn);

  return (
    <Modal.Root open={open} onOpenChange={onOpenChange}>
      {modalTrigger && (
        <Modal.Trigger asChild>{modalTrigger}</Modal.Trigger>
      )}
      <Modal.Portal>
        <Modal.Overlay />
        <BaseModalContent noButton={!isAnyButton} isFlexible={isFlexible}>
          {modalTitle && <Modal.Title asChild>{modalTitle}</Modal.Title>}
          <ModalDescription>{children}</ModalDescription>
          {isAnyButton && (
            <ModalButtonGroup>
              {onCancelBtn && <Modal.Close asChild>{onCancelBtn}</Modal.Close>}
              {onConfirmBtn && <>{onConfirmBtn}</>}
            </ModalButtonGroup>
          )}
          <Modal.Close asChild>
            <CloseButtonWrapper><CloseIcon /></CloseButtonWrapper>
          </Modal.Close>
        </BaseModalContent>
      </Modal.Portal>
    </Modal.Root>
  );
}

여기서 포인트가 하나 있다. 취소 버튼은 Modal.Close로 감싸서 자동으로 모달을 닫지만, 확인 버튼은 그냥 렌더링만 한다. 확인 버튼은 API 호출이나 폼 제출 같은 비동기 로직이 붙는 경우가 대부분이라, 닫는 타이밍을 외부에서 제어해야 하기 때문이다.

AdvancedTabModal — 탭 전환까지

기존 TabModal의 한계였던 버튼 커스텀을 해결한 AdvancedTabModal을 RootModal 위에 만들었다.

// AdvancedTabModal.tsx
export interface IAdavancedTabInfo {
  [key: string]: {
    name: string;
    component: React.ReactNode;
    confirmButton?: React.ReactNode;  // 기존 TabModal에 없던 것
    cancelButton?: React.ReactNode;   // 기존 TabModal에 없던 것
  };
}

export default function AdvancedTabModal({ tabInfo, defaultTab, ... }: AdvancedTabModalProps) {
  const [tab, setTab] = useState(defaultTab ?? Object.keys(tabInfo)[0]);

  return (
    <RootModal
      onConfirmBtn={tabInfo[tab].confirmButton}
      onCancelBtn={tabInfo[tab].cancelButton}
      modalTitle={
        Object.keys(tabInfo).length < 2
          ? <Title>{tabInfo[tab].name}</Title>
          : <Tab>
              {Object.entries(tabInfo).map(([k, v]) => (
                <TabBtn key={k} onClick={() => setTab(k)} isActive={tab === k}>
                  {v.name}
                </TabBtn>
              ))}
            </Tab>
      }
    >
      <Wrapper>{tabInfo[tab].component}</Wrapper>
    </RootModal>
  );
}

confirmButton과 cancelButton을 탭 정보에 포함시켜서, 탭마다 다른 버튼을 가질 수 있게 했다. 탭이 1개면 제목만, 2개 이상이면 탭 UI를 보여준다.

마이그레이션 — Before / After

43개 파일을 수정했다. 대표적으로 비밀번호 변경 모달의 변화를 보면:

Before:

// 기존 — TabModal 사용
function PasswordChange({ closeModal }) {
  // ... formik 로직 ...
  return (
    <Wrapper>
      {/* input 필드들 */}
      <CancelButton onClick={closeModal}>취소</CancelButton>
      <ConfirmButton onClick={formik.submitForm}>변경하기</ConfirmButton>
    </Wrapper>
  );
}

export default function PasswordChangeModal({ closeModal }) {
  const tabInfo = {
    password: {
      name: '비밀번호 변경',
      component: <PasswordChange closeModal={closeModal} />,
    },
  };
  return <TabModal tabInfo={tabInfo} closeModal={closeModal} />;
}

// 버튼 스타일 직접 정의
const CancelButton = styled(Button)`
  background: var(--field-fld-04);
  color: var(--text-txt-05);
`;
const ConfirmButton = styled(Button)`
  background: var(--keycolor-primary-color);
  color: var(--text-txt-01);
`;

After:

// 새 시스템 — AdvancedTabModal 사용
export default function PasswordChangeModal({ open, setOpen, closeModal }) {
  // ... formik 로직 ...

  const tabInfo: IAdavancedTabInfo = {
    password: {
      name: '비밀번호 변경',
      component: (
        <Wrapper>
          {/* input 필드들 */}
        </Wrapper>
      ),
      confirmButton: <ModalButton onClick={formik.submitForm}>변경하기</ModalButton>,
      cancelButton: <ModalButton type="cancel">취소</ModalButton>,
    },
  };

  return <AdvancedTabModal tabInfo={tabInfo} open={open} onOpenChange={setOpen} isFlexible />;
}

달라진 점:

버튼 스타일 코드 삭제 — ModalButton이 디자인 시스템의 버튼 스펙을 통일해서 관리
컴포넌트를 두 개로 쪼갤 필요 없음 — 기존에는 PasswordChange(내용)와 PasswordChangeModal(래핑)로 나눠야 했는데, 이제 하나로 합쳐짐
open/close 상태가 Controlled — 부모에서 open, setOpen을 넘기니까 상태 흐름이 명확

돌이켜보면

이 작업을 하면서 가장 크게 느낀 건, 라이브러리를 "가져다 쓴다"와 "분석하고 참고한다"는 완전히 다른 경험이라는 것이다. Radix UI를 npm install 했으면 30분이면 끝났을 수도 있다. 하지만 직접 Context로 상태를 공유하는 구조를 짜보고, cloneElement로 asChild 패턴을 구현해보고, Controlled/Uncontrolled을 동시에 지원하는 인터페이스를 설계해보면서, Compound Component 패턴이 왜 이런 모양인지를 이해하게 됐다.

실제로 이 모달 시스템을 만든 경험이 이후에 어드민 리모델링에서 Shadcn UI(Radix 기반)를 도입할 때 많은 도움이 됐다. 이미 같은 패턴을 직접 구현해봤으니까, Shadcn의 컴포넌트 구조가 바로 읽혔고 커스텀도 수월했다.

43개 파일을 고치는 건 솔직히 노동이었다. 근데 그 노동이 끝나고 나니까 새 모달 만들 때 체감이 확실히 달랐다. tabInfo에 이름, 컴포넌트, 버튼만 넣으면 일관된 모달이 나온다. 보일러플레이트가 줄어든 것보다, "모달은 이렇게 만드는 거다"라는 팀 내 기준이 생긴 게 더 값졌다.