# Breaking Changes
## Migrating
### Migration Guide
If you aren't sure where to start in upgrading to v4, we recommend reading through our [migration guide](https://ionicframework.com/docs/building/migration) first.
### Migration Linter
Looking for a tool that automatically warns (and sometimes fixes) the breaking changes listed? Check out our [migration linter](https://github.com/ionic-team/v4-migration-tslint)!
## Components
A list of the breaking changes introduced to each component in Ionic Angular v4.
- [Action Sheet](#action-sheet)
- [Alert](#alert)
- [Back Button](#back-button)
- [Button](#button)
- [Colors](#colors)
- [Component Imports](#component-imports)
- [Content](#content)
- [Datetime](#datetime)
- [Dynamic Mode](#dynamic-mode)
- [FAB](#fab)
- [Fixed Content](#fixed-content)
- [Grid](#grid)
- [Icon](#icon)
- [Infinite Scroll](#infinite-scroll)
- [Item](#item)
- [Item Divider](#item-divider)
- [Item Options](#item-options)
- [Item Sliding](#item-sliding)
- [Label](#label)
- [List Header](#list-header)
- [Loading](#loading)
- [Menu](#menu)
- [Menu Toggle](#menu-toggle)
- [Modal](#modal)
- [Nav](#nav)
- [Navbar](#navbar)
- [Option](#option)
- [Overlays](#overlays)
- [Popover](#popover)
- [Radio](#radio)
- [Range](#range)
- [Refresher](#refresher)
- [Scroll](#scroll)
- [Segment Button](#segment-button)
- [Select](#select)
- [Show When / Hide When](#show-when--hide-when)
- [Spinner](#spinner)
- [Tabs](#tabs)
- [Text / Typography](#text--typography)
- [Theming](#theming)
- [Toast](#toast)
- [Toolbar](#toolbar)
## Action Sheet
The `title`, `subTitle` and `enableBackdropDismiss` properties have been renamed to `header`, `subHeader` and `backdropDismiss` respectively.
**Old Usage Example:**
```js
const actionSheet = await actionSheetCtrl.create({
title: 'This is the title',
subTitle: 'this is the sub title',
enableBackdropDismiss: false
});
await actionSheet.present();
```
**New Usage Example:**
```js
const actionSheet = await actionSheetCtrl.create({
header: 'This is the title',
subHeader: 'this is the sub title',
backdropDismiss: false
});
await actionSheet.present();
```
## Alert
The `title`, `subTitle` and `enableBackdropDismiss` properties have been renamed to `header`, `subHeader` and `backdropDismiss` respectively.
**Old Usage Example:**
```js
const alert = await alertCtrl.create({
title: 'This is the title',
subTitle: 'this is the sub title',
enableBackdropDismiss: false
});
await alert.present();
```
**New Usage Example:**
```js
const alert = await alertCtrl.create({
header: 'This is the title',
subHeader: 'this is the sub title',
backdropDismiss: false
});
await alert.present();
```
## Back Button
The back button is no longer added by default to a navigation bar. It should be explicitly written in a toolbar:
**Old Usage Example:**
```html
Back Button Example
```
**New Usage Example:**
```html
Back Button Example
```
See the [back button documentation](https://github.com/ionic-team/ionic/blob/master/core/src/components/back-button) for more usage examples.
## Button
### Markup Changed
Button should now be written as an `` element. Ionic will determine when to render an anchor tag based on the presence of an `href` attribute.
**Old Usage Example:**
```html
Default Anchor
```
**New Usage Example:**
```html
Default Button
Default Anchor
```
### Attributes Renamed
Previously to style icons inside of a button the following attributes were used: `icon-left`, `icon-right`, (and with the added support of RTL) `icon-start`, `icon-end`.
These have been renamed to the following, and moved from the button element to the icon itself:
| Old Property | New Property | Property Behavior |
|---------------------------|----------------|-----------------------------------------------------------------------|
| `icon-left`, `icon-start` | `slot="start"` | Positions to the left of the button in LTR, and to the right in RTL. |
| `icon-right`, `icon-end` | `slot="end"` | Positions to the right of the button in LTR, and to the left in RTL. |
In addition, several sets of mutually exclusive boolean attributes have been combined into a single string attribute.
The `small` and `large` attributes are now combined under the `size` attribute. The `clear`, `outline`, and `solid` attributes have been combined under `fill`. The `full` and `block` attributes have been combined under `expand`. And, lastly, the `round` attribute is now used under `shape`.
| Old Property | New Property | Property Behavior |
| --------------------------- | ------------ | --------------------------- |
| `small`, `large` | `size` | Sets the button size. |
| `clear`, `outline`, `solid` | `fill` | Sets the button fill style. |
| `full`, `block` | `expand` | Sets the button width. |
| `round` | `shape` | Sets the button shape. |
**Old Usage Example:**
```html
Icon Left
Icon Left on LTR, Right on RTL
Icon Right
Icon Right on LTR, Left on RTL
Large Button
Outline Button
Full-width Button
Round Button
```
**New Usage Example:**
```html
Icon Left on LTR, Right on RTL
Icon Right on LTR, Left on RTL
Large Button
Outline Button
Full-width Button
Round Button
```
## Colors
The default Ionic theme colors have changed. Previously we had:
```
primary: #327eff
secondary: #32db64
danger: #f53d3d
light: #f4f4f4
dark: #222
```
Some of their values have changed, and we now include more colors by default:
```
primary: #3880ff
secondary: #0cd1e8
tertiary: #7044ff
success: #10dc60
warning: #ffce00
danger: #f04141
light: #f4f5f8
medium: #989aa2
dark: #222428
```
The `secondary` color saw the largest change. If you were previously using our `secondary` color we recommend switching to `success` instead.
## Component Imports
For consistency with other frameworks and the rest of APIs and tooling, the exported
Ionic components are now prefixed with `Ion`:
```diff
- import { Input, List, Slides } from 'ionic-angular';
+ import { IonInput, IonList, IonSlides } from '@ionic/angular';
```
## Content
Content is now a drop-in replacement for `ion-scroll`. This makes `ion-content` much more flexible. It can be used anywhere, even nested.
### Method Removed
The `resize` method has been removed from Content. In Ionic 4, the `ion-content` is based on a flex layout. This means the content size will automatically adjust without requiring a call to `resize()`.
### Attributes Renamed
| Old Property | New Property | Property Behavior |
|--------------|-----------------------|-------------------------------------------------------------------------|
| no-bounce | forceOverflow="false" | If true and the content does not cause an overflow scroll, the scroll interaction will cause a bounce. |
## Datetime
The Datetime classes and interfaces have changed capitalization from `DateTime` to `Datetime`. This is more consistent with other components and their tags.
**Old Usage Example:**
```javascript
import { DateTime } from 'ionic-angular';
```
**New Usage Example:**
```javascript
import { Datetime } from '@ionic/angular';
```
## Dynamic Mode
Components are no longer able to have their mode changed dynamically. You can change the mode before the first render, but after that it will not style properly because only the initial mode's styles are included.
## Events
Events now emit as a [CustomEvent](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) interface that extends the [Event](https://developer.mozilla.org/en-US/docs/Web/API/Event) interface. This interface includes a `detail` property that holds any data passed when the event is triggered.
This allows you to still get the details of the event. For example, to get the target where the event was dispatched, such as a button that was clicked, you can read in the value of `event.target`.
**Old Usage Example:**
```html
```
```typescript
onSelectChange(event) {
const value = event.value;
console.log('Select value is', value);
}
```
**New Usage Example:**
```typescript
onSelectChange(event: CustomEvent) {
const value = event.detail.value;
console.log('Select value is', value);
}
```
## FAB
### Markup Changed
Buttons inside of an `` container should now be written as an `` element. Ionic will determine when to render an anchor tag based on the presence of an `href` attribute.
**Old Usage Example:**
```html
```
**New Usage Example:**
```html
```
### Attributes Renamed
The mutually exclusive boolean attributes to position the fab have been combined into two single string attributes.
The attributes to align the fab horizontally are now combined under the `horizontal` attribute and the attributes to align the fab vertically are now combined under the `vertical` attribute:
| Old Property | New Property | Property Behavior |
|--------------|----------------------|-------------------------------------------------------------------------|
| left | Removed, see `start` | |
| right | Removed, see `end` | |
| center | `horizontal="center"`| Positions to the center of the viewport. |
| start | `horizontal="start"` | Positions to the left of the viewport in LTR, and to the right in RTL. |
| end | `horizontal="end"` | Positions to the right of the viewport in LTR, and to the left in RTL. |
| top | `vertical="top"` | Positions at the top of the viewport. |
| bottom | `vertical="bottom"` | Positions at the bottom of the viewport. |
| middle | `vertical="center"` | Positions at the center of the viewport. |
_Note that `middle` has been changed to `center` for the vertical positioning._
**Old Usage Example:**
```html
```
**New Usage Example:**
```html
```
## Fixed Content
The `` container was previously placed inside of the fixed content by default. Now, any fixed content should use the `fixed` slot.
**Old Usage Example:**
```html
Scrollable Content
```
**New Usage Example:**
```html
Scrollable Content
```
## Grid
### Markup Changed
The Grid has been refactored in order to support CSS variables and a dynamic number of columns. The following column attributes have been changed.
_In the following examples, `{breakpoint}` refers to the optional screen breakpoint (xs, sm, md, lg, xl) and `{value}` refers to the number of columns (`auto` or a number between `1` and `12`)._
- `col-{breakpoint}-{value}` attributes have been renamed to `size-{breakpoint}=“{value}”`
- `offset-{breakpoint}-{value}` attributes have been renamed to `offset-{breakpoint}=“{value}”`
- `push-{breakpoint}-{value}` attributes have been renamed to `push-{breakpoint}=“{value}”`
- `pull-{breakpoint}-{value}` attributes have been renamed to `pull-{breakpoint}=“{value}”`
Customizing the padding and width of a grid should now be done with CSS variables. For more information, see [Grid Layout](https://github.com/ionic-team/ionic-docs/blob/master/src/pages/layout/grid.md).
## Icon
### Fonts Removed
Icons have been refactored to use SVGs instead of fonts. Ionic will only fetch the SVG for the icon when it is needed, instead of having a large font file that is always loaded in.
If any `CSS` is being overridden for an icon it will need to change to override the SVG itself. Below is a usage example of the differences in changing the icon color.
**Old Usage Example:**
```css
.icon {
color: #000;
}
```
**New Usage Example:**
```css
ion-icon {
fill: #000;
}
```
_Note: we are no longer adding the `icon` class to an `ion-icon`, so the element should be targeted instead._
### Property Removed
The `isActive` property has been removed. It only worked for `ios` icons previously. If you would like to switch between an outline and solid icon you should set it in the `name`, or `ios`/`md` attribute and then change it when needed.
## Infinite Scroll
### Method Removed
The `enable()` method has been removed in favor of using the `disabled` property on the `ion-infinite-scroll` element.
**Old Usage Example:**
```html
```
```javascript
doInfinite(infiniteScroll) {
console.log('Begin async operation');
setTimeout(() => {
console.log('Async operation has ended');
infiniteScroll.complete();
// To disable the infinite scroll
infiniteScroll.enable(false);
}, 500);
}
```
**New Usage Example:**
```html
```
```javascript
doInfinite(event) {
console.log('Begin async operation');
setTimeout(() => {
console.log('Async operation has ended');
event.target.complete();
// To disable the infinite scroll
event.target.disabled = true;
}, 500);
}
```
## Item
### Markup Changed
Item should now be written as an `` element. Ionic will determine when to render an anchor tag based on the presence of an `href` attribute, and a button tag based on the presence of an `onclick` or `button` attribute. Otherwise, it will render a div.
**Old Usage Example:**
```html
Default Item
Anchor Item
```
**New Usage Example:**
```html
Default Item
Button Item
Anchor Item
```
### Label Required
Previously an `ion-label` would automatically get added to an `ion-item` if one wasn't provided. Now an `ion-label` should always be added in the item component.
```html
Item Label
```
### Attributes Renamed
Previously to position elements inside of an `ion-item` the following attributes were used: `item-left`, `item-right`, (and with the added support of RTL) `item-start`, `item-end`.
These have been renamed to the following:
| Old Property | New Property | Property Behavior |
|---------------------------|----------------|---------------------------------------------------------------------|
| `item-left`, `item-start` | `slot="start"` | Positions to the left of the item in LTR, and to the right in RTL. |
| `item-right`, `item-end` | `slot="end"` | Positions to the right of the item in LTR, and to the left in RTL. |
**Old Usage Example:**
```html