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 9.x
• Version 8.x
• Version 7.x
• Version 6.x
• Version 5.x
• Version 4.x
• Legacy

Version 9.x

• Components
  • Button
  • Card
  • Chip
  • Datetime
  • Grid
  • Input Otp
  • Radio Group
  • Textarea

Components

Button

• The border-radius of the ios and md button now defaults to 6px and 999px instead of 14px and 4px, respectively, in accordance with the iOS and Material Design 3 guidelines. To revert to the previous appearance, set the shape to "soft" for md and override the --border-radius CSS variable for ios to 14px, or set it to a different value entirely.

Card

• ion-card: The border-radius of the ios and md card now defaults to 14px and 12px instead of 8px and 4px, respectively, in accordance with the iOS and Material Design 3 guidelines. To revert to the previous appearance, set the shape to "soft", or override the --border-radius CSS variable to specify a different value.

• ion-card-content: The ion-card-content component has been updated to Shadow DOM. With this update, all card-related components now use Shadow DOM for style encapsulation. The default styles for heading elements inside ion-card-content have been removed. If you need custom styling for headings, you can add your own CSS targeting these elements. For example:

  ion-card-content h1 {
    margin-top: 0;
    margin-bottom: 2px;
  
    font-size: 1.5rem;
  }
  
  ion-card-content h2 {
    margin-top: 2px;
    margin-bottom: 2px;
  
    font-size: 1rem;
  }
  
  ion-card-content h3,
  ion-card-content h4,
  ion-card-content h5,
  ion-card-content h6 {
    margin-top: 2px;
    margin-bottom: 2px;
  
    font-size: 0.875rem;
  }
  

Chip

• The border-radius of the ios and md chip now defaults to 10px and 8px, respectively, instead of 16px in accordance with the iOS and Material Design 3 guidelines. To revert to the previous appearance, set the shape to "round", or override the --border-radius CSS variable to specify a different value.

Datetime

• The ion-buttons component has been removed from the internal implementation of ion-datetime and is no longer required when passing custom buttons to the slot="buttons". When providing custom buttons, use a div element instead of ion-buttons. While existing code using ion-buttons may continue to work visually, future updates to the ion-buttons component may cause any styles you rely on to break.

Grid

• The properties pull and push have been deprecated and no longer work. A similar look can be achieved with the newly added property order.

Example 1: Swap two columns

Version up to 8.x

<ion-grid>
  <ion-row>
    <ion-col push="4">1</ion-col>
    <ion-col pull="4">2</ion-col>
    <ion-col>3</ion-col>
  </ion-row>
</ion-grid>

Version 9.x+

<ion-grid>
  <ion-row>
    <ion-col order="2">1</ion-col>
    <ion-col order="1">2</ion-col>
    <ion-col order="3">3</ion-col>
  </ion-row>
</ion-grid>

Example 2: Reorder columns with specific sizes

To reorder two columns where column 1 has size="9" push="3" and column 2 has size="3" pull="9":

Version up to 8.x

<ion-grid>
  <ion-row>
    <ion-col push="3">1</ion-col>
    <ion-col pull="9">2</ion-col>
  </ion-row>
</ion-grid>

Version 9.x+

<ion-grid>
  <ion-row>
    <ion-col order="2">1</ion-col>
    <ion-col size="3" order="1">2</ion-col>
  </ion-row>
</ion-grid>

Example 3: Push

<ion-grid>
  <ion-row>
    <ion-col size="auto" push="1">
      <div>ion-col push 1</div>
    </ion-col>
    <ion-col size="auto" push="1">
      <div>ion-col push 1</div>
    </ion-col>
  </ion-row>
</ion-grid>

Version 9.x+

<ion-grid>
  <ion-row>
    <ion-col size="auto" offset="1">
      <div>ion-col size="auto" offset="1"</div>
    </ion-col>
    <ion-col size="auto">
      <div>ion-col size="auto"</div>
    </ion-col>
  </ion-row>
</ion-grid>

Example 4: Push and Pull

<ion-grid>
  <ion-row>
    <ion-col size="3" size-md="6" push="9" push-md="6">
      <div>ion-col size="3" size-md="6" push="9" push-md="6"</div>
    </ion-col>
    <ion-col size="9" size-md="6" pull="3" pull-md="6">
      <div>ion-col size="9" size-md="6" pull="3" pull-md="6"</div>
    </ion-col>
  </ion-row>
</ion-grid>

Version 9.x+

<ion-grid>
  <ion-row>
    <ion-col size="auto" order="2" order-md="2">
      <div>ion-col size="auto" order="2" order-md="2"</div>
    </ion-col>
    <ion-col size="auto" order="1" order-md="1">
      <div>ion-col size="auto" order="1" order-md="1"</div>
    </ion-col>
  </ion-row>
</ion-grid>

Input Otp

Converted ion-input-otp to use Shadow DOM.

If you were targeting the internals of ion-input-otp in your CSS, you will need to target the group, container, native, separator or description Shadow Parts instead, or use the provided CSS Variables.

Radio Group

Converted ion-radio-group to use Shadow DOM.

If you were targeting the internals of ion-radio-group in your CSS, you will need to target the supporting-text, helper-text or error-text Shadow Parts instead, or use the provided CSS Variables.

Additionally, the radio-group-wrapper div element has been removed, causing slotted elements to be direct children of the ion-radio-group.

Textarea

Converted ion-textarea to use Shadow DOM.

If you were targeting the internals of ion-textarea in your CSS, you will need to target the wrapper, container, label, native, supporting-text, helper-text, error-text, counter, or bottom Shadow Parts instead, or use the provided CSS Variables.