Releases

Releases

Radix Primitives 릴리스와 그 체인지로그예요.

출처: 문서

본문

이 문서는 Radix Primitives의 릴리스별 주요 변경사항(신규 프리미티브, 버그 수정, 성능 개선, breaking change 등)을 정리한 체인지로그예요. 각 항목에는 관련 PR 번호가 함께 표시돼요.

2026년 7월 20일

Dialog

• title 또는 description 요소가 렌더링되지 않는 Dialog에서 깨진 ARIA 참조를 수정했어요. – # 4031

Slider

• 슬라이더 썸이 다른 썸을 가로질러 드래그될 때 onValueCommit이 호출되지 않던 버그를 수정했어요. – # 3832

Toast

• Escape를 눌렀을 때 포커스가 아닌 Toast가 제거되던 문제를 수정했어요. – # 4005

Tooltip

• Tooltip.Content의 children이 DOM에 두 번 마운트되던 버그를 수정했어요. – # 4029

기타 업데이트

• Popper.Content에서 인라인 애니메이션 스타일을 덮어쓰던 문제를 수정했어요. – # 4046
• 번들러가 사용하지 않는 컴포넌트를 제거할 수 있도록 트리 셰이킹을 개선했어요. 컴포넌트 파트는 /* @__PURE__ */로 표시되고, Component.displayName = ... 할당 대신 명명된 render 함수를 사용해 일부 번들러에서 죽은 코드 제거가 안 되던 문제를 해결했어요. – # 4038
• popover 컴포넌트에서 virtualRef prop 타입을 RefObject<Measurable | null>까지 허용하도록 넓혔어요. – # 4034
• conditional exports와 함께 dev 전용 검사를 수정해 프로덕션 빌드에서 dev 경고가 제거되도록 했어요. – # 4039
• 각 primitive의 서브패스 엔트리포인트를 추가해 각 primitive를 직접 임포트할 수 있게 했어요. 예: import { Accordion } from "radix-ui/accordion" 또는 import * as Accordion from "radix-ui/accordion". 루트 radix-ui 엔트리포인트의 네임스페이스 export를 그대로 미러링해요. – # 4020
• <form> 안에서 Checkbox, Switch, RadioGroup의 값을 프로그래밍 방식으로 업데이트할 때(예: "select all" 컨트롤) 숨김 bubble input에서 click 이벤트가 발생해 조상 onClick 핸들러로 전파되던 버그를 수정했어요. – # 4028

2026년 7월 6일

기타 업데이트

• Navigation Menu 아이템 인디케이터의 translate 값을 위한 CSS 커스텀 프로퍼티를 추가했어요.
• Dismissable Layer의 버그를 수정해, 배경 중첩 popover가 바깥 클릭 시 모든 레이어를 닫던 문제를 고쳤어요. – # 3987
• Form.Message, Form.Control, Form.Label, Form.ValidityState가 Form.Field 컴포넌트 밖에서 렌더링될 때 발생하던 런타임 오류를 수정했어요. – # 3992
• 폼 컨트롤 컴포넌트가 연결된 폼이 리셋될 때 값을 업데이트하도록 버그를 수정했어요. RadioGroup, Slider, Select, Switch에 영향을 미쳐요. – # 3958
• 메뉴 아이템, 탭 트리거, 툴바 링크, 셀렉트 아이템이 포커스 가능한 자손에서 유래한 Space/Enter 키를 가로채던 문제를 수정했어요. – # 3999
• 인자 없이 이벤트 핸들러를 호출하면 throw되어 후속 이벤트 핸들러가 호출되지 않던 버그를 수정했어요. 내부 구현이 있는 이벤트 핸들러를 받는 모든 컴포넌트에 영향을 미쳐요. – # 4001
• Context Menu에서 열린 상태로 재트리거될 때 메뉴가 최신 포인터 위치로 올바르게 다시 앵커되도록 버그를 수정했어요. – # 4003
• React 19.2에서 stale onEscapeKeyDown/onDismiss 핸들러를 수정했어요. – # 4015
• Roving Focus Group의 아이템들이 Focus Scope 컴포넌트 안에서 마운트 시 자동 포커스되지 않던 문제를 수정했어요. – # 4002
• React의 useEffectEvent 버그에서 비롯된 Dismissable Layer의 회귀(regression)를 수정했어요. – # 4015
• corner가 제거될 때 --radix-scroll-area-corner-width/--radix-scroll-area-corner-height가 0으로 리셋되지 않던 문제를 수정했어요. 이전에는 값이 남아 남은 스크롤바에 영구적인 간격을 만들었어요. – # 4009
• 현재 값이 step 그리드에서 벗어났을 때 키보드 스테핑이 유효한 값을 건너뛰던 Slider 버그를 수정했어요. 스테핑은 이동 방향의 다음 step 정렬 값으로 스냅하며 네이티브 <input type="range"> 동작과 일치해요. – # 4006

