PixiUI

Class: Input

Input

Container-based component that creates an input to read the user's text.

The text, caret and selection live in a hidden native <input>, so typing, composition, autocorrect, suggestions and paste work as the platform does them; the component draws what that field holds. It is built in layers: InputView holds the state, background and sizing, InputText creates, measures and lays out the text, InputSelection handles the caret, selection and pointer gestures on the canvas, InputTouch the gestures on the hidden field on touch devices, and this class runs the editing session.

new Input (options) overrides

Creates an input.

Name Type Attributes Default Description
options InputOptions

Options object to use.
options.bg Sprite | Graphics | Texture | string

Background of the Input.
Can be a string (name of texture) or an instance of Texture, Sprite or Graphics.
If you want to use NineSliceSprite, you have to pass a text (name of texture) or an instance of Texture as a parameter.
options.textStyle PixiTextStyle

Text style of the Input.
options.placeholder string

Placeholder of the Input.
options.TextClass PixiTextClass <optional>
 Text

Class used to draw the text and the placeholder, e.g. BitmapText or HTMLText.
options.value string

Value of the Input.
options.maxLength number

Max length of the Input, in UTF-16 code units. Also applied to pasted text and keyboard suggestions, which the native limit does not cover.
options.secure boolean <optional>
 false

Draws each character as * and makes the hidden field type="password". Can be toggled later with Input#secure.
options.align 'left' | 'center' | 'right' <optional>
 'left'

Align of the text, when it fits.
options.padding Padding

Padding of the Input.
options.padding.top number

Top padding of the Input.
options.padding.right number

Right padding of the Input.
options.padding.bottom number

Bottom padding of the Input.
options.padding.left number

Left padding of the Input.
options.cleanOnFocus boolean <optional>
 false

Clear the value each time editing starts.
options.inputAttributes Record<string, string>

Attributes for the hidden native field, merged over the defaults that turn off autocomplete, autocapitalize, autocorrect and spellcheck and tell password managers to ignore the field. Use it for inputmode or enterkeyhint as well.
options.addMask boolean <optional>
 false

Add mask to the Input text, so it is cut off when it does not fit.
options.nineSliceSprite Array

NineSliceSprite values for bg ([left, top, right, bottom]).
!!! IMPORTANT: To make it work, you have to pass a texture name or texture instance as a bg parameter.

Example

new Input({
    bg: Sprite.from('input.png'),
    placeholder: 'Enter text',
    padding: {
     top: 11,
     right: 11,
     bottom: 11,
     left: 11
    } // alternatively you can use [11, 11, 11, 11] or [11, 11] or just 11
});

Extends

  • InputTouch

Members

onChange Signal<(text: string) => void>

Fires every time the user changes the text: typing, deleting, pasting, a keyboard suggestion. Not fired when Input#value is set from code or cleared by cleanOnFocus; during an IME composition that goes over maxLength it waits until the composition is committed and cut.

onEnter Signal<(text: string) => void>

Fires once when editing ends — Enter, Escape, or focus leaving the input (a press elsewhere, Tab, a dismissed keyboard) — with the current value.

composing boolean protected

True while the browser is composing text in the field (IME, or an Android keyboard composing a word).

Default Value:
  • false

tickerUpdate protectedreadonly

Shared ticker callback that drives the caret blink; kept as a field so destroy() can detach it.

Methods

onAnyPointerDown (e) void protected

Any press anywhere on the page forgets the component's own, so a blur that follows a press elsewhere, however quickly, ends the session. The component's pointerdown runs after this and marks the press again when it was on the component.

Name Type Description
e Event

the press, anywhere on the page.

onBlur () void protected

Ends the session when focus genuinely leaves — a click elsewhere, Tab, a dismissed keyboard. A press on the component itself also blurs the hidden field, because the canvas takes focus; that would end and restart editing on every caret move, losing the selection and emitting onEnter, so focus is handed back instead. The press is recognised by time rather than by a held flag: touch browsers move focus on the tap gesture, after the release, and a cancelled pointer never reports a release at all.

onCompositionEnd () void protected

The composed text is committed; apply anything that had to wait for it, such as the maxLength cut.

onInput () protected

Mirrors the hidden native input, which is the only thing that knows what the text actually is. Reconstructing it from keydown cannot work on mobile: on-screen keyboards report Unidentified there and only send the real characters on input, and composition, autocorrect and suggestions have no keydown representation at all.

onKeyDown (e) protected

Handles the keys that control the editing session itself. Text content is handled by Input.onInput, so this deliberately does not insert or delete characters.

Name Type Description
e KeyboardEvent

the native keyboard event.

removeInputField () protected

Detaches and removes the hidden DOM input, if one is currently mounted.

writeToField () void protected

Pushes a programmatic edit into the hidden field, so it does not overwrite the change on the next input.

Inherited Properties

From class InputTouch

activeDragAnchor number | undefined protected inherited

