A npm-script for creating custom icon fonts and an Angular 2 directive to render the icons in your Ionic 2 app.
- Description
- Installation
- Configuration
- Usage
- Example app
- Changelog
- Building the library
- Contribution
- License
- Acknowledgments
- Contact
The npm-script allows creating icon fonts from a given set of SVG vector images during the app's build phase. Internally the npm-script uses gulp and the awesome libraries gulp-iconfont (by Nicolas Froidure) to generate the SVG/TTF/EOT/WOFF/WOFF2 fonts and gulp-iconfont-scss (by Thomas Jaggi and Nicolas Froidure) to create Sass stylesheets from those generated fonts.
The Angular 2 directive CustomIcon provides a convenient way to embed the previously generated icon fonts in an Ionic 2 app by simply adding a component to the HTML template. See the following example:
<custom-icon set="myIconSet" name="myIcon"></custom-icon>A set of Sass/CSS rules comes along with directive, which allows adding icons to default Ionic 2 components like buttons and list items.
Theoretically the npm-script and directive should work within a generic Angular 2 environment with minor modifications but right now this is completely untested and unsupported.
Notice: Please be aware that there are serious reasons to not use icon fonts at all. See here for further discussions. But as the Ionic 2 team prefers icon fonts over other solutions, this is also the path I have chosen.
ionic2-custom-icons is available via the Node Package Manager (NPM). You can install the package with the following command:
npm install ionic2-custom-icons --save
The --save parameter is optional and saves a reference into the dependencies array in your project's package descriptor file package.json.
Ionic uses npm scripts and ionic-app-scripts for the build system. This new build system was introduced in version RC0.
In order to run this library's npm-script for building the icon fonts, you have to extend your package.json file. This file contains all dependencies of your app and is the main configuration for the build process.
Add a pre-build and a pre-watch script to the the scripts property:
...
"scripts": {
"prebuild": "ionic2-custom-icons",
"prewatch": "ionic2-custom-icons",
...
}
...
These scripts automatically get called BEFORE Ionic's build process starts. ionic2-custom-icons is the node script that runs the fonts creation. Thus the generated fonts and the SCSS data are ready to be processed and bundled by Ionic's build tools in the subsequent phase.
See the package.json of the example project for reference.
As already mentioned, the generated fonts and the SCSS data need to be processed and bundled in the main build phase of Ionic's build tools. For this to work you have to modify the paths processed by the copy and sass task which is achieved by extending Ionic's default configuration.
The first step to do so, is setting paths to custom config files for Ionic's copy and sass task. The ionic2-custom-icons library is also configured by a config file.
Add the following config property to your package.json:
...
"config": {
"ionic_copy": "./config/copy.config.js",
"ionic_sass": "./config/sass.config.js",
"custom_icons": "./config/custom-icons.config.js"
}
...
Note: Of course you can set any path you would like to use. Just make sure to adjust it in the next step.
Again, see the package.json of the example project for reference.
In this step you will set up the config files that are referenced in the previous step.
ionic-app-scripts provide default config files for the copy and sass task which you can copy and extend.
The safest way to get these config files is to look into your local node_modules directory.
node_modules/@ionic/app-scripts/config
Alternatively you can get the files from the project's GitHub repository: ionic-app-scripts/config. But be warned that these config files may be incompatible with your local installation as the code is being actively developed on.
Copy the files copy.config.js and sass.config.js to a directory called config in your app's root directory. See the following screenshot for a better understanding:
Add(!) the following object to the include array:
{
src: '.tmp-custom-icons/fonts/',
dest: 'www/assets/fonts/'
}
See the copy.config.js of the example project for reference.
Remove all properties except includePaths and variableSassFiles. (Don't worry about the now "missing" properties. Ionic merges them from the default config during the build process.)
Now add the following string to the includePaths array:
'.tmp-custom-icons/scss/'
Next, add the following string to the variableSassFiles array:
'.tmp-custom-icons/scss/variables.scss'
See the sass.config.js of the example project for reference.
This library also needs minimal configuration. You have to add each icon set you want to use to the file config/custom-icons.config.js.
See the following example:
// customIcons config
module.exports = {
iconSets: [
{
src: 'icons/my-icons-1/*.svg',
name: 'MyIcons1',
id: 'mi1
},
{
src: 'icons/my-icons-2/*.svg',
name: 'MyIcons2',
id: 'mi2
}
]
};
Each icon set needs to be added to the iconSets array. An icon set config is an object that consists of the following three properties: src, name and id:
| Option | Type | Description |
|---|---|---|
src |
stringor Array |
Source image files matching the provided glob or array of globs. Glob refers to node-glob syntax or a direct file path. See gulp.src(globs[, options]) for more info. |
name |
string |
A unique name for the icon set. May not contain whitespace. This value is used for naming the generated Sass files and the font-family property in the Sass files. |
id |
string |
A unique, preferably short, identifier string for the icon set. May not contain whitespace. Use this value for the directive's set attribute. |
Note: Make sure to use the module.exports property as presented in the example.
See the custom-icons.config.js of the example project for reference.
TODO
Using the Angular 2 directive in your Ionic 2 app to render custom icons is pretty easy.
As with every Angular 2 directive, you have to provide it's reference to use it in a template. Since Angular 2 RC5 this is done by using the @NgModule decorator function.
This library provides a module called CustomIconsModule. To use it in your app, locate your project's root module. Ionic names it app.module.ts by default. Add CustomIconsModule to the imports property of your app's root module configuration.
See the following example:
...
import { CustomIconsModule } from 'ionic2-custom-icons';
...
@NgModule({
...
imports: [
IonicModule.forRoot(MyApp),
CustomIconsModule // Add this!
],
...
})
export class AppModule {}See the app.module.ts of the example project for reference.
Use the directive as follows to render a custom icon in your app:
<custom-icon set="myIconSet" name="myIcon"></custom-icon>The directive has two data-bound input properties:
| Property | Type | Required | Description |
|---|---|---|---|
set |
string |
yes | The desired icon's set name as defined in the gulp taks's id option. |
name |
string |
yes | File name of the icon without it's file extension. Example: MyIcon.svg becomes MyIcon. |
Special use cases, like adding an icon to an Ionic Button, are also supported:
<button>
<custom-icon set="myIconSet" name="myIcon"></custom-icon>
My Button
</button>See the file icons.html in the example app for an overview.
Support for adding custom icons to Ionic's tab component was introduced in Version 0.2.0.
Instead of using the custom-icon directly, use the two properties customIconSet and customIconName inside the ion-tab component tag.
See the following example:
<ion-tabs class="tabs-icon-text">
...
<ion-tab customIconSet="mySet" customIconName="myIcon" tabTitle="My title" [root]="myPageCmp"></ion-tab>
...
</ion-tabs>Refer to the above table for the data-bound input property description. customIconSet is analogous to set and customIconName to name.
A fully working example app is provided in an independent GitHub repository: ionic2-custom-icons-example
A changelog with upgrade information is available here.
There are a few more steps required if you want to build the library. Please note, that this is not required if you just want to use the library in your Ionic 2 app.
Make sure that all npm dependencies are installed:
npm install
Build the library by running the following command:
npm run build
Any contribution is highly welcome! Please send pull requests, report bugs or request new features.
This project is licensed under the MIT License. See the LICENSE.md file for details.
The project originated during the development of the mobile app for the TU Dortmund University at the IT & Medien Centrum (ITMC) who kindly allowed me to release this piece of software to the public.
Gerrit Erpenstein gerrit.erpenstein.dev@gmail.com
Note: Please use the issue tracker for bug reports or feature requests.