Introduction

고품질·접근 가능한 디자인 시스템과 웹 앱을 구축하기 위한 오픈소스 UI 컴포넌트 라이브러리예요.

출처: 문서

본문

Radix Primitives는 접근성·커스터마이즈·개발자 경험에 초점을 맞춘 저수준 UI 컴포넌트 라이브러리예요. 이 컴포넌트들을 디자인 시스템의 기반 계층으로 쓰거나 점진적으로 도입할 수 있어요.

비전

대부분의 우리는 accordion, checkbox, combobox, dialog, dropdown, select, slider, tooltip 같은 공통 UI 패턴에 대해 비슷한 정의를 공유해요. 이 UI 패턴들은 WAI-ARIA가 문서화했고 커뮤니티에서 일반적으로 이해되고 있어요.

하지만 웹 플랫폼이 제공하는 구현은 부족해요. 존재하지 않거나, 기능이 부족하거나, 충분히 커스터마이즈할 수 없어요.

그래서 개발자는 커스텀 컴포넌트를 직접 만들어야 하며, 이는 굉장히 어려운 작업이에요. 그 결과 웹의 대부분 컴포넌트는 접근 불가능하고, 성능이 낮고, 중요한 기능이 부족해요.

우리의 목표는 커뮤니티가 접근 가능한 디자인 시스템을 만드는 데 사용할 수 있는, 충분히 지원받는 오픈소스 컴포넌트 라이브러리를 만드는 것이에요.

주요 기능

접근 가능

컴포넌트는 가능한 한 WAI-ARIA 디자인 패턴을 준수해요. aria와 role 속성, 포커스 관리, 키보드 내비게이션 같은 접근성 관련 까다로운 구현 세부사항을 처리해요. 자세한 내용은 accessibility 개요를 참고하세요.

스타일 없음

컴포넌트는 스타일 없이 배포되어 look & feel을 완전히 제어할 수 있어요. 어떤 스타일링 솔루션으로든 스타일링할 수 있어요. 자세한 내용은 styling 가이드를 참고하세요.

개방됨(Opened)

Radix Primitives는 여러분의 요구에 맞게 커스터마이즈되도록 설계됐어요. 개방적인 컴포넌트 아키텍처는 각 컴포넌트 파트에 세밀하게 접근할 수 있게 해 주며, 이를 감싸 자신만의 이벤트 리스너·props·refs를 추가할 수 있어요.

비제어

해당되는 곳에서 컴포넌트는 기본적으로 비제어이지만, 반대로 제어로도 쓸 수 있어요. 모든 동작 배선은 내부적으로 처리되므로, 로컬 상태를 만들 필요 없이 최대한 매끄럽게 시작할 수 있어요.

개발자 경험

주요 목표 중 하나는 최상의 개발자 경험을 제공하는 것이에요. Radix Primitives는 완전히 타입이 있는 API를 제공해요. 모든 컴포넌트가 유사한 API를 공유해 일관되고 예측 가능한 경험을 만들어요. 또한 asChild prop을 구현해 렌더링되는 요소를 완전히 제어할 수 있게 해 줘요.

점진적 도입

radix-ui 패키지를 설치하고 필요한 primitive만 임포트하는 것을 권장해요. 이것이 시작하기 가장 간단한 방법이며, 버전 충돌이나 중복을 막고 업데이트 관리를 쉽게 해요. 패키지는 트리 셰이킹 가능하므로 사용하는 컴포넌트만 번들에 포함돼요.

npm install radix-ui

import { Dialog, DropdownMenu, Tooltip } from "radix-ui";

대신 각 primitive를 개별적으로 설치할 수도 있어요:

npm install @radix-ui/react-dialog

npm install @radix-ui/react-dropdown-menu

npm install @radix-ui/react-tooltip

import * as Dialog from "@radix-ui/react-dialog";

import * as DropdownMenu from "@radix-ui/react-dropdown-menu";

import * as Tooltip from "@radix-ui/react-tooltip";

개별 설치 시에는 공유 의존성 중복을 막고 번들 크기를 줄이기 위해 모든 Radix 패키지를 함께 업데이트할 것을 권장해요.

커뮤니티

Radix 커뮤니티에 참여하고, 질문하고, 팁을 공유하려면 Discord에 가입하세요.

새 primitive 소식, 공지, 블로그 포스트, 일반적인 Radix 팁을 받으려면 Bluesky나 Twitter를 팔로우하세요.

이슈 제출, 기능 요청, 기여는 GitHub를 확인하세요.

더 알아보기 (Learn more)

Radix Primitives는 저수준·스타일 없는 컴포넌트로, 접근 가능하고 완전히 타입이 지정된 API를 제공하며 asChild prop으로 렌더링 요소를 제어할 수 있어요.
radix-ui 단일 패키지(트리 셰이킹) 또는 개별 @radix-ui/react-* 패키지로 설치할 수 있어요.