📄️ First Layout
At first, we will create 3 containers. One container is the root node with a size of 2 by 1 three.js untits, expressed by RootContainer. The RootContainer has a horizontal (row) flex-direction, while the children expressed by Container equally fill its width with a margin between them.
📄️ Scaling & Sizing
TLDR: Use the optional paramters sizeX and sizeY to define a specific size of the UI in three.js units. Use pixelSize to scale the pixels units of the UI instead of increasing the size of the individual elements (normal text should have a default size of 16px like in the web).
📄️ Asynchronous Content
Koestlich provides Text, Image, GLTF, and SVG components, which load their content asynchronously. The components use the Suspense API from react to handle the loading state. This allows the components to be wrapped in a Suspense component to display a fallback element while loading.
📄️ Text
The Text component enables rendering text using multi-channel signed distance functions (MSDF). A font can be created from a .ttf file to an MSDF representation as a JSON and a corresponding texture using msdf-bmfont-xml. We provide a set of precompiled MSDF fonts from here. There you will find a list of fonts you can instantly use in your applications. In the following, a Text is rendered with the Roboto font family.
📄️ Animations
Animations are built into koestlich and work out of the box. Almost all properties can be animated. In contrast to HTML/CSS, elements can transition from one place in a layout to another, a feature often referred to as AutoTransition. To declare how UI elements relate between two different layouts, the id property is used. Placing the same id property on two UI components in different layouts will keep the underlying UI element alive and automatically transition. However, both UI components need to have the same type. Therefore, it is impossible to transition an Image to a Text component.
📄️ 3D Content
The previous examples showed 2D elements positioned in the x/y plane. Integrating 3D geometries into the UI will make use of the z-Axis. In addition to having width and height, all components now have depth, which is their size on the z-Axis. All UI elements will be placed in front of their parent along the z-Axis.
📄️ Overflow, Scroll, and Clipping
Koestlich handles clipping and scrolling for you. You only need to specify overflow "scroll" or "hidden" on any container. First, however, we need to configure react-three/fiber to support visual clipping and clipping of events, which is done via ``.
📄️ Custom Materials
Koestlich allows to provide custom materials for the background on the Text, Container, and Image components. Using the library @coconut-xr/xmaterials, a new material can be built based on the existing three materials. Every provided material must be at least be a border material created through makeBorderMaterial. The makeBorderMaterial allows to provide default properties to the material. In the following example, we are creating a text element with a material based on the phong material with high specular and shininess. Using the border properties, we can create a border that creates the illusion of a 3d mesh. Specifically, the borderBend property allows bending the normals on the border to create this effect efficiently. The anchorX and anchorY properties allow the button in the following example to have its origin in (0,0,0).