Von pnpm -F ranui doc:api aus dem Komponenten-Quelltext generiert und daher nie im
Widerspruch zum ausgelieferten Code. Referenz je Element: Attribute, typisierte
Eigenschaften, Events (samt detail-Form und Dispatch-Optionen), Slots und
::part()-Namen. Die Beschreibungen stammen unverändert aus dem JSDoc im Quelltext und
bleiben deshalb englisch.
Die CSS-Variablen der einzelnen Elemente stehen in
style-tokens-public.md; zur Auswahl zwischen ihnen
das Designsystem und die
Designrichtlinien. Wie ein Element zu verwenden ist, steht auf
seiner eigenen Seite in der Seitenleiste; hier ist die vollständige Oberfläche an einem Ort.
Zu jedem Event stehen die Optionen, mit denen es ausgelöst wird: bubbles, composed
(überschreitet die Shadow-Grenze) und cancelable (preventDefault() legt sein Veto ein).
element-only heißt: keine der drei — ein delegierter Listener an einem Vorfahren sieht
dieses Event nie, binde ihn also an das Element selbst.
disabled: boolean | string — Blocks clicks and keyboard activation and removes the button from the tab order. Off by default; disabled="false" counts as enabled.
effect: boolean — Whether the click ripple is drawn. On by default; opt out with effect="false".
icon: string — Name of an <r-icon> drawn before the label, for example 'search'. No icon when empty.
iconSize: string — Icon size passed to the inner <r-icon>. Defaults to about 1.15× the button's font size; set it only when the icon needs a fixed size.
description: string — Secondary text shown under the heading. Empty by default; the header is hidden when the heading, description and extra slot are all empty.
heading: string — Heading text.
hoverable: boolean — Interactive card (Geist): hover darkens the border one step. Purely presentational — gate it to cards that are actually clickable.
sheet: string
Events: —
Slots: Standard, extra (benannt), footer (benannt)
Parts: body, card, description, extra, footer, header, title
alphaLabel: string — Accessible name of the opacity slider.
disabled: boolean — Blocks opening the picker and emitting change, and removes the swatch from the tab order. Off by default; disabled="false" counts as enabled.
hueLabel: string — Accessible name of the hue slider.
label: string — Accessible name of the swatch that opens the picker. Defaults to 'Choose color'.
sheet: string
value: string — Selected colour as #rrggbb (or #rgb), rgb(...) or rgba(...); picking a colour writes a hex value, or rgba(...) when opacity is below 1. Unparseable values are ignored. Empty until set; the swatch starts white.
active: string — The transient cursor that pointer hover and arrow keys move; r-select sets it. It shares the hover fill and carries no selection meaning.
selected: boolean — Marks the committed choice with a check mark. Unlike active (the transient cursor), it stays put while the cursor moves.
ranui-icon-registered · element-only · detail { name }
Slots: —
Parts: ran-icon
Bundled icons are loaded on demand.<r-icon name="lock"> works without registration:
its SVG is fetched on first use and cached. To register the entire bundled set eagerly,
optionally call the following in the browser before the first <r-icon> connects:
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.
disabled: boolean — Blocks typing and focus, greys the field out and leaves it out of form validation. Off by default; disabled="false" counts as enabled.
icon: string — Name of an r-icon shown before the text, for example search. No icon when unset.
label: string — Caption rendered above the field and linked to the inner input, so it is the field's accessible name and clicking it focuses the input. No caption when unset.
max: string — Highest accepted number. Applies only when type is 'number'; larger values fail form validation.
message: string — Helper or validation text shown below the field and linked to it with aria-describedby. Nothing is rendered when empty.
min: string — Lowest accepted number. Applies only when type is 'number'; smaller values fail form validation.
name: string — Key under which the value is submitted with the owning form.
placeholder: string — Hint text shown inside the field while it is empty.
required: boolean — Makes an empty value fail native form validation (checkValidity(), :invalid) and sets aria-required. Off by default; setting the property to false or 'false' removes it.
sheet: string
status: string — Validation state: 'error' | 'warning'. Colours the border and label and adds a status icon; pair it with message so the state is not shown by colour alone. Empty (neutral) by default.
step: string — Granularity of accepted numbers, forwarded to the native input. Applies only when type is 'number'; off-step values fail form validation.
type: string — Native input type forwarded to the inner <input>, such as text, password or number; number enables min, max and step. Behaves as text when unset.
validationMessage: string — The browser's message for the current constraint error; empty while the field is valid.
validity: ValidityState | undefined — Native ValidityState of the field, for reading constraint errors from script. undefined where ElementInternals is unavailable.
value: string — Current text of the field. Updates on every keystroke and is submitted with the owning form under name. Empty by default.
caret: string — Shows a blinking caret after the last block while text streams in; remove it when the answer is complete. Any value draws a block caret; 'circle' draws a dot.
content: string — Markdown source. Resolution order: the content property (set via JS, not reflected), the content attribute, then the element's text content.
copyable: boolean — Adds a copy button to each code block header. Reflects the copy attribute; off by default.
downloadable: boolean — Adds a download button to each code block header that saves the code as a file. Reflects the download attribute; off by default.
highlight: string | null — Shiki syntax highlighting for code blocks; off when the attribute is absent. "" → github-light/github-dark; "a" → both; "a b" → light / dark theme.
inlineMath: boolean — Treats $…$ as inline math. Off by default because $ often means currency; \(…\) always works. Reflects the inline-math attribute.
lineNumbers: boolean — Shows line numbers in code blocks. Reflects the line-numbers attribute; off by default.
linkTarget: string — target for rendered links, set with rel="noopener noreferrer". Defaults to '_blank'; use '_self' to open links in place. In-page # links are left alone.
mode: string — Parsing mode: 'streaming' | 'static'. Default 'streaming' repairs half-written syntax and re-renders only changed blocks; use 'static' for finished text.
sheet: string
theme: string — Colour scheme: 'auto' | 'light' | 'dark'. Default 'auto' follows the document theme; embedded Mermaid diagrams use the same value.
autoFocus: boolean — Moves focus to the first focusable element in the dialog (or the dialog itself) when it opens. On by default; turn off with autoFocus="false".
closable: boolean — Shows the close button in the corner. On by default; turn off with closable="false" when the dialog must be closed by its own actions.
closeOnEsc: boolean — Closes the topmost dialog when Escape is pressed. On by default; turn off with closeOnEsc="false".
heading: string — Heading text shown in the title bar; falls back to Modal when empty.
hideHeader: boolean — Headerless mode for content-only dialogs such as image lightboxes: drops the title bar and keeps only a floating close button when closable. Off by default.
lockScroll: boolean — Stops the page behind from scrolling while the dialog is open. On by default; turn off with lockScroll="false".
maskClosable: boolean — Closes the dialog when the backdrop outside it is clicked. On by default; turn off with maskClosable="false" for forms that must not be dismissed by a stray click.
open: boolean — Shows the dialog when set and closes it when removed. Off by default; open="false" counts as closed.
sheet: string
Events:
afterclose · element-only · detail { trigger }
afteropen · element-only
beforeclose · cancelable · detail { trigger }
beforeopen · cancelable
close · element-only · detail { trigger }
open · element-only
Slots: Standard, footer (benannt)
Parts: body, close, dialog, footer, header, mask, root, title
autoplay: boolean — Start playback as soon as the video can play, via the native autoplay flag. Browsers usually block unmuted autoplay, so pair it with muted. Off by default.
controllerBarTimeId: ReturnType<typeof setTimeout> | undefined — Internal timer id for auto-hiding the control bar. Not meant to be set by consumers.
currentTime: string — Playback position in seconds, also accepted as currenttime. In the markup it is the start position; a later change seeks. The getter returns the attribute, not the live position.
debug: string — Any non-empty value logs every internal change event and source-load errors to the console. An empty value (<r-player debug>) leaves logging off.
disableErrorModal: boolean — Suppress the built-in playback-error panel with its Retry button, for apps that show their own error UI. Off by default, so the panel shows.
format: string — Playback engine: 'hls' | 'dash' | 'flv' | 'webrtc' | 'native'. Empty by default, which detects it from the src extension; set it for signed or extensionless URLs, and always for webrtc (a WHEP endpoint).
labelError: string — Heading of the built-in playback-error panel. Defaults to 'Playback failed'.
labelRetry: string — Label of the panel's retry button. Defaults to 'Retry'.
loop: boolean — Restart from the beginning when playback ends, via the native loop flag. Off by default.
moveProgress — Internal seek-bar drag state (percentage, mouseDown), read by the player's own modules. Not meant to be set by consumers.
muted: boolean — Start silent: sets volume to 0 and the native muted flag. Removing the attribute restores the previous volume, or 50 if none was recorded. Off by default.
playbackRate: string — Speed multiplier such as 1, 1.5 or 2, also accepted as playbackrate. Applied from the markup and on every change.
poster: string — Image URL shown on the video before playback starts, passed to the native <video poster>.
rememberPosition: boolean — Save the position to localStorage, keyed by src, on pause and when the page is hidden, and resume there on the next load of the same src. The entry is cleared when playback ends. Off by default.
sheet: string
src: string — Media URL to play. The engine is picked from its extension unless format is set; changing it on a connected player reloads the source.
thumbnails: string — URL of a WebVTT sprite-sheet manifest that shows a preview thumbnail above the seek-bar hover tip.
tracks: PlayerTrackConfig[] — Subtitle and caption tracks as { src, srclang, label, kind?, default? } objects; property only, no attribute. Defaults to [].
volume: string — Volume on a 0-100 scale, clamped; muted wins. Applied from the markup and on every change; the getter returns the attribute, not the live volume.
getPopupContainerId: string — Id of the element the panel is mounted into, looked up in the popover's own root first and then the document. Defaults to document.body.
open: boolean — Whether the panel is showing.
placement: Placement — Which side of the trigger the panel sits on, with an optional alignment. Defaults to 'top'.
sheet: string
trigger: string — How the panel opens: 'hover' | 'click'. Default 'hover'. Click toggles the panel in either mode; hover is ignored on mobile devices.
exact: boolean — Match only the full path, so /users no longer shows for /users/42. Off by default; set it on a / home route.
params: Record<string, string> — Read-only. Values captured by the :name segments of path on the last match, URL-decoded. Empty when the route does not match.
path: string — Path pattern this route shows for. :name segments capture params and * matches the rest. Without exact, deeper paths also match. Defaults to '/'.
defaultValue: string — Option value to select initially when value is not set; also restored by form.reset(). Applied once the matching option exists.
disabled: boolean — Blocks opening, selection and search, removes the select from the tab order and closes an open dropdown. Off by default; disabled="false" counts as enabled.
dropdownclass: string — Class name set on the dropdown panel when it is first built, so the portaled panel can be styled from outside.
getPopupContainerId: string — Id of the element the dropdown panel is mounted into, looked up in the select's own root first and then the document. Defaults to document.body.
label: string — Caption rendered above the field and used as its accessible name; clicking it focuses the select. No caption when unset.
open: boolean — Whether the dropdown is showing.
placeholder: string — Empty-field hint; the field's accessible name remains its label.
placement: Placement — Which side of the trigger the panel opens on, with an optional alignment. Defaults to 'bottom'.
required: boolean — Makes an empty selection fail native form validation and sets aria-required. Ignored while disabled. Off by default; setting the property to false or 'false' removes it.
sheet: string
showSearch: string — Adds a search box that filters options as you type. Enabled whenever the attribute is present, whatever its value; remove the attribute to turn it off.
trigger: string — How the dropdown opens: 'click' | 'hover'. Default 'click'. Hover is ignored on mobile devices.
type: string — Visual style. 'text' drops the border, background and arrow so the select reads as inline text; any other value keeps the boxed field.
validationMessage: string — The browser's message for the current constraint error; empty while the field is valid.
validity: ValidityState | undefined — Native ValidityState of the field, for reading constraint errors from script. undefined where ElementInternals is unavailable.
value: string — Value of the selected option, submitted with the owning form. Setting it selects the matching option; an empty value clears the selection.
activeLabel: string — Accessible cancel/stop name while capture is pending or listening.
cancelHint: string — Replaces {@link holdHint} once the finger has slid far enough to discard.
continuous: boolean — Keep listening across pauses instead of stopping at the first one. On by default; set continuous="false" to stop at the first pause.
disabled: boolean — Disable the button so no capture can start. Off by default. Where speech recognition is unsupported the button is hidden instead, regardless of this.
holdHint: string — Shown above the button while a finger is held down.
label: string — Accessible name while idle.
lang: string — Language being spoken, as a BCP 47 tag.
listening: boolean — Whether a capture is running. Reflected, so :host([listening]) can style it.
sheet: string
supported: boolean — Whether this platform can recognize speech at all.