2026년 6월 30일

• 메모리 누수와 테스트 환경 오류를 막기 위해 Toast 컴포넌트를 언마운트할 때 close 타이머를 지웠어요. – # 3794
• 불안정한 구성 ref 콜백 참조 때문에 React 19에서 발생하던 무한 re-render 루프를 수정했어요. – # 3967 – # 3968
• 내보낸 선언 파일에서 전역 React.CSSProperties 증강을 제거했어요. – # 3983

2026년 6월 6일

이 릴리스는 새로운 composition API, 제어 가능한(controlled) Context Menu, 그리고 여러 primitive 전반의 버그 수정과 성능 개선을 도입해요.

Context Menu

ContextMenu.Root에 제어 가능한 open prop 지원을 추가했어요. 열린 상태를 읽고 메뉴를 프로그래밍 방식으로 닫기 위한 용도예요. 메뉴 열기는 위치를 올바르게 잡기 위해 사용자 상호작용에 의존하므로 프로그래밍 방식으로 여는 것은 권장하지 않아요.

function ControlledContextMenu() {
  const [open, setOpen] = React.useState(false);

  return (
    <ContextMenu.Root open={open} onOpenChange={setOpen}>
      <ContextMenu.Trigger>Open</ContextMenu.Trigger>

      <ContextMenu.Content>
        <button type="button" onClick={() => setOpen(false)}>
          Close me
        </button>

        <ContextMenu.Item>Item 1</ContextMenu.Item>

        <ContextMenu.Item>Item 2</ContextMenu.Item>
      </ContextMenu.Content>
    </ContextMenu.Root>
  );
}

또한 길게 누르기 터치 이벤트로 다시 열린 후 서브메뉴가 펼쳐진 채로 남아 있던 버그도 수정했어요.

새로운 불안정(unstable) composition 파트

여러 폼 컨트롤 primitive가 이제 이전에는 내부였던 composition을 노출해, 폼 제출을 위해 렌더링하는 시각적으로 숨겨진 입력에 직접 접근하고 재구성할 수 있게 됐어요. 각 컴포넌트는 계속 기본적으로 이 파트들을 렌더링하며, 새 파트는 unstable_ 접두사로 export돼요.

• Radio Group — unstable_ItemProvider, unstable_ItemTrigger, unstable_ItemBubbleInput
• Select — unstable_Provider, unstable_BubbleInput
• Slider — unstable_ThumbProvider, unstable_ThumbTrigger, unstable_BubbleInput
• Switch — unstable_Provider, unstable_Trigger, unstable_BubbleInput

import { Switch } from "radix-ui";

function ExampleSwitch() {
  return (
    <Switch.unstable_Provider>
      <Switch.unstable_Trigger>
        <Switch.Thumb />
      </Switch.unstable_Trigger>

      {/* the hidden input is now exposed and can be omitted if not needed */}

      <Switch.unstable_BubbleInput />
    </Switch.unstable_Provider>
  );
}

Select

