Skip to main content
Version: v8 (beta)

Hide Contrast Mode

Ionic ships with themes for increased contrast for users with low vision. These themes work by increasing the contrast between foreground content, such as text, and background content, such as UI components. Ionic provides light and dark variants for high contrast.

Overview​

The Ionic colors in the high contrast theme have been updated to meet Level AAA color contrast as defined by the Web Content Accessibility Guidelines (WCAG) when used with the appropriate contrast color. The theme also seeks to improve the contrast of UI components such as the border on an Item. However, Ionic's high contrast theme prioritizes text. This means that if increasing the contrast of a UI component against the page background would significantly reduce the contrast of the component's text against the component's background, the UI component contrast will not be modified.

Enabling High Contrast Theme​

There are three provided ways to enable the high contrast theme in an app: always, based on system settings, or by using a class.

Always​

The default theme provided with Ionic Framework also uses the default color contrast levels. The high contrast theme can be enabled by importing the following stylesheet in the appropriate files. This approach will enable the high contrast theme regardless of a user's preference for high contrast.

@import '@ionic/angular/css/themes/high-contrast.always.css';

The high contrast dark theme can be applied by importing high-contrast-dark.always.css instead of high-contrast.always.css.

The following example will always display the high contrast light theme, regardless of the user's preference for high contrast or dark mode.

System​

The system approach to enabling high contrast mode involves checking the system settings for the user's preferred contrast. This is the default when starting a new Ionic Framework app. Importing the following stylesheets in the appropriate file will automatically retrieve the user's preference from the system settings and apply the high contrast theme when high contrast is preferred.

@import '@ionic/angular/css/themes/high-contrast.system.css';
@import '@ionic/angular/css/themes/high-contrast-dark.system.css';

This approach activates the high contrast theme when the CSS media query for prefers-contrast is more. The prefers-contrast media query is supported by all modern browsers. If support for an older browser is required, we recommend using the class approach.

The following example uses the system settings to decide when to show high contrast mode.

info

Not sure how to change the system settings? Here's how to enable high contrast mode on Windows 11 and on macOS.

The high contrast light theme must be imported after core.css, and the

high contrast dark theme must be imported after dark.system.css. Otherwise, the standard contrast theme will take priority.

Class​

While the previous approaches are excellent for enabling the high contrast theme through file imports alone, there are scenarios where you may need more control over its application. In cases where you need to apply the high contrast theme conditionally, such as through a toggle, or if you want to extend the functionality based on system settings, we provide a high contrast theme class file. This file applies the high contrast theme when a specific class is added to an app. Importing the following stylesheets into the appropriate file will provide the necessary styles for using the high contrast theme with the class:

@import '@ionic/angular/css/themes/high-contrast.class.css';
@import '@ionic/angular/css/themes/high-contrast-dark.class.css';

This approach activates the high contrast theme when the .ion-theme-high-contrast class is set on the html element. This class must be applied by the developer. This can be combined with the .ion-theme-dark class to conditionally apply the high contrast dark theme.

The following example combines site settings, system settings, and the toggle to decide when to show high contrast mode. The site's theme takes precedence over system settings. If your system settings differ from the site's theme when the demo loads, it will use the site's theme.

info

Not sure how to change the system settings? Here's how to enable high contrast mode on Windows 11 and on macOS.

Important The high contrast light theme must be imported after core.css,

and the high contrast dark theme must be imported after dark.class.css. Otherwise, the standard contrast theme will take priority. :::

Important

The .ion-theme-high-contrast class must be added to the html element in order to work with the imported high contrast theme.

Customizing Ionic High Contrast Theme​

Ionic has a recommended high contrast theme that can be enabled in three different ways: always, based on system settings, or by using a class. Each of these methods involves importing the high contrast theme file with the corresponding name.

The theme variables are set by importing the relevant high contrast theme file and do not need to be copied into an app. For more information on the variables being changed, including additional variables for further customization, refer to the Themes section.

The always high contrast theme behaves in the following ways:

  1. Sets the Ionic colors for all modes to complement a high contrast theme in the :root selector. The :root selector is identical to the selector html, except that its specificity is higher.
  2. Setting variables for the high contrast theme on ios devices using the :root.ios selector.
  3. Setting variables for the high contrast theme on md devices using the :root.md selector.

Contents

Edit this page