Skip to main content
Version: v8 (beta)

Hide Contrast Mode

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

Overview​

The default theme in Ionic provides Ionic colors that meet Level AA color contrast as defined by Web Content Accessibility Guidelines (WCAG) when used with the appropriate contrast color. The Ionic colors in the high contrast theme have been updated to meet Level AAA color contrast when used with the appropriate contrast color. Notably, improvements have been made to the contrast of UI components, including border, text, and background colors. However, it's important to note that within the high contrast theme, priority is given to text legibility. This means that if adjusting the contrast of a UI component against the page background would significantly compromise the contrast between the component's text and its background, the contrast of the UI component background will remain unchanged.

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 CSS class.

Always​

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 the system settings for contrast preference.

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

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.

The following example shows how to include both the high contrast light theme as well as the high contrast dark theme. The system's dark mode preference will be checked to show either the light or dark variant of the high contrast theme.

@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 CSS 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.

caution

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.

CSS 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 where it is applied. 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.

caution

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.

caution

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 CSS 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 following provides details on how to customize the high contrast theme depending on how it was applied in an application.

The always high contrast theme can be accessed by importing high-contrast.always.css for the light variant and high-contrast-dark.always.css for the dark variant.

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