RmlUi - The HTML/CSS User Interface Library Evolved

RmlUi logo

RmlUi - now with added boosters taking control of the rocket, targeting your games and applications.

RmlUi is the C++ user interface package based on the HTML and CSS standards, designed as a complete solution for any project's interface needs. It is a fork of the libRocket project, introducing new features, bug fixes, and performance improvements.

RmlUi aims at being a light-weight and performant library with its own layout engine and few dependencies. In essence, RmlUi takes your HTML/CSS-like source files and turns them into vertices, indices and draw commands, and then you bring your own renderer to draw them. And of course there is full access to the element hierarchy/DOM, event handling, and all the interactivity and customizability you would expect. All of this directly from C++, or optionally from scripting languages using plugins. The core library compiles down to fractions of the size it takes to integrate a fully fledged web browser.

RmlUi is based around the XHTML1 and CSS2 standards while integrating features from HTML5 and CSS3, and extends them with features suited towards real-time applications. Take a look at the conformance and enhancements sections below for details.

Documentation is located at https://mikke89.github.io/RmlUiDoc/

Features

Cross-platform architecture: Windows, Linux, macOS, Android, iOS, Switch, and more.
Dynamic layout system.
Full animation and transform support.
Efficient application-wide styling, with a custom-built templating engine.
Fully featured control set: buttons, sliders, drop-downs, and more.
Runtime visual debugging suite.

Extensible

Abstracted interfaces for plugging in to any game engine.
Decorator engine allowing custom application-specific effects that can be applied to any element.
Generic event system that binds seamlessly into existing projects.
Easily integrated and extensible with the Lua scripting plugin.

Controllable

The user controls their own update loop, calling into RmlUi as desired.
The library strictly runs as a result of calls to its API, never in the background.
Input handling and rendering is performed by the user.
The library generates vertices, indices, and textures for the user to render how they like.
File handling and the font engine can optionally be fully replaced by the user.

Conformance

RmlUi aims to support the most common and familiar features from HTML and CSS, while keeping the library light and performant. We do not aim to be fully compliant with CSS or HTML, in particular when it conflicts with lightness and performance. Users are generally expected to author documents specifically for RmlUi, but any experience and skills from web design should be transferable.

RmlUi supports most of CSS2 with some CSS3 features such as

Animations and transitions
Transforms (with full interpolation support)
Flexbox layout
Media queries
Border radius
Box shadows and mask images
Gradients (linear, radial, and conic) as decorators
Filters and backdrop filters (with all CSS filter functions)

and many of the common HTML elements including <input>, <textarea>, and <select>.

For details, see

RCSS Property index for all supported properties and differences from CSS.
RML Element index for all supported elements.

Enhancements

RmlUi adds features and enhancements over CSS and HTML where it makes sense, most notably the following.

Data binding (model-view-controller). Synchronization between application data and user interface.
Decorators. Full control over the styling of all elements.
Sprite sheets. Define and use sprites with easy high DPI support.
Templates. Making windows look consistent.
Localization. Translate any text in the document.
Spatial navigation. Suitable for controllers.

Dependencies

FreeType. However, it can be fully replaced by a custom font engine.
The standard library.

In addition, a C++17 compatible compiler is required.

Building RmlUi

CMake

RmlUi can be built using CMake and your favorite compiler, see the building documentation for details and all the options. Windows binaries are also available for the latest release.

vcpkg

RmlUi can also be fetched from a dependency manager such as vcpkg.

vcpkg install rmlui

That's it! See below for details on integrating RmlUi.

To build RmlUi with the included samples we can use git and CMake together with vcpkg to handle dependencies.

vcpkg install freetype glfw3
git clone https://github.com/mikke89/RmlUi.git
cd RmlUi
cmake -B Build -S . --preset samples -DRMLUI_BACKEND=GLFW_GL3 -DCMAKE_TOOLCHAIN_FILE="<path-to-vcpkg>/scripts/buildsystems/vcpkg.cmake"
cmake --build Build

Make sure to replace <path-to-vcpkg> as appropriate. This example uses the GLFW_GL3 backend, other backends are available as shown below. When this completes, feel free to test the freshly built samples, such as the invaders sample (rmlui_sample_invaders target), and enjoy! The executables should be located somewhere in the Build directory.

To make all the samples available, you can additionally install lua lunasvg rlottie harfbuzz and pass --preset samples-all during CMake configuration.

Integrating RmlUi

Here are the general steps to integrate the library into a C++ application, have a look at the integration documentation for details.

Build RmlUi as above or fetch the binaries, and link it up to your application.
Implement the abstract render interface, or fetch one of the backends listed below.
Initialize RmlUi with the interfaces, create a context, provide font files, and load a document.
Call into the context's update and render methods in a loop, and submit input events.
Compile and run!

Several samples demonstrate everything from basic integration to more complex use of the library, feel free to have a look for inspiration.

RmlUi Backends

To ease the integration of RmlUi, the library includes many backends adding support for common renderers and platforms. The following terms are used here:

Renderer: Implements the render interface for a given rendering API, and provides initialization code when necessary.
Platform: Implements the system interface for a given platform (operating system or window library), and adds procedures for providing input to RmlUi contexts.
Backend: Combines a renderer and a platform for a complete windowing framework sample, implementing the basic Backend interface.

The provided renderers and platforms are intended to be usable as-is by client projects without modifications, thereby circumventing the need to write custom interfaces. We encourage users to only make changes here when they are useful to all users, and then contribute back to the project. However, if they do not meet your needs it is also possible to copy them into your project for modifications. Feedback is welcome to find the proper abstraction level. The provided system and render interfaces are designed such that they can be derived from and further customized by the backend or end user.

The provided backends on the other hand are not intended to be used directly by client projects, but rather copied and modified as needed. They are intentionally light-weight and implement just enough functionality to make the included samples run, while being simple to understand and build upon by users. See the manual for backend integration details.

Renderers

| Renderer features | Basic rendering | Transforms | Clip masks | Filters | Shaders | Built-in image support | |-------------------|:---------------:|:----------:|:----------:|:-------:|:-------:|-------------------------------------------------------------------| | OpenGL 3 (GL3)* | ✔️ | ✔️ | ✔️ | ✔️ | ✔️

RmlUi

Install / Use

README