Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 37 ยท Components and Theming

Ionic Theming with CSS Variables and Dark Mode

Customize Ionic with CSS variables: the color palette and its five shades, global and per-component variables, dark mode, fonts and custom colors.

Ionic's theming system is built on CSS custom properties. One file, src/theme/variables.css, defines your palette, and every component reads from it. Changing a single variable recolours the whole app, and dark mode is a matter of redefining a few of them. This lesson explains the palette, how to add your own colour, how to scope changes, and how to support dark mode.

The default palette

Ionic ships nine colours, each referenced by a role name:

primary, secondary, tertiary, success, warning, danger, light, medium, dark.

For each one, Ionic needs six variables:

Variable Meaning
--ion-color-primary The base colour
--ion-color-primary-rgb The same colour as r, g, b for transparent versions
--ion-color-primary-contrast Text colour on top of the base
--ion-color-primary-contrast-rgb Contrast colour as r, g, b
--ion-color-primary-shade A slightly darker version for pressed states
--ion-color-primary-tint A lighter version for hover/focus

Redefine them under :root:

CSS
:root {
  --ion-color-primary: #0f766e;
  --ion-color-primary-rgb: 15, 118, 110;
  --ion-color-primary-contrast: #ffffff;
  --ion-color-primary-contrast-rgb: 255, 255, 255;
  --ion-color-primary-shade: #0d6861;
  --ion-color-primary-tint: #278480;
}

Every color="primary" button, toolbar and toggle now uses teal. You never need to touch the components.

Adding your own colour

Define the six variables and a class that connects them to Ionic's internal names:

CSS
:root {
  --ion-color-brand: #a21caf;
  --ion-color-brand-rgb: 162, 28, 175;
  --ion-color-brand-contrast: #ffffff;
  --ion-color-brand-contrast-rgb: 255, 255, 255;
  --ion-color-brand-shade: #8f189b;
  --ion-color-brand-tint: #ac32b8;
}

.ion-color-brand {
  --ion-color-base: var(--ion-color-brand);
  --ion-color-base-rgb: var(--ion-color-brand-rgb);
  --ion-color-contrast: var(--ion-color-brand-contrast);
  --ion-color-contrast-rgb: var(--ion-color-brand-contrast-rgb);
  --ion-color-shade: var(--ion-color-brand-shade);
  --ion-color-tint: var(--ion-color-brand-tint);
}

Now <ion-button color="brand"> works. The .ion-color-* class is what Ionic components apply when you set color.

Generating the shade and tint by hand is tedious. The rule of thumb is: shade is about 12% darker, tint about 10% lighter. This stand-in computes them from a base colour so you can see the calculation. It is JavaScript, not Ionic's own tool.

JS Stand-in: derive rgb, shade and tint

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Global variables

Besides colours, :root accepts layout and typography variables:

CSS
:root {
  --ion-font-family: 'Inter', system-ui, sans-serif;
  --ion-background-color: #ffffff;
  --ion-text-color: #1f2937;
  --ion-toolbar-background: #ffffff;
  --ion-item-background: #ffffff;
  --ion-safe-area-top: env(safe-area-inset-top);
}

Ionic also uses a step colour scale (--ion-color-step-50 to --ion-color-step-950) for borders and subtle backgrounds. Defining them is mainly necessary for dark mode.

Component-level variables

Each component documents variables of its own. Set them on the element, on a class, or under a parent selector to scope the change:

CSS
ion-toolbar {
  --background: var(--ion-color-primary);
  --color: var(--ion-color-primary-contrast);
}

.danger-zone ion-item {
  --background: #fee2e2;
  --border-color: #fca5a5;
}

Scoping like this keeps the change where you want it and avoids leaking into other pages.

Dark mode

Ionic ships three dark palettes, imported from CSS: dark.always.css, dark.class.css and dark.system.css.

TypeScript
// main.ts: follow the device setting
import '@ionic/react/css/palettes/dark.system.css';

With .system the app follows the OS setting through prefers-color-scheme. With .class you toggle a class on <html>:

TypeScript
function setDark(on: boolean) {
  document.documentElement.classList.toggle('ion-palette-dark', on);
}

Dark mode is a variable override under :root.ion-palette-dark, so you can customise it:

CSS
:root.ion-palette-dark {
  --ion-background-color: #0b1220;
  --ion-text-color: #e5e7eb;
  --ion-color-primary: #5eead4;
}

Here is a stand-in for the decision logic of a three-state theme switch (light, dark, system) with a saved preference. It cannot touch the real DOM here, so it works on a plain object:

JS Stand-in: light, dark or system

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Tips

  • Check contrast: text on primary must meet WCAG contrast (4.5:1 for normal text).
  • Test both modes whenever you add a custom colour.
  • Do not hard-code hex values in components; refer to variables so themes stay possible.
  • See platform modes for how mode-specific values layer on top.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where do you normally redefine the app palette?

    The theme variables file holds the --ion-color-* definitions.
  2. 2. What does --ion-color-primary-contrast define?

    Contrast is the foreground colour that stays readable on the base colour.
  3. 3. How do you make color="brand" work?

    Ionic applies the .ion-color-name class, which maps your variables to its internal ones.
  4. 4. Which palette file follows the operating system dark-mode setting?

    dark.system.css uses prefers-color-scheme.

Summary

  • Palette colours need six variables each (base, rgb, contrast, contrast-rgb, shade, tint).
  • Add custom colours with variables plus a .ion-color-name class.
  • Set global fonts and backgrounds on :root; set component variables on elements for scoped changes.
  • Dark mode uses the dark.always, dark.class or dark.system palettes.

Next: Platform Modes: iOS and Material Design