@ronnie.barker/angular-fontawesome

angular-fontawesome

Font Awesome 5 Angular component using SVG with JS

• Get started
  • Upgrading Font Awesome?
  • Is this the package for you?
  • Learn about our new SVG implementation
  • Going from an older pre-release version?
• Installation
• Add more styles or Pro icons
• Usage
  • Explicit reference
  • Using the Icon Library
  • Using other styles
  • Changing the default prefix
• Features
  • Basic
  • Advanced usage
• Examples
• Tree Shaking
• How to Help
• Contributors
• Releasing this project

Get started

Built with ng-packagr and conforming to the Angular Package Format.

Hey there! We're glad you're here...

Upgrading Font Awesome?

If you've used Font Awesome in the past (version 4 or older) there are some things that you should learn before you dive in.

https://fontawesome.com/how-to-use/on-the-web/setup/upgrading-from-version-4

Is this the package for you?

This package is for integrating with Angular (not AngularJS). If you aren't using Angular then it's not going to help you. Head over to our "Get Started" page for some guidance.

https://fontawesome.com/how-to-use/on-the-web/setup/getting-started

Learn about our new SVG implementation

This package, under the hood, uses SVG with JS and the @fortawesome/fontawesome-svg-core library. This implementation differs drastically from the web fonts implementation that was used in version 4 and older of Font Awesome. You might head over there to learn about how it works.

https://fontawesome.com/how-to-use/on-the-web/advanced/svg-javascript-core

Going from an older pre-release version?

See UPGRADING.md.

You might also be interested in the larger umbrella project UPGRADING.md

Installation

$ yarn add @fortawesome/fontawesome-svg-core
$ yarn add @fortawesome/free-solid-svg-icons
$ yarn add @fortawesome/angular-fontawesome

Add more styles or Pro icons

Brands are separated into their own style and for customers upgrading from version 4 to 5 we have a limited number of Regular icons available.

Visit fontawesome.com/icons to search for free and Pro icons

$ yarn add @fortawesome/free-brands-svg-icons
$ yarn add @fortawesome/free-regular-svg-icons

If you are a Font Awesome Pro subscriber you can install Pro packages.

$ yarn add @fortawesome/pro-solid-svg-icons
$ yarn add @fortawesome/pro-regular-svg-icons
$ yarn add @fortawesome/pro-light-svg-icons

Using the Pro packages requires additional configuration.

Usage

These examples are based on a freshly created project with Angular CLI.

Explicit reference

Not as convenient as using the library but if you believe "explicit is better than implicit" then this method is for you.

src/app/app.component.html

<div style="text-align:center">
  <fa-icon [icon]="faCoffee"></fa-icon>
</div>

src/app/app.component.ts

import { Component } from '@angular/core';
import { faCoffee } from '@fortawesome/free-solid-svg-icons';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  title = 'app';
  faCoffee = faCoffee;
}

src/app/app.module.ts

1. Import { FontAwesomeModule } from '@fortawesome/angular-fontawesome'
2. Add FontAwesomeModule to imports

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

import { AppComponent } from './app.component';
import { FontAwesomeModule } from '@fortawesome/angular-fontawesome';

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

Using the Icon Library

The icon library provides convenient usage in your templates but you have to manage the icons separate from your components. This means that if someone accidentally removes the icon from the icon library your component which uses it could break.

Icons can be registered once in app.module with library.add(). Icons added to the library will be available to any other component whose parent module also imports FontAwesomeModule. This eliminates the need to redefine or explicitly import icons into individual components across multiple modules, lazy-loaded or not.

src/app/app.component.html

<div style="text-align:center">
  <!-- simple name only that assumes the 'fas' prefix -->
  <fa-icon icon="coffee"></fa-icon>
  <!-- ['fas', 'coffee'] is an array that indicates the [prefix, iconName] -->
  <fa-icon [icon]="['fas', 'coffee']"></fa-icon>
</div>

src/app/app.module.ts

1. Import { FontAwesomeModule } from '@fortawesome/angular-fontawesome'
2. Add FontAwesomeModule to imports
3. Import { library } from '@fortawesome/fontawesome-svg-core'
4. Import an icon like { faCoffee } from '@fortawesome/free-solid-svg-icons'
5. Add to the library with library.add(faCoffee)

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

import { AppComponent } from './app.component';
import { FontAwesomeModule } from '@fortawesome/angular-fontawesome';
import { library } from '@fortawesome/fontawesome-svg-core';
import { faCoffee } from '@fortawesome/free-solid-svg-icons';

// Add an icon to the library for convenient access in other components
library.add(faCoffee);

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

You can also import entire icon styles. But be careful! Whatever you import may end up bloating your final bundle with icons you're not using.

import { library } from '@fortawesome/fontawesome-svg-core';
import { fas } from '@fortawesome/free-solid-svg-icons';
import { far } from '@fortawesome/free-regular-svg-icons';

library.add(fas, far);

Using other styles

Adding a brand icon

import { faTwitter } from '@fortawesome/free-brands-svg-icons';

// Add an icon to the library for convenient access in other components
library.add(faTwitter);

<fa-icon [icon]="['fab', 'twitter']"></fa-icon>

Adding an icon from the Regular style:

