radix-ui/primitives 딥다이브
— "디자인 없는 부품 상자"가 shadcn/ui의 엔진이 된 이유

1한 줄 정체

Radix Primitives는 완성된 디자인 시스템이 아니다. Bootstrap이나 Material UI처럼 열면 예쁜 버튼이 나오는 라이브러리가 아니라, "버튼처럼 보이지 않는 버튼"을 준다. 겉모습은 아무 스타일도 없는 HTML 요소와 똑같지만, 그 속에는 키보드로 Tab·화살표·Esc를 눌렀을 때 어떻게 반응해야 하는지, 스크린리더에게 지금 열려 있는지 닫혀 있는지 어떻게 알려야 하는지가 전부 구현되어 있다.

구성은 Dialog.Root·Dialog.Trigger·Dialog.Content처럼 여러 개의 작은 컴포넌트를 조합(compose)하는 방식이다. 30개가 넘는 컴포넌트 패키지(아코디언·다이얼로그·드롭다운·팝오버·셀렉트·슬라이더·툴팁·툴바 등)와, 그 컴포넌트들이 공통으로 쓰는 유틸리티 패키지(포털·포커스 관리·컨텍스트·충돌 감지 등)로 나뉘어 있다.

2왜 지금 뜨는가

① shadcn/ui가 세계에서 가장 유명한 Radix 소비자가 됐다

2023년 이후 폭발적으로 퍼진 shadcn/ui는 "라이브러리를 설치하지 말고 코드를 네 프로젝트에 복사해라"는 방식을 취했는데, 그 복사되는 컴포넌트 코드 안쪽 엔진이 대부분 Radix Primitives다. v0·Cursor·Claude 같은 AI 코딩 도구가 UI를 생성할 때도 shadcn/ui 패턴을 기본값처럼 쓰면서, 그 밑단의 Radix가 사실상 "AI가 만든 프론트엔드의 표준 접근성 엔진"이 됐다.

② "헤드리스(headless) UI"라는 카테고리 자체의 성장

Tailwind CSS의 대유행으로 "스타일은 유틸리티 클래스로, 동작·접근성은 별도 라이브러리로" 나누는 방식이 표준이 됐다. Radix는 이 헤드리스 UI 카테고리에서 React Aria·Headless UI·Base UI·Ark UI와 함께 초기부터 자리를 지켜온 선두주자다.

③ 접근성이 "선택"에서 "요건"으로

웹 접근성 규제(ADA·유럽 EAA 등)가 강화되면서 기업들이 WAI-ARIA 준수를 사이드 프로젝트가 아니라 필수 요건으로 다루기 시작했다. 처음부터 접근성을 설계에 박아 넣은 Radix는 "나중에 접근성 감사에서 뜯어고칠" 리스크를 줄여준다.

3무엇을 해결하는가

philosophy.md에 저자들이 직접 밝힌 문제의식이 있다. 아코디언·체크박스·다이얼로그·드롭다운·셀렉트·슬라이더·툴팁 같은 UI 패턴은 이미 WAI-ARIA가 "어떻게 동작해야 하는지" 표준으로 문서화해 두었지만, 웹 플랫폼(순수 HTML)이 제공하는 구현은 아예 없거나, 기능이 부족하거나, 충분히 커스터마이징할 수 없다.

그 결과 개발자들은 매번 처음부터 만들어야 했고, 그 어려움 때문에 웹의 수많은 컴포넌트가 실제로는 접근성이 없고, 느리고, 기능이 빠진 채 배포되어 왔다. Radix는 이 문제를 "제대로 만드는 팀이 한 번만 짜고, 모두가 가져다 쓰게" 만들어 해결한다.

4전체 구조 — 모노레포 지도

저장소는 pnpm 워크스페이스 모노레포다(pnpm-workspace.yaml). 실제로 클론해 packages/를 열어 보면 이렇게 나뉜다.