• presence 기반 퇴장(exit) 애니메이션 지원을 추가했어요.
• bubble 숨김 input이 값이 선택되지 않았을 때 빈 문자열을 제출하도록 수정했어요.
• 열린 shadow DOM 안에서 렌더링될 때 콘텐츠를 터치 스크롤한 후 Select가 예기치 않게 닫히던 문제를 수정했어요.
• asChild와 placeholder를 함께 사용할 때 Select.Value가 잘못된 prop 오류를 기록하던 문제를 수정했어요.

Slider

• 프로그래밍 방식 포커스 관리와 함께 :focus-visible로 스타일을 점진적으로 켤 수 있도록 슬라이더 썸의 비키보드 상호작용에 focusVisible 지원을 추가했어요.
• 아주 작은 step 값이 썸을 응답하지 않게 만들던 버그를 수정했어요.
• 스크롤 가능한 컨텍스트에서 슬라이더의 포커스 버그를 수정했어요.

Slot

• render prop을 통한 중첩 Slottable 아이템 지원을 추가했어요. 슬롯된 요소를 감싸면서도 Slot props와 ref를 그 위에 병합할 수 있어요.
• Slot이 매 렌더마다 새 ref 콜백을 만들어 React 19에서 발생하던 무한 re-render 루프를 수정했어요.
• 잘못된 slot children에 대한 오류 메시지를 개선했어요.

Dialog

• 다이얼로그 안의 HTML 입력에서 iOS 텍스트 선택·편집이 깨지던 버그를 수정했어요.
• 닫힌 다이얼로그에서 비활성화된 포인터 이벤트가 발생하던 버그를 수정했어요.

One-Time Password Field

• 레거시 "Text" 클립보드 형식을 지원하지 않는 환경에서 붙여넣기 값이 "text/plain"으로 읽히도록 수정했어요.
• React 19.2+의 포커스 관리 문제를 수정했어요.
• 필드 길이를 초과하는 붙여넣기 값이 잘리도록 했어요.

Tooltip

• 이벤트 대상이 Node가 아닌 엔티티일 때 런타임 오류를 수정했어요.
• skipDelayDuration={0}이 기대대로 동작하도록 버그를 수정했어요. 이전에는 트리거 사이를 이동할 때 열기 지연이 여전히 건너뛰어질 수 있었어요.

기타 업데이트

• Dropdown Menu, Context Menu, Menubar의 SubContent 파트에 앵커 아이템 기준 서브메뉴 방향을 제어하는 align prop을 추가했어요.
• 토스트 공지용 컨테이너를 지정할 수 있도록 Toast.Provider에 announcerContainer prop을 추가했어요.
• Popper 앵커 요소에 data-side와 data-align 속성을 노출했어요.
• Menu.SubContent에 align prop을 추가했어요.
• Scroll Area 스크롤바에 누락된 data-state 속성을 수정했어요.
• popper 인스턴스가 많은 페이지에서 발생하던 "Maximum update depth exceeded" 버그와 React 19의 Presence에서 유사한 버그를 수정했어요.
• 일부 컴포넌트를 임포트할 때 ESM 전용 브라우저 번들이 크래시하던 CJS 전용 shim 대신 React 내장 useSyncExternalStore(React 18+)를 사용해요.
• 콘텐츠가 DOM에서 제거될 때 존재하지 않는 요소를 aria-controls로 참조하던 트리거를 수정했어요 – # 3243.
• 공유 가드 쌍을 캐시하고 가장자리 위치가 바뀔 때만 DOM에 쓰도록 해 오버레이를 열 때 focus-guard 성능을 개선했어요.
• RSC에서 오류를 일으키던 모듈에 누락된 use client 지시문을 추가했어요.

2025년 8월 13일

One-Time Password Field

• Root 컴포넌트가 비활성화되면 모든 입력 요소가 비활성화되도록 버그를 수정했어요.
• iOS Chrome 자동완성 버그를 수정했어요 – # 3641.

기타 업데이트

