README

ng-favicon

A simple angular service to change favicon or display unread messages and notifications on top of favicon

this.faviconService.set('iconName');

Simple favicon changes
Configurable icon sets
Predefined renderers to display unread messages and notifications on top of default favicon
Custom resolvers and icon generators can be plugged in

Examples/Demo

Demo
A simple example can be found under src/app directory of this repository.

Getting started

Step 1: Install `ng-favicon`:

npm

npm install --save @enzedd/ng-favicon

yarn

yarn add @enzedd/ng-favicon

Step 2: Import `FaviconModule`:

import {FaviconModule} from '@enzedd/ng-favicon';

@NgModule({
  declarations: [AppComponent],
  imports: [
    ...
    FaviconModule,
  ],
  bootstrap: [AppComponent]
})
export class AppModule {}

Step 3: Inject `FaviconService` in component constructor

import {FaviconService} from '@enzedd/ng-favicon';

@Component({
    ...
})
export class AppComponent {
    constructor(private faviconService: FaviconService) {
    }
}

Step 4: Use `FaviconService` methods to set favicons

import {FaviconService} from '@enzedd/ng-favicon';

@Component({
    ...
    template: `<button type="button" (click)="setFavicon($event)">Set favicon</button>`,
})
export class AppComponent {
    constructor(private faviconService: FaviconService) {
    }

    setFavicon($event) {
        $event.preventDefault();
        this.faviconService.setDot();
    }
}

See API section for other FaviconService methods

Configuration

All configuration items are optional

Named favicons configuration

Configure application favicons by providing values for FAVICON_CONFIG token in a NgModule e.g. src/app/app.module.ts

import {FAVICON_CONFIG} from '@enzedd/ng-favicon';

@NgModule({
    ...
    providers: [
        {
            provide: FAVICON_CONFIG,
            useValue: {
                icons: {
                    dotted: {
                        rel: 'icon',
                        type: 'image/png',
                        sizes: '32x32',
                        href: 'assets/images/favicons/favicon-dotted-32x32.png'
                    },
                },
            },
        },
    ],
})
export class AppModule {
}

Values can be provided as a single icon or as icon set (multiple sizes of same icon for different devices). It is recommended to keep in sync icon count and types in html and configuration. Otherwise app icon may disappear on some devices when changed.

    providers: [
        {
            provide: FAVICON_CONFIG,
            useValue: {
                icons: {
                    dotted: [{
                        rel: 'icon', type: 'image/png', sizes: '16x16',
                        href: 'assets/images/favicons/favicon-dotted-16x16.png'
                    }, {
                        rel: 'icon', type: 'image/png', sizes: '32x32',
                        href: 'assets/images/favicons/favicon-dotted-32x32.png'
                    }],
                },
            },
        },
    ],

Colors configuration

Favicon notification text and background colors can be configured

    providers: [
        {
            provide: FAVICON_CONFIG,
            useValue: {
                color: '#fff',    // favicon notification text color
                bgColor: '#00f',  // favicon notification background color
                icons: {
                    ...
                },
            },
        },
    ],

API

Methods

setDefault()

Resets favicon to default

set()

Sets favicon by name. Requires favicons to be configured. See configuration section for details.

Parameter	Type	Default	Required	Description
name	string	null	no	Name of icon or icon set. If name is null, resets to default.

setIcon()

Set icon

Parameter	Type	Default	Required	Description
href	string	-	yes	Icon url or dataUrl
rel	string	'icon'	no	Icon rel
type	string	null	no	Icon type
sizes	string	null	no	Icon size
cacheKey	string	null	no	Cache key. If set, icon is cached and accessible by name

setIcons()

Set icon set

Parameter	Type	Default	Required	Description
icons	Icon[]	-	yes	Icon set
cacheKey	string	null	no	Cache key. If set, icon set is cached and accessible by name

setNumber()

Sets number overlay on default favicon. Use to display unread messages and notifications.

Parameter	Type	Default	Required	Description
num	number	-	yes	Number to set
options	NumberRendererOptions	null	no	Options

returns Icon set observable

setDot()

Sets dot overlay on default favicon. Use to indicate the presence of notifications.

Parameter	Type	Default	Required	Description
options	DotRendererOptions	null	no	Options

returns Icon set observable

setCustom()

Sets custom favicon using GetIconFn. Use for custom implementations of favicon resolving or generation.

Parameter	Type	Default	Required	Description
getIconFn	GetIconFn	-	yes	Icon resolving or generating function
options	any	null	no	Options
cacheKey	string	null	no	Cache key. If set icon is cached and not regenerated again

returns Icon set observable

Example 1: Resolve favicon

Do any icon handling to get new favicon url

