Ionic gives you nine default colors: primary, secondary, tertiary, success, warning, danger, dark, medium, and light. They cover most common UI needs, but are they always enough?
Maybe your design calls for a unique accent or a specific brand color that doesn’t fit into the default palette. That’s when adding a custom color becomes the better approach.
In this guide, we’ll walk through how Ionic handles colors under the hood, why using custom colors makes sense, and how to implement them cleanly in your project using SCSS.
How Ionic Handles Colors?
Colors in Ionic aren’t just single values, but they’re collections of CSS variables that define how components look across different states. Each color includes:
- a base color (used as the main background or fill)
- a contrast color (used for text or icons on top)
- a shade (darker variation)
- a tint (lighter variation)
Each of these also has an RGB version defined separately. This is important because some components use RGB for handling opacity or overlays, and having both HEX and RGB ensures consistent rendering.
When you assign a color to a component using the color attribute (like <ion-button color="primary">), Ionic looks for that color’s full variable set and applies it automatically, including the shade and tint for pressed or hovered states.
All of this is handled using CSS custom properties defined at the :root level and tied together using a class like .ion-color-primary.
When Ionic Built-In Colors Aren’t Enough?
The default color set is designed to cover broad use cases like status indicators, branding defaults, readable contrasts, etc. However, the downside is that it’s still fixed to semantic meaning.
For example, using danger to display a promotional banner just because it’s red can be confusing for users. Modifying built-in colors like primary or secondary is possible, but you’re limited in how many you can safely reuse.
Hence, adding new colors from scratch is the safer and more scalable option. So, let’s build a custom color in Ionic.
Steps to Add a Custom Color in Ionic
To define a new color that works just like Ionic’s built-in ones, you’ll need to:
1. Pick a Color Name and Base Value
Choosing a unique name like brandAccent helps you reference the color consistently throughout your app. The base value is the primary HEX color that defines how it looks across all components.
2. Define the Required CSS Variables
Ionic relies on six variables per color to handle different component states and themes. These include the base color, contrast text color, and subtle variations for shading and tinting.
:root {
--ion-color-brandAccent: #4edfe9;
--ion-color-brandAccent-rgb: 78,223,233;
--ion-color-brandAccent-contrast: #000000;
--ion-color-brandAccent-contrast-rgb: 0, 0, 0;
--ion-color-brandAccent-shade: #45c4cd;
--ion-color-brandAccent-tint: #60e2eb;
}3. Create the Color Class Block
It links your new color variables to Ionic’s internal system. When you use the color in a component, Ionic applies these properties automatically using the .ion-color-{name} convention.
.ion-color-brandAccent {
--ion-color-base: var(--ion-color-brandAccent);
--ion-color-base-rgb: var(--ion-color-brandAccent-rgb);
--ion-color-contrast: var(--ion-color-brandAccent-contrast);
--ion-color-contrast-rgb: var(--ion-color-brandAccent-contrast-rgb);
--ion-color-shade: var(--ion-color-brandAccent-shade);
--ion-color-tint: var(--ion-color-brandAccent-tint);
}Pro Tip: If you don’t want to calculate shades and contrasts manually, you can generate this code using the Ionic Color Generator.
4. Import It into Your Global Styles
This step makes sure your color definitions are loaded into the app’s global stylesheet. Without this import, the custom variables and class won’t be recognized.
// global.scss
@import './theme/colors.scss';Note: Make sure colors.scss is placed in your src/theme/ folder, or update the path accordingly in global.scss.
5. Use It in Your Components
Once everything is set up, you can use your custom color just like any built-in Ionic color. Add it via the color attribute on supported components.
<ion-button color="brandAccent">
Use Custom Color
</ion-button>Wrapping Up
Custom colors work best when they’re added consistently and purposefully. Instead of overwriting built-in semantic colors like danger or warning, define your own names that clearly reflect their role, like brandAccent, promoBanner, or userBadge.
As a best practice, always define the full color set: base, contrast, shade, tint, and their RGB variants. This ensures the color behaves correctly across all Ionic components, including buttons, cards, alerts, and overlays. Keep all custom color definitions in a separate SCSS file and import them into the global.scss to keep things organized and maintainable.