ranui/docs/COMPONENTS.md

A framework-agnostic Web Components UI library built on native custom elements, with TypeScript types, light/dark theming, SSR and PWA support.

# ranui Component API (Generated)

Auto-generated by `bin/generate-component-api.ts` (`npm run doc:api`).
Per-element reference of attributes, typed properties, events (with `detail`
shape), slots, and `::part()` names — extracted from source. For CSS variables
(theming tokens) see [style-tokens-public.md](./style-tokens-public.md); for
design rules see [DESIGN.md](./DESIGN.md).

Generated at: 2026-07-19T06:49:49.451Z

32 custom elements.

## `<r-button>`

Source: `components/button/index.ts`

- **Attributes**: `disabled: boolean | string`, `effect: string`, `icon: string`, `iconSize: string`, `sheet: string`, `type: string`
- **Properties**:
  - `disabled: boolean | string`
  - `effect: string`
  - `icon: string`
  - `iconSize: string`
  - `sheet: string`
  - `type: string` — Visual variant: `''` (default) | `'primary'` (monochrome) | `'warning'` | `'text'`. Drives the `:host([type=...])` styles.
- **Events**: —
- **Slots**: `default`
- **Parts**: `button`, `content`

## `<r-card>`

Source: `components/card/index.ts`

- **Attributes**: `description: string`, `hoverable: boolean`, `sheet: string`, `title: string`
- **Properties**:
  - `description: string`
  - `hoverable: boolean` — Interactive card (Geist): hover darkens the border and lifts to the elevated shadow tier. Purely presentational — gate it to cards that are actually clickable.
  - `sheet: string`
  - `title: string`
- **Events**: —
- **Slots**: `default`, `extra (named)`, `footer (named)`
- **Parts**: `body`, `card`, `description`, `extra`, `footer`, `header`, `title`

## `<r-checkbox>`

Source: `components/checkbox/index.ts`

- **Attributes**: `checked: boolean`, `disabled: boolean`, `sheet: string`, `value: string`
- **Properties**: `checked: boolean`, `disabled: boolean`, `sheet: string`, `value: string`
- **Events**: `change` → detail `{ checked }`
- **Slots**: `default`
- **Parts**: `checkbox`, `inner`, `input`, `label`, `wrapper`

## `<r-colorpicker>`

Source: `components/colorpicker/index.ts`

- **Attributes**: `disabled: boolean`, `sheet: string`, `value: string`
- **Properties**: `disabled: boolean`, `sheet: string`, `value: string`
- **Events**: `change`
- **Slots**: —
- **Parts**: `block`, `swatch`

## `<r-content>`

Source: `components/popover/content/index.ts`

- **Attributes**: —
- **Properties**: —
- **Events**: `change`
- **Slots**: `default`
- **Parts**: —

## `<r-dropdown>`

Source: `components/dropdown/index.ts`

- **Attributes**: `arrow: string`, `sheet: string`, `transit: string`
- **Properties**: `arrow: string`, `sheet: string`, `transit: string`
- **Events**: —
- **Slots**: `default`
- **Parts**: `dropdown`

## `<r-dropdown-item>`

Source: `components/select/dropdown-item/index.ts`

- **Attributes**: `active: string`, `sheet: string`, `title: string`, `value: string`
- **Properties**: `active: string`, `sheet: string`, `title: string`, `value: string`
- **Events**: —
- **Slots**: `default`
- **Parts**: `content`, `item`

## `<r-form>`

Source: `components/form/index.ts`

- **Attributes**: `sheet: string`
- **Properties**: `sheet: string`, `value: string | null`
- **Events**: —
- **Slots**: `default`, `r-form_content (named)`
- **Parts**: —

## `<r-glass>`

Source: `components/glass/index.ts`