A drag on the hidden field counts once it has moved past the threshold.

clickingField boolean protected inherited

Set around the synthetic click() on focus so it is not mistaken for a tap on the field.

Default Value:
  • false

fieldDragAnchor number | undefined protected inherited

Index a press on the hidden field went down on, while a drag-selection on it is possible.

fieldDragged boolean protected inherited

True once a press on the hidden field has dragged, so the click that ends it is not taken as a tap.

Default Value:
  • false

fieldTakesPointer boolean protected inherited

Whether presses should land on the hidden field itself rather than on the canvas. On touch devices the field has to stay the touch target: its long-press callout is the only paste path on iOS. Taps on it are mapped onto the drawn text by Input.onFieldClick.

From class InputSelection

autoScrollElapsed number protected inherited

Frames since the drag-selection last auto-scrolled.

Default Value:
  • 0

contextSelection [number, number, SelectionDirection] | undefined protected inherited

Selection a right-button press settled on, to put back after the context-menu request collapses it.

dragAnchor number | undefined protected inherited

Index the pointer went down on while editing; set while a drag-selection is in progress.

dragLocalX number | undefined protected inherited

Local x of the pointer during a drag-selection, on the canvas or the hidden field, for auto-scrolling.

lastPressTime protected inherited

performance.now() of the last press, drag or release on the component, so a blur of the hidden field that the press caused can be told apart from focus genuinely leaving.

Default Value:
  • -

pendingSelection [number, number] | undefined protected inherited

Selection to apply once the hidden field exists, set by a pointer press before editing began.

tapCounter protectedreadonly inherited

Multi-click counting; see TapCounter.

From class InputText

isOverflowing boolean protected inherited

Whether the drawn text is wider than the space it has.

metricsCache { key : string, boundaries : number[], widths : number[] } | undefined protected inherited

Prefix widths of the displayed text at each grapheme boundary, measured once per text and style.

scrollX number protected inherited

How far the text is shifted left, in local units, so the caret stays inside the visible width when the text is wider than it. Zero while the text fits or the input is idle.

Default Value:
  • 0

textLeft number protected inherited

Left edge of the drawn text in local coordinates, whatever its anchor.

viewWidth number protected inherited

Width available to the text: the background less the horizontal padding.

From class InputView

bg inherited

Sets the background: a texture name, a Texture, a Sprite or a Graphics. A texture name or Texture becomes a NineSliceSprite when nineSliceSprite is set. The previous background is destroyed.

height inherited

Sets height of a Input. If nineSliceSprite is set, then height will be set to nineSliceSprite. If nineSliceSprite is not set, then height will control components height as Container.

padding inherited

Set paddings

paddingBottom number inherited

Bottom side padding

Default Value:
  • 0

paddingLeft number inherited

Left side padding

Default Value:
  • 0

paddingRight number inherited

Right side padding

Default Value:
  • 0

paddingTop number inherited

Top side padding

Default Value:
  • 0

secure inherited

Masks the drawn text with * and switches the hidden field to type="password". Can be toggled while editing, e.g. for a show/hide password button; the caret and selection are kept.

value inherited

Sets the input text.

width inherited

Sets width of a Input. If nineSliceSprite is set, then width will be set to nineSliceSprite. If nineSliceSprite is not set, then width will control components width as Container.

displayText string protected inherited

What is drawn: the value itself, or one mask character per code unit when secure.

selectionDirection SelectionDirection protected inherited

Which end of the mirrored selection holds the caret.

Default Value:
  • "none"

selectionEnd number protected inherited

End of the mirrored selection; equal to InputView#selectionStart for a plain caret.

Default Value:
  • 0

selectionStart number protected inherited

Mirror of the hidden field's selection, in UTF-16 code units of Input.value. Collapsed (start === end) when there is just a caret.

Default Value:
  • 0

Inherited Methods

From class InputTouch

indexAtClient (clientX, clientY) number protected inherited

The caret index nearest to a point on the hidden field. The field sits at the component's global position, so an offset into it is an offset in global space.

Name Type Description
clientX number

horizontal position in the viewport.
clientY number

vertical position in the viewport.
Returns:
Type Description
number

localXAtClient (clientX, clientY) number protected inherited

The local x of a point on the hidden field; see Input.indexAtClient.

Name Type Description
clientX number

horizontal position in the viewport.
clientY number

vertical position in the viewport.
Returns:
Type Description
number

onFieldClick (e) void protected inherited

A tap on the hidden field placed the native caret by the field's own layout, which never matches the canvas; move it to where the tap landed on the drawn text instead.

Name Type Description
e MouseEvent

the click on the field.

onFieldPointerDown (e) void protected inherited

A press on the hidden field may become a drag-selection; the field's own drag would select nothing on touch devices, or select by its invisible layout.

Name Type Description
e PointerEvent

the press on the field.

onFieldPointerMove (e) void protected inherited

