ionChange will only emit from user committed changes

[sean-perkins]

Summary

Depending on the kind of element being changed and the way the user interacts with the element, the ionChange event should fire at a different moment:

• When a ion-checkbox or ion-radio element is checked or unchecked (by clicking or using the keyboard);
• When the user commits the change explicitly (e.g., by selecting a value from an ion-select dropdown with a mouse click, by selecting a date from the ion-datetime, etc.);
• When the element loses focus after its value was changed, but not committed (e.g. after editing the value of ion-textarea or ion-input).

The ionChange event should not fire as a result of external value changes (e.g.: manually assigning a value).

Motivation

Ionic Framework has had this API design for ionChange for quite some time. As a result, there have been a number of issues over the years and frustrations from developers; such as:

1. ionChange is emitted multiple times from a single (external) change event
2. Developers cannot determine if the ionChange was a result of the user interacting with the control or their app setting the value on the control.
3. ionChange is emitted at un-expected times, such as resetting the state of a form.

This pattern is also inconsistent with HTML form elements, such as input, textarea and select.

Related Issues:

• bug: changing value of component in ionChange results in an infinite loop #20106
• bug: React IonRange gets into infinite render loop #21101
• bug: ion-datetime triggers ionChange on load #20873
• bug: The ionChange event of ion-input is triggered the second time the page is entered #20061
• feat: ionChange event: determine whether it by user interaction #19651

Proposed Design

There will be no change to the public API for ionChange, while the behavior for when ionChange is fired will change.

The ionChange event for each component will align to their equivalent HTML element, if available. Custom components without an equivalent, will fire ionChange when the user commits the change explicitly. This will align the behavior of ionChange with the change event: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event

Internally, the Ionic team will move away from this pattern:

@Watch('value')
handleValueChange() {
  this.ionChange.emit({ value: this.value });
}

This approach of listening for any internal/external change to value, is the root cause of this architectural issue.

The following components will be affected:

• ion-accordion-group
• ion-checkbox (with the checked property)
• ion-datetime
• ion-input
• ion-radio-group
• ion-range
• ion-searchbar
• ion-segment
• ion-select
• ion-textarea
• ion-toggle

Usage

With the following example:

@Component({
  selector: 'my-component',
  template: `<ion-input [value]="myValue" (ionChange)="onChange($event)"></ion-input>`
})
export class MyComponent {
  myValue: string;

  ngOnInit() {
    this.myValue = 'Hello world';
  }

  onChange(ev) {
    this.myValue = ev.detail.value;
  }
}

• ionChange is fired when the user types within the ion-input and the control is blurred.
• ionChange will not fire when myValue is set to “Hello world”

Benefits

1. Aligns the form control web components of Ionic Framework with the change event pattern that developers expect from existing form elements (e.g. input, textarea).
2. ionChange will only be emitted as a result of committed value changes to the control. This provides developers a consistent API to respond to user interaction vs. setting the state of a form control.
3. Decouples the API between change and input, allowing Ionic to explore features such as input masking.

Drawbacks

Since this pattern has existed in Ionic Framework for awhile, it is expected that developers have either written applications that have dependency on this pattern or have written custom code within their ionChange event handlers, that uses comparisons to try and determine if the change is a result of user interaction. As a result, developers would need to audit their implementations after this change, to make sure that their applications continue to behave consistently or refactor them accordingly.

Alternatives

Comparing Previous Value

Developers have been able to work around this pattern by comparing the previous value against the new value before handling the interaction.

myValue: string;

onChange(ev) {
  if (this.myValue === ev.detail.value) {
    // The previous value matches the current value,
    // this is likely emitted as a result of manually setting the value
    return;
  }
  this.myValue = ev.detail.value;
  // TODO handle/save the new value
}

The downsides of this implementation pattern is that it requires a lot of boilerplate in each ionChange event handler. It also is difficult to discern between if the change event is from the initial value being set on the control or from the user changing the value for the first time.

Skip First Emission

Developers may also have been able to work around this issue by ignoring the first emission of ionChange, as it is likely a result of the value being set.

myValue: string;
hasEmittedValue = false;

loadData() {
  this.myValue = 'API Response Data';
}

onChange(ev) {
  if (this.hasEmittedValue === false) {
    // Skip the first emission, as it is from setting `this.myValue`
    // after we load some API data.
    this.hasEmittedValue = true;
    return;
  }
  // TODO handle/save the new value
}

This approach has many downsides. If the user was to interact with the control before the API response has been resolved, the interaction would be skipped. It also assumes that only a single interaction will manually set this.myValue.

Using ionInput event

Developers can use the ionInput on the components that support the event API, to only subscribe to changes when the user types.

<ion-input (ionInput)="onChange($event)"></ion-input>

While this API suffices for ion-input, it is not available for all Ionic form controls, such as ion-datetime, ion-range and ion-select.

Breaking Changes

Listening for changes while focused (input, textarea)

Developers using the ionChange event to listen for immediate value changes as the user types for ion-input or ion-textarea, should migrate their implementations to use the ionInput event.

Before

<ion-input (ionChange)="onChange($event)"></ion-input>

After

<ion-input (ionInput)="onChange($event)"></ion-input>

Developers can continue to use ionChange to listen for when the value is committed to the input. This happens when the control loses focus.

debounce property

The debounce property on ion-input, ion-textarea and ion-searchbar controls the time in milliseconds to wait to trigger ionChange after each keystroke. This behavior is invalid now that ionChange emits on blur.

This behavior will be migrated to apply to the ionInput event instead. Developers using debounce on ion-input, ion-textarea or ion-searchbar will delay the emission of the ionInput event after each keystroke.

[babycourageous]

Thanks so much @sean-perkins for this awesome RFC!

[ghost]

You are awesome and an inspiration of mine sir ☺️

[below43]

This sounds awesome thanks 😊

[maxt3r]

This is a great suggestion. It is very weird that a basic use case like loading data for ion-select from an external API required workarounds to only watch for the changes you actually need.

[Saqib92]

what if user autofill their FORMS from password managers or anything like that? there should be an option to enable / disable for ionChange to trigger!

[sean-perkins]

Browsers such as Chrome will not emit a change event until user interaction occurs. Since auto-fill is not from user interaction, the change event is not emitted until the user interacts with the control. The same behavior would apply here. If developers need to respond to the behavior of autofill, they would use the input/ionInput event, similar to how they would for built-in controls such as input or textarea.

[sean-perkins]

Hello everyone, thank you so much for expressing your feedback surrounding this RFC. We will be moving forward with this change to form controls in an upcoming major release of Ionic Framework.