Skip to main content

Class: UITextInput<TEventMap>

Defined in: src/ui/components/UITextInput.ts:100

A single-line or multiline text field backed by native browser editing.

Extends​

Type Parameters​

TEventMap​

TEventMap extends THREE.Object3DEventMap = THREE.Object3DEventMap

Constructors​

Constructor​

new UITextInput<TEventMap>(__namedParameters): UITextInput<TEventMap>

Defined in: src/ui/components/UITextInput.ts:118

Parameters​

__namedParameters​

UITextInputOptions

Returns​

UITextInput<TEventMap>

Overrides​

UIElement.constructor

Properties​

ariaLabel​

readonly ariaLabel: string

Defined in: src/ui/components/UITextInput.ts:104


isUI​

readonly isUI: true = true

Defined in: src/ui/UIElement.ts:326

Inherited from​

UIElement.isUI


isXRScript​

isXRScript: boolean = true

Defined in: src/core/Script.ts:100

Inherited from​

UIElement.isXRScript


multiline​

readonly multiline: boolean

Defined in: src/ui/components/UITextInput.ts:105


name​

name: string = 'UITextInput'

Defined in: src/ui/components/UITextInput.ts:103

Optional name of the object

Remarks​

(doesn't need to be unique).

Default Value​

""

Overrides​

UIElement.name


onBlur()?​

optional onBlur: () => void

Defined in: src/ui/components/UITextInput.ts:110

Returns​

void


onChange()?​

optional onChange: (value) => void

Defined in: src/ui/components/UITextInput.ts:107

Parameters​

value​

string

Returns​

void


onFocus()?​

optional onFocus: () => void

Defined in: src/ui/components/UITextInput.ts:109

Returns​

void


onInput()?​

optional onInput: (value) => void

Defined in: src/ui/components/UITextInput.ts:106

Parameters​

value​

string

Returns​

void


onSubmit()?​

optional onSubmit: (value) => void

Defined in: src/ui/components/UITextInput.ts:108

Parameters​

value​

string

Returns​

void


xb?​

optional xb: XBObjectOptions

Defined in: src/interaction/InteractionTypes.ts:34

Inherited from​

UIElement.xb

Accessors​

disabled​

Get Signature​

get disabled(): boolean

Defined in: src/ui/components/UITextInput.ts:267

Returns​

boolean

Set Signature​

set disabled(value): void

Defined in: src/ui/components/UITextInput.ts:271

Parameters​
value​

boolean

Returns​

void


error​

Get Signature​

get error(): Error | undefined

Defined in: src/ui/components/UITextInput.ts:208

A module or text-rendering failure reported by the mounted backend.

Returns​

Error | undefined


focused​

Get Signature​

get focused(): boolean

Defined in: src/ui/components/UITextInput.ts:212

Returns​

boolean


maxLength​

Get Signature​

get maxLength(): number | undefined

Defined in: src/ui/components/UITextInput.ts:291

Returns​

number | undefined

Set Signature​

set maxLength(value): void

Defined in: src/ui/components/UITextInput.ts:295

Parameters​
value​

number | undefined

Returns​

void


nativeKeyboardSuppressed​

Get Signature​

get nativeKeyboardSuppressed(): boolean

Defined in: src/ui/components/UITextInput.ts:217

Whether a custom keyboard currently owns software-keyboard suppression.

Returns​

boolean


placeholder​

Get Signature​

get placeholder(): string

Defined in: src/ui/components/UITextInput.ts:255

Returns​

string

Set Signature​

set placeholder(value): void

Defined in: src/ui/components/UITextInput.ts:259

Parameters​
value​

string

Returns​

void


readOnly​

Get Signature​

get readOnly(): boolean

Defined in: src/ui/components/UITextInput.ts:279

Returns​

boolean

Set Signature​

set readOnly(value): void

Defined in: src/ui/components/UITextInput.ts:283

Parameters​
value​

boolean

Returns​

void


ready​

Get Signature​

get ready(): boolean

Defined in: src/ui/components/UITextInput.ts:203

Returns​

boolean


selection​

Get Signature​

get selection(): UITextInputSelection | undefined

Defined in: src/ui/components/UITextInput.ts:315

UTF-16 code unit offsets, matching browser text field indexing.

Returns​

UITextInputSelection | undefined


selectionDirection​

Get Signature​

get selectionDirection(): UITextInputSelectionDirection | undefined

Defined in: src/ui/components/UITextInput.ts:310

Returns​

UITextInputSelectionDirection | undefined


selectionEnd​

Get Signature​

get selectionEnd(): number | undefined

Defined in: src/ui/components/UITextInput.ts:306

Returns​

number | undefined


selectionStart​

Get Signature​

get selectionStart(): number | undefined

Defined in: src/ui/components/UITextInput.ts:302

Returns​

number | undefined


style​

Get Signature​

get style(): UIStyle

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

Returns​

UIStyle

Set Signature​

set style(style): void

Defined in: src/ui/UIElement.ts:380

Parameters​
style​

UIStyle

Returns​

void

Inherited from​

UIElement.style


value​

Get Signature​

get value(): string

Defined in: src/ui/components/UITextInput.ts:239

Returns​

string

Set Signature​

set value(value): void

Defined in: src/ui/components/UITextInput.ts:244

Programmatic assignment never emits onInput and rebases onChange.

Parameters​
value​

string

Returns​

void

Methods​

add()​

add(...objects): this

Defined in: src/ui/UIElement.ts:358

Adds another Object3D as child of this Object3D.

Parameters​

objects​

...Object3D<Object3DEventMap>[]

Returns​

this

Remarks​

An arbitrary number of objects may be added Any current parent on an object passed in here will be removed, since an Object3D can have at most one parent.

See​

  • attach
  • THREE.Group | Group for info on manually grouping objects.

Inherited from​

UIElement.add


attach()​

attach(object): this

Defined in: src/ui/UIElement.ts:364

Adds a Object3D as a child of this, while maintaining the object's world transform.

Parameters​

object​

Object3D

Returns​

this

Remarks​

Note: This method does not support scene graphs having non-uniformly-scaled nodes(s).

See​

add

Inherited from​

UIElement.attach


blur()​

blur(): void

Defined in: src/ui/components/UITextInput.ts:345

Returns​

void


dispose()​

dispose(): void

Defined in: src/core/Script.ts:270

Called when the script is removed from the scene. Opposite of init.

Returns​

void

Inherited from​

UIElement.dispose


focus()​

focus(): void

Defined in: src/ui/components/UITextInput.ts:339

Returns​

void


getWorldPosition()​

getWorldPosition(target): Vector3

Defined in: src/ui/UIElement.ts:369

Returns a vector representing the position of the object in world space.

Parameters​

target​

Vector3

The result will be copied into this Vector3.

Returns​

Vector3

Inherited from​

UIElement.getWorldPosition


init()​

init(_?): void | Promise<void>

Defined in: src/core/Script.ts:109

Initializes an instance with XR controllers, grips, hands, and default options. We allow all scripts to quickly access its user (e.g., user.isSelecting(), user.hands), world (e.g., physical depth mesh, lighting estimation, and recognized objects), and scene (the root of three.js's scene graph). If this returns a promise, we will wait for it.

Parameters​

_?​

object

Returns​

void | Promise<void>

Inherited from​

UIElement.init


initPhysics()​

initPhysics(_physics): void | Promise<void>

Defined in: src/core/Script.ts:119

Enables depth-aware interactions with physics. See /samples/advanced/ballpit

Parameters​

_physics​

Physics

Returns​

void | Promise<void>

Inherited from​

UIElement.initPhysics


insertText()​

insertText(text): void

Defined in: src/ui/components/UITextInput.ts:350

Replaces the current selection, honoring maxLength like typed input.

Parameters​

text​

string

Returns​

void


markUIContentDirty()​

protected markUIContentDirty(): void

Defined in: src/ui/UIElement.ts:396

Marks durable content for the next renderer commit.

Returns​

void

Inherited from​

UIElement.markUIContentDirty


markUIDirty()​

protected markUIDirty(): void

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

Returns​

void

Inherited from​

UIElement.markUIDirty


markUIStructureDirty()​

protected markUIStructureDirty(): void

Defined in: src/ui/UIElement.ts:400

Returns​

void

Inherited from​

UIElement.markUIStructureDirty


onHoverEnter()​

onHoverEnter(_event): void

Defined in: src/core/Script.ts:222

Called when a source starts hovering over this object.

Parameters​

_event​

HoverEvent

The hover source, target, surface, and intersection. Call event.stopPropagation() to stop bubbling to ancestor Scripts.

Returns​

void

Inherited from​

UIElement.onHoverEnter


onHoverExit()​

onHoverExit(_event): void

Defined in: src/core/Script.ts:228

Called when a source stops hovering over this object.

Parameters​

_event​

HoverEvent

The hover source, target, surface, and intersection. Call event.stopPropagation() to stop bubbling to ancestor Scripts.

Returns​

void

Inherited from​

UIElement.onHoverExit


onHovering()​

onHovering(_event): void

Defined in: src/core/Script.ts:234

Called while a source hovers over this object.

Parameters​

_event​

HoverEvent

The hover source, target, surface, and intersection. Call event.stopPropagation() to stop bubbling to ancestor Scripts.

Returns​

void

Inherited from​

UIElement.onHovering


onKeyDown()​

onKeyDown(_event): void

Defined in: src/core/Script.ts:159

Called on keyboard keypress.

Parameters​

_event​

KeyEvent

Event containing .code to read the keyboard key.

Returns​

void

Inherited from​

UIElement.onKeyDown


onKeyUp()​

onKeyUp(_event): void

Defined in: src/core/Script.ts:160

Parameters​

_event​

KeyEvent

Returns​

void

Inherited from​

UIElement.onKeyUp


onLongSelect()​

onLongSelect(_event): void

Defined in: src/core/Script.ts:153

Called when an object selection reaches the long-select delay.

Parameters​

_event​

LongSelectEvent

Returns​

void

Inherited from​

UIElement.onLongSelect


onObjectGrabbing()​

onObjectGrabbing(_event): void

Defined in: src/core/Script.ts:260

Called every frame a hand is grabbing this object.

Parameters​

_event​

ObjectGrabEvent

Returns​

void

Inherited from​

UIElement.onObjectGrabbing


onObjectGrabEnd()​

onObjectGrabEnd(_event): void

Defined in: src/core/Script.ts:265

Called when a hand stops grabbing this object. This ends built-in direct-touch manipulation without ending contact.

Parameters​

_event​

ObjectGrabEvent

Returns​

void

Inherited from​

UIElement.onObjectGrabEnd


onObjectGrabStart()​

onObjectGrabStart(_event): void

Defined in: src/core/Script.ts:256

Called when a hand starts grabbing this object (touching + pinching). A grab starts built-in direct-touch manipulation when enabled.

Parameters​

_event​

ObjectGrabEvent

Returns​

void

Inherited from​

UIElement.onObjectGrabStart


onObjectLongSelect()​

onObjectLongSelect(_event): void

Defined in: src/core/Script.ts:210

Called once when a captured selection is held for the long-select delay. Manipulation captures do not emit this callback.

Parameters​

_event​

LongSelectEvent

The controller and completed hold duration. Call event.stopPropagation() to stop bubbling to ancestor Scripts. Call event.stopGlobalPropagation() to suppress global selection callbacks for the rest of this capture

Returns​

void

Inherited from​

UIElement.onObjectLongSelect


onObjectManipulate()​

onObjectManipulate(_event): void

Defined in: src/core/Script.ts:216

Called for each phase of an automatic object manipulation. Call event.stopPropagation() to stop bubbling. Calling preventDefault() on a start event suppresses the automatic action.

Parameters​

_event​

ManipulationEvent

Returns​

void

Inherited from​

UIElement.onObjectManipulate


onObjectSelectEnd()​

onObjectSelectEnd(event): void

Defined in: src/ui/components/UITextInput.ts:198

Called when a source stops selecting the object this Script represents.

Parameters​

event​

SelectEvent

Returns​

void

Overrides​

UIElement.onObjectSelectEnd


onObjectSelectStart()​

onObjectSelectStart(event): void

Defined in: src/ui/components/UITextInput.ts:193

Whether a mounted backend can currently accept editing operations.

Parameters​

event​

SelectEvent

Returns​

void

Overrides​

UIElement.onObjectSelectStart


onObjectTouchEnd()​

onObjectTouchEnd(_event): void

Defined in: src/core/Script.ts:251

Called when a hand's index finger stops touching this object. This ends the default selection lifecycle after the touch callback.

Parameters​

_event​

ObjectTouchEvent

Returns​

void

Inherited from​

UIElement.onObjectTouchEnd


onObjectTouching()​

onObjectTouching(_event): void

Defined in: src/core/Script.ts:246

Called every frame that a hand's index finger is touching this object. The object remains selected during these frames unless touch selection was prevented when contact started.

Parameters​

_event​

ObjectTouchEvent

Returns​

void

Inherited from​

UIElement.onObjectTouching


onObjectTouchStart()​

onObjectTouchStart(_event): void

Defined in: src/core/Script.ts:240

Called when a hand's index finger starts touching this object. Direct touch starts the object's selection lifecycle by default. Call event.preventDefault() to handle contact without selecting.

Parameters​

_event​

ObjectTouchStartEvent

Returns​

void

Inherited from​

UIElement.onObjectTouchStart


onSelect()​

onSelect(_event): void

Defined in: src/core/Script.ts:145

Called whenever pinch / mouse click successfully completes, globally.

Parameters​

_event​

SelectEvent

The interaction source and completed target.

Returns​

void

Inherited from​

UIElement.onSelect


onSelectEnd()​

onSelectEnd(_event): void

Defined in: src/core/Script.ts:139

Called whenever pinch / mouse click discontinues, globally.

Parameters​

_event​

SelectEndEvent

The completed state and end reason.

Returns​

void

Inherited from​

UIElement.onSelectEnd


onSelecting()​

onSelecting(_event): void

Defined in: src/core/Script.ts:150

Called whenever pinch / mouse click is happening, globally.

Parameters​

_event​

SelectEvent

Returns​

void

Inherited from​

UIElement.onSelecting


onSelectStart()​

onSelectStart(_event): void

Defined in: src/core/Script.ts:133

Called whenever pinch / mouse click starts, globally.

Parameters​

_event​

SelectEvent

The interaction source and optional captured target.

Returns​

void

Inherited from​

UIElement.onSelectStart


onSimulatorStarted()​

onSimulatorStarted(): void

Defined in: src/core/Script.ts:125

Returns​

void

Inherited from​

UIElement.onSimulatorStarted


onSqueeze()​

onSqueeze(_event): void

Defined in: src/core/Script.ts:182

Called whenever gamepad trigger successfully completes, globally.

Parameters​

_event​

SelectEvent

event.source.controller identifies the controller.

Returns​

void

Inherited from​

UIElement.onSqueeze


onSqueezeEnd()​

onSqueezeEnd(_event): void

Defined in: src/core/Script.ts:171

Called whenever gamepad trigger stops, globally.

Parameters​

_event​

SelectEvent

event.source.controller identifies the controller.

Returns​

void

Inherited from​

UIElement.onSqueezeEnd


onSqueezeStart()​

onSqueezeStart(_event): void

Defined in: src/core/Script.ts:166

Called whenever gamepad trigger starts, globally.

Parameters​

_event​

SelectEvent

event.source.controller identifies the controller.

Returns​

void

Inherited from​

UIElement.onSqueezeStart


onSqueezing()​

onSqueezing(_event): void

Defined in: src/core/Script.ts:176

Called whenever gamepad is being triggered, globally.

Parameters​

_event​

SelectEvent

Returns​

void

Inherited from​

UIElement.onSqueezing


onXRSessionEnded()​

onXRSessionEnded(): void

Defined in: src/core/Script.ts:123

Returns​

void

Inherited from​

UIElement.onXRSessionEnded


onXRSessionStarted()​

onXRSessionStarted(_session?): void

Defined in: src/core/Script.ts:122

Parameters​

_session?​

XRSession

Returns​

void

Inherited from​

UIElement.onXRSessionStarted


physicsStep()​

physicsStep(): void

Defined in: src/core/Script.ts:120

Returns​

void

Inherited from​

UIElement.physicsStep


pressKey()​

pressKey(key, modifiers?): boolean

Defined in: src/ui/components/UITextInput.ts:363

Applies one KeyboardEvent.key name from a virtual keyboard or automation.

Returns whether the key was applied. Physical keyboards and IME go through the native element instead of this narrow path.

Parameters​

key​

string

modifiers?​

UITextInputKeyModifiers

Returns​

boolean


setSelectionRange()​

setSelectionRange(start, end, direction): void

Defined in: src/ui/components/UITextInput.ts:319

Parameters​

start​

number

end​

number

direction​

UITextInputSelectionDirection = 'none'

Returns​

void


suppressNativeKeyboard()​

suppressNativeKeyboard(): () => void

Defined in: src/ui/components/UITextInput.ts:226

Requests that the browser's software keyboard stay hidden while a custom keyboard is active. Call the returned function to release this request. Native text editing remains enabled; support depends on the browser.

Returns​

(): void

Returns​

void


update()​

update(_time?, _frame?): void

Defined in: src/core/Script.ts:114

Runs per frame.

Parameters​

_time?​

number

_frame?​

XRFrame

Returns​

void

Inherited from​

UIElement.update