- **Attributes**: `blur`, `displace: string`, `frequency: string`, `radius: string`, `saturate: string`, `tint: string`
- **Properties**:
  - `displace: string` — Liquid refraction strength — the SVG displacement scale. `0` is a flat pane.
  - `frequency: string` — Turbulence base frequency — smaller = larger, smoother liquid ripples.
  - `interactive: boolean` — Hover lift + press-scale feedback (for clickable glass).
  - `radius: string` — Corner radius, in px.
  - `saturate: string` — `r-glass` — a liquid / frosted glass surface.
  - `sheen: boolean` — Animated specular sweep across the surface.
  - `tint: string` — Glass fill tint (any CSS background value).
- **Events**: —
- **Slots**: `default`
- **Parts**: `glass`, `specular`

## `<r-icon>`

Source: `components/icon/index.ts`

- **Attributes**: `aria-label`, `color: string`, `decorative: boolean`, `name: string`, `sheet: string`, `size: string`, `spin: boolean`
- **Properties**: `ariaLabel: string`, `color: string`, `decorative: boolean`, `name: string`, `sheet: string`, `size: string`, `spin: boolean`
- **Events**: `ranui-icon-registered` → detail `{ name }`
- **Slots**: —
- **Parts**: `ran-icon`

> **Requires registration.** `<r-icon>` has no built-in icon set — it renders only SVGs
> registered into its in-memory registry, so `<r-icon name="lock">` is **blank** until `lock`
> is registered. Register once, in the browser, before the first `<r-icon>` connects:
>
> ```ts
> import { registerBuiltinIcons } from 'ranui'; // or 'ranui/icons'
> registerBuiltinIcons(); // registers every name in RAN_ICON_NAMES
> ```
>
> For a custom set, call `registerIcon(name, svgString)` / `registerIcons({ … })`, or pass raw
> SVG markup straight to `name` (rendered as-is when it starts with `<svg`). Valid bundled
> names are the `RanIconName` union / `RAN_ICON_NAMES` tuple.

## `<r-img>`

Source: `components/image/index.ts`

- **Attributes**: —
- **Properties**:
  - `alt` — Alternative text forwarded to the inner `<img>`. Defaults to `''` (empty),
  - `fallback`
  - `sheet`
- **Events**: —
- **Slots**: —
- **Parts**: —

## `<r-input>`

Source: `components/input/index.ts`

- **Attributes**: `disabled: boolean`, `icon: string`, `label: string`, `max: string`, `message: string`, `min: string`, `name: string`, `placeholder: string`, `required: boolean`, `sheet: string`, `status: string`, `step: string`, `type: string`, `value: string`
- **Properties**:
  - `disabled: boolean` — input 上 disabled 属性
  - `icon: string` — 一个 icon
  - `label: string` — 类似于 Metiral Design 的输入体验。
  - `max: string` — 当 input 类型为 number 类型时，可以获取 max 属性
  - `message: string` — 下方的提示/校验文案
  - `min: string` — 当 input 类型为 number 类型时，可以获取 min 属性
  - `name: string` — 与 form 组件联动时，收集的属性名
  - `placeholder: string` — input 的占位字符
  - `required: boolean` — input 是否为必选
  - `sheet: string`
  - `status: string` — input 框的状态
  - `step: string` — 当 input 类型为 number 类型时，可以获取 step 属性
  - `type: string` — input 的类型
  - `value: string` — 聚焦到内部原生 <input>。宿主自身不在 tab 序、也无内建 focus 行为，
- **Events**: `change` → detail `{ value }` · `input` → detail `{ value }`
- **Slots**: —
- **Parts**: `content`, `input`, `label`, `message`

## `<r-link>`

Source: `components/link/index.ts`

- **Attributes**: `href: string`, `replace: boolean`, `sheet: string`
- **Properties**: `href: string`, `replace: boolean`, `sheet: string`
- **Events**: `ran-navigate` → detail `{ path, replace }`
- **Slots**: —
- **Parts**: —

## `<r-loading>`

Source: `components/loading/index.ts`

