RmlUi API guide
The RmlUi API reference is generated from this package's TypeScript declarations and four-language TSDoc. Overview entries show short descriptions; member pages contain signatures, defaults, parameters, return values and lifetime details.
Strings and resource URLs cover retained byte views, UTF-8 iteration, batched offsets and typed native formatting.
Find a contract
| Task | API |
|---|---|
| Bind a render window | initialise, InitialiseOptions |
| Load fonts and release glyph caches | loadFontFace, Font guide |
| Observe Native lifecycle notifications | Plugin, Plugin guide |
| Inspect and release renderer resources | Renderer resources, RenderInterface |
| Inspect layout, scroll and project coordinates | Element layout, Element |
| Inspect native scroll and transform components | ElementScroll, TransformState, ElementTransformBuffer |
| Construct and inspect box values | Box values, Box, RenderBox |
| Resolve numeric values and units | Numeric values, NumericValue |
| Read and assign typed properties | Properties, Property |
| Animate typed properties and evaluate easing | Animation, Tween |
| Create, update and render a context | createContext, Context |
| Read physical dimensions | ContextDimensions |
| Bind native data and custom views/controllers | Data models, DataView, DataController, Factory |
| Show and unload documents | Document |
| Query, style and listen to elements | Element |
| Attach, recursively detach and explicitly dispatch events | EventDispatcher, Element state |
| Read live events and copied parameters | RmlEvent, RmlEventListener |
| Release the runtime | shutdown |
Native element components
element.getStyle() exposes the actual checked ElementStyle, including cascade, dirty sets, explicit definition updates, owned computation, snapshot iterators and reusable keyframe resolution. See Element state for lifecycle, layout consumption and shared numeric command contracts.
element.getElementBackgroundBorder() returns the canonical element-owned ElementBackgroundBorder. dirtyBackground() and dirtyBorder() mark geometry for the next native render(). Rendering uses current computed style, layout and manager state; prepare the manager viewport first. A detached element without a manager does not draw. Another manager's active layer and effect callback reentry are rejected.
getClipGeometry(area) accepts BoxArea.Border, Padding or Content and returns an independent native Geometry snapshot. Margin and Auto throw. No manager produces an empty geometry. Component regeneration, element destruction, snapshot editing and snapshot release do not change other snapshots or the component mesh. The manager still controls GPU resource lifetime; getMesh() copies survive manager release and shutdown.
const background = element.getElementBackgroundBorder();
context.getRenderManager().prepareRender({
x: context.dimensions.width, y: context.dimensions.height,
});
background.render();
const clip = background.getClipGeometry(BoxArea.Padding);
const mesh = clip.getMesh();
clip.release();element.getElementScroll() returns the element-owned ElementScroll. ScrollOrientation.VERTICAL is 0 and HORIZONTAL is 1. Its update(), enableScrollbar(orientation, elementWidth), disableScrollbar(orientation), updateScrollbar(orientation), formatScrollbars() and updateProperties() run the native component operations. getScrollbar(orientation) returns a live element, or null if the scrollbar has never been created. getScrollbarSize(orientation) returns the vertical width or horizontal height in pixels, and zero when disabled. Disabling changes the native property; updateProperties() recomputes scrollbar properties before visibility queries. The component invalidates with its element and retains detached ownership.
element.getTransformState() returns a read-only current native state or null. RmlUi updates transforms during context.render(). getTransform(), getLocalPerspective() and getInverseTransform() return independent native-owned Float32Array snapshots with sixteen column-major values. Unset matrices return null; singular transforms have no inverse. Snapshots remain usable after element destruction and runtime shutdown. new TransformState() owns an independent state with setTransform(matrix) and setLocalPerspective(matrix); each copies sixteen finite floats or clears with null, and returns whether the native value changed.
For repeated reads across many elements, allocate ElementTransformBuffer once. refresh() uses one native entry, no JS callbacks and no output reallocation. Each element occupies 48 column-major floats: transform at 0, perspective at 16, inverse at 32. flags[i] has presence bits 1, 2 and 4; absent matrices contain zeros. Writes only change snapshots. All owners are checked before output changes; destroyed elements and stale runtimes throw. Numerical views retain only their storage, including after wrapper collection.
const { ElementTransformBuffer } = require('sfml.js-rmlui');
const transforms = new ElementTransformBuffer(elements);
context.update();
context.render();
transforms.refresh();
const firstTransform = transforms.matrices.subarray(0, 16);
const firstPresence = transforms.flags[0];Important return values
initialise returns success; repeating it does not replace the process-wide window or options. loadFontFace returns whether a font loaded. Element queries return null for no match. setProperty returns whether the RCSS property was accepted.
processEvent returns propagation for key/text/wheel events and non-interaction for mouse/touch input. Direct input methods and exact return rules are covered in Documents and events. update and render forward RmlUi 6.3's result, currently always true; do not use them as dirty flags or visibility tests.
Defaults and ownership
highDpi defaults to true; font fallback, modal display and listener capture default to false. These values also appear on their API detail pages.
Obtain context and element wrappers through runtime creation, loaders or element queries. Their internal handles are not public API. These wrappers borrow native objects; see documents and events for invalidation and listener removal.
Box and RenderBox have public constructors. They own independent native values and shared numerical views; see box values for their lifetime and snapshot rules.
The source entry point and exported declarations are the source of truth. This binding covers the documented surface, rather than every C++ RmlUi API.