• 무한 render 루프를 야기하던 Popper 버그를 수정했어요.
• keyframe에 이스케이프 가능한 문자가 있을 때 animationend 이벤트가 올바르게 처리되도록 했어요 – # 2763.
• React 19에서 Slot 컴포넌트가 lazy React 컴포넌트와 상호작용하는 방식을 수정했어요. lazy 컴포넌트 인스턴스의 경우 결과 promise를 소비해 원하는 컴포넌트를 렌더링해요.
• 여러 Toast 접근성 문제를 수정했어요. 포커스 가능한 요소에서 aria-hidden 제거, 리스트 아이템 요소에서 role=status 제거, 중복된 기본 aria-atomic 제거를 포함해요.
• 디버깅 개선을 위해 내부 context 객체에 displayName을 추가했어요.

2025년 5월 20일

• 사용자 대상 API 변경이 없는 의존성 유지보수 릴리스예요.

2025년 5월 6일

• 사용자 대상 API 변경이 없는 의존성 유지보수 릴리스예요.

2025년 5월 5일

이 릴리스는 프리뷰의 완전히 새로운 primitive를 도입해요: PasswordToggleField.

이 새 primitive는 비밀번호 입력 옆에 표시 여부를 토글하는 버튼을 렌더링하는 컴포넌트를 제공해요. 기본 기능 외에도 다음을 포함해요:

• 포인터로 토글 시 입력으로 포커스 반환
• 키보드/가상 내비게이션으로 토글 시 포커스 유지
• 폼 제출 후 우발적 저장을 막기 위해 표시 상태를 숨김으로 리셋
• 아이콘 기반 토글 버튼을 위한 암시적 접근 가능 라벨링

이 API는 현재 불안정하며, 테스트에 도움을 주길 바라요! unstable_ 접두사로 primitive를 임포트하세요.

import { unstable_PasswordToggleField as PasswordToggleField } from "radix-ui";

export function PasswordField() {
  return (
    <PasswordToggleField.Root>
      <PasswordToggleField.Input />

      <PasswordToggleField.Toggle>
        <PasswordToggleField.Icon visible={<EyeOpenIcon />} hidden={<EyeClosedIcon />} />
      </PasswordToggleField.Toggle>
    </PasswordToggleField.Root>
  );
}

기타 업데이트

