UISurfaceOptions

Defined in: ui/src/types.ts:879

Options for creating a UISurface (the Component that mounts a UI tree on an entity).

The surface takes the root panel’s props. new UISurface({ focus: true }) turns the whole surface into one focus scope, reached through surface.focusScope.

Extends

• UIPanelProps

Properties

alignItems?

optional alignItems?: AlignItems

Defined in: ui/src/types.ts:619

Inherited from

UIPanelProps.alignItems

---

alignSelf?

optional alignSelf?: "auto" | "center" | "flex-start" | "flex-end" | "stretch" | "baseline"

Defined in: ui/src/types.ts:157

Inherited from

UIPanelProps.alignSelf

---

anchor?

optional anchor?: Anchor

Defined in: ui/src/types.ts:880

---

background?

optional background?: BackgroundOptions

Defined in: ui/src/types.ts:622

Inherited from

UIPanelProps.background

---

bottom?

optional bottom?: PositionValue

Defined in: ui/src/types.ts:183

Offset from the containing block’s bottom edge — px or "<n>%" (only applies to position: "absolute").

Inherited from

UIPanelProps.bottom

---

consumeInput?

optional consumeInput?: boolean

Defined in: ui/src/types.ts:264

Inherited from

UIPanelProps.consumeInput

---

direction?

optional direction?: FlexDirection

Defined in: ui/src/types.ts:616

Inherited from

UIPanelProps.direction

---

flex?

optional flex?: number

Defined in: ui/src/types.ts:156

Shorthand for the common CSS flex: <number> case — expands to flexGrow: <number>, flexShrink: 1, flexBasis: 0. Use it for a child that should fill the remaining main-axis space (e.g. the text column between a fixed icon and a fixed button): sizing from a 0 basis means it won’t claim its content width and push its siblings, and its text wraps cleanly. Prefer this over flexGrow: 1 alone, which keeps flexBasis: auto (content width) and overflows. Explicit flexGrow/flexShrink/flexBasis override the parts this expands to.

Inherited from

UIPanelProps.flex

---

flexBasis?

optional flexBasis?: LayoutValue

Defined in: ui/src/types.ts:145

Inherited from

UIPanelProps.flexBasis

---

flexGrow?

optional flexGrow?: number

Defined in: ui/src/types.ts:143

Inherited from

UIPanelProps.flexGrow

---

flexShrink?

optional flexShrink?: number

Defined in: ui/src/types.ts:144

Inherited from

UIPanelProps.flexShrink

---

focus?

optional focus?: boolean | UIFocusScopeOptions

Defined in: ui/src/types.ts:640

Make this panel a focus scope over its descendants, so keyboard and gamepad input walks them. true takes every default; an object sets them. Reached afterwards through panel.focusScope. By default the scope also owns the pointer; see UIFocusScopeOptions.modal.

Passing focus again through update() refreshes the existing scope’s options and keeps focus where it is. false or an explicit undefined disposes the scope.

Inherited from

UIPanelProps.focus

---

focusable?

optional focusable?: boolean

Defined in: ui/src/types.ts:376

Take part in focus navigation. Defaults to true for UIButton, UICheckbox and the six interactive @pixi/ui wrappers, false for everything else. false leaves the element enabled for the pointer.

Inherited from

UIPanelProps.focusable

---

focusBackground?

optional focusBackground?: BackgroundOptions

Defined in: ui/src/types.ts:629

Background painted while a focusable panel holds focus. Omitted, a focused panel keeps its resting background. An override supplying only a colour keeps the resting corner radius. A panel with no background paints this fill while focused and nothing at rest.

Inherited from

UIPanelProps.focusBackground

---

focusId?

optional focusId?: string

Defined in: ui/src/types.ts:382

Name this element so a sibling’s FocusProps.focusNeighbors can point at it. Unique inside one scope: a duplicate id draws a development warning, and the first element in tree order answers to it.

Inherited from

UIPanelProps.focusId

---

focusNeighbors?

optional focusNeighbors?: FocusNeighbors

Defined in: ui/src/types.ts:384

Per-direction overrides of the position rule.

Inherited from

UIPanelProps.focusNeighbors

---

focusStyle?

optional focusStyle?: UIFocusStyle | null

Defined in: ui/src/types.ts:401

The focus outline for this element alone. Each field falls back to the plugin-level focusStyle, then to the built-in default. null draws no outline on this element.

Inherited from

UIPanelProps.focusStyle

---

gap?

optional gap?: number

Defined in: ui/src/types.ts:617

Inherited from

UIPanelProps.gap

---

height?

optional height?: LayoutValue

Defined in: ui/src/types.ts:135

Inherited from

UIPanelProps.height

---

justifyContent?

optional justifyContent?: JustifyContent

Defined in: ui/src/types.ts:620

Inherited from

UIPanelProps.justifyContent

---

layer?

optional layer?: string

Defined in: ui/src/types.ts:889

Target UI layer name on the scene’s render tree. Defaults to UI_DEFAULT_LAYER ("ui"), which is auto-provisioned as a screen-space layer via SceneRenderTreeKey.ensureLayer(...) on first use. Any other explicit name must be declared on the scene’s readonly layers or the component throws on add.

---

left?

optional left?: PositionValue

Defined in: ui/src/types.ts:177

Offset from the containing block’s left edge — px or "<n>%" (only applies to position: "absolute").

Inherited from

UIPanelProps.left

---

margin?

optional margin?: number | { bottom?: number; left?: number; right?: number; top?: number; }

