Docs
API Reference

UI

UI for rendering to a WebGPU canvas. Import from @uno.build/ui/UI. For engine surfaces, see UIWorldSpace.

Properties

PropertyTypeDescription
rootNode | nullRoot node.
rendererRendererWebGPU | nullRenderer instance.
resourcesResourcesWebGPU | nullResource store.
defined_eventsDefinedEvent[]Installed event definitions.
eventsEventEmitter<UIEventMap>Normalized UI events.
events_sourceEventEmitter<CoreEventMap>Source and lifecycle events.
operationsOperationsMutation journal.

Methods

MethodReturnsDescription
static create(options: UIOptions)Promise<{ ui: UI }>Creates and initializes a UI.
create()Node | undefinedCreates a detached Node.
update()voidApplies pending changes.
draw(options?: WebGPUDrawOptions)WebGPUDrawResult | undefinedDraws the current UI state.
setViewport(width: number, height: number)voidSets logical viewport dimensions.
setDevicePixelRatio(device_pixel_ratio: number)voidSets raster density.
setRootSize(root_size: number)voidSets the pixel size of 1rem.
addChild(parent: Node, child: Node, before_node: Node | null)voidInserts a child; null appends.
detachNode(node: Node)voidDetaches a subtree for reuse.
destroyNode(node: Node)voidDestroys a subtree; the root destroys the UI.
registerPlatformEvents()voidRegisters canvas event listeners.
removePlatformEvents()voidRemoves registered canvas listeners.
dispatchPlatformEvent(source_event: PlatformEvent)voidForwards a platform event into the UI.
destroy()boolean | voidDestroys the UI.

Creation options

OptionTypeDefault
resourcesResourcesWebGPURequired
register_platform_eventsbooleantrue
defined_eventsArray<(options: { ui: UI }) => DefinedEvent>[]
image_min_filter'linear' | 'nearest''linear'
image_mag_filter'linear' | 'nearest''linear'
yogabooleantrue

register_platform_events registers canvas listeners during creation. UIOptions and DefinedEvent are exported by @uno.build/ui/UI. See Custom event definitions for a defined_events example. yoga: false lays the UI out without Yoga; see Layout without Yoga.

Layout without Yoga

With yoga: false, every node is an absolutely positioned box and there is no flexbox. It is meant for UIs that only place information on screen, such as a gameplay HUD with labels that follow 3D objects. A change lays out only the changed node, and its children when its size changes; siblings and ancestors are never laid out again. The low-level classes (UIWebGPU, UIWebGPUThree, …) use this mode when they are created without loadYoga.

const { ui } = await UI.create({ resources, yoga: false })
ui.setViewport(canvas.clientWidth, canvas.clientHeight)

const label = ui.create()
label.style('left', '20px')
label.style('top', '20px')
label.text('100')
ui.root.add(label)
  • Position. A node is placed inside its parent's border, with left, top, right and bottom. Without insets it sits at the start of the parent's content box, so siblings overlap. left wins over right, and top over bottom. Percentages resolve against the parent's size inside its border.
  • Size. width and height take px or %. With both left and right (or top and bottom) and no size, the node stretches between them. A text node without a size takes the size of its text; it only wraps when its width is set or stretched. Any other node without a size measures only its padding and border: children never grow their parent.
  • Supported layout styles. left, top, right, bottom, width, height, minWidth, minHeight, maxWidth, maxHeight, padding*, border*Width, boxSizing and display: none. A min larger than its max wins, as in CSS. The other layout styles (flex*, align*, justify*, gap, margin, position, aspectRatio) are ignored. Paint and text styles work as usual.
  • No scrolling. overflow clips, but nothing scrolls: scrollWidth, scrollHeight, clientWidth and clientHeight stay 0, and wheel and scroll events do not move content. Pointer, click and focus events work.
  • The root fills the viewport and ignores its insets: call setViewport() before update().

To center text in a box, use textAlign: 'center' and a lineHeight equal to the box height. Move things every frame with translate, scale, and rotate, which only repaint. left and top are layout changes: moving a subtree with them places its glyphs again.

Draw options

OptionTypeDefault
submitbooleantrue
command_encoderGPUCommandEncoderNew encoder
texture_viewGPUTextureViewCurrent canvas texture view
load_op'load' | 'clear''load'

Draw result

PropertyType
command_encoderGPUCommandEncoder
texture_viewGPUTextureView

On this page