docs(core): ionChange will not emit from programmatically changing value (#29407)

Issue number: resolves
ionic-team/ionic-docs#3588

---------

<!-- Please do not submit updates to dependencies unless it fixes an
issue. -->

<!-- Please try to limit your pull request to one type (bugfix, feature,
etc). Submit multiple pull requests if needed. -->

## What is the current behavior?
<!-- Please describe the current behavior that you are modifying. -->

The documentation around `ionChange` not being emitted when
programmatically changing the property associated to the "value" is
either inconsistent or missing from certain components.

## What is the new behavior?
<!-- Please describe the behavior or changes that are being added by
this PR. -->

- Adds the documentation to the missing components.
- Makes the documentation consistent across components.

## Does this introduce a breaking change?

- [ ] Yes
- [x] No

<!--
  If this introduces a breaking change:
1. Describe the impact and migration path for existing applications
below.
  2. Update the BREAKING.md file with the breaking change.
3. Add "BREAKING CHANGE: [...]" to the commit description when merging.
See
https://github.com/ionic-team/ionic-framework/blob/main/docs/CONTRIBUTING.md#footer
for more information.
-->


## Other information

<!-- Any other information that is important to this PR such as
screenshots of how the component looks before and after the change. -->

Author: sean-perkins

core/src/components.d.ts

@@ -4770,7 +4770,7 @@ declare namespace LocalJSX {
          */
         "multiple"?: boolean;
         /**
-          * Emitted when the value property has changed as a result of a user action such as a click. This event will not emit when programmatically setting the value property.
+          * Emitted when the value property has changed as a result of a user action such as a click.  This event will not emit when programmatically setting the `value` property.
          */
         "onIonChange"?: (event: IonAccordionGroupCustomEvent<AccordionGroupChangeEventDetail>) => void;
         /**
@@ -5345,7 +5345,7 @@ declare namespace LocalJSX {
          */
         "onIonBlur"?: (event: IonCheckboxCustomEvent<void>) => void;
         /**
-          * Emitted when the checked property has changed as a result of a user action such as a click. This event will not emit when programmatically setting the checked property.
+          * Emitted when the checked property has changed as a result of a user action such as a click.  This event will not emit when programmatically setting the `checked` property.
          */
         "onIonChange"?: (event: IonCheckboxCustomEvent<CheckboxChangeEventDetail>) => void;
         /**
@@ -5601,7 +5601,7 @@ declare namespace LocalJSX {
          */
         "onIonCancel"?: (event: IonDatetimeCustomEvent<void>) => void;
         /**
-          * Emitted when the value (selected date) has changed.
+          * Emitted when the value (selected date) has changed.  This event will not emit when programmatically setting the `value` property.
          */
         "onIonChange"?: (event: IonDatetimeCustomEvent<DatetimeChangeEventDetail>) => void;
         /**
@@ -5971,7 +5971,7 @@ declare namespace LocalJSX {
          */
         "onIonBlur"?: (event: IonInputCustomEvent<FocusEvent>) => void;
         /**
-          * The `ionChange` event is fired when the user modifies the input's value. Unlike the `ionInput` event, the `ionChange` event is only fired when changes are committed, not as the user types.  Depending on the way the users interacts with the element, the `ionChange` event fires at a different moment: - When the user commits the change explicitly (e.g. by selecting a date from a date picker for `<ion-input type="date">`, pressing the "Enter" key, etc.). - When the element loses focus after its value has changed: for elements where the user's interaction is typing.
+          * The `ionChange` event is fired when the user modifies the input's value. Unlike the `ionInput` event, the `ionChange` event is only fired when changes are committed, not as the user types.  Depending on the way the users interacts with the element, the `ionChange` event fires at a different moment: - When the user commits the change explicitly (e.g. by selecting a date from a date picker for `<ion-input type="date">`, pressing the "Enter" key, etc.). - When the element loses focus after its value has changed: for elements where the user's interaction is typing.  This event will not emit when programmatically setting the `value` property.
          */
         "onIonChange"?: (event: IonInputCustomEvent<InputChangeEventDetail>) => void;
         /**
@@ -6620,7 +6620,7 @@ declare namespace LocalJSX {
          */
         "numericInput"?: boolean;
         /**
-          * Emitted when the value has changed.
+          * Emitted when the value has changed.  This event will not emit when programmatically setting the `value` property.
          */
         "onIonChange"?: (event: IonPickerColumnCustomEvent<PickerColumnChangeEventDetail>) => void;
         /**
@@ -6961,7 +6961,7 @@ declare namespace LocalJSX {
          */
         "name"?: string;
         /**
-          * Emitted when the value has changed.
+          * Emitted when the value has changed.  This event will not emit when programmatically setting the `value` property.
          */
         "onIonChange"?: (event: IonRadioGroupCustomEvent<RadioGroupChangeEventDetail>) => void;
         /**
@@ -7023,7 +7023,7 @@ declare namespace LocalJSX {
          */
         "onIonBlur"?: (event: IonRangeCustomEvent<void>) => void;
         /**
-          * The `ionChange` event is fired for `<ion-range>` elements when the user modifies the element's value: - When the user releases the knob after dragging; - When the user moves the knob with keyboard arrows  `ionChange` is not fired when the value is changed programmatically.
+          * The `ionChange` event is fired for `<ion-range>` elements when the user modifies the element's value: - When the user releases the knob after dragging; - When the user moves the knob with keyboard arrows  This event will not emit when programmatically setting the `value` property.
          */
         "onIonChange"?: (event: IonRangeCustomEvent<RangeChangeEventDetail>) => void;
         /**
@@ -7324,7 +7324,7 @@ declare namespace LocalJSX {
          */
         "onIonCancel"?: (event: IonSearchbarCustomEvent<void>) => void;
         /**
-          * The `ionChange` event is fired for `<ion-searchbar>` elements when the user modifies the element's value. Unlike the `ionInput` event, the `ionChange` event is not necessarily fired for each alteration to an element's value.  The `ionChange` event is fired when the value has been committed by the user. This can happen when the element loses focus or when the "Enter" key is pressed. `ionChange` can also fire when clicking the clear or cancel buttons.
+          * The `ionChange` event is fired for `<ion-searchbar>` elements when the user modifies the element's value. Unlike the `ionInput` event, the `ionChange` event is not necessarily fired for each alteration to an element's value.  The `ionChange` event is fired when the value has been committed by the user. This can happen when the element loses focus or when the "Enter" key is pressed. `ionChange` can also fire when clicking the clear or cancel buttons.  This event will not emit when programmatically setting the `value` property.
          */
         "onIonChange"?: (event: IonSearchbarCustomEvent<SearchbarChangeEventDetail>) => void;
         /**
@@ -7386,7 +7386,7 @@ declare namespace LocalJSX {
          */
         "mode"?: "ios" | "md";
         /**
-          * Emitted when the value property has changed and any dragging pointer has been released from `ion-segment`.
+          * Emitted when the value property has changed and any dragging pointer has been released from `ion-segment`.  This event will not emit when programmatically setting the `value` property.
          */
         "onIonChange"?: (event: IonSegmentCustomEvent<SegmentChangeEventDetail>) => void;
         /**
@@ -7506,7 +7506,7 @@ declare namespace LocalJSX {
          */
         "onIonCancel"?: (event: IonSelectCustomEvent<void>) => void;
         /**
-          * Emitted when the value has changed.
+          * Emitted when the value has changed.  This event will not emit when programmatically setting the `value` property.
          */
         "onIonChange"?: (event: IonSelectCustomEvent<SelectChangeEventDetail>) => void;
         /**
@@ -7809,7 +7809,7 @@ declare namespace LocalJSX {
          */
         "onIonBlur"?: (event: IonTextareaCustomEvent<FocusEvent>) => void;
         /**
-          * The `ionChange` event is fired when the user modifies the textarea's value. Unlike the `ionInput` event, the `ionChange` event is fired when the element loses focus after its value has been modified.
+          * The `ionChange` event is fired when the user modifies the textarea's value. Unlike the `ionInput` event, the `ionChange` event is fired when the element loses focus after its value has been modified.  This event will not emit when programmatically setting the `value` property.
          */
         "onIonChange"?: (event: IonTextareaCustomEvent<TextareaChangeEventDetail>) => void;
         /**
@@ -8028,7 +8028,7 @@ declare namespace LocalJSX {
          */
         "onIonBlur"?: (event: IonToggleCustomEvent<void>) => void;
         /**
-          * Emitted when the user switches the toggle on or off. Does not emit when programmatically changing the value of the `checked` property.
+          * Emitted when the user switches the toggle on or off.  This event will not emit when programmatically setting the `checked` property.
          */
         "onIonChange"?: (event: IonToggleCustomEvent<ToggleChangeEventDetail>) => void;
         /**

core/src/components/accordion-group/accordion-group.tsx

@@ -59,10 +59,9 @@ export class AccordionGroup implements ComponentInterface {
   @Prop() expand: 'compact' | 'inset' = 'compact';
 
   /**
-   * Emitted when the value property has changed
-   * as a result of a user action such as a click.
-   * This event will not emit when programmatically setting
-   * the value property.
+   * Emitted when the value property has changed as a result of a user action such as a click.
+   *
+   * This event will not emit when programmatically setting the `value` property.
    */
   @Event() ionChange!: EventEmitter<AccordionGroupChangeEventDetail>;
 

core/src/components/checkbox/checkbox.tsx

@@ -97,10 +97,9 @@ export class Checkbox implements ComponentInterface {
   @Prop() alignment: 'start' | 'center' = 'center';
 
   /**
-   * Emitted when the checked property has changed
-   * as a result of a user action such as a click.
-   * This event will not emit when programmatically
-   * setting the checked property.
+   * Emitted when the checked property has changed as a result of a user action such as a click.
+   *
+   * This event will not emit when programmatically setting the `checked` property.
    */
   @Event() ionChange!: EventEmitter<CheckboxChangeEventDetail>;
 

core/src/components/datetime/datetime.tsx

@@ -477,6 +477,8 @@ export class Datetime implements ComponentInterface {
 
   /**
    * Emitted when the value (selected date) has changed.
+   *
+   * This event will not emit when programmatically setting the `value` property.
    */
   @Event() ionChange!: EventEmitter<DatetimeChangeEventDetail>;
 

core/src/components/input/input.tsx

@@ -296,6 +296,8 @@ export class Input implements ComponentInterface {
    * from a date picker for `<ion-input type="date">`, pressing the "Enter" key, etc.).
    * - When the element loses focus after its value has changed: for elements
    * where the user's interaction is typing.
+   *
+   * This event will not emit when programmatically setting the `value` property.
    */
   @Event() ionChange!: EventEmitter<InputChangeEventDetail>;
 

core/src/components/picker-column/picker-column.tsx

@@ -66,6 +66,8 @@ export class PickerColumn implements ComponentInterface {
 
   /**
    * Emitted when the value has changed.
+   *
+   * This event will not emit when programmatically setting the `value` property.
    */
   @Event() ionChange!: EventEmitter<PickerColumnChangeEventDetail>;
 

core/src/components/radio-group/radio-group.tsx

@@ -47,6 +47,8 @@ export class RadioGroup implements ComponentInterface {
 
   /**
    * Emitted when the value has changed.
+   *
+   * This event will not emit when programmatically setting the `value` property.
    */
   @Event() ionChange!: EventEmitter<RadioGroupChangeEventDetail>;
 

core/src/components/range/range.tsx

@@ -235,7 +235,7 @@ export class Range implements ComponentInterface {
    * - When the user releases the knob after dragging;
    * - When the user moves the knob with keyboard arrows
    *
-   * `ionChange` is not fired when the value is changed programmatically.
+   * This event will not emit when programmatically setting the `value` property.
    */
   @Event() ionChange!: EventEmitter<RangeChangeEventDetail>;
 

core/src/components/searchbar/searchbar.tsx

@@ -225,6 +225,8 @@ export class Searchbar implements ComponentInterface {
    * by the user. This can happen when the element loses focus or
    * when the "Enter" key is pressed. `ionChange` can also fire
    * when clicking the clear or cancel buttons.
+   *
+   * This event will not emit when programmatically setting the `value` property.
    */
   @Event() ionChange!: EventEmitter<SearchbarChangeEventDetail>;
 

core/src/components/segment/segment.tsx

@@ -94,8 +94,9 @@ export class Segment implements ComponentInterface {
   @Prop() selectOnFocus = false;
 
   /**
-   * Emitted when the value property has changed and any
-   * dragging pointer has been released from `ion-segment`.
+   * Emitted when the value property has changed and any dragging pointer has been released from `ion-segment`.
+   *
+   * This event will not emit when programmatically setting the `value` property.
    */
   @Event() ionChange!: EventEmitter<SegmentChangeEventDetail>;
 

core/src/components/select/select.tsx

@@ -197,6 +197,8 @@ export class Select implements ComponentInterface {
 
   /**
    * Emitted when the value has changed.
+   *
+   * This event will not emit when programmatically setting the `value` property.
    */
   @Event() ionChange!: EventEmitter<SelectChangeEventDetail>;
 

core/src/components/textarea/textarea.tsx

@@ -263,6 +263,8 @@ export class Textarea implements ComponentInterface {
    * The `ionChange` event is fired when the user modifies the textarea's value.
    * Unlike the `ionInput` event, the `ionChange` event is fired when
    * the element loses focus after its value has been modified.
+   *
+   * This event will not emit when programmatically setting the `value` property.
    */
   @Event() ionChange!: EventEmitter<TextareaChangeEventDetail>;
 

core/src/components/toggle/toggle.tsx

@@ -107,8 +107,9 @@ export class Toggle implements ComponentInterface {
   @Prop() alignment: 'start' | 'center' = 'center';
 
   /**
-   * Emitted when the user switches the toggle on or off. Does not emit
-   * when programmatically changing the value of the `checked` property.
+   * Emitted when the user switches the toggle on or off.
+   *
+   * This event will not emit when programmatically setting the `checked` property.
    */
   @Event() ionChange!: EventEmitter<ToggleChangeEventDetail>;
 

packages/angular/src/directives/proxies.ts

@@ -53,10 +53,9 @@ import type { AccordionGroupChangeEventDetail as IIonAccordionGroupAccordionGrou
 
 export declare interface IonAccordionGroup extends Components.IonAccordionGroup {
   /**
-   * Emitted when the value property has changed
-as a result of a user action such as a click.
-This event will not emit when programmatically setting
-the value property.
+   * Emitted when the value property has changed as a result of a user action such as a click.
+
+This event will not emit when programmatically setting the `value` property.
    */
   ionChange: EventEmitter<CustomEvent<IIonAccordionGroupAccordionGroupChangeEventDetail>>;
 }
@@ -530,10 +529,9 @@ import type { CheckboxChangeEventDetail as IIonCheckboxCheckboxChangeEventDetail
 
 export declare interface IonCheckbox extends Components.IonCheckbox {
   /**
-   * Emitted when the checked property has changed
-as a result of a user action such as a click.
-This event will not emit when programmatically
-setting the checked property.
+   * Emitted when the checked property has changed as a result of a user action such as a click.
+
+This event will not emit when programmatically setting the `checked` property.
    */
   ionChange: EventEmitter<CustomEvent<IIonCheckboxCheckboxChangeEventDetail>>;
   /**
@@ -664,6 +662,8 @@ export declare interface IonDatetime extends Components.IonDatetime {
   ionCancel: EventEmitter<CustomEvent<void>>;
   /**
    * Emitted when the value (selected date) has changed.
+
+This event will not emit when programmatically setting the `value` property.
    */
   ionChange: EventEmitter<CustomEvent<IIonDatetimeDatetimeChangeEventDetail>>;
   /**
@@ -1001,6 +1001,8 @@ event fires at a different moment:
 from a date picker for `<ion-input type="date">`, pressing the "Enter" key, etc.).
 - When the element loses focus after its value has changed: for elements
 where the user's interaction is typing.
+
+This event will not emit when programmatically setting the `value` property.
    */
   ionChange: EventEmitter<CustomEvent<IIonInputInputChangeEventDetail>>;
   /**
@@ -1487,6 +1489,8 @@ import type { PickerColumnChangeEventDetail as IIonPickerColumnPickerColumnChang
 export declare interface IonPickerColumn extends Components.IonPickerColumn {
   /**
    * Emitted when the value has changed.
+
+This event will not emit when programmatically setting the `value` property.
    */
   ionChange: EventEmitter<CustomEvent<IIonPickerColumnPickerColumnChangeEventDetail>>;
 }
@@ -1656,6 +1660,8 @@ import type { RadioGroupChangeEventDetail as IIonRadioGroupRadioGroupChangeEvent
 export declare interface IonRadioGroup extends Components.IonRadioGroup {
   /**
    * Emitted when the value has changed.
+
+This event will not emit when programmatically setting the `value` property.
    */
   ionChange: EventEmitter<CustomEvent<IIonRadioGroupRadioGroupChangeEventDetail>>;
 }
@@ -1692,7 +1698,7 @@ modifies the element's value:
 - When the user releases the knob after dragging;
 - When the user moves the knob with keyboard arrows
 
-`ionChange` is not fired when the value is changed programmatically.
+This event will not emit when programmatically setting the `value` property.
    */
   ionChange: EventEmitter<CustomEvent<IIonRangeRangeChangeEventDetail>>;
   /**
@@ -1922,6 +1928,8 @@ The `ionChange` event is fired when the value has been committed
 by the user. This can happen when the element loses focus or
 when the "Enter" key is pressed. `ionChange` can also fire
 when clicking the clear or cancel buttons.
+
+This event will not emit when programmatically setting the `value` property.
    */
   ionChange: EventEmitter<CustomEvent<IIonSearchbarSearchbarChangeEventDetail>>;
   /**
@@ -1967,8 +1975,9 @@ import type { SegmentChangeEventDetail as IIonSegmentSegmentChangeEventDetail }
 
 export declare interface IonSegment extends Components.IonSegment {
   /**
-   * Emitted when the value property has changed and any
-dragging pointer has been released from `ion-segment`.
+   * Emitted when the value property has changed and any dragging pointer has been released from `ion-segment`.
+
+This event will not emit when programmatically setting the `value` property.
    */
   ionChange: EventEmitter<CustomEvent<IIonSegmentSegmentChangeEventDetail>>;
 }
@@ -2022,6 +2031,8 @@ import type { SelectChangeEventDetail as IIonSelectSelectChangeEventDetail } fro
 export declare interface IonSelect extends Components.IonSelect {
   /**
    * Emitted when the value has changed.
+
+This event will not emit when programmatically setting the `value` property.
    */
   ionChange: EventEmitter<CustomEvent<IIonSelectSelectChangeEventDetail>>;
   /**
@@ -2232,6 +2243,8 @@ export declare interface IonTextarea extends Components.IonTextarea {
    * The `ionChange` event is fired when the user modifies the textarea's value.
 Unlike the `ionInput` event, the `ionChange` event is fired when
 the element loses focus after its value has been modified.
+
+This event will not emit when programmatically setting the `value` property.
    */
   ionChange: EventEmitter<CustomEvent<IIonTextareaTextareaChangeEventDetail>>;
   /**
@@ -2384,8 +2397,9 @@ import type { ToggleChangeEventDetail as IIonToggleToggleChangeEventDetail } fro
 
 export declare interface IonToggle extends Components.IonToggle {
   /**
-   * Emitted when the user switches the toggle on or off. Does not emit
-when programmatically changing the value of the `checked` property.
+   * Emitted when the user switches the toggle on or off.
+
+This event will not emit when programmatically setting the `checked` property.
    */
   ionChange: EventEmitter<CustomEvent<IIonToggleToggleChangeEventDetail>>;
   /**

packages/angular/standalone/src/directives/proxies.ts

@@ -126,10 +126,9 @@ import type { AccordionGroupChangeEventDetail as IIonAccordionGroupAccordionGrou
 
 export declare interface IonAccordionGroup extends Components.IonAccordionGroup {
   /**
-   * Emitted when the value property has changed
-as a result of a user action such as a click.
-This event will not emit when programmatically setting
-the value property.
+   * Emitted when the value property has changed as a result of a user action such as a click.
+
+This event will not emit when programmatically setting the `value` property.
    */
   ionChange: EventEmitter<CustomEvent<IIonAccordionGroupAccordionGroupChangeEventDetail>>;
 }
@@ -1486,6 +1485,8 @@ import type { PickerColumnChangeEventDetail as IIonPickerColumnPickerColumnChang
 export declare interface IonPickerColumn extends Components.IonPickerColumn {
   /**
    * Emitted when the value has changed.
+
+This event will not emit when programmatically setting the `value` property.
    */
   ionChange: EventEmitter<CustomEvent<IIonPickerColumnPickerColumnChangeEventDetail>>;
 }