k-icon

k-icon is a lightweight Angular library for managing and using SVG icons. The library allows you to easily display SVG icons in your Angular application.

Installation

To install the library, use npm:

npm install k-icon

To use this library, you need to provide http client module in your project. provideHttpClient() is the function that provides the HttpClient service.

For Angular 18 and above, you can add provideHttpClient() to app.config.ts:

export const appConfig: ApplicationConfig = {
  providers: [
    provideZoneChangeDetection({ eventCoalescing: true }), 
    provideRouter(routes), 
    provideHttpClient() // add this
  ],
};

Read more here, stackoverflow.com.

Usage

1. Prepare the assets/icons Directory

Ensure that your Angular project's public directory contains an assets/icons directory.

In the icons directory, place the SVG files you want to use. For example:

public/assets/icons/
  home.svg
  user.svg

• Storage icons (300+): https://github.com/kodoku-san/k-icon-storage

2. Use KIconComponent

Youtube demo using.

Import KIconComponent and use it as follows:

import { Component } from '@angular/core';
import { KIconComponent } from 'k-icon';

@Component({
  selector: 'app-root',
  template: `
    <k-icon name="home" width="30" height="30" stroke="red" stroke-width="2"></k-icon>
    <k-icon name="user" width="30" height="30" stroke="blue" stroke-width="2"></k-icon>
  `,
})
export class AppComponent {}

You can customize the way icons are fetched by using the setCustomIconLoader method in KIconService. This allows you to specify a custom logic to load icons from an API or any other source.

Example:

import { Component } from '@angular/core';
import { KIconService } from 'k-icon';
import { HttpClient } from '@angular/common/http';

@Component({
  selector: 'app-root',
  template: `
    <!-- from default path /assets/icons -->
    <k-icon name="home" width="30" height="30" stroke="red" stroke-width="2"></k-icon>

    <!-- from custom loader 1 -->
    <k-icon loader="loader-name-1" name="home" width="30" height="30" stroke="red" stroke-width="2"></k-icon>

    <!-- from custom loader 2 -->
    <k-icon loader="loader-name-2" name="home" width="30" height="30" stroke="red" stroke-width="2"></k-icon>
  `,
})
export class AppComponent {
  constructor(private iconService: KIconService, private http: HttpClient) {
    // Set custom loader to return URL
    this.iconService.setCustomIconLoader(
      'loader-name-1',
      (name: string) => `https://example.com/api/icons/${name}.svg`
    );

    // Alternatively, it is possible to set up a custom loader to return an Observable
    this.iconService.setCustomIconLoader(
      'loader-name-2',
      (name: string) => this.http.get(`https://example.com/api/icons/${name}.svg`, { responseType: 'text' })
    );
  }
}

• setCustomIconLoader(loaderName: string, loader: (name: string) => string | Observable<string>): Set a custom icon loader.

This feature allows you to fetch icons from any endpoint, giving you flexibility in how icons are managed and retrieved.

Other methods in KIconService

import { Component } from '@angular/core';
import { KIconService } from 'k-icon';

@Component({
  selector: 'app-root',
  template: `
    <!-- from path /assets/private-icons -->
    <k-icon name="home" width="30" height="30" stroke="red" stroke-width="2"></k-icon>
  `,
})
export class AppComponent {
  constructor(private iconService: KIconService) 
  {
    this.iconService.setDefaultIconPath('/assets/private-icons'); // default path for icons
    
    this.iconService.clearCache(); // clear all cache

    this.iconService.clearCache('loader-name-1'); // clear cache for loader-name-1

    this.iconService.removeCustomIconLoader('loader-name-1'); // remove custom loader
  }
}

• setDefaultIconPath(path: string): Set the default path for icons.
• clearCache(): void: Clear all icon cache.
• clearCache(loaderName: string): void: Clear icon cache for a specific loader.
• removeCustomIconLoader(loaderName: string): void: Remove a custom icon loader.

3. Display the Icon

