🔀 Radix から Base UI へ移行する — shadcn/ui で実際につまずく5箇所と手順

前回、shadcn/uiのデフォルトがBase UIに変わった話を書いた。あのときは「急いで移行しなくていい」で締めた。今回は逆で、実際に手を動かして移行したときに何が起きるかを書く。

結論から言うと、asChildをrenderに機械置換するだけでは終わらない。ref、型、data-testid、アニメーション、バンドル構成——5箇所で静かに壊れる。しかも壊れ方がどれも「型チェックは通るのに実行時だけ変」というやつで、地味に厄介だった。

Radix と Base UI、移行前後の差分

先に全体像を表にしておく。

項目	Radix	Base UI
パッケージ	コンポーネント単位で分割(@radix-ui/react-dialogなど)	@base-ui/reactに統合(v1.0.0で旧名@base-ui-components/reactから改名)
差し込み方	asChild	render
コンテンツ配置	Contentが配置も内容も持つ	Positioner(配置)とContent(内容)が分離
ラベル	Label単体で置ける	Groupで囲む必要がある
ref	forwardRefがあれば自動で繋がる	渡す要素自体がrefを受け取れる必要がある
data-testid	asChildが子要素にそのまま引き継ぐ	renderに明示しないと消える
アニメーション制御	data-state="open"などの単一属性	data-open/data-closed(アニメーション用)とdata-starting-style/data-ending-style(トランジション用)が分かれる
import	パッケージ単位	サブパス単位(@base-ui/react/popoverなど)

ここから、実際にコンポーネントを1つずつ移行したときに踏んだ落とし穴を順番に書く。

1. パッケージ名がそもそも古い

一番拍子抜けしたのがこれだった。@base-ui-components/reactでインストールしようとして気づいた。

2025年12月11日リリースのv1.0.0で、パッケージが@base-uiorgに移管され、名前が@base-ui-components/reactから@base-ui/reactに変わっている。リリースノートはこれを**破壊的変更(breaking change)**として分類していて、非推奨のまま併存させるという書き方はしていない。

# 旧名(v1.0.0 で置き換えられた)
npm install @base-ui-components/react

# 現在
npm install @base-ui/react

ネット上のチュートリアルやAIの回答は、平気で旧名のまま出てくることがある。移行を始める前に、まずここだけ確認しておくと事故らない。

2. ref: renderに渡した要素は自分でrefを受け取れる必要がある

asChildはRadix側がforwardRefを見つけて自動で繋いでいたが、renderはそうではない。渡す要素自体がrefを受け取れる構造になっている必要がある。

// Radix — MyButtonにforwardRefがあれば自動で繋がる
<Dialog.Trigger asChild>
  <MyButton>開く</MyButton>
</Dialog.Trigger>

// Base UI — MyButton側でrefを受け取れないと、クリックは通るのにフォーカス管理だけ動かない
<Dialog.Trigger render={<MyButton />}>
  開く
</Dialog.Trigger>

フォーカス制御やアニメーション連携でrefを使っているコンポーネントから移行すると、このズレを早めに踏んで学習できる。後回しにすると、直すべき箇所が積み上がってから気づくことになる。

3. 型: render propはコンポーネントのnamespace型と噛み合わせる

Base UIは型に厳しい。各コンポーネントはComponent.Root.Propsのようにnamespaceで型を持っていて、render関数の第2引数には状態(state)が渡ってくる。

import { Popover } from "@base-ui/react/popover";

<Popover.Positioner
  render={(props, state) => (
    <div {...props} data-open={state.open}>
      {/* ... */}
    </div>
  )}
/>

Radixでは素通りしていた微妙な型のズレが、Base UIではコンパイルエラーとして表面化することがある。移行中に型エラーが増えたら、ライブラリのせいではなく元々あったズレが見えるようになったと考えたほうがいい。

4. data-testid: 明示しないと消える

asChildはdata-testidもそのまま子要素に引き継いでいたが、renderは渡した要素自体がpropsを受け取る構造なので、render={<Button />}と書いただけではdata-testidが消える。

// data-testidが消える
<Dialog.Trigger render={<Button />}>開く</Dialog.Trigger>

// 明示的に持たせ直す
<Dialog.Trigger render={<Button data-testid="dialog-trigger" />}>開く</Dialog.Trigger>

