を置き、アプリ全体を包む */
.root {
isolation: isolate;
}
/* iOS 26 以降の Safari でダイアログの背景を画面全体に広げる */
.backdrop {
position: absolute;
inset: 0;
}
body {
position: relative;
}
```
### AIエージェントに読ませる同梱ドキュメントとllms.txt
Base UIは、npmパッケージの中にMarkdown形式のドキュメントを入れています。`npm pack` で中身を数えると、1.5.0には `docs/` が無く、1.6.0から入っていました。1.9.0では `node_modules/@base-ui/react/docs/` に80ファイルあり、内訳は37種のコンポーネント・ハンドブック6本・リリースノートなどです。入れた版と同じ版の説明なので、Claude CodeやCursorなどのエージェントに読ませれば、古い版のAPIで書かれる事故を減らせます。
```
ls node_modules/@base-ui/react/docs/react
# components handbook overview utils
# エージェントへの指示例
# 「Base UI の API は node_modules/@base-ui/react/docs を参照して書くこと」
```
同じ内容のWeb版目次が [base-ui.com/llms.txt](https://base-ui.com/llms.txt) にあります。冒頭には `The Tailwind CSS examples are written for Tailwind CSS v4.` とあり、Tailwind CSS v3のプロジェクトではv3で書ける形に直すようエージェントへ指示しています。公式のTailwind例をv3の環境へそのまま貼ると、一部のクラスが効かないことがあります。
## 基本の使い方：Dialog・Popover・Select・Menuのコード例
### Dialogの最小構成
Root・Trigger・Portal・Backdrop・Popupを組み立てます。タイトルと説明は `Dialog.Title` と `Dialog.Description` に書くと、ダイアログのアクセシブルな名前と説明として関連付けられます。
```
import * as React from 'react';
import { Dialog } from '@base-ui/react/dialog';
export function DeleteDialog() {
const [open, setOpen] = React.useState(false);
return (
削除する
ファイルを削除しますか
この操作は取り消せません。
キャンセル
);
}
```
この例と以降のコード例は、@base-ui/react 1.9.0・React 19.3.1・TypeScript 7.0.2の `strict` 設定で、型エラーが出ないことを確認しています。
### 自作ボタンをトリガーにするrender prop
公式の[Compositionガイド](https://base-ui.com/react/handbook/composition)は、`render` に渡すコンポーネントの条件を「refを転送し、受け取ったpropsをすべてDOMノードへ展開すること」としています。propsとrefをDOMへ渡さないと、クリック処理・ARIA属性・フォーカス制御が失われます。次の例は、refを通常のpropとして受け取れるReact 19向けです。React 17・18では `React.forwardRef` でrefを転送してください。
```
import * as React from 'react';
import { Popover } from '@base-ui/react/popover';
type MyButtonProps = React.ComponentPropsWithRef<'button'> & { size?: 'sm' | 'md' };
// 受け取った props（ref を含む）をそのまま DOM に渡すのが条件
function MyButton({ size = 'md', className, ...props }: MyButtonProps) {
return
;
}
export function Info() {
return (
}>詳細
配送について
3営業日以内に発送します。
);
}
```
### スタイルの当て方：className関数・data属性・CSS変数
スタイルの手がかりは4つあります。`className` と `style` は、状態を引数に取る関数も受け付けます。状態は `data-checked` や `data-open` などのdata属性にも出ます。位置やサイズの値は `--available-height` などのCSS変数で受け取れます。開閉アニメーションは、表示開始時の `data-starting-style` と終了時の `data-ending-style` に初期値と終了値を書けば、CSSのtransitionだけで動きます。CSS Modulesでも、同じセレクタをモジュールのファイルに書けば使えます。
```
// className に関数を渡すと、状態に応じてクラスを切り替えられる
(state.checked ? 'thumb on' : 'thumb off')} />
/* data 属性で状態ごとに当てる（開閉アニメーションもこの形） */
.popup {
transition: opacity 150ms, transform 150ms;
}
.popup[data-starting-style],
.popup[data-ending-style] {
opacity: 0;
transform: scale(0.96);
}
/* Popover が出す CSS 変数で高さを画面内に収める */
.popup {
max-height: var(--available-height);
}
```
Tailwind CSSでは `data-starting-style:opacity-0` のようにバリアントとして書けます。Tailwindと組み合わせるヘッドレスUIの選択肢は「[Headless UIとは？React・Vue版の違いとTailwind連携の使い方](/tech/details/9449/)」でも比較しています。
### onOpenChangeのeventDetailsによる外側クリック時のクローズ抑止
2つ目の引数 `eventDetails` には、変化の理由を表す `reason` と、状態の変化を取り消す `cancel()` があります。`reason` は `'outside-press'`・`'escape-key'`・`'close-press'` などの文字列です。編集中のフォームで、外側クリックによる誤操作だけを防ぐなら次のように書きます。
```
import * as React from 'react';
import { Dialog } from '@base-ui/react/dialog';
export function Guarded({ dirty }: { dirty: boolean }) {
return (
{
if (!open && dirty && eventDetails.reason === 'outside-press') {
eventDetails.cancel();
}
}}
>
編集
編集
未保存の変更があるときは、外側クリックでは閉じません。
閉じる
);
}
```
### 複数選択のSelectとフォーム送信
`Select.Root` に `multiple` を付けると複数選択になります。`items` を渡すと、Trigger内の `Select.Value` に値ではなくラベルが表示されます。
```
import * as React from 'react';
import { Select } from '@base-ui/react/select';
const langs = [
{ value: 'ts', label: 'TypeScript' },
{ value: 'go', label: 'Go' },
{ value: 'rust', label: 'Rust' },
];
export function LangSelect() {
return (
{langs.map((lang) => (
✓
{lang.label}
))}
);
}
```
TypeScriptとGoを選んだ状態でサーバー描画すると、選んだ値の数だけ `name="langs"` のhidden inputが出ました。通常の `