Ranui

ranui — web component library

Framework-agnostic Web Components (Custom Elements + Shadow DOM). Works in React, Vue, Svelte, Solid, or plain JS. Each element is <r-*> and is used like native HTML. Styling crosses the shadow boundary via CSS variables, ::part(), or the per-instance sheet attribute (escape hatch).

Authoritative reference (read these for exact APIs — don't guess)

When ranui is installed in a project, its docs ship inside the package:

• node_modules/ranui/docs/COMPONENTS.md — generated per-element API: every element's attributes, typed properties, events (with detail shape), slots, and ::part() names. This is the source of truth for props/events. Regenerated in the source repo via npm run doc:api.
• node_modules/ranui/docs/DESIGN.md — design system rules (color states, spacing, motion, accessibility §7, pre-ship checklist).
• node_modules/ranui/docs/style-tokens-public.md — the CSS variable (theming token) catalog.

In the source repo (packages/ranui) there is also a deep CLAUDE.md (architecture, builder internals, LESS conventions, testing) — not shipped in the npm package.

Import map

Per-component, tree-shakeable side-effect imports register the custom element:

import 'ranui/button';   // then use <r-button>
import 'ranui/modal';
import 'ranui/select';
import 'ranui/input';
import 'ranui/message';  // also exposes an imperative message API
import 'ranui/checkbox';

Available element subpaths: button icon image input message skeleton tab tabpane radar modal select progress player popover dropdown content loading colorpicker math checkbox card router route link.

The fluent DOM builder + reactivity (no custom-element registration):

import { Div, View, Span, Label, ButtonBuilder, signal, createEffect, EventManager, Style } from 'ranui/builder';

SSR helpers: import { defineSSR } from 'ranui/ssr-registry' (source) / ranui/ssr, ranui/ssr-stream. Types: ranui/typings.

Elements at a glance

• Forms: r-input, r-checkbox, r-select (+ r-option, r-dropdown-item), r-colorpicker. These are form-associated custom elements (attachInternals() + ElementInternals.setFormValue()) — their values are collected by new FormData(form) when they're real descendants of a native <form>, same as any native field — no wrapper component required. Use serializeForm(form) (from ranui) to turn a submit into a plain object.
• Feedback/overlay: r-message (toasts), r-modal, r-popover, r-loading, r-skeleton, r-progress.
• Layout/content: r-card, r-section, r-tab/r-tabs, r-icon, r-img, r-link, r-math, r-player, r-radar.
• Routing: r-router, r-route, r-link (history/hash SPA routing).
• Streaming transcript: r-conversation — renders an append-only event log. Register each kind of content as a view (match/start/update fold state, mount/patch render it) before the first push; it throws afterwards. Bottom-follow is on by default and does not fight the reader; pinnedchange drives a "jump to latest" button. Use <r-markdown> as the prose row — its mode="streaming" already closes half-streamed markdown. Projection and cadence: ranuts/conversation.
• Tool calls: r-tool-card — set call / result / status from a declared intent (generic / terminal / diff), never markup. Views must be pure functions of the call's arguments, because they are recomputed on replay; an unrecognised card degrades to generic instead of throwing.
• Chain of thought: r-reasoning — expands while streaming is set, collapses when it clears, and stops following once the reader opens or closes it themselves (setting open from script counts). Feed content from ranuts/stream's reasoning-delta blocks.
• Attachments: r-attachments — holds the files staged with a message, previews them, validates, and owns its object URLs (revoked on detach/clear/disconnect). It does not collect files: call add(files) from paste, drop or a picker. Removal is detach(id), because remove() already means "take yourself out of the document". Rejections are reported, never silent.
• Dictation: r-voice-button — a microphone button over ranuts' createSpeechRecognizer. It reports the whole capture so far on each voiceresult (interim results are revised), so remember the text already in the box at voicestart and concatenate once. It never sends, hides itself where the API is absent, and only denied/failed are worth surfacing — noSpeech/aborted are routine.