핵심은 packages/react/radix-ui다. 이 패키지의 src/dialog.ts는 코드 전체가 단 한 줄, export * from '@radix-ui/react-dialog'다. 즉 통합 패키지 radix-ui는 새 구현이 아니라, 기존 개별 패키지 30여 개를 한 번에 설치하도록 묶은 "재수출 껍데기"다. 실제 로직·버전·변경 이력은 여전히 각 개별 패키지(@radix-ui/react-dialog 등)에 있다.

5핵심 설계·동작 원리

Radix를 이해한다는 건 결국 이 6가지 재료를 이해하는 것이다. 아래는 전부 실제 소스(packages/react/*/src/*.tsx)에서 직접 확인한 내용이다.

① asChild + Slot — "내 태그로 갈아 끼우기"

모든 Radix 컴포넌트는 packages/react/primitive/src/primitive.tsx의 Primitive를 기반으로 한다. 각 HTML 태그(button·div·a…)마다 createSlot으로 만든 Slot 컴포넌트를 하나씩 갖고 있고, asChild prop이 있으면 실제 태그 대신 이 Slot을 렌더링한다.

const Primitive = NODES.reduce((primitive, node) => {
  const Slot = createSlot(`Primitive.${node}`);
  const Node = React.forwardRef((props, forwardedRef) => {
    const { asChild, ...primitiveProps } = props;
    const Comp = asChild ? Slot : node; // asChild면 진짜 태그 대신 Slot 사용
    return <Comp {...primitiveProps} ref={forwardedRef} />;
  });
  return { ...primitive, [node]: Node };
}, {});

packages/react/slot/src/slot.tsx의 createSlot이 진짜 마법이다. Slot은 자기 자식이 정확히 하나의 유효한 React 엘리먼트인지 확인한 뒤, 그 자식을 React.cloneElement로 복제하면서 자신이 받은 props(slotProps)와 자식의 props(childProps)를 mergeProps로 병합해 자식에게 그대로 떠넘긴다. 이때 병합 규칙이 꽤 섬세하다.

function mergeProps(slotProps, childProps) {
  const overrideProps = { ...childProps }; // 기본은 자식(child)이 이긴다
  for (const propName in childProps) {
    const isHandler = /^on[A-Z]/.test(propName);
    if (isHandler) {
      // onClick 등 이벤트 핸들러는 "둘 다 실행"되도록 합성(compose)
      if (slotProps[propName] && childProps[propName]) {
        overrideProps[propName] = (...args) => {
          childProps[propName](...args);
          slotProps[propName](...args);
        };
      }
    } else if (propName === 'style') {
      overrideProps[propName] = { ...slotProps[propName], ...childProps[propName] }; // style은 병합
    } else if (propName === 'className') {
      overrideProps[propName] = [slotProps[propName], childProps[propName]].filter(Boolean).join(' '); // className은 이어붙임
    }
  }
  return { ...slotProps, ...overrideProps };
}

즉 이벤트 핸들러는 합쳐서 둘 다 실행, style/className은 병합, 나머지 일반 prop은 자식이 우선이라는 규칙이다. 그리고 ref는 useComposedRefs로 합성해, Radix 내부가 관리하는 ref와 사용자가 자식 컴포넌트에 건 ref가 동시에 같은 DOM 노드를 가리키게 만든다. 자식이 없거나(falsy) 여러 개거나 엘리먼트가 아니면 명확한 에러를 던진다(조용히 무시하지 않음).

② 합성 컴포넌트(Root/Trigger/Content) API

모든 컴포넌트는 여러 조각으로 나뉜다. 예컨대 Dialog는 Dialog(=Root, 상태 보관)·Trigger·Portal·Overlay·Content·Title·Description·Close로 구성된다. 이 방식은 "조합이 설정보다 낫다(composition over configuration)"는 philosophy.md의 원칙을 그대로 코드로 옮긴 것이다 — 옵션 하나를 추가하는 대신, 필요한 조각만 가져다 쓰거나 위치를 바꿔 조립한다.

③ createContextScope — 중첩 인스턴스 격리

packages/react/context/src/create-context.tsx에는 일반 createContext 외에 createContextScope가 있다. 문제는 이렇다 — 예를 들어 Tooltip 안에 다른 라이브러리가 Tooltip을 또 렌더링하면(중첩), 평범한 React Context로는 안쪽 인스턴스가 바깥 인스턴스의 상태까지 읽어버릴 위험이 있다. createContextScope는 각 컴포넌트 인스턴스마다 __scopeTooltip 같은 이름의 prop으로 전용 Context 배열을 전달할 수 있게 해, 인스턴스별로 완전히 격리된 상태를 갖게 한다. 또한 다른 컴포넌트의 스코프(createCollectionScope 등)를 의존성으로 합성할 수 있어, RovingFocusGroup처럼 내부적으로 다른 프리미티브를 쓰는 컴포넌트도 스코프 충돌 없이 동작한다.

④ Presence — "사라지는 애니메이션이 끝날 때까지 언마운트를 미룬다"

present=false가 되는 순간 바로 DOM에서 지워버리면 CSS exit 애니메이션이 재생될 시간이 없다. packages/react/presence/src/presence.tsx는 유한 상태 머신(mounted → unmountSuspended → unmounted)으로 이 문제를 푼다. present가 false가 되면 곧바로 언마운트하지 않고, 실제 animationName이 바뀌었는지 계산 스타일을 읽어 "애니메이션이 실행 중"이라고 판단되면 unmountSuspended 상태로 대기하다가, 브라우저의 animationend 이벤트를 받은 뒤에야 실제로 언마운트한다.

⑤ Portal — document.body로 그려서 겹침·잘림을 피한다

packages/react/portal/src/portal.tsx는 매우 짧다. useLayoutEffect에서 mounted를 true로 바꾼 뒤에야 ReactDOM.createPortal로 실제 DOM 트리(기본은 document.body, container prop으로 다른 요소 지정 가능)에 콘텐츠를 그린다. Dialog·Popover·Tooltip처럼 overflow:hidden인 부모 요소 밖으로 튀어나가야 하는 UI가 전부 이 Portal 위에 얹힌다.

⑥ FocusScope · DismissableLayer · RovingFocusGroup — 상호작용 3종 유틸

⑦ WAI-ARIA 준수 방식 — data-state로 상태를 "노출"한다

philosophy.md는 상태를 불리언 대신 열거형 문자열로 표현하고 data-state 속성으로 DOM에 그대로 노출하라고 규정한다. 예컨대 Accordion 아이템은 data-state="open"/"closed"를 갖는데, 이는 ① CSS 선택자로 스타일을 걸 수 있게 하고 ② role·aria-* 속성과 함께 스크린리더가 정확한 상태를 읽게 하는 이중 역할을 한다. 새로운 컴포넌트를 설계할 땐 먼저 WAI-ARIA 문서화 패턴을 찾고, 없으면 잘 검증된 네이티브 구현(운영체제 UI 등)을 참고한다고 명시되어 있다.

6기술 스택 · 의존성

7설치 · 요구사항

필요한 컴포넌트만 개별로 설치하거나(예전 방식·여전히 유효), 전부 한 번에 설치하는(통합 패키지) 두 갈래가 있다.

# 방법 1 — 컴포넌트별 개별 설치(번들 크기를 세밀하게 관리하고 싶을 때)
npm install @radix-ui/react-dialog @radix-ui/react-tooltip

# 방법 2 — 통합 패키지 하나로 전체 설치(현재 공식 문서가 권장하는 방식)
npm install radix-ui

8실제 사용 흐름

가장 흔한 예로 다이얼로그(모달)를 조립하는 전형적인 코드다. 문서가 아니라 소스 코드의 실제 export 이름(Dialog, Trigger, Portal, Overlay, Content, Close)을 그대로 썼다.

import { Dialog } from 'radix-ui'; // 통합 패키지에서 네임스페이스로 가져오기

function EditProfile() {
  return (
    <Dialog.Root>
      {/* asChild: Radix의 기본 button 대신 내가 만든 버튼을 그대로 사용 */}
      <Dialog.Trigger asChild>
        <MyStyledButton>프로필 수정</MyStyledButton>
      </Dialog.Trigger>

      {/* Portal: document.body로 이동해서 그려짐(overflow:hidden 문제 회피) */}
      <Dialog.Portal>
        <Dialog.Overlay className="overlay" />
        <Dialog.Content className="content">
          <Dialog.Title>프로필 수정</Dialog.Title>
          <Dialog.Description>
            변경 사항은 저장 버튼을 눌러야 반영됩니다.
          </Dialog.Description>

          {/* 여기 안에서는 FocusScope가 Tab 포커스를 가둔다 */}
          <input placeholder="이름" />

          <Dialog.Close asChild>
            <MyStyledButton>닫기</MyStyledButton>
          </Dialog.Close>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  );
}