- **Attributes**: `name: 'double-bounce' | 'rotate' | 'stretch' | 'cube' | 'dot' | 'triple-bounce' | 'scale-out' | 'circle' | 'circle-line' | 'square' | 'pulse' | 'solar' | 'cube-fold' | 'circle-fold' | 'cube-grid' | 'circle-turn' | 'circle-rotate' | 'circle-spin' | 'dot-bar' | 'dot-circle' | 'line' | 'dot-pulse' | 'line-scale' | 'text' | 'cube-dim' | 'dot-line' | 'arc' | 'drop' | 'pacman'`, `sheet: string`
- **Properties**: `name: 'double-bounce' | 'rotate' | 'stretch' | 'cube' | 'dot' | 'triple-bounce' | 'scale-out' | 'circle' | 'circle-line' | 'square' | 'pulse' | 'solar' | 'cube-fold' | 'circle-fold' | 'cube-grid' | 'circle-turn' | 'circle-rotate' | 'circle-spin' | 'dot-bar' | 'dot-circle' | 'line' | 'dot-pulse' | 'line-scale' | 'text' | 'cube-dim' | 'dot-line' | 'arc' | 'drop' | 'pacman'`, `sheet: string`
- **Events**: —
- **Slots**: —
- **Parts**: `sun`

## `<r-math>`

Source: `components/math/index.ts`

- **Attributes**: `latex: string`, `sheet: string`
- **Properties**: `latex: string`, `sheet: string`
- **Events**: —
- **Slots**: —
- **Parts**: —

## `<r-mermaid>`

Source: `components/mermaid/index.ts`

- **Attributes**: `code: string`, `copy`, `download`, `fullscreen`, `sheet: string`, `theme: string`
- **Properties**: `code: string`, `copyable: boolean`, `downloadable: boolean`, `fullscreenable: boolean`, `sheet: string`, `theme: string`
- **Events**: —
- **Slots**: —
- **Parts**: `button`, `diagram`, `error`, `menu`, `mermaid`, `toolbar`

## `<r-message>`

Source: `components/message/index.ts`

- **Attributes**: —
- **Properties**: `content: string | null`, `sheet: string`, `type: string | null`
- **Events**: —
- **Slots**: —
- **Parts**: —

## `<r-modal>`

Source: `components/modal/index.ts`

- **Attributes**: `autoFocus: boolean`, `closable: boolean`, `closeOnEsc: boolean`, `hide-header`, `lockScroll: boolean`, `maskClosable: boolean`, `open: boolean`, `sheet: string`, `title: string`
- **Properties**:
  - `autoFocus: boolean`
  - `closable: boolean`
  - `closeOnEsc: boolean`
  - `hideHeader: boolean` — Headerless mode: drops the title bar and its border, leaving only a floating
  - `lockScroll: boolean`
  - `maskClosable: boolean`
  - `open: boolean`
  - `sheet: string`
  - `title: string`
- **Events**: `afterclose` → detail `{ trigger }` · `afteropen` · `beforeclose` → detail `{ trigger }` · `beforeopen` · `close` → detail `{ trigger }` · `open`
- **Slots**: `default`, `footer (named)`
- **Parts**: `body`, `close`, `dialog`, `footer`, `header`, `mask`, `root`, `title`

## `<r-option>`

Source: `components/select/option/index.ts`

- **Attributes**: —
- **Properties**: `disabled: boolean | string | undefined | null`, `sheet`, `value`
- **Events**: —
- **Slots**: `default`
- **Parts**: —

## `<r-player>`

Source: `components/player/index.ts`

- **Attributes**: `currenttime`, `currentTime: string`, `debug: string`, `playbackrate`, `playbackRate: string`, `sheet: string`, `src: string`, `volume: string`
- **Properties**: `currentTime: string`, `debug: string`, `playbackRate: string`, `sheet: string`, `src: string`, `volume: string`
- **Events**: `change` → detail `{ currentTime, data, duration, tag, type }`
- **Slots**: —
- **Parts**: —

## `<r-popover>`

Source: `components/popover/index.ts`

- **Attributes**: `placement: string`, `sheet: string`, `trigger: string`
- **Properties**: `getPopupContainerId: string`, `placement: string`, `sheet: string`, `trigger: string`
- **Events**: —
- **Slots**: `default`
- **Parts**: —

## `<r-progress>`

Source: `components/progress/index.ts`

