ranui
ネイティブのカスタム要素で作られた UI ライブラリです。どのコンポーネントも <r-*> タグなので、 React でも Vue でも Svelte でも Solid でも Astro でも、素の HTML ファイルでも同じように動きます。 アダプターは要らず、フレームワークのバージョンを合わせる必要もありません。TypeScript の型定義、 デザイントークンによるライト／ダークテーマ、Shadow DOM によるカプセル化、サーバーレンダリングを 最初から備えています。
- npm:
ranui· ソース:packages/ranui - ranui は alpha です。バージョンには破壊的変更が入ります。バージョンを正確に固定し、 アップグレード前に更新履歴を読んでください。
インストール
npm install ranui<!-- CDN からでも。ビルド工程は不要 -->
<script src="https://unpkg.com/ranui/dist/umd/index.umd.cjs"></script>使い方
import すると要素が登録されます。あとはタグを書くだけです。
import 'ranui'; // すべてのコンポーネント
import 'ranui/button'; // 一つだけでも<r-button type="primary">プロジェクトをデプロイ</r-button>タグはどのフレームワークでも同じです。違うのは値の渡し方とイベントの結び付け方だけで、それは コーディング規約で詳しく扱っています。
<script src="https://unpkg.com/ranui/dist/umd/index.umd.cjs"></script>
<body>
<r-button>Button</r-button>
</body>import 'ranui';
export const App = () => <r-button type="primary">Deploy</r-button>;
// 複雑な値とイベントリスナーは ref 経由で渡します — コーディング規約を参照。<template>
<r-button type="primary" @click="deploy">Deploy</r-button>
</template>
<script setup>
import 'ranui';
</script>
<!-- ビルド設定の compilerOptions.isCustomElement に `r-` を追加してください。 -->import 'ranui';
const button = document.createElement('r-button');
button.textContent = 'Deploy';
document.body.appendChild(button);エントリーポイント
各エントリーは名前どおりのものだけを登録します。テーマだけが欲しいページがコンポーネント ライブラリの分を負担することはありません。
| import | 中身 |
|---|---|
ranui | すべてのコンポーネント |
ranui/<component> | コンポーネント一つ：ranui/button、ranui/select、… |
ranui/theme | ライト／ダークテーマとトークンの上書き。要素は含まない |
ranui/i18n | 翻訳エンジン。要素は含まない |
ranui/fonts | セルフホストの Geist Sans + Geist Mono |
ranui/style | スタイルシート。自動で読み込まれない環境向け |
ranui/builder | 細粒度リアクティビティつきの流暢な DOM ビルダー |
ranui/ssr, ranui/ssr-stream | サーバーレンダリング |
ranui/testing | テストから閉じた shadow root に手を入れるためのヘルパー |
ranui/typings | アンビエントな JSX / TS の要素型 |
コンポーネント
40 要素。属性、プロパティ、イベント、スロット、::part() 名まで含めた全体像は 要素 API リファレンスにあります。
データ入力: Input · CheckBox · Select · ColorPicker · Attachments · VoiceButton · Forms
データ表示: Card · Section · Tabs · Image · Progress · Radar · Player · Preview · Glass · Scratch · StateDot · DisclosureRow
コンテンツ描画: Markdown · Math · Mermaid
AI とチャット: Conversation · Reasoning · ToolCard · TokenMeter
オーバーレイとフィードバック: Modal · Popover · Dropdown · Message · Skeleton
ナビゲーション: Router · Route · Link
基盤: テーマ · ThemeSwitch · i18n
5 つの要素には専用ページがありません。ほかの要素の内側でしか存在しないからです：<r-option> （Select）、<r-tabs>（Tabs）、<r-img>（Image）、<r-dropdown-item>（Dropdown）、 <r-content>（Popover）。ほかと同じく API リファレンスには載っています。
ライブ
スタイリング
コンポーネントは閉じた shadow root に描画されます。ページ側の CSS は中へ漏れず、セレクターも 中へ届きません。入口は 4 つあり、以下は推奨順です。
1. デザイントークン（CSS カスタムプロパティ）：境界を越えて継承されるので、:root でも、外側のコンテナでも、要素そのものでも指定できます。
<r-progress
percent="0.7"
type="drag"
style="--ran-progress-track-background: linear-gradient(to right, #f00, #ff0, #0f0, #0ff, #00f)"
></r-progress>2. ::part()：トークンでは届かない構造的な調整に · 3. sheet 属性：shadow root へ CSS を注入する · 4. スロットに渡した内容：あなたのドキュメントに留まり、ページの CSS がそのまま効きます。
トークンの名前はデザインシステムに、どれを選ぶかの基準は デザインガイドラインに、仕組みは コーディング規約にあります。
イベント
コンポーネントは CustomEvent を派発し、中身は detail に入ります。リスナーは要素に結び付けて ください。イベントがバブリングするかはコンポーネントごとの判断で、API リファレンスがすべてについて 明記しています。
<r-select id="env"></r-select>
<script>
document.getElementById('env').addEventListener('change', (event) => {
console.log(event.detail.value);
});
</script>これらは普通の DOM 要素なので onchange="…" 属性形式も el.onchange = … プロパティ形式も動きます。 ただしハンドラーは一つしか持てず、キャプチャフェーズも使えないので、まずは addEventListener を 選んでください。
次に読むもの
| やりたいこと | 読むページ |
|---|---|
| 要素の正確な API を調べる | 要素 API |
| どのトークンを使うべきか、その理由を知る | デザインシステム |
| 一つの体系に見える画面を作る | デザインガイドライン |
| ranui をアプリへ正しく組み込む | コーディング規約 |
| ライト／ダークを足す、全体を作り替える | テーマ |
| インターフェースを翻訳する | i18n |
| サーバー側で描画する | サーバーレンダリング |
| フレームワークなしでリアクティブな画面を作る | ビルダー |
| アップグレード前に変更点を確認する | 更新履歴 |
ブラウザ対応
Custom Elements v1、Shadow DOM v1、CSS カスタムプロパティの上に作られているので、現代のブラウザ すべてで動きます。Internet Explorer は対象外です。
コントリビューター
さらに読む
このライブラリが立脚する標準：W3C · ECMA · RFC · Can I use
開いておく価値のあるデザインの参考資料：Checklist Design · Laws of UX · Geist · Ant Design · Element UI · Animista · WebGradients