setCustomFavicon1($event) {
    function getIcon(options, defaultIcons?: IconMap): Observable<Icon[]> {
        const icon: Icon = Object.values(defaultIcons)[0];
        const url = icon.href.slice(0, icon.href.length - 9) + 'dotted' + icon.href.slice(icon.href.length - 10, icon.href.length);
        return of([{
            rel: icon.rel, type: icon.type, sizes: icon.sizes,
            href: url,
        }]);
    }

    $event.preventDefault();
    this.faviconService.setCustom(getIcon);
}

Example 2: Generate favicon

Provide function to draw your own favicon

setCustomFavicon2($event) {
    function dotRenderer(options, defaultIcons?: IconMap): Observable<Icon[]> {
        const icon: Icon = Object.values(defaultIcons)[0];
        const img: HTMLImageElement = new Image();
        img.src = icon.href;
        return fromEvent(img, 'load').pipe(
            map((event: Event) => event.target),
            map((image: HTMLImageElement) => {
                const canvas = document.createElement('canvas');
                canvas.width = image.width;
                canvas.height = image.height;
                const context = canvas.getContext('2d');
                context.drawImage(image, 0, 0);
                context.fillStyle = 'blue';
                context.beginPath();
                context.arc(context.canvas.width * 0.7, context.canvas.height * 0.75,
                    context.canvas.width * 0.25, 0, Math.PI * 2);
                context.closePath();
                context.fill();
                return [{
                    rel: icon.rel, type: icon.type, sizes: icon.sizes,
                    href: canvas.toDataURL(),
                }];
            })
        );
    }

    $event.preventDefault();
    this.faviconService.setCustom(dotRenderer);
}

cacheIcon()

Put icon to cache in runtime. May override configured icons.

Parameter	Type	Default	Required	Description
name	string	-	yes	Cache key
href	string	-	yes	Icon url or dataUrl
rel	string	'icon'	no	Icon rel
type	string	null	no	Icon type
sizes	string	null	no	Icon size

cacheIcons()

Put icon set to cache in runtime. May override configured icons.

Parameter	Type	Default	Required	Description
href	string	-	yes	Icon url or dataUrl
iconSet	Icon[]	-	yes	Icon set

resetCache()

Resets cache to configured only favicons

Interfaces

NumberRendererOptions

Field	Type	Default	Required	Description
color	string	'#fff'	no	Number color (hex format)
bgColor	string	'#f00'	no	Number background color (hex format)

Options can be configured globally, see configuration section for details.

DotRendererOptions

Field	Type	Default	Required	Description
color	string	'#f00'	no	Dot color (hex format). Can be configured globally, set bgColor in configuration.
centerX	number	0.7	no	Relative position by x axis (from 0 to 1)
centerY	number	0.25	no	Relative position by y axis (from 0 to 1)
radius	number	0.25	no	Radius relative to icon size (from 0 to 1)

GetIconFn

Parameter	Type	Default	Required	Description
options	any		yes	Options passed from setCustom
defaultIcons	[sizes: string]: Icon		yes	Default icons

returns Observable<Icon[]>

Icon

Field	Type	Default	Required	Description
href	string		yes	Icon url or dataUrl
rel	string	null	no	Icon rel
type	string	null	no	Icon type
sizes	string	null	no	Icon size

Development

Library location is under projects/ng-favicon directory of this repository.

Demo application is under src directory of this repository.

Development server

Run npm run lib:watch to incrementally build library as a background process in your dev environment

Run ng serve for a dev server. Navigate to http://localhost:4200/. The app will automatically reload if you change any of the source files.

Build library

Run npm run lib:build to build the project. The build artifacts will be stored in the dist/ directory.

Publishing

After building your library, go to the dist folder cd dist/ng-favicon and run npm publish.

Running unit tests

Run npm run lib:test to execute the library unit tests via Karma.

Usage no npm install needed!

README

ng-favicon

Examples/Demo

Getting started

Step 1: Install ng-favicon:

Step 2: Import FaviconModule:

Step 3: Inject FaviconService in component constructor

Step 4: Use FaviconService methods to set favicons

Configuration

Named favicons configuration

Colors configuration

API

Methods

setDefault()

set()

setIcon()

setIcons()

setNumber()

setDot()

setCustom()

Example 1: Resolve favicon

Example 2: Generate favicon

cacheIcon()

cacheIcons()

resetCache()

Interfaces

NumberRendererOptions

DotRendererOptions

GetIconFn

Icon

Development

Development server

Build library

Publishing

Running unit tests

Step 1: Install `ng-favicon`:

Step 2: Import `FaviconModule`:

Step 3: Inject `FaviconService` in component constructor

Step 4: Use `FaviconService` methods to set favicons