ionic-framework/BREAKING.md

Breaking Changes

This is a comprehensive list of the breaking changes introduced in the major version releases of Ionic Framework.

Versions

• Version 7.x
• Version 6.x
• Version 5.x
• Version 4.x
• Legacy

Version 7.x

• Browser and Platform Support
• Components
  • Accordion Group
  • Action Sheet
  • Back Button
  • Button
  • Card Header
  • Checkbox
  • Datetime
  • Input
  • Item
  • Modal
  • Overlays
  • Picker
  • Radio Group
  • Range
  • Searchbar
  • Segment
  • Select
  • Slides
  • Textarea
  • Toggle
  • Virtual Scroll
• Config
• Types
  • Overlay Attribute Interfaces
• JavaScript Frameworks
  • Angular
  • React
  • Vue
• CSS Utilities
  • hidden attribute

Browser and Platform Support

This section details the desktop browser, JavaScript framework, and mobile platform versions that are supported by Ionic 7.

Minimum Browser Versions

Desktop Browser	Supported Versions
Chrome	79+
Safari	14+
Firefox	70+
Edge	79+

Minimum JavaScript Framework Versions

Framework	Supported Version
Angular	14+
React	17+
Vue	3.0.6+

Minimum Mobile Platform Versions

Platform	Supported Version
iOS	14+
Android	5.1+ with Chromium 79+

Components

Accordion Group

• ionChange is no longer emitted when the value of ion-accordion-group is modified externally. ionChange is only emitted from user committed changes, such as clicking or tapping the accordion header.

• Accordion Group no longer automatically adjusts the value property when passed an array and multiple="false". Developers should update their apps to ensure they are using the API correctly.

Action Sheet

• Action Sheet is updated to align with the design specification.

Design tokens

Token	Previous Value	New Value
--height	100%	auto

Button

• Button is updated to align with the design specification for iOS.

Design tokens

Token	Previous Value	New Value
$button-ios-letter-spacing	-0.03em	0
$button-ios-clear-letter-spacing	0	Removed
$button-ios-height	2.8em	3.1em
$button-ios-border-radius	10px	14px
$button-ios-large-height	2.8em	3.1em
$button-ios-large-border-radius	12px	16px

Back Button

• Back Button is updated to align with the design specification for iOS.

Design tokens

Token	Previous Value	New Value
--icon-margin-end	-5px	1px
--icon-font-size	1.85em	1.6em

Card Header

• The card header has ben changed to a flex container with direction set to column (top to bottom). In ios mode the direction is set to column-reverse which results in the subtitle displaying on top of the title.

Checkbox

• ionChange is no longer emitted when the checked property of ion-checkbox is modified externally. ionChange is only emitted from user committed changes, such as clicking or tapping the checkbox.

• The --background and --background-checked CSS variables have been renamed to --checkbox-background and --checkbox-background-checked respectively.

Datetime

• ionChange is no longer emitted when the value property of ion-datetime is modified externally. ionChange is only emitted from user committed changes, such as clicking or tapping a date.

• Datetime no longer automatically adjusts the value property when passed an array and multiple="false". Developers should update their apps to ensure they are using the API correctly.

• Datetime no longer incorrectly reports the time zone when value is updated. Datetime does not manage time zones, so any time zone information provided is ignored.

• Passing the empty string to the value property will now error as it is not a valid ISO-8601 value.

• The haptics when swiping the wheel picker are now enabled only on iOS.

Input

• ionChange is no longer emitted when the value of ion-input is modified externally. ionChange is only emitted from user committed changes, such as typing in the input and the input losing focus, clicking the clear action within the input, or pressing the "Enter" key.

  • If your application requires immediate feedback based on the user typing actively in the input, consider migrating your event listeners to using ionInput instead.

• The debounce property has been updated to control the timing in milliseconds to delay the event emission of the ionInput event after each keystroke. Previously it would delay the event emission of ionChange.

