ranui

Eine UI-Bibliothek auf Basis nativer Custom Elements. Jede Komponente ist ein <r-*>-Tag und funktioniert deshalb in React, Vue, Svelte, Solid, Astro oder einer schlichten HTML-Datei gleich. Es gibt keinen Adapter und keine Framework-Version, die zusammenpassen müsste. TypeScript-Typen, helles und dunkles Theme über Design-Tokens, Kapselung per Shadow DOM und Server-Rendering sind enthalten.

npm: ranui · Quelltext: packages/ranui
ranui ist Alpha: Versionen bringen Breaking Changes mit. Pinne eine exakte Version und lies vor dem Upgrade das Änderungsprotokoll.

Installation

bash

npm install ranui

html

<!-- oder von einem CDN, ohne Build-Schritt -->
<script src="https://unpkg.com/ranui/dist/umd/index.umd.cjs"></script>

Verwendung

Der Import registriert die Elemente; danach schreibst du einfach Tags.

import 'ranui'; // alle Komponenten
import 'ranui/button'; // oder nur eine

html

<r-button type="primary">Projekt ausrollen</r-button>

Es ist in jedem Framework dasselbe Tag: Unterschiedlich ist nur, wie jedes Werte übergibt und Events bindet — das behandeln die Coding-Richtlinien vollständig:

HTMLReactVuePlain JS

html

<script src="https://unpkg.com/ranui/dist/umd/index.umd.cjs"></script>

<body>
  <r-button>Button</r-button>
</body>

jsx

import 'ranui';

export const App = () => <r-button type="primary">Deploy</r-button>;
// Komplexe Werte und Event-Listener laufen über eine ref — siehe die Coding-Richtlinien.

vue

<template>
  <r-button type="primary" @click="deploy">Deploy</r-button>
</template>

<script setup>
import 'ranui';
</script>
<!-- Ergänze `r-` in compilerOptions.isCustomElement deiner Build-Konfiguration. -->

import 'ranui';

const button = document.createElement('r-button');
button.textContent = 'Deploy';
document.body.appendChild(button);

Einstiegspunkte

Jeder Einstiegspunkt registriert genau das, was sein Name sagt — eine Seite, die nur Theming will, zahlt also nie für die Komponentenbibliothek.

Import	Enthält
`ranui`	Alle Komponenten
`ranui/<component>`	Eine Komponente: `ranui/button`, `ranui/select`, …
`ranui/theme`	Helles/dunkles Theme und Token-Überschreibungen; keine Elemente
`ranui/i18n`	Die Übersetzungs-Engine; keine Elemente
`ranui/fonts`	Selbst gehostete Geist Sans + Geist Mono
`ranui/style`	Das Stylesheet, falls dein Setup es nicht selbst einbindet
`ranui/builder`	Der flüssige DOM-Builder mit feingranularer Reaktivität
`ranui/ssr`, `ranui/ssr-stream`	Server-Rendering
`ranui/testing`	Helfer, um aus einem Test in einen geschlossenen Shadow Root zu greifen
`ranui/typings`	Ambiente JSX-/TS-Elementtypen

Komponenten

40 Elemente. Alle, samt Attributen, Eigenschaften, Events, Slots und ::part()-Namen, stehen in der Element-API-Referenz.

Allgemein: Button · Icon · Loading

Dateneingabe: Input · CheckBox · Select · ColorPicker · Attachments · VoiceButton · Forms

Datendarstellung: Card · Section · Tabs · Image · Progress · Radar · Player · Preview · Glass · Scratch · StateDot · DisclosureRow

Inhaltsdarstellung: Markdown · Math · Mermaid

KI & Chat: Conversation · Reasoning · ToolCard · TokenMeter

Overlays & Rückmeldung: Modal · Popover · Dropdown · Message · Skeleton

Navigation: Router · Route · Link

Grundlagen: Theming · ThemeSwitch · i18n

Fünf Elemente haben keine eigene Seite, weil sie nur innerhalb eines anderen existieren: <r-option> (Select), <r-tabs> (Tabs), <r-img> (Image), <r-dropdown-item> (Dropdown) und <r-content> (Popover). In der API-Referenz stehen sie wie alles andere.

Live

Primary

Warning

Text

Default

Styling

Komponenten rendern in einen geschlossenen Shadow Root: Seiten-CSS dringt nicht hinein, und Selektoren greifen nicht hindurch. Es gibt vier Wege, in bevorzugter Reihenfolge.

1. Design-Tokens (CSS-Custom-Properties): Sie werden über die Grenze vererbt — eines auf :root, auf einem Wrapper oder auf dem Element selbst zu setzen funktioniert also gleichermaßen:

html

<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() für strukturelle Feinheiten, die die Tokens nicht abdecken · 3. das Attribut sheet, um CSS in den Shadow Root zu injizieren · 4. Slot-Inhalt, der in deinem Dokument bleibt und dein Seiten-CSS übernimmt.

Die Tokennamen sind das Designsystem; die Regeln zur Auswahl sind die Designrichtlinien; die Mechanik steht in den Coding-Richtlinien.

Events

Komponenten lösen CustomEvents aus, die Nutzlast steckt in detail. Binde am Element: Ob ein Event bubbelt, entscheidet jede Komponente für sich, und die API-Referenz nennt es für jede:

html

<r-select id="env"></r-select>

<script>
  document.getElementById('env').addEventListener('change', (event) => {
    console.log(event.detail.value);
  });
</script>

Die Attributform onchange="…" und die Eigenschaftsform el.onchange = … funktionieren ebenfalls, da dies gewöhnliche DOM-Elemente sind — sie erlauben aber nur einen Handler und keine Capture-Phase, addEventListener ist also die erste Wahl.

Wie es weitergeht

Wenn du … willst	Lies
die genaue API eines Elements nachschlagen	Element-API
wissen, welches Token du nimmst und warum	Designsystem
einen Screen bauen, der wie ein System wirkt	Designrichtlinien
ranui sauber in eine App einbinden	Coding-Richtlinien
Hell/Dunkel ergänzen oder alles umgestalten	Theming
die Oberfläche übersetzen	i18n
auf einem Server rendern	Server-Rendering
reaktive Views ohne Framework bauen	Builder
vor dem Upgrade sehen, was sich geändert hat	Änderungsprotokoll

Browserunterstützung

Die Bibliothek läuft in jedem modernen Browser: Sie setzt auf Custom Elements v1, Shadow DOM v1 und CSS-Custom-Properties. Internet Explorer wird nicht unterstützt.

Mitwirkende

Weiterführendes

Standards, auf denen diese Bibliothek aufbaut: W3C · ECMA · RFCs · Can I use

Design-Referenzen, die man offen lassen sollte: Checklist Design · Laws of UX · Geist · Ant Design · Element UI · Animista · WebGradients

ranui ​

Installation ​

Verwendung ​

Einstiegspunkte ​

Komponenten ​

Live ​

Styling ​

Events ​

Wie es weitergeht ​

Browserunterstützung ​

Mitwirkende ​

Weiterführendes ​

ranui

Installation

Verwendung

Einstiegspunkte

Komponenten

Live

Styling

Events

Wie es weitergeht

Browserunterstützung

Mitwirkende

Weiterführendes