mirror of https://github.com/ionic-team/ionic-framework.git synced 2025-08-26 08:13:34 +08:00

Files

Brandy Carney a8e1e168ee fix(themes): modify the dark themes to use :root for mode-specific styles (#28833 )

Issue number: N/A

---------

## What is the current behavior?
The `system` and `always` dark theme files target the mode-specific
styles by using the following selectors:

```scss
:root {
  @include dark-base-theme();
}

.ios body {
  @include dark-ios-theme();
}

.md body {
  @include dark-md-theme();
}
```

This is an issue because then users **cannot** override the dark theme
by targeting `:root.ios`, they must target the `body`.

## What is the new behavior?
Updates the mode selectors to target the `:root` with the mode-specific
class:

```scss
:root {
  @include dark-base-theme();
}

:root.ios {
  @include dark-ios-theme();
}

:root.md {
  @include dark-md-theme();
}
```

This makes more sense, since we want it to still be global but
mode-specific, and allows users to override it on `:root` if desired.

## Does this introduce a breaking change?

- [ ] Yes
- [x] Maybe
- [ ] No

BREAKING CHANGES:

In previous versions, it was recommended to define the dark theme in the
following way:

```css
@media (prefers-color-scheme: dark) {
  body {
    /* global app variables */
  }

  .ios body {
    /* global ios app variables */
  }

  .md body {
    /* global md app variables */
  }
}
```

In Ionic Framework version 8, the dark theme is being distributed via
css files that can be imported. Below is an example of importing a dark
theme file in Angular:

```css
/* @import '@ionic/angular/css/themes/dark.always.css'; */
/* @import "@ionic/angular/css/themes/dark.class.css"; */
@import "@ionic/angular/css/themes/dark.system.css";
```

By importing the `dark.system.css` file, the dark theme variables will
be defined like the following:

```css
@media (prefers-color-scheme: dark) {
  :root {
    /* global app variables */
  }

  :root.ios {
    /* global ios app variables */
  }

  :root.md {
    /* global md app variables */
  }
}
```

Notice that the dark theme is now applied to the `:root` selector
instead of the `body` selector. The
[`:root`](https://developer.mozilla.org/en-US/docs/Web/CSS/:root)
selector represents the `<html>` element and is identical to the
selector `html`, except that its specificity is higher.

While migrating to include the new dark theme files is unlikely to cause
breaking changes, these new selectors can lead to unexpected overrides
if custom CSS variables are being set on the `body` element. We
recommend updating any instances where global application variables are
set to target the `:root` selector instead.

For more information on the new dark theme files, refer to the [Dark
Mode documentation](https://ionicframework.com/docs/theming/dark-mode).

## Other Information

Dev build: `7.6.2-dev.11705355381.14b22962`

2024-01-19 10:48:29 -05:00

5.7 KiB

Raw Blame History

Breaking Changes

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

Versions

Version 8.x

Browser and Platform Support
Dark Theme
Global Styles
Components
- Button
- Content
- Datetime
- Nav
- Picker

Browser and Platform Support

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

Minimum Browser Versions

Desktop Browser	Supported Versions
Chrome	89+
Safari	15+
Firefox	75+
Edge	89+

Minimum JavaScript Framework Versions

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

Minimum Mobile Platform Versions

Platform	Supported Version
iOS	15+
Android	5.1+ with Chromium 89+

Dark Theme

In previous versions, it was recommended to define the dark theme in the following way:

@media (prefers-color-scheme: dark) {
  body {
    /* global app variables */
  }

  .ios body {
    /* global ios app variables */
  }

  .md body {
    /* global md app variables */
  }
}

In Ionic Framework version 8, the dark theme is being distributed via css files that can be imported. Below is an example of importing a dark theme file in Angular:

/* @import '@ionic/angular/css/themes/dark.always.css'; */
/* @import "@ionic/angular/css/themes/dark.class.css"; */
@import "@ionic/angular/css/themes/dark.system.css";

By importing the dark.system.css file, the dark theme variables will be defined like the following:

@media (prefers-color-scheme: dark) {
  :root {
    /* global app variables */
  }

  :root.ios {
    /* global ios app variables */
  }

  :root.md {
    /* global md app variables */
  }
}

Notice that the dark theme is now applied to the :root selector instead of the body selector. The :root selector represents the <html> element and is identical to the selector html, except that its specificity is higher.

While migrating to include the new dark theme files is unlikely to cause breaking changes, these new selectors can lead to unexpected overrides if custom CSS variables are being set on the body element. We recommend updating any instances where global application variables are set to target the :root selector instead.

For more information on the new dark theme files, refer to the Dark Mode documentation.

Global Styles

The core.css file has been updated to set the text color on the body element:

body {
+  color: var(--ion-text-color);
}

This allows components to inherit the color properly when used outside of Ionic Framework and is required for custom themes to work properly. However, it may have unintentional side effects in apps if the color was not expected to inherit.

Components

Button

Button text now wraps by default. If this behavior is not desired, add the ion-text-nowrap class from the CSS Utilities.

Content

Content no longer sets the --background custom property when the .outer-content class is set on the host.

Datetime

The CSS shadow part for month-year-button has been changed to target a button element instead of ion-item. Developers should verify their UI renders as expected for the month/year toggle button inside of ion-datetime.
- Developers using the CSS variables available on ion-item will need to migrate their CSS to use CSS properties. For example:
```
ion-datetime::part(month-year-button) {
-  --background: red;

+  background: red;
}
```

Nav

getLength returns Promise<number> instead of <number>. This method was not previously available in Nav's TypeScript interface, but developers could still access it by casting Nav as any. Developers should ensure they await their getLength call before accessing the returned value.

Picker

ion-picker and ion-picker-column have been renamed to ion-picker-legacy and ion-picker-legacy-column, respectively. This change was made to accommodate the new inline picker component while allowing developers to continue to use the legacy picker during this migration period.
- Only the component names have been changed. Usages such as ion-picker or IonPicker should be changed to ion-picker-legacy and IonPickerLegacy, respectively.
- Non-component usages such as pickerController or useIonPicker remain unchanged. The new picker displays inline with your page content and does not have equivalents for these non-component usages.

5.7 KiB Raw Blame History