Skip to content

RML and RCSS basics ​

RML defines the elements in a RmlUi document. RCSS selects those elements and sets their layout and appearance. JavaScript loads the document and connects it to application state. This chapter uses the counter example; complete the quick start first.

Follow the three files ​

FileResponsibility
tutorial.rmlElement tree, IDs, text and the stylesheet link
tutorial.rcssLayout, fonts, colors and hover states
demo.cjsWindow, fonts, document loading, input, click handler and frame loop

Write the document ​

The following is a reduced version of tutorial.rml. It keeps the IDs used by demo.cjs, so you can try it with that launcher and the stylesheet below.

xml
<rml>
  <head>
    <title>Counter</title>
    <link type="text/rcss" href="tutorial.rcss" />
  </head>
  <body>
    <div id="window">
      <div id="title">My counter</div>
      <div id="counter" class="muted">Clicks: 0</div>
      <button id="increment">Increment</button>
    </div>
  </body>
</rml>

<rml> is the root, <head> describes document resources, and <body> contains the visible interface. The stylesheet path is relative to the RML file. Use matching closing tags and quoted attribute values; self-close empty elements such as <link />. Escape literal & and < as &amp; and &lt;.

An id identifies one element for queries and styling. A class groups elements that share a style; multiple classes are separated by spaces. RML does not give arbitrary tag names their browser appearance: in particular, a div needs display: block for block layout.

Style it with RCSS ​

Place these rules in tutorial.rcss beside the RML file. The launcher already loads the LatoLatin regular and bold fonts before loading the document.

css
body {
  width: 100%;
  height: 100%;
  font-family: LatoLatin;
  font-size: 16dp;
  color: #f5f7fa;
  background: #1d2430;
}

div {
  display: block;
}

#window {
  width: 480dp;
  margin: auto;
  padding: 24dp;
  box-sizing: border-box;
  background: #2b3446;
  border: 1dp #46546e;
}

#title {
  font-size: 22dp;
  font-weight: bold;
  margin-bottom: 12dp;
}

.muted {
  color: #8fd3ff;
  margin-bottom: 18dp;
}

button {
  display: inline-block;
  padding: 10dp 24dp;
  background: #e84c88;
}

button:hover {
  background: #ff6aa2;
}
SelectorMatches
buttonEvery button element
#windowThe element with id="window"
.mutedElements with the muted class
#window buttonButtons inside #window
button:hoverA button under the pointer

margin is space outside the box; padding is space between its content and border. box-sizing: border-box includes padding and borders in the declared width. Font and text color inherit from the parent; more specific matching selectors can override a general rule. Hover styling changes appearance only; the click action still needs a listener.

Use dp for fixed UI sizes and fonts: at a density ratio of 2, 16dp becomes 32 render pixels and keeps its logical size. px uses render pixels; % depends on the property's reference size. The binding initializes the context's density ratio; see Retina sizing. font-family must match a loaded font's internal family name, not its filename.

RCSS has its own supported property set. For example, its border shorthand is border: 1dp #46546e; do not assume every browser CSS declaration is supported. Flexbox, templates and decorators have dedicated upstream documentation.

Connect a click to state ​

The launcher queries the document after loading it and registers this handler once, outside the frame loop:

js
const counter = document.getElementById('counter');
const button = document.getElementById('increment');

if (!counter || !button) {
  throw new Error('Counter elements are missing');
}

let clicks = 0;

function increment() {
  clicks += 1;
  counter.innerRML = `Clicks: ${clicks}`;
}

button.addEventListener('click', increment);

The frame loop forwards SFML events to context.processEvent, then calls update and render. A click updates the existing element; the next frame displays the value. innerRML parses markup, so escape untrusted text before assigning it. This package does not run <script> contents or inline onclick JavaScript from RML.

Before unloading the document, call button.removeEventListener('click', increment) with the same function. Continue with documents and events for queries, class changes and native lifetimes.

Try an edit ​

Change the title, the .muted color or the button padding, then restart the example from the monorepo root:

sh
node packages/sfml.js-rmlui/examples/demo.cjs

RML and RCSS edits need no native rebuild. The launcher loads them at startup; it does not watch for changes. The reduced document shows a title, counter and button; Increment increases the count by one.

Official syntax references ​

The upstream online manual follows its development branch. This binding targets RmlUi 6.3 and exposes a subset of its APIs and rendering features. Check the local rendering coverage and API guide before relying on an upstream feature.

Icons made by Lorc, Delapouite & Skoll game-icons.net · CC BY 3.0