• The debounce property's default value has changed from 0 to undefined. If debounce is undefined, the ionInput event will fire immediately.

• The detail payload for the ionInput event now contains an object with the current value as well as the native event that triggered ionInput.

Design tokens

Token	Previous Value	New Value
--placeholder-opacity	0.5	0.6

Item

Design tokens

iOS:

Token	Previous Value	New Value
$item-ios-font-size	17px	16px
--inner-padding-end	10px	16px
--padding-start	20px	16px

Modal

• The swipeToClose property has been removed in favor of canDismiss.
• The canDismiss property now defaults to true and can no longer be set to undefined.

Overlays

Ionic now listens on the keydown event instead of the keyup event when determining when to dismiss overlays via the "Escape" key. Any applications that were listening on keyup to suppress this behavior should listen on keydown instead.

Picker

• The refresh key has been removed from the PickerColumn interface. Developers should use the columns property to refresh the ion-picker view.

Radio Group

• ionChange is no longer emitted when the value of ion-radio-group is modified externally. ionChange is only emitted from user committed changes, such as clicking or tapping an ion-radio in the group.

Range

• Range is updated to align with the design specification for supported modes.

  Design tokens

  iOS:

  Token	Previous Value	New Value
  --bar-border-radius	0px	$range-ios-bar-border-radius (2px default)
  --knob-size	28px	$range-ios-knob-width (26px default)
  $range-ios-bar-height	2px	4px
  $range-ios-bar-background-color	rgba(var(--ion-text-color-rgb, 0, 0, 0), .1)	var(--ion-color-step-900, #e6e6e6)
  $range-ios-knob-box-shadow	0 3px 1px rgba(0, 0, 0, .1), 0 4px 8px rgba(0, 0, 0, .13), 0 0 0 1px rgba(0, 0, 0, .02)	0px 0.5px 4px rgba(0, 0, 0, 0.12), 0px 6px 13px rgba(0, 0, 0, 0.12)
  $range-ios-knob-width	28px	26px

• ionChange is no longer emitted when the value of ion-range is modified externally. ionChange is only emitted from user committed changes, such as dragging and releasing the range knob or selecting a new value with the keyboard arrows.

  • If your application requires immediate feedback based on the user actively dragging the range knob, consider migrating your event listeners to using ionInput instead.

• The debounce property's value value has changed from 0 to undefined. If debounce is undefined, the ionInput event will fire immediately.

• Range no longer clamps assigned values within bounds. Developers will need to validate the value they are assigning to ion-range is within the min and max bounds when programmatically assigning a value.

• The name property defaults to ion-r-${rangeIds++} where rangeIds is a number that is incremented for every instance of ion-range.

Searchbar

• ionChange is no longer emitted when the value of ion-searchbar is modified externally. ionChange is only emitted from user committed changes, such as typing in the searchbar and the searchbar losing focus or pressing the "Enter" key.

  • If your application requires immediate feedback based on the user typing actively in the searchbar, consider migrating your event listeners to using ionInput instead.

• The debounce property has been updated to control the timing in milliseconds to delay the event emission of the ionInput event after each keystroke. Previously it would delay the event emission of ionChange.

• The debounce property's default value has changed from 250 to undefined. If debounce is undefined, the ionInput event will fire immediately.

• The detail payload for the ionInput event now contains an object with the current value as well as the native event that triggered ionInput.

Design tokens

Token	Previous Value	New Value
--placeholder-opacity	0.5	0.6

Segment

• ionChange is no longer emitted when the value of ion-segment is modified externally. ionChange is only emitted from user committed changes, such as clicking a segment button or dragging to activate a segment button.

• The type signature of value supports string | undefined. Previously the type signature was string | null | undefined.

  • Developers needing to clear the checked segment item should assign a value of '' instead of null.

Select

• ionChange is no longer emitted when the value of ion-select is modified externally. ionChange is only emitted from user committed changes, such as confirming a selected option in the select's overlay.

• The icon CSS Shadow Part now targets an ion-icon component.

Design tokens

Token	Previous Value	New Value
--placeholder-opacity	0.33	0.6

Slides

ion-slides, ion-slide, and the IonicSwiper plugin have been removed from Ionic.

Developers using these components will need to migrate to using Swiper.js directly, optionally using the IonicSlides plugin. Guides for migration and usage are linked below:

• Angular
• React
• Vue

Textarea

• ionChange is no longer emitted when the value of ion-textarea is modified externally. ionChange is only emitted from user committed changes, such as typing in the textarea and the textarea losing focus.

  • If your application requires immediate feedback based on the user typing actively in the textarea, consider migrating your event listeners to using ionInput instead.

• The debounce property has been updated to control the timing in milliseconds to delay the event emission of the ionInput event after each keystroke. Previously it would delay the event emission of ionChange.

• The debounce property's default value has changed from 0 to undefined. If debounce is undefined, the ionInput event will fire immediately.

• ionInput dispatches an event detail of null when the textarea is cleared as a result of clear-on-edit="true".

• The detail payload for the ionInput event now contains an object with the current value as well as the native event that triggered ionInput.

Design tokens

Token	Previous Value	New Value
--placeholder-opacity	0.5	0.6

Toggle

• ionChange is no longer emitted when the checked property of ion-toggle is modified externally. ionChange is only emitted from user committed changes, such as clicking the toggle to set it on or off.

• The --background and --background-checked variables have been renamed to --track-background and --track-background-checked, respectively.

Virtual Scroll

ion-virtual-scroll has been removed from Ionic.

Developers using the component will need to migrate to a virtual scroll solution provided by their framework:

• Angular
• React
• Vue

Any references to the virtual scroll types from @ionic/core have been removed. Please remove or replace these types: Cell, VirtualNode, CellType, NodeChange, HeaderFn, ItemHeightFn, FooterHeightFn, ItemRenderFn and DomRenderFn.

Config

• innerHTMLTemplatesEnabled defaults to false. Developers who wish to use the innerHTML functionality inside of ion-alert, ion-infinite-scroll-content, ion-loading, ion-refresher-content, and ion-toast must set this config to true and properly sanitize their content.

Types

Overlay Attribute Interfaces

ActionSheetAttributes, AlertAttributes, AlertTextareaAttributes, AlertInputAttributes, LoadingAttributes, ModalAttributes, PickerAttributes, PopoverAttributes, and ToastAttributes have been removed. Developers should use { [key: string]: any } instead.

JavaScript Frameworks

Angular

• Angular v14 is now required to use @ionic/angular and @ionic/angular-server. Upgrade your project to Angular v14 by following the Angular v14 update guide.

• null values on form components will no longer be converted to the empty string ('') or false. This impacts ion-checkbox, ion-datetime, ion-input, ion-radio, ion-radio-group, ion-range, ion-searchbar, ion-segment, ion-select, ion-textarea, and ion-toggle.

• The dev-preview environmentInjector property has been removed from ion-tabs and ion-router-outlet. Standalone component routing is now available without additional custom configuration. Remove the environmentInjector property from your ion-tabs and ion-router-outlet components.

React

@ionic/react and @ionic/react-router no longer ship a CommonJS entry point. Instead, only an ES Module entry point is provided for improved compatibility with Vite.

Vue

@ionic/vue and @ionic/vue-router no longer ship a CommonJS entry point. Instead, only an ES Module entry point is provided for improved compatibility with Vite.

CSS Utilities

`hidden` attribute

The [hidden] attribute has been removed from Ionic's global stylesheet. The [hidden] attribute can continue to be used, but developers will get the native hidden implementation instead. The main difference is that the native implementation is easier to override using display than Ionic's implementation.

Developers can add the following CSS to their global stylesheet if they need the old behavior:

[hidden] {
  display: none !important;
}