Editable UI

Editable UI (Creator Hub UI Designer)

The Creator Hub UI editor has no saved format of its own: the scene's real @dcl/react-ecs .tsx files under src/ui/ are the document. The editor parses them into a node tree, renders that on a canvas, and writes visual edits back as minimal text splices. A 1s disk watcher reflects external edits back onto the canvas.

Consequence: "editable in the editor" is a checkable property of the code, not a style preference. Code the parser cannot statically understand degrades in one of two ways:

Both are silent. Write to the contract below and neither happens.

Prerequisite knowledge: the build-ui skill (React-ECS elements, uiTransform/uiBackground, flex layout). This skill only covers what makes that code editor-editable.

[EXPERIMENTAL] The UI editor is opt-in: the user enables Settings > Experimental > UI Editor in the Creator Hub, and the scene must be on @dcl/sdk 7.26.0+ (the version that ships ScreenInsetArea / InteractableArea and the per-device default virtual screen). The 2D/3D mode switch is hidden otherwise. Code written to this contract is ordinary React-ECS and runs anywhere regardless.

Two workflows

A. Generate a new editable UI

1. One component per file: src/ui/<ComponentName>.tsx. Basename must be a valid PascalCase identifier equal to the exported function name — the editor ignores any file whose basename is not already in that form.
2. Create src/ui/interaction.tsx and (if you use platform variants) src/ui/platform.tsx verbatim from {baseDir}/references/interaction-helper.md. These are the two reserved helper filenames; the editor scaffolds them itself and never lists them as UIs.
3. Write each component to the contract in The contract below. Start from {baseDir}/references/component-template.md.
4. Write src/ui/index.tsx in the exact generated shape (see The aggregator), and call setupUi() from main() in src/index.ts.
5. Put every clock, easing, timer, formatter and state machine in a plain .ts file outside src/ui/ — see The driver pattern.
6. Run the self-check list at the bottom of this file over every file you produced.

B. Adapt an existing coded UI

1. Split the UI into one file per component under src/ui/; move any non-JSX logic (helpers, clocks, math, data) out to a .ts file outside src/ui/.
2. Mechanically eliminate the five blockers, in this order — see {baseDir}/references/adapting-coded-ui.md for before/after code on each:
   • .map() / loops → unroll every item as sibling elements.
   • {cond && <X/>} and cond ? <A/> : <B/> → useInteraction active layer with display: 'none' (the only exception: the desktop/mobile platform variant, which is a supported construct). Put each gate on the element being hidden, never on an enclosing full-screen wrapper — the spread carries pointer handlers (see Interaction layers).
   • computed style values (arithmetic, Math.*, calls, string concat, ternaries, shared theme identifiers) → one driver-maintained bound state variable per derived value, or an inline literal.
   • inline-interpolated text → mixed-text segment bindings, with the formatting moved into the driver.
   • hand-tracked hover/press booleans → hover / press layers.
3. Replace tween/animation code that computes style values in render with a driver that eases the finished value into a bound state variable.
4. Every size and position value becomes a plain px number, and every component root and component-ref wrapper gains an explicit width/height — coded UI routinely auto-sizes containers from their children, which survives the port and then renders as height 0 on the canvas (see Sizing and mobile).
5. Re-run the self-check list.

Expect the adapted file to be larger than the original: unrolling loops and variants is the price of editability. Report that trade-off to the user rather than silently half-porting.

File layout

src/ui/
  index.tsx        <- GENERATED aggregator. Never hand-edit.
  interaction.tsx  <- reserved helper (useInteraction). Verbatim.
  platform.tsx     <- reserved helper (usePlatform). Verbatim.
  MyScreen.tsx     <- a top-level UI (rendered by the aggregator)
  MyWidget.tsx     <- a reusable component (marked /** @ui-component */)
src/ui-behaviors.ts  <- driver: outside src/ui/, never parsed by the editor

• A legacy single-file src/ui.tsx is backed up to src/ui.tsx.bak and deleted the first time the editor opens the scene. Always author under src/ui/.
• Every file starts with /** @jsx ReactEcs.createElement */ and imports ReactEcs from @dcl/sdk/react-ecs.
• Exactly one exported component per file (the editor reads the first exported function that returns JSX).
• Use // comments only. {/* JSX comments */} parse as opaque expression children.

The aggregator (src/ui/index.tsx)

Generated from the list of top-level roots. It is rewritten whenever the editor opens the scene and whenever a root file is added, renamed, removed or re-inset — so any hand edit to it is lost. Emit it in exactly this shape:

/** @jsx ReactEcs.createElement */
import ReactEcs, { UiEntity, ReactEcsRenderer, ScreenInsetArea } from '@dcl/sdk/react-ecs'
import { MyScreen } from './MyScreen'

export function setupUi() {
  ReactEcsRenderer.setUiRenderer(() => (
    <UiEntity uiTransform={{ width: '100%', height: '100%' }}>
      <ScreenInsetArea>
        <MyScreen />
      </ScreenInsetArea>
    </UiEntity>
  ))
}

Screen inset is a per-root choice, and device is the default. Verified against @dcl/react-ecs 7.27.0 (components/ScreenInsetArea, components/InteractableArea):

ScreenInsetArea owns its own positionType/position; a child sized 100%×100% fills the safe area exactly. Both wrappers belong only in index.tsx — inside a component file their element names are unknown to the parser and would make the subtree opaque.

setUiRenderer is generated with no options object, so the scene gets the SDK platform default virtual canvas (desktop 1920x1080, mobile 1600x720). Do not hand-add virtualWidth/virtualHeight here — the next regeneration drops them. This is the one place where build-ui's "always pass the virtual size explicitly" rule cannot be honored; design px values against those two canvases instead.

The editor also ensures main() calls setupUi() (it uncomments the template's //setupUi() line and adds the import). When authoring by hand, wire it yourself.

The contract

Elements

Only these five element names are modeled: UiEntity, Label, Input, Dropdown, Button.

The one additional first-class element is a reference to another root file in src/ui/ — <MyWidget />. That is the sanctioned reuse unit: selectable, movable, with per-instance editable props. Any other element name (a local helper component, a library component, ScreenInsetArea) is opaque.

• Text lives on Label / Button only: value, fontSize, textAlign, color, font, textWrap. A uiText={{...}} bag on a UiEntity is not modeled — restructure it as a Label child. No emoji in any text value (see Sizing and mobile).
• Input props: placeholder, value, color, placeholderColor, disabled, textAlign, font, fontSize.
• Dropdown props: acceptEmpty, emptyLabel, options, selectedIndex, disabled, color, textAlign, font, fontSize.
• A <MyWidget /> instance cannot be moved or sized from outside — give each instance a wrapper UiEntity when it needs margins or positioning. That wrapper needs explicit width/height too, not just a margin (see Sizing and mobile).
• Component refs accept no nested JSX children — there is no slot/children mechanism, so a generic <Card> wrapper is not expressible.

State: the binding surface

export interface State {
  score: number
  label: string
  visible: boolean
  panelWidth: number
  labelColor: { r: number; g: number; b: number; a: number }
  options: string[]
}
export const state: State = {
  score: 0,
  label: '00.00',
  visible: false,
  panelWidth: 320,
  labelColor: { r: 1, g: 1, b: 1, a: 1 },
  options: ['A', 'B'],
}

Module-level export interface State + export const state: State is the recognized signature; every property is an editable variable. Supported types: number, string, boolean, Color4 (annotate structurally as { r: number; g: number; b: number; a: number } — the annotation is matched by having r/g/b members, not by the name Color4), and string[].

• state is a plain exported module object — that is exactly what lets the driver mutate it (see below).
• Module state is shared by every instance of a file. Per-instance values must live in the parent and arrive as props (React's controlled-component pattern).
• A number[] variable (e.g. a uvs quad) binds and works, but the panel infers string[] from the initializer and mislabels it as an options list. Usable; just a wrong label.

Style bindings

Any uiTransform / uiBackground key whose value is a bare reference — state.x or props.x, with no operators, calls, or concatenation — is a first-class editable binding, not a freeze:

uiTransform={{ width: state.panelWidth, position: { top: state.panelTop }, borderColor: state.frameColor }}
uiBackground={{ color: state.panelColor, texture: { src: state.iconSrc } }}

Recognized binding positions: top-level keys (width, height, zIndex, color, uvs, …), members of the nested edge groups (position/margin/padding → { left: state.x }), whole groups written at once (borderColor: state.c), and the dotted paths texture.src / avatarTexture.userId. Literal and bound siblings mix freely in one object. Nesting is one level deep — exactly react-ecs's own shape.

Text and element props bind the same way: value={state.label}, color={state.labelColor}, fontSize={state.size}, selectedIndex={state.i}, options={state.options}.

Mixed text (the counter/timer/readout workhorse)

A template literal whose interpolations are all bare references round-trips as ordered literal/binding segments and stays fully editable:

<Label value={`Score: <b>${state.score}</b>`} />
<Label value={`${state.mins}:${state.secs}`} />
<Label value={`env: ${state.realm}\nplayers: ${state.count}`} />

Multi-line \n literals are fine. One computed interpolation (${state.a + 1}, ${fmt(state.t)}) breaks the whole attribute and freezes the node — do the formatting in the driver and interpolate the finished value.

(The three lines above show only the value attribute. Every real Label also needs an explicit uiTransform width/height — see Sizing and mobile.)

Actions (event handlers)

type UiAction = { state: State; props: Parameters<typeof MyScreen>[0]; value?: unknown }

/** @ui-action */
function openPanel({ state }: UiAction) {
  state.visible = true
}

Wire with the canonical thunk: onMouseDown={() => openPanel({ state, props })}, or for value-bearing events onChange={(value) => setName({ state, props, value })}. Recognized events: onMouseDown, onMouseUp, onMouseEnter, onMouseLeave, and onChange/onSubmit on Input/Dropdown.

• Handler bodies are free-form code — any logic is allowed there. They are never parsed as styles.
• An unrecognized handler expression (an inline arrow with a block body) is simply not shown as bound; it does not freeze the node.
• Actions mutate state synchronously. Anything time-based belongs in the driver — an action sets a flag, the driver animates.

Interaction layers: hover, press, and visibility

useInteraction is the recognized construct for per-state styling. Layers are deep-merged in precedence order base → active → hover → press; the second argument drives the active layer and may be any expression (stored verbatim).

const panel = useInteraction(
  {
    base: { uiTransform: { display: 'flex', width: 320, height: 200 } },
    active: { uiTransform: { display: 'none' } },
  },
  state.visible !== true,
)
return <UiEntity {...panel}>…</UiEntity>

Rules:

• Visibility is always an active display gate. Never {state.visible && <X/>} (opaque) and never display: state.visible ? 'flex' : 'none' (frozen).
• Hover/press feedback is always a hover/press layer. Never hand-tracked booleans with onMouseEnter/onMouseLeave.
• {...someInteractionConst} is the only spread the parser accepts. Any other spread makes the node opaque. Extra attributes may sit alongside the spread (<UiEntity {...panel}>).
• The spread carries pointer handlers, so it must never land on a full-screen wrapper. useInteraction returns all four listeners (onMouseDown/Up/Enter/Leave) unconditionally — it needs them to track hover and press — even when you called it purely as a visibility gate with only base + active layers. A UI element with any listener captures pointer input across its whole rect, so {...gate} on a 100%×100% layout wrapper makes the entire screen swallow clicks: no other UI element and nothing in the 3D world can be clicked, while the UI still looks correct because the visible panel is small. Put the gate on the panel — the smallest element the visibility decision applies to — and leave the full-screen wrapper as a plain literal-styled UiEntity that only does positioning. See the dialog before/after in {baseDir}/references/component-template.md §4 and the recipe in {baseDir}/references/adapting-coded-ui.md §4. Two deliberately-blocking full-screen overlays are sanctioned — a modal backdrop meant to swallow clicks, and a drag-release catcher gated off while no drag runs ({baseDir}/references/drag-slider.md) — the rule is that blocking is always an explicit, gated decision, never a side effect of where a spread was placed.
• Elements are hidden, not unmounted — everything is present in the tree at all times, and the canvas renders the base layer, so all states appear stacked while editing. That is expected.
• For UI that animates out before disappearing, use the two-variable pattern: visible (intent, flipped by actions) plus hidden (render gate, cleared by the driver only after the exit animation finishes). Gate on state.hidden === true.

/** @ui-component */
export function MyWidget(props: { label?: string; fillPx?: number; on?: boolean; onPress?: (value?: unknown) => void }) {

const platform = usePlatform()
return platform === 'mobile' ? <PhoneMenu /> : <DesktopBar />

// src/ui-behaviors.ts — outside src/ui/, invisible to the editor
import { engine } from '@dcl/sdk/ecs'
import { state as panel } from './ui/MyPanel'

const OPEN_WIDTH = 480
let anim = 0

export function registerUiBehaviors() {
  engine.addSystem((dt: number) => {
    const target = panel.visible ? 1 : 0
    anim = Math.max(0, Math.min(1, anim + (target > anim ? dt : -dt) / 0.25))
    const t = 1 - Math.pow(1 - anim, 3) // easeOutCubic
    panel.panelWidth = Math.max(1, Math.round(OPEN_WIDTH * t))
    panel.textColor.a = t
    if (target === 0 && anim <= 0) panel.hidden = true // release the display gate
  })
}