Name Type Description
e PointerEvent

onFieldPointerUp () void protected inherited

From class InputSelection

selectAll () void inherited

Selects the whole value. Only takes effect while the input is being edited.

autoScrollDrag (dt) void protected inherited

Keeps a drag-selection held past an edge of overflowing text moving, one character every few frames, as a native field auto-scrolls; the text follows the focus end.

Name Type Description
dt number

ticker delta, in frames.

clampToView (localX) number protected inherited

Clamps a local x to the visible text area while the text overflows, so a drag past an edge selects up to the edge and auto-scrolls from there, rather than jumping into the hidden text.

Name Type Description
localX number

x in the component's local space.
Returns:
Type Description
number

countTap (e) number protected inherited

Counts taps in a quick sequence at one spot, as a multi-click. Pixi's detail does this per pointer id, and touch browsers issue a new id for every touch, so it stays at 1 there.

Name Type Description
e FederatedPointerEvent

the tap.
Returns:
Type Description
number

countTapAt (x, y, touch) number protected inherited

Counts a tap at a position; see Input.countTap. The canvas path passes global coordinates and the hidden-field path client coordinates, which never mix on one device.

Name Type Default Description
x number

horizontal position of the tap.
y number

vertical position of the tap.
touch boolean false

whether it is a finger, which gets a wider spot and a shorter window.
Returns:
Type Description
number

extendDragTo (anchor, focus) void protected inherited

Sets a drag-selection from its anchor to a focus index, with the direction the drag went.

Name Type Description
anchor number

index the drag started from.
focus number

index the drag is at now.

indexAt (e) number protected inherited

The caret index nearest to a pointer, snapped to grapheme boundaries so a click can never land inside a surrogate pair or combining sequence.

Name Type Description
e FederatedPointerEvent

pointer event in global coordinates.
Returns:
Type Description
number

onContextMenu () void protected inherited

Restores the selection a right-button press settled on. The browser adjusts the document selection as part of showing a context menu, after the press, which collapses the hidden field's selection; it is put back once the menu request has been processed.

onPointerDown (e) void protected inherited

Name Type Description
e FederatedPointerEvent

onPointerMove (e) void protected inherited

Name Type Description
e FederatedPointerEvent

onPointerTap (e, clicks) void protected inherited

Handles a tap during editing: a double click selects a word, a triple click the whole value.

Name Type Description
e FederatedPointerEvent

the tap.
clicks

click count from TapCounter: 2 selects a word, 3 the whole value.

onPointerUp () void protected inherited

selectWordAt (index) void protected inherited

Selects the run of like characters (word, whitespace or punctuation) around an index, as a double click does in a native field.

Name Type Description
index number

position in Input.value to expand from.

setSelection (start, end, direction) void protected inherited

Sets the selection on the hidden field and mirrors it back.

Name Type Default Description
start number

first selected index.
end number

index after the last selected one; equal to start for a plain caret.
direction SelectionDirection 'none'

which end holds the caret, for Shift-extension.

syncSelection () void protected inherited

Copies the hidden field's selection into the component and moves the drawn caret and selection highlight to match. The browser owns caret movement — arrows, Home/End, Shift-selection, word jumps — so this is read back rather than reimplemented.

From class InputText

align () protected inherited

drawSelection () void protected inherited

Redraws the selection highlight behind the selected range, or clears it when collapsed.

getAlign () 0 | 1 | 0.5 protected inherited

Returns:
Type Description
0 | 1 | 0.5

getCursorPosX () protected inherited

X of the drawn caret: the focus end of the selection, measured along the displayed text.

indexAtLocalX (localX) number protected inherited

The caret index nearest to an x in local coordinates, see Input.indexAt.

Name Type Description
localX number

x in the component's local space.
Returns:
Type Description
number

init () protected inherited

measureText (text) number protected inherited

Width of a string in the text field's style. Only ever used as a ratio against the full string, so the unit does not matter — which also keeps bitmap and canvas text on one path.

Name Type Description
text string

string to measure.
Returns:
Type Description
number

offsetAt (index) number protected inherited

Horizontal offset from Input.textLeft to the caret position before index.

Name Type Description
index number

position in the displayed text.
Returns:
Type Description
number

textMetrics () { boundaries : number[], widths : number[] } protected inherited

Widths of every grapheme prefix of the displayed text, in the text's style. Measured once per text and style rather than on every pointer move, which would be quadratic in the length.

Returns:
Type Description
{ boundaries : number[], widths : number[] }

updateScroll () void protected inherited

Shifts overflowing text so the caret stays inside the visible width, scrolling only as far as needed in the caret's direction, as a native field does. Idle text shows its start.

From class InputView

setSize (value, height) void inherited

Name Type Attributes Description
value number | Optional<Size, "height">
height number <optional>

createInputMask (bg) protected inherited

Name Type Description
bg ViewType

updateInputMaskSize () protected inherited