- **Attributes**: `drag`, `primary`
- **Properties**: `dot: string`, `percent: string`, `sheet: string`, `total: string`, `type: string`
- **Events**: `change` → detail `{ percent, total, value }`
- **Slots**: —
- **Parts**: `dot`, `fill`, `track`

## `<r-radar>`

Source: `components/radar/index.ts`

- **Attributes**: —
- **Properties**: `abilitys`, `colorLine`, `colorPolygon`, `fillColor`, `fontColor`, `sheet`, `strokeColor`
- **Events**: —
- **Slots**: —
- **Parts**: —

## `<r-route>`

Source: `components/route/index.ts`

- **Attributes**: `exact: boolean`, `path: string`, `sheet: string`, `src: string`
- **Properties**:
  - `exact: boolean`
  - `params: Record<string, string>`
  - `path: string`
  - `sheet: string`
  - `src: string` — A lazy page module's default export: render into `host`, optionally return a cleanup. */
- **Events**: `routematch` → detail `{ params, path }`
- **Slots**: `default`
- **Parts**: —

## `<r-router>`

Source: `components/router/index.ts`

- **Attributes**: `base: string`, `mode: 'history' | 'hash'`, `sheet: string`
- **Properties**: `base: string`, `mode: 'history' | 'hash'`, `sheet: string`
- **Events**: `routechange` → detail `{ path }`
- **Slots**: `default`
- **Parts**: —

## `<r-scratch>`

Source: `components/scratch/index.ts`

- **Attributes**: `disabled`, `effect`, `icon`, `iconSize`, `sheet`
- **Properties**: —
- **Events**: —
- **Slots**: —
- **Parts**: —

## `<r-section>`

Source: `components/section/index.ts`

- **Attributes**: `heading: string`, `sheet: string`, `subtitle: string`
- **Properties**: `heading: string`, `sheet: string`, `subtitle: string`
- **Events**: —
- **Slots**: `default`
- **Parts**: `body`, `header`, `heading`, `subtitle`

## `<r-select>`

Source: `components/select/index.ts`

- **Attributes**: `defaultvalue`, `disabled: boolean`, `dropdownclass: string`, `getPopupContainerId: string`, `placement: string`, `sheet: string`, `showsearch`, `trigger: string`, `type: string`, `value: string`
- **Properties**: `defaultValue: string`, `disabled: boolean`, `dropdownclass: string`, `getPopupContainerId: string`, `placement: string`, `sheet: string`, `showSearch: string`, `trigger: string`, `type: string`, `value: string`
- **Events**: `change` → detail `{ label, value }` · `search` → detail `{ value }`
- **Slots**: `default`
- **Parts**: `icon`, `search`, `select`, `selection`, `selection-item`

## `<r-skeleton>`

Source: `components/skeleton/index.ts`

- **Attributes**: `sheet: string`
- **Properties**: `sheet: string`
- **Events**: —
- **Slots**: —
- **Parts**: —

## `<r-tab>`

Source: `components/tabpane/index.ts`

- **Attributes**: —
- **Properties**: `disabled`, `effect`, `icon`, `iconSize`, `key`, `label`, `sheet`
- **Events**: —
- **Slots**: `default`
- **Parts**: `content`

## `<r-tabs>`

Source: `components/tab/index.ts`

- **Attributes**: `active: string | null`, `align: string`, `effect: string | null`, `sheet: string`, `type: string`
- **Properties**: `active: string | null`, `align: string`, `effect: string | null`, `sheet: string`, `type: string`
- **Events**: `change` → detail `{ active }`
- **Slots**: `default`
- **Parts**: `content`, `content-wrap`, `header`, `indicator`, `nav`, `tabs`

## `<r-theme-switch>`

Source: `components/theme-switch/index.ts`

- **Attributes**: `label-dark`, `label-light`, `label-system`, `sheet: string`
- **Properties**:
  - `sheet: string`
  - `value: RanThemeName` — `<r-theme-switch>` — a three-state (system / light / dark) segmented control
- **Events**: `change` → detail `{ theme }`
- **Slots**: —
- **Parts**: `button ${choice}`, `switch`