Radix UIは、React向けのUIコンポーネント群です。スタイルを持たずアクセシビリティの挙動だけを提供する「Radix Primitives」と、デザイン済みの「Radix Themes」に分かれます。2026年10月時点のnpm最新版は、Primitivesの統合パッケージ radix-ui が1.8.1(2026年10月12日公開)、Themesの @radix-ui/themes が3.3.0(2026年1月31日公開)です。この記事では、2つの違いと選び方、導入手順、1.7〜1.8で増えたAPI、全30コンポーネント、asChild の落とし穴、shadcn/ui・Base UIとの選び方を、公式の一次情報とローカルでの描画・型検査の結果をもとに説明します。
まとめ:Radix UIの要点と選ぶ条件
- Radix UIはPrimitives(無スタイル)とThemes(スタイル付き)の2本立てです。ThemesはPrimitivesの上に作られています。
- Primitivesは
npm install radix-uiの1パッケージで入れるのが公式の推奨です。個別の@radix-ui/react-dialogなども引き続き公開されています。 - 1.7.0でPopoverにTitle・Descriptionが加わり、1.8.0では
exactOptionalPropertyTypesを有効にしたTypeScriptでも型エラーが出なくなりました。どちらも公式サイトのリリースノートには未掲載です。 - Dialogの「Titleが無い」警告は2026年6月に削除されたままです。Titleの付け忘れはテストで検出します。
- shadcn/uiは新規プロジェクトの既定をBase UIへ変えましたが、Radixは非推奨になっていません。Comboboxや複数選択のSelectが要らないなら、Radixを選んで問題ありません。
Radix UIの構成・読み方と開発元
Radixは日本語では「ラディックス」と読まれることが多く、公式サイトに読み方の表記はありません。もともとはModulzが開発しており、WorkOSが2022年6月1日にModulzの買収を発表しました。現在のリポジトリのライセンス表記は「MIT License, Copyright © 2022-present WorkOS」で、商用プロジェクトでも無料で使えます。
「Radix UI」は製品群の総称で、npmでは次のパッケージに分かれます。
| 製品 | npmパッケージ | 最新版 | 公開日 |
|---|---|---|---|
| Primitives(統合) | radix-ui | 1.8.1 | 2026-10-12 |
| Primitives(個別) | @radix-ui/react-dialog ほか | 1.3.1(Dialog) | 2026-10-12 |
| Themes | @radix-ui/themes | 3.3.0 | 2026-01-31 |
| Icons | @radix-ui/react-icons | 1.3.2 | 2024-11-14 |
| Colors | @radix-ui/colors | 3.0.0 | 2023-10-02 |
IconsとColorsはUI部品ではなく、アイコン集とカラーパレットです。Colorsは @radix-ui/themes 3.3.0の依存関係にも入っていて、Themesの色はこのパレットから作られています。PrimitivesとThemesは2026年も更新されていますが、IconsとColorsはここ1年以上新しい版が出ていません。
Radix PrimitivesとRadix Themesの違いと選び方
Primitivesは、キーボード操作・フォーカス管理・ARIA属性だけを受け持ち、見た目はすべて利用者が書きます。Themesは、Primitivesを部品として使い、色・余白・角丸をprops(accentColor、radius など)で切り替える完成品のライブラリです。@radix-ui/themes 3.3.0は依存関係に radix-ui を ^1.1.3 の範囲で含むため、依存範囲が重なるため、npmで両方を入れた検証環境では npm ls radix-ui の結果が1.8.1の1つだけで、Themes側は deduped(重複排除)と表示されました。ロックファイルに古い版が残っていると重複することがあるので、入れた後に同じコマンドで確かめてください。
| 観点 | Primitives | Themes |
|---|---|---|
| 見た目 | なし(CSSを自分で書く) | あり(propsで調整) |
| 同梱CSS | なし | styles.css 約794KiB |
| スタイル手段 | Tailwind・CSS Modules等なんでも | propsとテーマトークンが前提 |
| 向く場面 | 自社デザインシステムの土台 | 管理画面・社内ツール・試作 |
デザイナーが作ったデザインシステムを実装するならPrimitivesです。Themesはトークンとpropsで閉じた設計なので、Figmaのデザインに1pxずつ合わせる用途では上書きが増えます。公式のスタイリングガイドも、Themesの見た目から大きく離れたい場合は「Radix Themesが合っているか考え直す」よう書いています。デザイナーがいない社内ツールなら、Themesで画面を早く揃えられます。画面設計やデザインシステムの整備から外部に頼みたい場合は、一創のUI/UXデザイン支援でも対応しています。
Radix Primitivesの導入手順と基本実装
radix-uiと@radix-ui/react-*の違い
公式のIntroductionは、radix-ui パッケージを入れて必要なプリミティブをimportする方法を推奨しています。バージョンの食い違いや重複を防げるためです。radix-ui 1.8.1は55個の @radix-ui/* パッケージを依存関係として束ねたもので、個別パッケージが廃止されたわけではありません。
npm install radix-ui@latest
この記事のコードと実測は1.8.1で行っています。同じ版で再現したい場合は npm install [email protected] と版を固定してください。
2026年7月20日のリリースからプリミティブごとのサブパスがあり、import * as Popover from "radix-ui/popover"; のように書けます。同じリリースで部品に /* @__PURE__ */ 注釈が付き、使っていない部品をバンドラーが削りやすくなりました。
Dialogの最小構成とdata-stateでのスタイル
各プリミティブは Root・Trigger・Content などの部品に分かれています。この記事のTSXは、TypeScript 5.9.3・React 19.3.1・radix-ui 1.8.1で、strictを有効にした型検査を通過しています。
"use client";
import { Dialog } from "radix-ui";
export function DeleteDialog({ onDelete }: { onDelete: () => void }) {
return (
<Dialog.Root>
<Dialog.Trigger className="btn">削除</Dialog.Trigger>
<Dialog.Portal>
<Dialog.Overlay className="overlay" />
<Dialog.Content className="content">
<Dialog.Title>記事を削除しますか?</Dialog.Title>
<Dialog.Description>この操作は取り消せません。</Dialog.Description>
<Dialog.Close className="btn">キャンセル</Dialog.Close>
<button className="btn danger" onClick={onDelete}>削除する</button>
</Dialog.Content>
</Dialog.Portal>
</Dialog.Root>
);
}
開閉などの状態は data-state="open" / "closed" 属性として出力されるので、CSSは属性セレクタで書きます。Tailwind CSSなら data-[state=open]: バリアントが使えます。
.overlay { position: fixed; inset: 0; background: rgb(0 0 0 / .4); }
.content { position: fixed; top: 50%; left: 50%; transform: translate(-50%, -50%); width: min(90vw, 32rem); max-height: 85vh; overflow: auto; padding: 1.5rem; background: white; color: #111; }
.content[data-state="open"] { animation: fadeIn 150ms ease-out; }
@keyframes fadeIn { from { opacity: 0; } to { opacity: 1; } }
Dialogのopen・onOpenChangeによる開閉制御
上の例は開閉状態をRadixが内部で持つ「非制御」の書き方です。保存が終わってから閉じたい、保存中は閉じさせたくない、といった場合は open と onOpenChange を渡して状態を自分で持ちます。onOpenChange はEscキー・外側クリック・Dialog.Close のどれで閉じようとしても呼ばれるので、条件を1か所に書けます。
"use client";
import { useState } from "react";
import { Dialog } from "radix-ui";
export function RenameDialog({ save }: { save: (name: string) => Promise<void> }) {
const [open, setOpen] = useState(false);
const [pending, setPending] = useState(false);
return (
<Dialog.Root open={open} onOpenChange={(next) => { if (!pending) setOpen(next); }}>
<Dialog.Trigger className="btn">名前を変更</Dialog.Trigger>
<Dialog.Portal>
<Dialog.Overlay className="overlay" />
<Dialog.Content className="content">
<Dialog.Title>名前を変更</Dialog.Title>
<Dialog.Description>新しい名前を入力してください。</Dialog.Description>
<form
onSubmit={async (e) => {
e.preventDefault();
const name = String(new FormData(e.currentTarget).get("name") ?? "");
setPending(true);
try {
await save(name);
setOpen(false);
} catch {
window.alert("保存に失敗しました。入力内容を確認して再試行してください。");
} finally {
setPending(false);
}
}}
>
<label>新しい名前<input name="name" required /></label>
<button type="submit" disabled={pending}>保存</button>
</form>
</Dialog.Content>
</Dialog.Portal>
</Dialog.Root>
);
}
save が失敗して例外になった場合は setOpen(false) に届かず、catch で失敗を知らせたうえでDialogは開いたまま残ります。入力内容も消えないので、そのまま再試行できます。
Next.js App Routerでのuse client指定
DialogやPopoverなど部品パッケージの配布ファイルは、先頭に "use client" を持っています。それでも、onClick や useState を書くファイルは自分でClient Componentにする必要があるため、上の例のように先頭へ "use client" を付けます。radix-ui 1.6.6と1.6.7は「React Server Componentsとの互換性問題を起こした破壊的変更を戻した」リリースで、1.7.0でもRSCとの互換性の修正が入っています。1.6.3〜1.6.5に固定しているプロジェクトは1.8系へ上げてください。
Radix Themesの導入手順と注意点
Themesは、パッケージを入れ、CSSを読み込み、Theme でアプリ全体を包む3手順です。
npm install @radix-ui/themes
import "@radix-ui/themes/styles.css";
import { Theme } from "@radix-ui/themes";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="ja">
<body>
<Theme accentColor="crimson" grayColor="sand" radius="large">
{children}
</Theme>
</body>
</html>
);
}
Theme は class="radix-themes" と data-accent-color・data-radius などの属性を持つdivとして描画され、各部品はこの属性を手がかりに色を決めます。そのため、自作のPortalで Theme の外に描画した要素には色が付きません。公式は、Portalの中身をもう一度 Theme で包む方法を案内しています。
CSSの量にも注意が要ります。styles.css は使う部品の数にかかわらず全部品分を含み、3.3.0の配布ファイルは圧縮前で812,667バイトありました。実際の転送量はビルド時の圧縮やHTTP圧縮によって変わります。自前のCSSとの優先順位を調整したい場合は、tokens.css・components.css・utilities.css に分けて読み込めます。Tailwind CSS v3の @tailwind base はボタンのリセットでThemesのボタン背景を消すことがあるため、公式はCSSレイヤーを分けるなどの回避策を挙げています。
Themesのnpm最新版は2026年1月の3.3.0のままです。GitHubのCHANGELOGには未公開の3.4.0(Buttonの ghost-offset バリアントなど)が載っていますが、npmには出ていないので、使えるのは3.3.0までの機能です。
Radix Primitivesのコンポーネント一覧
公式ドキュメントのComponents欄は30件、Utilities欄は5件です。
| 分類 | コンポーネント |
|---|---|
| オーバーレイ | Dialog・Alert Dialog・Popover・Hover Card・Tooltip・Toast |
| メニュー | Dropdown Menu・Context Menu・Menubar・Navigation Menu |
| フォーム | Checkbox・Radio Group・Switch・Select・Slider・Label・Toggle |
| フォーム(Preview) | Form・One-Time Password Field・Password Toggle Field |
| 構造・表示 | Accordion・Collapsible・Tabs・Toggle Group・Toolbar |
| その他 | Avatar・Aspect Ratio・Progress・Scroll Area・Separator |
| ユーティリティ | Accessible Icon・Direction Provider・Portal・Slot・Visually Hidden |
Preview扱いの3件のうち、One-Time Password FieldとPassword Toggle Fieldは、radix-ui 1.8.1でも unstable_OneTimePasswordField・unstable_PasswordToggleField という名前でexportされます。名前に unstable_ が付いている間はAPIが変わる前提で使ってください。Combobox(入力しながら候補を選ぶ部品)と日付選択は一覧にありません。
radix-ui 1.7〜1.8で増えたAPIと変更点
1.7.0(2026年10月5日)と1.8.0・1.8.1(2026年10月12日)は機能追加を含むリリースですが、公式サイトのReleasesページは2026年7月20日の項目で止まっています。PopoverのドキュメントにもTitleとDescriptionはまだ載っていません。変更点は radix-uiパッケージのCHANGELOG で確認します。
Popover.Title・Descriptionによる名前と説明の設定
1.7.0で、Popoverの中身にアクセシブルネームと説明を付ける Popover.Title・Popover.Description が追加されました。jsdomで開くと、role="dialog" のContentに aria-labelledby が付き、Titleのidを指しました。Titleの既定の要素は h2 なので、ページの見出し構造に混ぜたくなければ asChild で別の要素に替えます。
import { Popover } from "radix-ui";
export function NotifyPopover() {
return (
<Popover.Root>
<Popover.Trigger className="btn">通知設定</Popover.Trigger>
<Popover.Portal>
<Popover.Content className="popover" sideOffset={8}>
<Popover.Title asChild>
<p className="popover-title">通知設定</p>
</Popover.Title>
<Popover.Description>メールを送る頻度を選びます。</Popover.Description>
<Popover.Close aria-label="閉じる">×</Popover.Close>
</Popover.Content>
</Popover.Portal>
</Popover.Root>
);
}
1.8.0では、閉じているPopoverのTriggerに aria-controls が付く不具合も直りました。1.8.1で閉じた状態を描画すると、Triggerの属性は aria-haspopup・aria-expanded="false"・data-state などで、aria-controls はありませんでした。
Navigation Menuは、既定ではTriggerへのホバーで開きます。1.7.0で追加された activationMode="manual" を指定すると、ホバーでは開かず、クリックまたはTrigger上でのEnter・Spaceキー操作で開くようになります。Rootに付ければ NavigationMenu.Sub にも引き継がれます。メガメニューがマウスの通過で開いて邪魔になる、という不満にはこの1行で対応できます。
<NavigationMenu.Root activationMode="manual">
<NavigationMenu.List>
<NavigationMenu.Item value="products">
<NavigationMenu.Trigger>製品</NavigationMenu.Trigger>
<NavigationMenu.Content>
<NavigationMenu.Link href="/products/a">製品A</NavigationMenu.Link>
</NavigationMenu.Content>
</NavigationMenu.Item>
</NavigationMenu.List>
<NavigationMenu.Viewport />
</NavigationMenu.Root>
exactOptionalPropertyTypesへの対応
1.8.0で、省略可能なpropsすべてに undefined を明示的に渡せるようになりました。tsconfigで exactOptionalPropertyTypes を有効にし、open={props.open}(型は boolean | undefined)のように親のpropsをそのまま渡すと、1.6.7では TS2375 の型エラーになり、1.8.1ではエラーなく通りました。このフラグを使っているプロジェクトで、ラッパー部品に条件分岐を書いて回避していたなら、1.8系へ上げると消せます。
radix-ui 1.7〜1.8の移行対象APIと不具合修正
- ScrollArea.Content(1.7.0):Viewportが暗黙に描画していた内側のdivを自分で書けるようになりました。CHANGELOGは、次のメジャー版でViewportがこの要素を描画しなくなるとして、今のうちの移行を勧めています。
- Slider の preserveThumbOrder(1.7.0):範囲指定のつまみが互いを追い越さないようにできます。
- モーダルDialog内の非モーダルPopover(1.7.0):Dialogのフォーカストラップがフォーカスを奪い返し、Popoverの中を操作できなかった不具合が直りました。
- コールバック型の後退(1.8.1):1.8.0で、引数の型が狭いハンドラーを渡すと型エラーになる後退があり、1.8.1で直っています。1.8系に上げるなら1.8.1以降にします。
asChildとSlotの失敗例と描画検証
asChild を付けると、Radixは既定の要素(Dialog.Triggerなら button)を描画せず、直下の子要素にpropsと挙動を渡します。内部で使われているのがSlotで、className は親と子の値が連結されます。radix-ui 1.8.1を react-dom/server で描画すると、次の4つの失敗が確認できました。
- propsを展開しない自作コンポーネント:
({children}) => <button>{children}</button>にasChildで渡すと、出力は<button>開く</button>だけになり、aria-haspopup・aria-expanded・data-stateがすべて消えます。クリックしてもDialogは開かず、エラーも出ません。 - 子が2つ以上、または文字列だけ:
Primitive.button failed to slot onto its childrenというエラーで描画が止まります。 - asChildを付け忘れてbuttonを渡す:
<button>の中に<button>が入る不正なHTMLになります。 - aタグに渡す:
<a href="#x" type="button">のように、リンクにもtype="button"が付きます。ページ遷移させたいならTriggerではなく普通のリンクにします。
自作コンポーネントを渡すときは、受け取ったpropsを要素へ展開します。React 19では ref もpropsとして届くので forwardRef は不要です。
import type { ComponentProps } from "react";
import { Tooltip } from "radix-ui";
function IconButton(props: ComponentProps<"button">) {
const { className, ...rest } = props;
return <button {...rest} className={["icon-btn", className].filter(Boolean).join(" ")} />;
}
export function SaveButton() {
return (
<Tooltip.Provider>
<Tooltip.Root>
<Tooltip.Trigger asChild>
<IconButton aria-label="保存">保存</IconButton>
</Tooltip.Trigger>
<Tooltip.Portal>
<Tooltip.Content sideOffset={4}>変更内容を保存</Tooltip.Content>
</Tooltip.Portal>
</Tooltip.Root>
</Tooltip.Provider>
);
}
Tooltipは Tooltip.Provider の外に置くと `Tooltip` must be used within `TooltipProvider` というエラーになります。アプリのルートに1つ置いておくのが簡単です。
Dialog.Titleの省略とアクセシブルネームの検証
jsdomでDialogを開くと、Radixは最初のフォーカス可能な要素へのフォーカス移動、Dialog以外の要素への aria-hidden="true"、Title・Descriptionと aria-labelledby・aria-describedby の結び付けを自動で行います。
以前のreact-dialogは、Titleが無いと開発中に DialogContent requires a DialogTitle で始まるエラーをコンソールへ出していました。react-dialogのCHANGELOGには、1.1.17(2026年6月15日)で Removed dev-only warnings for dialogs when title and/or description is not rendered. とあります。1.3.1でTitle無しのDialogを開いても、コンソールへの出力は0件で、Contentには aria-labelledby も aria-describedby も付きませんでした。名前の無いダイアログが黙って出来上がります。
見出しを画面に出したくないDialogでもTitleは削除せず、Visually Hiddenで包みます。Descriptionが要らない場合は、公式どおり aria-describedby={undefined} を渡します。
import { Dialog, VisuallyHidden } from "radix-ui";
<Dialog.Content aria-describedby={undefined}>
<VisuallyHidden.Root asChild>
<Dialog.Title>サイト内検索</Dialog.Title>
</VisuallyHidden.Root>
<label>検索語
<input type="search" />
</label>
</Dialog.Content>
テストでは getByRole("dialog", { name: "サイト内検索" }) のようにアクセシブルネームで要素を取得しておくと、Titleの付け忘れがテストの失敗として出ます。また、defaultOpen で最初から開いたDialogでも、Portalの中身はサーバー描画のHTMLに含まれませんでした。検索エンジンに読ませたい本文をDialogの中だけに置かないでください。
SwitchとCheckboxのフォーム送信値
SwitchとCheckboxは、ネイティブの input ではなく button として描画されます。<form> の中に置いたSwitchは次のHTMLになりました。
<button type="button" role="switch" aria-checked="true" data-state="checked" value="on">
<span data-state="checked"></span>
</button>
<input type="checkbox" aria-hidden="true" tabindex="-1" name="n" checked="" value="on"
style="position:absolute;pointer-events:none;opacity:0;margin:0;transform:translateX(-100%)"/>
フォーム送信に使われるのは、視覚的に隠されたcheckboxです。値を指定しなければ送信値は on で、オフのときはネイティブのcheckboxと同じく送信されません。name を付け忘れると値は送られないので、Server Actionsや FormData で受け取る場合は必ず name を渡します。1.8.0では、フォーム内の部品でユーザー操作による変更がプログラムからの変更と誤って扱われ、親要素のイベントハンドラーが呼ばれない不具合も直っています。
shadcn/ui・Base UIとの関係と2026年の選び方
shadcn/uiは2023年1月の公開時からRadixを土台にしてきました。2026年7月の変更履歴で新規プロジェクトの既定をBase UIへ切り替え、shadcn/createで作られるプロジェクトは「Base UIがRadixの2対1」になったと書いています。同じ文書には Radix is not being deprecated. You do not need to migrate. とあり、新しい部品も両方に出す方針です。新規でRadixを使うなら npx shadcn init -b radix を指定します。CIなどで非対話の shadcn init を実行しているなら、このフラグを付けないと次からBase UIで生成されます。2026年7月17日には React Ariaも3つ目の土台として選べるようになりました。
Base UIはRadix・Material UI・Floating UIの開発者が作っている無スタイルのライブラリです。両者の違いは次のとおりです。
| 観点 | Radix Primitives | Base UI |
|---|---|---|
| npm最新版 | radix-ui 1.8.1(2026-10-12) | @base-ui/react 1.9.0(2026-10-09) |
| 部品の差し替え | asChild | render prop |
| Combobox | なし | あり |
| 複数選択のSelect | なし | あり |
| shadcn/uiの既定 | -b radix で選択 | 既定 |
- 既存のRadix製アプリ:機能要件を満たしているなら、既定の変更だけを理由に移行する必要はありません。
asChildとrenderの違いがあるため、置き換えは部品ごとの書き換えになります。 - 新規で、Comboboxや複数選択のSelectが必要:Base UIを選びます。
- 新規で、上の部品が要らない:どちらでも構いません。社内に
asChildの書き方が定着しているならRadixのほうが教育コストが低く済みます。
APIの細かな違いはBase UI(React)とは?Radix UI・MUIとの違いと使い方【v1.9対応】で、shadcn/uiの導入手順はshadcn/uiとは?読み方・導入手順とBase UI既定化の変更点をReact開発者向けに解説で扱っています。
MUI・Chakra UI・Headless UIとの比較
| ライブラリ | 最新版(npm) | 見た目 | 主な用途 |
|---|---|---|---|
| Radix Primitives | radix-ui 1.8.1 | なし | デザインシステムの土台 |
| Radix Themes | 3.3.0 | あり | 素早い画面構築 |
| Headless UI | 2.2.10 | なし | Tailwind CSSと組む無スタイルUI |
| Material UI | 9.5.0 | あり(Material Design) | 業務アプリ全般 |
| Chakra UI | 3.37.0 | あり | propsでのスタイル指定 |
無スタイル同士で比べると、Radixのほうが部品数が多く、Headless UIに無いMenubar・Navigation Menu・Toast・Sliderを持っています。逆にComboboxはHeadless UIにあってRadixにありません。Headless UIの使い方はHeadless UIとは?React・Vue版の違いとTailwind連携の使い方にまとめています。デザイン済みのライブラリと比べるなら、Material Designに沿うかどうかが分かれ目です。沿うならMaterial UI、沿わないならRadix ThemesかChakra UIです。詳しくはMaterial UIとは:v9系の導入からGrid・テーマ設定までコード付きで解説とChakra UIとは?v3の使い方・インストール手順とv2移行の注意点【2026年9月】を参照してください。
よくある質問
Radix UIは無料で商用利用できますか?
できます。PrimitivesもThemesもMITライセンスです。
radix-uiと@radix-ui/react-dialogのどちらを入れればよいですか?
新規なら統合パッケージの radix-ui です。公式がこちらを推奨しており、プリミティブ間のバージョンの食い違いを防げます。既存プロジェクトの個別パッケージは、そのまま使い続けても問題ありません。
Radix UIは開発が終わったのですか?
終わっていません。radix-ui は2026年6月から10月までに1.5.0から1.8.1まで更新され、1.7.0ではPopover.Titleなどの新しいAPIも加わりました。shadcn/uiも2026年7月の変更履歴で、Radixは非推奨にしないと明記しています。
Radix UIはReact 19に対応していますか?
対応しています。radix-ui 1.8.1と @radix-ui/themes 3.3.0のpeerDependenciesは、React 16.8から19までを許容しています。
Radix UIとTailwind CSSは併用できますか?
Primitivesなら問題なく併用できます。className を渡し、data-[state=open]: のような属性バリアントで状態ごとのスタイルを書きます。Themesと併用する場合は、Tailwindのbaseスタイルがボタンの背景を消すことがあるため、CSSレイヤーを分けてください。