ranui

ネイティブのカスタム要素で作られた UI ライブラリです。どのコンポーネントも <r-*> タグなので、 React でも Vue でも Svelte でも Solid でも Astro でも、素の HTML ファイルでも同じように動きます。アダプターは要らず、フレームワークのバージョンを合わせる必要もありません。TypeScript の型定義、デザイントークンによるライト／ダークテーマ、Shadow DOM によるカプセル化、サーバーレンダリングを最初から備えています。

v0.5.0-alpha.7MITesm · cjs · iifepackages/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>

<!-- ビルド設定の 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 リファレンスにあります。

共通: Button · Icon · Loading

データ入力: 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 リファレンスには載っています。

ライブ

Primary

Warning

Text

Default

スタイリング

コンポーネントは閉じた 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
サーバー側で描画する	サーバーレンダリング
フレームワークなしでリアクティブな画面を作る	ビルダー
アップグレード前に変更点を確認する	更新履歴