ng-symbols-viewer

Angular Symbols Viewer

Angular Symbols Viewer helps developers to easily manage their project icons / symbols library. It create quick view of all the svg symbols available on your angular project.

It also comes with a search functionality and auto-generated html code to use these icons / symbols with the selected sizes.

Angular Symbols Viewer is non-intrusive and accessible from any page by clicking on the hidden button that appear when placing the cursor on the bottom right corner of the window.

Install

npm i ng-symbols-viewer

Usage

Import Module

You need to import the NgSymbolsViewerModule in the module of your app where you want to use it (usually AppModule or SharedModule).

Exemple for import in AppModule :

import { BrowserModule } from "@angular/platform-browser";
import { NgModule } from "@angular/core";

import { AppComponent } from "./app.component";
import { NgSymbolsViewerModule } from "ng-symbols-viewer";

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule, NgSymbolsViewerModule],
  providers: [],
  bootstrap: [AppComponent],
})
export class AppModule {}

Selector

Basics

Use the <ng-symbols-viewer></ng-symbols-viewer> selector to make the Symbols Viewer available on your project.

CAUTION The <ng-symbols-viewer></ng-symbols-viewer> selector should only be used once in your project. Having multiple selectors at the same time will cause issues.

/!\ IMPORTANT While Angular Symbols Viewer config is optional, it is meant to help developers and therefore only being accessible on a DEV environment.

It is strongly recommended to set a default config with the minimal excludedEnv option.

Exemple :

import { environment } from "src/environments/environment";

myConfig = {
  excludedEnv: environment.production,
};

<ng-symbols-viewer [config]="myConfig"></ng-symbols-viewer>

See more details in the Options section.

Recommendations

I recommend placing the <ng-symbols-viewer></ng-symbols-viewer>

• either directly inside the app.component.html right after the <router-outlet></router-outlet>
• or right next to your svg symbols declaration.

Exemple :

<ng-symbols-viewer></ng-symbols-viewer>

<svg style="display: none">

  <symbol id="icon-search" viewBox="0 0 24 24">
    <path fill="currentColor" d="..." />
  </symbol>

  [...]

</svg>

Search & data-labels

Angular Symbols Viewer include a search functionnality that allows you to find icons / symbols by id. You can also add more search keywords / tags to a <symbol> with the data attribute data-labels

Exemple :

<symbol
  id="icon-delete"
  viewBox="0 0 24 24"
  data-labels="remove, trash, erase, cancel"
>
  <path fill="currentColor" d="..." />
</symbol>

CSS & icons sizes

Angular Symbols Viewer comes with some default classes and values for your icons sizes. Add this css code to your project common styles :

[class^="icon-"],
[class~=" icon-"],
.icon {
    display: inline-block;
}

.icon { width: 32px; width: 32px; }
.icon-xs { width: 16px; width: 16px; }
.icon-sm { width: 24px; width: 24px; }
.icon-lg { width: 48px; width: 48px; }
.icon-xl { width: 64px; width: 64px; }

If you don't want to use the default values, you can apply new class prefix or/and new icon sizes in the [config].

Exemple :

Step 1 : Create your custom config

myConfig = {
  classPrefix: 'symbol'
  sizes: [
    {name:'default', size: 24},
    {name:'small', size: 16},
    {name:'big', size: 50},
  ],
};

Step 2 : Create your custom icons styles

[class^="symbol-"],
[class~=" symbol-"],
.symbol {
    display: inline-block;
}

.symbol { width: 24px; width: 24px; }
.symbol-small { width: 16px; width: 16px; }
.symbol-big { width: 50px; width: 50px; }

Step 3 : Profit

<ng-symbols-viewer [config]="myConfig"></ng-symbols-viewer>

Options

Here is the list of all currently available options to be used in the [config]

Option	Type	Default	Description
classPrefix	string	"icon"	The class prefix that will be used in the auto-generated html code
excludedEnv	boolean	false	If true, the Angular Symbols Viewer will NOT be accessible. More details here.
sizes	SymbolsViewerSize[]	defaultSizes	Define the different selectable sizes.

Environments

Make Angular Symbols Viewer unavailable to Production environment :

import { environment } from "src/environments/environment";

myConfig = {
  excludedEnv: environment.production,
};

Make Angular Symbols Viewer unavailable to multiple environments :

import { environment } from "src/environments/environment";

myConfig = {
  excludedEnv: environment.testing || environment.preprod || environment.production,
};

Config default values

Default sizes

[
  {
    name: 'xs',
    size: 16
  },
  {
    name: 'sm',
    size: 24
  },
  {
    name: 'default',
    size: 32
  },
  {
    name: 'lg',
    size: 48
  },
  {
    name: 'xl',
    size: 64
  },
];