Customizing Ionic With Sass

The core of Ionic's CSS is built using Sass.

One thing that makes Sass such a powerful tool is its variables feature. By modifying existing Ionic Sass variables, we've made it easy to achieve your desired theme.

Ionic already comes with a complete CSS stylesheet built from our default Sass files, so if you have little to customize, it is probably better to stick with the default CSS file and override the few properties you need. However, if you have big plans for your theme, and/or your app will be a large project, then we highly recommend leveraging the power of Sass to simplify development.

Install or Upgrade Sass

  • Haven't installed Sass yet? Then Install Sass.
  • If you already have Sass installed, make sure you have the latest version: gem update sass.
  • In a terminal or command prompt, enter sass -v to verify Sass has been setup correctly and to see which version you're running (it should be the most recent version, if all goes swimmingly).

Ionic Source Files

Once you have node and npm ready to go on your machine, start an Ionic project using the Ionic CLI with the following commands:

npm install -g ionic cordova
ionic start my_app
cd my_app

Your App Directory Structure

At the root level of an Ionic project, you'll find a directory structure like the following:

- my_app
  - hooks
  - plugins
  - scss
  - www
    - css
    - fonts
    - js
    - lib
      - ionic
        - css
        - js
        - sass
    - templates

All the Sass magic starts from your app's scss/ directory. Additionally, the code that builds Ionic's default icon font, Ionicons, can be found in your app's www/lib/ionic/scss/ionicons/ directory . However, at this point, all you need to be concerned about are the files in the scss/ directory, which will eventually output your custom CSS into the css/ directory.

We recommend that your app have its own Sass file within the scss/ directory, such as scss/ From within your file, you'll want to import the sass sheets from Ionic, using this syntax:

// your variable changes can go here

@import "www/lib/ionic/scss/ionic";

// your slick styles can go here...
// when Sass processes, both Ionic's Sass and your Sass will combine
// into one file and saved in your app's directory as www/css/app.css

"Watch" Your Sass!

Browsers still need to reference plain old CSS files, since they do not understand Sass files. Because of this, the Sass files will need to be processed into a CSS file. Sass is able to take many files and combine them into one CSS file, which is yet another reason why Sass is a powerful development tool.

To automatically output a CSS file that the browser will understand, you'll want to "watch" your app's Sass files for any changes. Every time changes are saved to a Sass file, the CSS file will automatically rebuild. In your terminal, enter:

sass --watch scss/

The above command instructs Sass to constantly watch in the scss/ directory. Once a Sass file changes, it will rebuild the CSS file and resave the www/css/ionic.css file. For more information regarding watching Sass files, please see their documentation. Once you have successfully run this command, you are ready to start customizing.

Sass Variables

Think of variables as a way to store information that you want to reuse throughout your stylesheet. You can store things like colors, font stacks, or any CSS value you want to reuse.

-- Sass Variables Documentation

Inside your app's www/lib/ionic/scss directory, the Ionic Framework has already been built with a _variables.scss file. The variables file is the first place to go when you want to customize any of the default styles. For example, Ionic comes with a small set of colors to start with, but as a general rule, colors are meant to be overridden to fit your "brand."

$light:                 #fff !default;
$stable:                #f8f8f8 !default;
$positive:              #4a87ee !default;
$calm:                  #43cee6 !default;
$balanced:              #66cc33 !default;
$energized:             #f0b840 !default;
$assertive:             #ef4e3a !default;
$royal:                 #8a6de9 !default;
$dark:                  #444 !default;

Feel free to customize these variables as much as you'd like (after all, the world doesn't need a bunch of apps that look identical). While you can change the _variables.scss file directly, we recommend you override these variables in your own file. By not changing the variables files directly and instead simply overriding its values, it makes it easier to upgrade Ionic as new versions come out. Once a change is made, the CSS file will be rebuilt using the new values you've specified.

Colors are only one example, however. You'll see throughout the _variables.scss file that you can override many different properties, such as padding, font sizes, margins, border colors, widths, heights, etc. There's absolutely no need to change them all, but they are there to be tweaked if you choose to. Below is an example of your file importing ionic.scss, then overriding a few variables:

$light:                 #fff;
$stable:                #f8f8f8;
$positive:              #4ea4be;

// Any variables you did not define will use the defaults
@import "www/lib/ionic/scss/ionic";

Full Customization

Changing the variables is the easiest way to start modifying your Ionic app. However, there is nothing stopping you from going into each of the separate Sass files and customizing them to fit your requirements. (And if you've got a few cool tricks up your sleeve that you think others may find useful, we'd love to have you contribute to Ionic).

Now, start building some awesome apps, and tell us all about it!