Skip to content

UITextBeforeInputEvent ​

UITextBeforeInputEvent represents one change the user is making to the content of a text input, before the change takes effect.

The beforeinput event of both the single-line UITextField and the multiline UITextView is this class. It says which range the change will replace and with what; when a listener calls preventDefault(), the change isn't made.

Inheritance: Event → UITextBeforeInputEvent

Constructor ​

UITextBeforeInputEvent()

Creates a UITextBeforeInputEvent. The runtime creates one itself when it fires the events below; app code can use it to build an event object and fire it with dispatchEvent() to try out a listener.

Instance properties ​

Also inherits the properties of Event; the most commonly used are type and target. The properties below are read-only; assigning to them throws TypeError.

PropertyDescription
range read-onlyThe range to be replaced
replacementString read-onlyThe text to put in its place

These properties live on the prototype, not on the event object itself: Object.keys(event) and { ...event } don't include them, so read them one by one. See Events with fields.

Events that use this class ​

ObjectEvents
UITextFieldbeforeinput
UITextViewbeforeinput

It can be canceled: cancelable is true, and calling preventDefault() leaves the content unchanged. Listeners run on the spot; the system waits for all of them to finish before deciding whether to make the change.

Examples ​

js
const field = new UITextField();
field.addEventListener('beforeinput', (e) => {
  console.log(e instanceof UITextBeforeInputEvent, e.range.location, e.replacementString);
  const next = field.text.slice(0, e.range.location) + e.replacementString +
    field.text.slice(e.range.location + e.range.length);
  if (next.length > 6) {
    e.preventDefault();
  }
});

Effect: before each edit, prints true, the start of the change, and the replacement text. Changes that would make the content longer than 6 characters don't take effect. Only real keyboard input fires it.

Corresponding iOS API ​

ObjCJS
textField:shouldChangeCharactersInRange:replacementString:beforeinput of UITextField
textView:shouldChangeTextInRange:replacementText:beforeinput of UITextView
The range parameterevent.range
The string or text parameterevent.replacementString
Returning NOCalling event.preventDefault()

See also ​