You can display an icon using the KIconComponent in your template:

<k-icon name="home" width="30" height="30" stroke="red" stroke-width="2"></k-icon>
<k-icon name="user" width="30" height="30" stroke="blue" stroke-width="2"></k-icon>

Attribute Table for KIconComponent

| Attribute | Type | Default | Required | Description | |-----------------|--------------|----------------|----------|--------------------------------------------------------------------------| | loader | string | undefined | No | The name of the custom icon loader to use. If not specified, the icon will be loaded from the default path. | | name | string | N/A | Yes | The name of the SVG file (excluding the .svg extension). Example: home to load home.svg. | | width | string | undefined | No | The width of the icon, which can be set as a string with units (e.g., 30px, 2rem, etc.). | | height | string | undefined | No | The height of the icon, which can be set as a string with units (e.g., 30px, 2rem, etc.). | | stroke | string | currentColor | No | The color of the icon's stroke. Use any valid value for the SVG stroke attribute. | | stroke-width | string | 1.5 | No | The thickness of the stroke, which can be set as a string value (e.g., 2, 1.5). | | fill | string | none | No | The fill color of the icon. The default is none to leave the background transparent. You can change this as needed. | | class | string | '' (empty) | No | Additional CSS classes that can be applied to the SVG icon. | | viewbox | string | undefined | No | The viewBox property, which allows you to adjust the icon's scale and viewport. | | animation | string | undefined | No | The animation to apply to the icon. Currently supported animations: spin, pulse, bounce. | | animationDuration | string | undefined | No | The duration of the animation. | | animationTimingFunction | string | undefined | No | The timing function of the animation. | | animationIterationCount | string | undefined | No | The iteration count of the animation. | | lazyLoad | boolean | false | No | The lazy load of the icon. |

4. Configure IconService

IconService automatically retrieves SVG files from the assets/icons/ directory. No additional configuration is needed; just ensure that the SVG files are placed correctly.

5. Animation Support

k-icon now supports animations for SVG icons. You can add animations to your icons using the animation attribute:

<!-- single animation -->
<k-icon name="spinner" animation="spin"></k-icon>

<!-- multiple animations -->
<k-icon name="spinner" [animation]="['spin', 'fade']"></k-icon>

<!-- custom animation -->
<k-icon name="spinner" animation="custom-animation"></k-icon>

<!-- animation with custom duration, timing function, and iteration count -->
<k-icon
  name="spinner"
  [animation]="['spin', 'fade']"
  animationDuration="1s"
  animationTimingFunction="linear"
  animationIterationCount="3" />

The animation attribute accepts an array of animations.

• If you want to use multiple animations, you can use an array.
• If 2 animations are of the same type or any css animation, the last animation will be applied.
• If you want to use custom animation, you can use KIconService or Css Style Global to add new custom animation.

Animation Attributes

| Attribute | Type | Default in component | Default in css | Required | Description | |-----------------|--------------|----------------------|----------------|----------|--------------------------------------------------------------------------| | animation | KIconAnimations | undefined | undefined | No | The animation to apply to the icon. | | animationDuration | KIconAnimationDuration | undefined | 1s | No | The duration of the animation. | | animationTimingFunction | KIconAnimationTimingFunction | undefined | linear | No | The timing function of the animation. | | animationIterationCount | KIconAnimationIterationCount | undefined | infinite | No | The iteration count of the animation. |

Currently supported animations: spin, pulse, bounce, snake, fade, swing, shake.

Dynamic Animation

This component has the ability to dynamically change its animation based on the state of the component. This is achieved through the use of property binding in Angular.

How it works:

1. The component defines a property for the animation:

   testAnimation: KIconAnimation = 'spin';

2. This property is bound to the animation attribute of k-icon:

   <k-icon
     [animation]="testAnimation"
     name="spinner"
     width="30"
     height="30"
   />