import { faCalendar } from '@fortawesome/free-regular-svg-icons';

// Add an icon to the library for convenient access in other components
library.add(faCalendar);

<fa-icon [icon]="['fas', 'calendar']"></fa-icon>

Adding an icon from the Pro-only Light style:

import { faArrowAltRight } from '@fortawesome/pro-light-svg-icons';

// Add an icon to the library for convenient access in other components
library.add(faArrowAltRight);

<fa-icon [icon]="['fal', 'calendar']"></fa-icon>

Features

The following features are available as part of Font Awesome. Note that the syntax is different from our general web-use documentation.

Basic

Size:

<fa-icon [icon]="['fas', 'coffee']" size="xs"></fa-icon>
<fa-icon [icon]="['fas', 'coffee']" size="lg"></fa-icon>
<fa-icon [icon]="['fas', 'coffee']" size="6x"></fa-icon>

Fixed width:

<fa-icon [icon]="['fas', 'coffee']" [fixedWidth]="true"></fa-icon>

Rotate:

<fa-icon [icon]="['fas', 'coffee']" rotate="90"></fa-icon>
<fa-icon [icon]="['fas', 'coffee']" rotate="180"></fa-icon>
<fa-icon [icon]="['fas', 'coffee']" rotate="270"></fa-icon>

Flip horizontally, vertically, or both:

<fa-icon [icon]="['fas', 'coffee']" flip="horizontal"></fa-icon>
<fa-icon [icon]="['fas', 'coffee']" flip="vertical"></fa-icon>
<fa-icon [icon]="['fas', 'coffee']" flip="both"></fa-icon>

Spin and pulse animation:

<fa-icon [icon]="['fas', 'spinner']" [spin]="true"></fa-icon>
<fa-icon [icon]="['fas', 'spinner']" [pulse]="true"></fa-icon>

Border:

<fa-icon [icon]="['fas', 'coffee']" [border]="true"></fa-icon>

Pull left or right:

<fa-icon [icon]="['fas', 'coffee']" pull="left"></fa-icon>
<fa-icon [icon]="['fas', 'coffee']" pull="right"></fa-icon>

Changing the default prefix

The default prefix, fas, can be adjusted by injecting the FaIconService and modifying the defaultPrefix property.

import { FaIconService } from '@fortawesome/angular-fontawesome';

export class AppComponent {

  constructor(private faIconService: FaIconService) {
      this.faIconService.defaultPrefix = 'far';
  }

}

Advanced Usage

With Mask and Transform:

<fa-icon [icon]="['fas', 'coffee']" transform="shrink-9 right-4" [mask]="['fas', 'square']"></fa-icon>

Spin animation with click toggle:

<fa-icon [icon]="['fas', 'sync']" [spin]="isSyncAnimated" (click)="isSyncAnimated=!isSyncAnimated"></fa-icon>

Transform within binding:

<fa-icon [icon]="['fas', 'magic']" transform="rotate-{{magicLevel}}"></fa-icon>
<input type='range' [value]="magicLevel" (input)="magicLevel=$event.target.value"/>

(Slide input range to "turn up the magic")

Layers:

<fa-layers [fixedWidth]="true">
  <fa-icon [icon]="['fas', 'square']"></fa-icon>
  <fa-icon [inverse]="true" [icon]="['fas', 'spinner']" transform="shrink-6"></fa-icon>
</fa-layers>

Layers text:

<fa-layers [fixedWidth]="true">
  <fa-icon [icon]="['fas', 'square']"></fa-icon>
  <fa-layers-text content="Yo" style="color: white;" transform="shrink-4"></fa-layers-text>
</fa-layers>

Layers counters:

<fa-layers [fixedWidth]="true">
  <fa-icon [icon]="['fas', 'envelope']"></fa-icon>
  <fa-layers-counter content="99+"></fa-layers-counter>
</fa-layers>

Examples

Found in the examples directory.

Start the Webpack dev server using:

$ yarn start

Tree Shaking

Tree shaking—automatically eliminating unused icons from the final bundle—Just Works^TM.

How to Help

Review the following docs before diving in:

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md

And then:

1. Write more tests like those in icon.component.spec.ts to increase our test coverage and submit pull requests.

2. If you are an experienced Angular developer, after experimenting with this component, provide feedback about what refinements might help it feel more like an "Angular" way of doing things. Open a new issue with each distinct recommendation, or submit a pull request with your suggested revisions.

Contributors

The following contributors have either hepled to start this project, have contributed code, are actively maintaining it (including documentation), or in other ways being awesome contributors to this project. We'd like to take a moment to recognize them.

	Name	GitHub
	Yaroslav Admin	@devoto13
	Zeev Katz	@zeevkatz
	Scott Cooper	@scttcper
	Davide Pastore	@DavidePastore
	donmckenna	@donmckenna
	Austin Turner	@paustint
	Maximilian Zellhofer	@mzellho

If we've missed someone (which is quite likely) submit a Pull Request to us and we'll get it resolved.

The Font Awesome team:

	Name	GitHub
	Mike Wilkerson	@mlwilkerson
	Travis Chase	@supercodepoet
	Rob Madole	@robmadole
	Brian Talbot	@talbs

Releasing this project

See DEVELOPMENT.md