UI Input Binding

Bind input actions to your own UI elements so they drive player input.

UiInputBinding turns any UI element into a control button. Bind an element to one or more InputActions, and while it's pressed — by touch or pointer — those actions are held down, driving both the local player's input (movement, jumping) and any scene InputAction listeners, exactly like the native on-screen buttons.

Use it to build your own touch controls. It's typically paired with On-screen Controls: hide the native buttons, then put your own in their place.

Bind an action to a UI element

Add a uiInputBinding prop to any element in your .tsx UI and list the actions to hold while it's pressed. The prop is available on every UI element (UiEntity, Button, Label, …), just like uiTransform and uiBackground.

A button that moves the player forward while held:

import { InputAction } from '@dcl/sdk/ecs'
import { Button } from '@dcl/sdk/react-ecs'

export const forwardButton = () => (
    <Button
        value="▲"
        uiTransform={{ width: 100, height: 100 }}
        uiInputBinding={{ actions: [InputAction.IA_FORWARD] }}
    />
)

Build a custom control cluster

Combine several bound elements to assemble a full control scheme.

A movement button plus an action button that fires IA_PRIMARY:

import { InputAction } from '@dcl/sdk/ecs'
import { Button, UiEntity } from '@dcl/sdk/react-ecs'

export const customControls = () => (
    <UiEntity uiTransform={{ width: 240, height: 120 }}>
        <Button
            value="▲"
            uiTransform={{ width: 100, height: 100 }}
            uiInputBinding={{ actions: [InputAction.IA_FORWARD] }}
        />
        <Button
            value="Use"
            uiTransform={{ width: 100, height: 100 }}
            uiInputBinding={{ actions: [InputAction.IA_PRIMARY] }}
        />
    </UiEntity>
)

The bound actions behave just like the native buttons: IA_FORWARD / IA_BACKWARD / IA_LEFT / IA_RIGHT move the avatar, and any action can be read by your scene's InputAction listeners. Removing the prop (or the component) releases the binding.

Properties

Property	Type	Description
actions	array of InputAction	The input actions held down while this element is pressed. See Click events for the full list of InputAction values.

Related

• On-screen Controls
• UI Button Events
• Input on mobile
• Click events