Skip to main content
Version: v8

High Contrast Mode

Ionic offers palettes with increased contrast for users with low vision. These palettes 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 palette 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 palette 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 palette, 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 palette in an app: always, based on system settings, or by using a CSS class.

Always​

The high contrast palette can be enabled by importing the following stylesheet in the appropriate files. This approach will enable the high contrast palette regardless of the system settings for contrast preference.

@import '@ionic/angular/css/palettes/high-contrast.always.css'; // Light palette
// @import '@ionic/angular/css/palettes/high-contrast-dark.always.css'; // Dark palette

The high contrast dark palette 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 palette, 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 palette when high contrast is preferred.

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

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

This approach activates the high contrast palette 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 palette must be imported after core.css, and the high contrast dark palette must be imported after dark.system.css. Otherwise, the standard contrast palette will take priority.

CSS Class​

While the previous approaches are excellent for enabling the high contrast palette 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 palette conditionally, such as through a toggle, or if you want to extend the functionality based on system settings, we provide a high contrast palette class file. This file applies the high contrast palette 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 palette with the class:

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

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

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

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 palette must be imported after core.css, and the high contrast dark palette must be imported after dark.class.css. Otherwise, the standard contrast palette will take priority.

caution

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

Customizing Ionic High Contrast Theme​

Ionic has a recommended high contrast palette 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 palette file with the corresponding name.

The theme variables are set by importing the relevant high contrast palette 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 palette depending on how it was applied in an application.

The always high contrast palette 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 palette behaves in the following ways:

  1. Sets the Ionic colors for all modes to complement a high contrast palette 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 palette on ios devices using the :root.ios selector.
  3. Setting variables for the high contrast palette on md devices using the :root.md selector.

Contents

Edit this page