getByRoleベースのテストはARIA属性がそのまま保たれるので影響を受けにくいが、getByTestIdに依存したテストスイートはコンポーネント移行のたびに1件ずつ落ちる。移行対象のコンポーネント配下でdata-testidを使っている箇所を先に洗い出しておくと慌てずに済む。

5. アニメーション: data-state依存のCSSはそのまま動かない

これが一番書き直しが多かった箇所だ。RadixはCSSアニメーション向けにdata-state="open"のような単一属性を出す設計だったが、Base UIは用途別に属性が分かれている。

• data-open / data-closed — CSSアニメーション(@keyframes)向け
• data-starting-style / data-ending-style — CSSトランジション向け

/* CSSトランジション: 開閉の途中でキャンセルされても自然に戻る */
.Popup {
  transition: transform 150ms, opacity 150ms;
  &[data-starting-style],
  &[data-ending-style] {
    opacity: 0;
    transform: scale(0.9);
  }
}

Motionのようなライブラリと組み合わせる場合は、アンマウントをAnimatePresenceに任せるか、keepMountedで要素をDOMに残したままopenの状態でスタイルを切り替えるかを選ぶ必要がある。前者はポップオーバーのように閉じたらDOMから消したいケース、後者はDOMに残したままアニメーションだけ切り替えたいケース向けだ。

ちなみに、Popover・Tooltip・Navigation MenuのPositionerでFirefoxだけマウント時のトランジションが崩れる不具合が以前あって、これもv1.0.0で修正されている(Popoverはさらにビューポート追従時のトランジションが飛ぶ不具合も同じバージョンで直っている)。アニメーションが変な動きをする場合、コードよりまずバージョンを疑ったほうが早いこともある。

6. tree-shaking: importの書き方で変わる

前回の記事で、Base UIは1パッケージにまとまっている分、Radixほどツリーシェイキングが削れないという話をした。バンドルサイズの差自体は計測済みなので繰り返さないが、書き方である程度は取り返せる。

// パッケージ直下から呼ぶ(不要なコンポーネントまで巻き込みやすい)
import { Popover } from "@base-ui/react";

// サブパスから呼ぶ(コンポーネント単位でimportできる)
import { Popover } from "@base-ui/react/popover";

移行のついでにimport文をサブパス形式に揃えておくと、ビルド後のサイズで損をしにくい。バンドルアナライザで移行前後を1回ずつ計測しておくと、あとで「なんか重くなった気がする」で悩まなくて済む。

移行の手順

ここまでを、実際に手を動かす順番に並べ直す。

1. パッケージ名を確認する。@base-ui/reactになっているか(なっていなければまずここだけ直す)
2. コンポーネント単位で1つずつ移行する。refを使っている箇所(フォーカス制御・アニメーション連携)から着手すると後半が楽になる
3. 型エラーを潰す。エラーが増えたら元々あったズレが見えるようになったと捉える
4. data-testidを持たせ直す。事前に対象コンポーネント配下の使用箇所を洗い出しておく
5. アニメーションを付け直す。data-open/data-closedとdata-starting-style/data-ending-styleを用途で使い分ける
6. importをサブパス形式に揃え、ビルドサイズを移行前後で計測する

1コンポーネントを移して、テストを通し、コミットする。この小さいサイクルで回すのが結局一番早い。

移行しない判断もありうる

ここまで書いておいてなんだが、今すぐ全部移行する必要があるプロジェクトはそう多くないと思う。

• Combobox・Autocomplete・Number Fieldを使う予定がない(v1.0.0のリリースノートで手が入っている顔ぶれで、Base UI側が力を入れている領域。Radix側の対応状況は各自で確認してほしい)
• バンドルサイズがシビアで、tree-shakingの差を許容できない
• getByTestIdに依存したテストが大量にあり、書き換えコストが移行のメリットを上回る
• 今のRadix構成が安定していて、他に優先すべき作業がある

Radixは廃止されていない。新規プロジェクトはBase UIを素直に選んでいいと思うが、既存プロジェクトは「Combobox系の機能が要るようになったら、そこだけ部分導入する」くらいの温度感でも十分だと思う。全部移行するかしないかの二択で悩む必要はない。