Defined in: ui/src/types.ts:140

Inherited from

UIPanelProps.margin

---

maxHeight?

optional maxHeight?: LayoutValue

Defined in: ui/src/types.ts:139

Inherited from

UIPanelProps.maxHeight

---

maxWidth?

optional maxWidth?: LayoutValue

Defined in: ui/src/types.ts:137

Inherited from

UIPanelProps.maxWidth

---

minHeight?

optional minHeight?: LayoutValue

Defined in: ui/src/types.ts:138

Inherited from

UIPanelProps.minHeight

---

minWidth?

optional minWidth?: LayoutValue

Defined in: ui/src/types.ts:136

Inherited from

UIPanelProps.minWidth

---

offset?

optional offset?: object

Defined in: ui/src/types.ts:881

x

x: number

y

y: number

---

onAdjust?

optional onAdjust?: (direction) => void

Defined in: ui/src/types.ts:395

Called with -1 for left and 1 for right while this element is focused, consuming that press. Up and down still move focus.

Parameters

direction

-1 | 1

Returns

void

Inherited from

UIPanelProps.onAdjust

---

onFocusChange?

optional onFocusChange?: (focused) => void

Defined in: ui/src/types.ts:390

Called with true when focus arrives and false when it leaves, including when the scope stops taking input. Use it to show focus without an outline: a marker beside the row, a swapped sprite, a sound.

Parameters

focused

boolean

Returns

void

Inherited from

UIPanelProps.onFocusChange

---

onHover?

optional onHover?: (hovering) => void

Defined in: ui/src/types.ts:286

Parameters

hovering

boolean

Returns

void

Inherited from

UIPanelProps.onHover

---

onPointerOut?

optional onPointerOut?: () => void

Defined in: ui/src/types.ts:285

Returns

void

Inherited from

UIPanelProps.onPointerOut

---

onPointerOver?

optional onPointerOver?: () => void

Defined in: ui/src/types.ts:284

Returns

void

Inherited from

UIPanelProps.onPointerOver

---

overflow?

optional overflow?: "visible" | "hidden"

Defined in: ui/src/types.ts:621

Inherited from

UIPanelProps.overflow

---

padding?

optional padding?: Padding

Defined in: ui/src/types.ts:618

Inherited from

UIPanelProps.padding

---

position?

optional position?: "relative" | "absolute"

Defined in: ui/src/types.ts:175

Positioning mode for this element relative to its parent. Defaults to "relative" — the element flows in the parent’s flex layout. Set to "absolute" to lift the element out of the flow and pin it via left / top / right / bottom against the parent’s content box.

A position: "relative" ancestor acts as the containing block for any absolute-positioned descendants — useful for HUD overlays, modal backdrops, and badge markers. See <ZStack> in @yagejs/ui-react for an opinionated overlay primitive.

Inherited from

UIPanelProps.position

---

positioning?

optional positioning?: UIPositioning

Defined in: ui/src/types.ts:905

How the surface’s root container is positioned each frame.

• "anchor" (default) — resolve anchor against the viewport (virtualSize). Classic HUD/menu behavior.
• "transform" — read entity.get(Transform).worldPosition and reinterpret anchor as the pivot on the panel itself (e.g. BottomCenter → panel’s bottom-center sits at the Transform). Requires a Transform on the entity. The panel is positioned in the layer’s local coords, so this plays with any layer type: screen-space layers (paired with a ScreenFollow component that writes projected screen coords) for constant-size billboards, or world-space layers for genuinely diegetic UI that scales with the camera.

---

right?

optional right?: PositionValue

Defined in: ui/src/types.ts:181

Offset from the containing block’s right edge — px or "<n>%" (only applies to position: "absolute").

Inherited from

UIPanelProps.right

---

rotation?

optional rotation?: number

Defined in: ui/src/types.ts:199

Rotation in radians about LayoutProps.transformOrigin. Default 0.

Inherited from

UIPanelProps.rotation

---

scale?

optional scale?: number | { x: number; y: number; }

Defined in: ui/src/types.ts:197

Scale about LayoutProps.transformOrigin, one number for both axes or one per axis. Default 1. 0 and negative values are allowed.

Inherited from

UIPanelProps.scale

---

top?

optional top?: PositionValue

Defined in: ui/src/types.ts:179

Offset from the containing block’s top edge — px or "<n>%" (only applies to position: "absolute").

Inherited from

UIPanelProps.top

---

transformOrigin?

optional transformOrigin?: number | { x: number; y: number; }

Defined in: ui/src/types.ts:192

The point scale and rotation turn about, as fractions of the element’s computed size: 0 is the top-left corner, 0.5 the centre, { x: 0.5, y: 1 } the middle of the bottom edge. Default 0. This prop, scale, rotation and zIndex change how the element is drawn, never its Yoga box.

Inherited from

UIPanelProps.transformOrigin

---

visible?

optional visible?: boolean

Defined in: ui/src/types.ts:184

Inherited from

UIPanelProps.visible

---

width?

optional width?: LayoutValue

Defined in: ui/src/types.ts:134

Inherited from

UIPanelProps.width

---

zIndex?

optional zIndex?: number

Defined in: ui/src/types.ts:206

Draw and pointer order among the siblings in the same container: a higher value draws on top and takes the pointer first. Default 0; siblings with equal values keep the order they were added in. To rise above an element in a neighbouring container, raise that container.

Inherited from

UIPanelProps.zIndex