3. When the value of testAnimation changes, the icon's animation changes accordingly:

   changeAnimation() {
     this.testAnimation = this.testAnimation === 'spin' ? 'pulse' : this.testAnimation === 'pulse' ? 'bounce' : 'spin';
     // This demo is a simple example. It changes 3 animations in turn: spin, pulse, bounce
   }

This allows the icon's animation to change dynamically based on application logic, creating a more interactive and engaging user experience.

Example:

import { Component } from '@angular/core';
import { KIconComponent, KIconAnimation } from 'k-icon';

@Component({
  selector: 'app-dynamic-icon',
  standalone: true,
  template: `
    <k-icon
      [animation]="currentAnimation"
      name="spinner"
      width="30"
      height="30"
    />
    <button (click)="changeAnimation()">Change Animation</button>
  `
})
export class DynamicIconComponent {
  currentAnimation: KIconAnimation = 'spin';

  changeAnimation() {
    const animations: KIconAnimation[] = ['spin', 'pulse', 'bounce'];
    const currentIndex = animations.indexOf(this.currentAnimation);
    this.currentAnimation = animations[(currentIndex + 1) % animations.length];
  }
}

In this example, clicking the button will cycle through different animations for the icon, demonstrating how the animation can be dynamically changed based on user interaction or other application states.

In addition, KIconDuration, KIconTimingFunction, and KIconIterationCount also can be dynamically changed.

6. Custom Animations

k-icon allows you to create and use custom animations, giving you the flexibility to design unique icon behaviors tailored to your application's needs.

Creating a Custom Animation

1. Define your custom animation in your global styles (e.g., styles.css or styles.scss):

Add prefix k-icon- to animation name to avoid conflicts with other animations. (Required)

@keyframes k-icon-custom-bounce {
  0%, 100% { transform: translateY(0); }
  50% { transform: translateY(-10px); }
}

2. Use the custom animation in your component:

<!-- animation name without `k-icon-` prefix will be ignored -->
<k-icon name="your-icon" animation="custom-bounce"></k-icon>

This is how to custom animation by writing directly in css file. In addition, you can custom animation by using KIconService.

Creating a Custom Animation with KIconService

import { KIconService } from 'k-icon';

@Component({
  selector: 'app-root',
  standalone: true,
  template: `
    <k-icon name="your-icon" animation="custom-bounce"></k-icon>
  `
})
export class YourComponent {
  constructor(private iconService: KIconService) 
  {
    iconService.addCustomAnimation(
      'custom-bounce', 
      `
        0%, 100% { transform: translateY(0); }
        50% { transform: translateY(-10px); }
      `
    ); // this only. Without @keyframes
  }
}

This method allows you to add custom animations to your icons without the need to define them in your global styles.

Currently, k-icon animation features are quite flexible to customize. You can try to combine it, to see the benefits and more interesting things

7. Lazy Load

k-icon supports lazy load for icons. You can use lazyLoad attribute to lazy load the icon.

<k-icon [lazyLoad]="true" name="home" width="30" height="30" stroke="red" stroke-width="2" />

By default, lazyLoad is false. If lazyLoad is true, the icon will be loaded when the KIconComponent is loaded and this k-icon tag is in viewport.

Notes

• The library does not include any SVG files by default. You need to add your own SVG files to the assets/icons/ directory.
• k-icon cache the icons after they have been loaded to avoid reloading them from the server.
• k-icon supports both Angular standalone components and NgModules.
• In the current version, I'm trying to improve the performance and reduce the size of the library. Looking forward to the next version, I will add more features and improve the performance. The biggest criteria of k-icon is compactness and flexibility. I will develop based on that criteria.

Troubleshooting

If you encounter any issues, please check the following:

1. Ensure that your SVG files are placed in the correct directory (assets/icons/ by default).
2. Check that the icon names in your code match the filenames of your SVG files (without the .svg extension).
3. Make sure you have provided the HttpClient in your app configuration.

If you're still having problems, please open an issue on the GitHub repository.

License

This package is licensed under the MIT License. See the LICENSE file for details.

KODOKU