• Checkbox에 불안정한 Provider, Trigger, BubbleInput 파트를 추가했어요 (#3459)
• 기본 input 타입을 text로 업데이트하고 기본 input 요소에 전달해요 (#3510)

2025년 4월 22일

• 엔트리포인트가 유효하도록 use-sync-external-store 의존성을 업데이트했어요 – # 3491

2025년 4월 17일

이 릴리스는 프리뷰의 완전히 새로운 primitive를 도입해요: OneTimePasswordField.

이 새 컴포넌트 그룹은 문자별 별도 입력 필드로 표시되는 일회용 비밀번호 필드의 일반적인 디자인 패턴을 구현하도록 설계됐어요. 상호작용이 사용자 기대를 따르도록 구현하는 것은 겉보기보다 복잡해요. 이 새 primitive는 다음을 포함한 모든 복잡성을 처리해요:

• 단일 입력 필드처럼 동작하는 키보드 내비게이션
• 붙여넣기 시 값 덮어쓰기
• 비밀번호 관리자 자동완성 지원
• 숫자/영숫자 값 입력 검증
• 완료 시 자동 제출
• 포커스 관리
• 폼 데이터에 단일 값을 제공하는 숨김 입력

프리뷰 릴리스이므로 API는 현재 불안정해요. 테스트에 도움을 주고 결과를 알려주길 바라요.

unstable_ 접두사로 primitive를 임포트하세요.

import { unstable_OneTimePasswordField as OneTimePasswordField } from "radix-ui";

export function Verify() {
  return (
    <OneTimePasswordField.Root>
      <OneTimePasswordField.Input />
      <OneTimePasswordField.Input />
      <OneTimePasswordField.Input />
      <OneTimePasswordField.Input />
      <OneTimePasswordField.Input />
      <OneTimePasswordField.Input />
      <OneTimePasswordField.HiddenInput />
    </OneTimePasswordField.Root>
  );
}

기타 업데이트

• 내부 bubble input이 있는 모든 폼 컨트롤이 기본적으로 Radix Primitive 컴포넌트를 사용해요. 향후 릴리스에서 이 컴포넌트들을 노출해 사용자가 이 동작을 더 잘 제어하도록 할 수 있어요.
• useControllableState에 대한 소폭 개선: 성능 향상, 버그 표면 축소, 오용 시 경고 기록

2025년 4월 8일

• Tooltip provider의 렌더링 성능을 개선했어요 – # 2720
• 트리거에서 pointerdown이 발생하면 Tooltip이 닫히도록 했어요 – # 3380
• Avatar 이미지에 crossOrigin 지원을 추가했어요 – # 3261
• 이미지가 이미 캐시되었을 때 Avatar가 깜빡이던 문제를 수정했어요 – # 3008
• slottable 컴포넌트의 더 나은 디버깅을 위해 displayName을 개선했어요 – # 3441

2025년 2월 5일

• react와 react-dom의 peer dependency 경고를 제거하기 위해 의존성을 업데이트했어요 – # 3350
• 자식이 Fragment일 때 SlotClone에 ref 전달을 건너뛰어요 – # 3229

2025년 1월 22일

• 모든 Radix Primitives의 최신 버전을 한 곳에서 노출하는 radix-ui 패키지를 추가했어요. 이 트리 셰이킹 가능한 엔트리포인트로 필요한 컴포넌트를 쉽게 가져오고, 충돌하거나 중복된 의존성을 걱정하지 않고 최신 상태로 유지할 수 있어요.
• 다음 컴포넌트의 aria-hidden과 react-remove-scroll 의존성을 업데이트했어요:
  • Alert Dialog
  • Context Menu
  • Dialog
  • Dropdown Menu
  • Hover Card
  • Menubar
  • Navigation Menu
  • Popover
  • Select
  • Toast
  • Tooltip

2024년 10월 1일

Alert Dialog

1.1.2

• 트랙패드 사용자를 위한 allowPinchZoom 버그를 수정했어요 – # 3127

Avatar

1.1.1

• 이미지 로딩 상태를 확인할 때 referrerPolicy를 확인하도록 했어요 – # 2772

Checkbox

1.1.2

• 비제어 체크박스에서 defaultChecked가 예기치 않게 바뀌던 버그를 수정했어요 – # 2135
• 부모가 아닌 폼 제출을 고치기 위해 form prop을 bubble input 요소로 전달해요 – # 3161

Dialog

1.1.2

• 트랙패드 사용자를 위한 allowPinchZoom 버그를 수정했어요 – # 3127

Radio Group

1.2.1

• 부모가 아닌 폼 제출을 고치기 위해 form prop을 bubble input 요소로 전달해요 – # 3161

Scroll Area

1.2.0

• Viewport에서 asChild prop이 기대대로 동작하지 않던 문제를 수정했어요 – # 2945
• Viewport의 다른 문제를 고치기 위해 내부 스타일을 업데이트했어요 – # 2945

Select

2.1.2

• 아이템이 처음에 undefined일 때 발생하던 오류를 수정했어요 – # 3168

이후 섹션들은 다운스트림 (2022~2024) 릴리스의 컴포넌트별 버전·변경사항을 정리한 내용이에요. 각 primitive의 주요 변경사항:

2023~2022년 릴리스 (주요)

이 기간에는 Portal 파트 도입, collisionTolerance → collisionPadding 이름 변경, Arrow의 offset 제거, z-index 관리 제거 등 breaking change가 대거 포함됐어요.

• Breaking Content 파트의 collisionTolerance를 collisionPadding으로 이름 변경하고 숫자 또는 padding 객체를 받아요 – # 1531
• Breaking Arrow 파트의 offset 제거 – # 1531
• Breaking 새 Portal 파트 추가. 포털링 동작을 원하면 이 파트를 사용하세요. z-index는 더 이상 관리되지 않아 레이어링을 완전히 제어할 수 있어요. – # 1463
• Content 파트에 collisionBoundary, arrowPadding, sticky, hideWhenDetached props 추가 – # 1531
• Breaking allowPinchZoom prop 제거, 기본 true – # 1514

Dialog 1.0.0: Dialog.Portal의 forceMount로 JS 애니메이션 라이브러리 호환성 개선, 닫는 동안/후 페이지 상호작용 회귀 수정.

Dropdown Menu 1.0.0: 간접 중첩 개선(서브메뉴는 명시적 파트 필요), data-highlighted 속성 추가, Firefox/Safari 전체화면 escape 키 문제 방지.

Navigation Menu 1.0.0: NavigationMenu.Link 클릭 후 메뉴 닫힘 보장, onSelect prop 추가.

Tooltip 1.0.0: 기본적으로 Tooltip.Content가 호버 시 열린 채 유지(WCAG 2.1 Content on Hover 준수). Tooltip.Provider의 disableHoverableContent로 이전 동작 복원 가능. side 기본값 top, Tooltip.Provider 이제 필수.

Select 1.0.0: data-state 값을 active|inactive → checked|unchecked로 이름 변경, Select.Content에 asChild 사용 시 위치 깨짐 수정, placeholder prop 지원.

Scroll Area: ScrollArea.Thumb 이제 애니메이션 가능.

Toast 1.0.0: 기본 토스트 순서 변경(오래된 것→새것 위→아래), React key prop 업데이트 시 토스트 재정렬 문제 수정, 애니메이션 라이브러리 호환성 개선.

RadioGroup 1.0.0: root에 aria-required 추가.

Portal 1.0.0: containerRef(ref) → container(element)로 prop 변경, data-radix-portal 제거(asChild로 요소 제어 가능).

2022년 2월 28일

Select, Toast, NavigationMenu 3개의 새 프리미티브를 프리뷰로 도입하는 동시에 수많은 수정·개선을 포함한 릴리스예요.

• Accordion 0.1.6: Accordion.Trigger를 누를 때 폼 제출 방지, React 18 애니메이션 문제 수정
• Alert Dialog 0.1.7: pointer-events 관리 개선
• Checkbox 0.1.5: enter 키로 활성화 방지
• Collapsible 0.1.6: React 18 애니메이션 문제 수정
• Context Menu 0.1.6: DropdownMenu.TriggerItem 클릭이 두 번 발생하던 문제 방지, 유휴 성능 개선

2021년 릴리스 (알파/베타)

• 2021년 9월 7일: 모든 primitive가 Beta로 이동하고 0.1.0 버전. Breaking 다형성 as prop을 asChild boolean prop으로 교체.
• 2021년 8월 4일: 다형성 타입 성능 개선. AlertDialog.Content의 onPointerDownOutside prop 제거 등 breaking change. modal prop으로 modality 지원 추가.
• 2021년 6월 24일: Context Menu 터치 길게 누르기로 트리거 가능. Dialog에 선택적 Title/Description 파트 추가.
• 2021년 6월 15일: Breaking Accordion.Button → Accordion.Trigger, Accordion.Panel → Accordion.Content 이름 변경. type="single" Accordion에 기본 false인 새 collapsible prop 추가. Checkbox onCheckedChange(event) → onCheckedChange(checked: CheckedState).

이후 릴리스들은 각 primitive 초기 버전의 수정, 성능·타입·접근성 개선, breaking change를 점진적으로 반영했어요.

더 알아보기 (Learn more)

• 최신 primitive·기능 소식은 이 체인지로그와 GitHub PR 링크를 참고하세요.
• 각 컴포넌트의 상세 API는 해당 primitive 문서 페이지를 참고하세요.