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.