이 20줄 안에서 실제로 일어나는 일을 순서대로 풀면:

1. Dialog.Root가 useControllableState로 open 상태를 만들고 createContextScope로 만든 Context에 담아 자식들에게 내려보낸다.
2. Dialog.Trigger가 asChild를 받아 Slot으로 바뀌고, onClick을 MyStyledButton의 기존 onClick과 합성해 클릭 시 open을 토글한다.
3. open이 true가 되면 Dialog.Content를 감싼 Presence가 mounted 상태로 전이하고, Dialog.Portal이 이를 document.body에 그린다.
4. Content 내부의 FocusScope가 포커스를 안에 가두고, DismissableLayer가 바깥 클릭·Esc를 감지해 onOpenChange(false)를 부른다.
5. open이 false가 되면 Presence가 CSS exit 애니메이션이 끝날 때까지 기다렸다가 실제로 언마운트한다.

9함정 · 오해 방지

10대안 비교

11정리 · 누가 쓰면 좋은가

Radix Primitives는 완제품 UI 킷이 아니라 접근성 엔진이다. 30여 개 컴포넌트 패키지가 공통으로 asChild+Slot(태그 갈아 끼우기), createContextScope(중첩 인스턴스 격리), Presence(퇴장 애니메이션 대기), Portal·FocusScope·DismissableLayer·RovingFocusGroup(레이어·포커스·키보드 탐색)이라는 소수의 정밀한 유틸리티 위에 조립되어 있다. 통합 패키지 radix-ui는 그 개별 패키지들을 한 번에 설치하는 재수출 껍데기일 뿐, 실제 버전과 변경 이력의 진실원은 여전히 각 개별 패키지다.

12직접 해볼 수 있는 실습 과제

아래 경로와 명령은 모두 Radix 저장소 루트 기준이다. 의존성이 설치된 별도의 학습용 사본에서 진행하고, 브라우저 테스트에는 Playwright용 Chromium도 준비한다. 실행 명령의 정의는 루트 package.json, 예제 탐색 범위는 apps/storybook/.storybook/main.ts에서 확인할 수 있다.

pnpm storybook

pnpm test --run packages/react/slot/src/slot.test.tsx

pnpm storybook
# 다른 터미널에서 실행
pnpm test --run packages/react/tabs/src/tabs.test.tsx

pnpm e2e e2e/dialog.spec.ts

13관련 기술 심화 학습 로드맵

매주 예제를 먼저 조작하고, 해당 동작을 만드는 소스를 읽은 뒤 결과물을 남긴다. 버전 번호를 외우기보다 상태·DOM·이벤트가 연결되는 경로를 설명하는 데 집중한다.

14핵심 키워드 사전