- Ember.js v3.28 or above
- Embroider or ember-auto-import v2
If you are using an older version of Ember, see our 2.x branch. If you are using an ancient version of Ember, see our 1.x branch.
Font Awesome Ember component using SVG with JS
- Introduction
- Installation
- Usage
- Features
- How to Help
- Contributors
- Releasing this project (only project owners can do this)
- Contributing
- License
Hey there! We're glad you're here...
If you've used Font Awesome in the past (version 5 or older) there are some things that you should learn before you dive in.
This package is for integrating with Ember.js. If you aren't using Ember then it's not going to help you. Head over to our "Get Started" page for some guidance.
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.
See UPGRADING.md.
You might also be interested in the larger umbrella project UPGRADING.md
This project is an Ember addon. So we'll add that first:
ember install @fortawesome/ember-fontawesome @fortawesome/fontawesome-svg-core
We need at least one style. Let's start with the free version of Solid.
npm install --save-dev @fortawesome/free-solid-svg-icons
or with pnpm
pnpm add -D @fortawesome/free-solid-svg-icons
or with Yarn
yarn add --dev @fortawesome/free-solid-svg-icons
After installation you need to setup the package in your app by adding the section parts like bellow.
If you are using template tag you can set it up as follows.
With this approach, you can import icons directly in your template without needing to import each one individually in font-awesome.js/ts.
To configure this setup, create font-awesome.js/ts with following content:
// app/font-awesome.ts
import { config } from '@fortawesome/fontawesome-svg-core';
import '@fortawesome/fontawesome-svg-core/styles.css'; // This adds the basic icon styles into your app
// Disable auto CSS import into head. It solved the side effect for jumping icon size.
// This is required for Fastboot apps, otherwise build fails
// It's the recommended way for setup Font Awesome in your app
config.autoAddCss = false;Import the created font-awesome.js/ts file in app.js/ts.
// app/app.ts
import Application from '@ember/application';
import Resolver from 'ember-resolver';
import loadInitializers from 'ember-load-initializers';
import config from 'app-name/config/environment';
import './font-awesome'; // Add this import statement for Font Awesome setup
export default class App extends Application {
modulePrefix = config.modulePrefix;
podModulePrefix = config.podModulePrefix;
Resolver = Resolver;
}
loadInitializers(App, config.modulePrefix);In your template, you can use icons like this:
// app/components/some-component.gts
import FaIcon from '@fortawesome/ember-fontawesome/components/fa-icon';
import { faSquare } from '@fortawesome/free-solid-svg-icons';
<template>
<FaIcon @icon={{faSquare}} />
</template>With this approach, you no longer need to pass @prefix and the defaultPrefix configuration in environment.js will be ignored.
However, with this setup, you must always pass the icon definition instead of a string; otherwise, the icon will not render, and a warning will appear in the developer console.
Note:
This setup also works with .hbs files, but it is more complex to use.
Create app/font-awesome.js/ts with following content
// app/font-awesome.ts
import { library, config } from '@fortawesome/fontawesome-svg-core';
import '@fortawesome/fontawesome-svg-core/styles.css'; // This adds the basic icon styles into your app
import * as freeSolidIcons from '@fortawesome/free-solid-svg-icons';
// Disable auto CSS import into head. It solved the side effect for jumping icon size.
// This is required for Fastboot apps, otherwise build fails
// It's the recommended way for setup Font Awesome in your app
config.autoAddCss = false;
// option to import all icons from solid pack.
// If you want to import only a subset of icons from pack, see section "Subsetting icons"
library.add(freeSolidIcons['fas']);Import the created font-awesome.js/ts file in app.js/ts.
// app/app.ts
import Application from '@ember/application';
import Resolver from 'ember-resolver';
import loadInitializers from 'ember-load-initializers';
import config from 'app-name/config/environment';
import './font-awesome'; // Add this import statement for Font Awesome setup
export default class App extends Application {
modulePrefix = config.modulePrefix;
podModulePrefix = config.podModulePrefix;
Resolver = Resolver;
}
loadInitializers(App, config.modulePrefix);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
npm install --save-dev @fortawesome/free-solid-svg-icons
npm install --save-dev @fortawesome/free-regular-svg-icons
npm install --save-dev @fortawesome/free-brands-svg-icons
Do this for each icon pack you'll use in your app. By default, all installed
icon packs will be bundled into vendor.js.
If you are a Font Awesome Pro subscriber you can install Pro packages.
npm install --save-dev @fortawesome/pro-solid-svg-icons
npm install --save-dev @fortawesome/pro-regular-svg-icons
npm install --save-dev @fortawesome/pro-light-svg-icons
npm install --save-dev @fortawesome/pro-thin-svg-icons
npm install --save-dev @fortawesome/pro-duotone-svg-icons
npm install --save-dev @fortawesome/duotone-regular-svg-icons
npm install --save-dev @fortawesome/duotone-light-svg-icons
npm install --save-dev @fortawesome/duotone-thin-svg-icons
npm install --save-dev @fortawesome/sharp-solid-svg-icons
npm install --save-dev @fortawesome/sharp-regular-svg-icons
npm install --save-dev @fortawesome/sharp-light-svg-icons
npm install --save-dev @fortawesome/sharp-thin-svg-icons
npm install --save-dev @fortawesome/sharp-duotone-solid-svg-icons
npm install --save-dev @fortawesome/sharp-duotone-regular-svg-icons
npm install --save-dev @fortawesome/sharp-duotone-light-svg-icons
npm install --save-dev @fortawesome/sharp-duotone-thin-svg-icons
Using the Pro packages requires additional configuration.
If you want to include only a subset of icons from an icon pack, you must import only the specific icons from pack and register them by using libary.add().
The following example declares that all icons in
free-solid-svg-icons should be included in build,
and, only adjust, ambulance, and pencil-alt from pro-light-svg-icons
are to be included.
import * as freeSolidIcons from '@fortawesome/free-solid-svg-icons';
import {
faAdjust,
faAmbulance,
faPencilAlt,
} from '@fortawesome/pro-light-svg-icons';
library.add(freeSolidIcons['fas']);
library.add(
faAdjust,
faAmbulance,
faPencilAlt,
);Update your template registry to extend this addon. Check the Glint documentation for more information.
/* types/global.d.ts */
import '@glint/environment-ember-loose';
import type EmberFontAwesomeRegistry from '@fortawesome/ember-fontawesome/template-registry';
declare module '@glint/environment-ember-loose/registry' {
export default interface Registry extends EmberFontAwesomeRegistry, /* other addon registries */ {
// local entries
}
}If you want to use icons in your addon there are a few steps to take.
First ensure @fortawesome/ember-fontawesome, @fortawesome/fontawesome-svg-core and any icon packs are in
the peerDependency section of your package.json. This requires the consumer app to install the necessary packages.
Second you need to declare in your setup documentation what icons you are using, so apps that subset icons will know what to include. You can do this like bringing import example as explained in section "Subsetting icons"
You should avoid listing any Font Awesome Pro packages as dependencies unless you are confident that whoever is using your addon has access to those.
Out of the box, icons will use the Solid style unless a prefix is manually specified.
To change the default to Regular or Light, add a fontawesome configuration object
to your application's environment.js and set the defaultPrefix option.
module.exports = function(environment) {
let ENV = {
// Add options here
fontawesome: {
defaultPrefix: 'fal' // light icons
}
};
// ...
return ENV;
};As a reminder, the free version of Font Awesome does not include a complete set of icons for any style other than Solid, so this setting is recommended only for Pro subscribers.
This is what it would look like in your template:
Without a prefix specified, the default specified in environment.js (or fas, if none set) is assumed:
If you want to use an icon from any style other than the default, use prefix=.
Note:
The packages also allows passing @icon as an object (Icon Definition), as shown below:
If you use this approach consistently, you only need to configure config.autoAddCss = false; inside font-awesome.ts.
This use case is especially useful for people using template tag components (.gjs/.gts). You can find more about template tags here
// app/components/some-component.gts
import FaIcon from '@fortawesome/ember-fontawesome/components/fa-icon';
import { faSquare } from '@fortawesome/free-solid-svg-icons';
<template>
<FaIcon @icon={{faSquare}} />
</template>In this case you don't need to pass @prefix because the prefix is automatically defined within the imported object.
The following features are available as part of Font Awesome. Note that the syntax is different from our general web-use documentation.
Size:
Flip horizontally, vertically, or both:
Spin and pulse animation:
<span class="fa-layers fa-lg">
<FaIcon @icon="circle" />
<FaIcon @icon="check" class="fa-inverse" @transform="shrink-6" />
</span><span class="fa-layers fa-lg">
<FaIcon @icon="circle" />
<span class="fa-layers-text">8</span>
</span>Review the following docs before diving in:
And then:
- Check the existing issue and see if you can help!
The following contributors have either helped 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 |
|---|---|
| Ilya Radchenko | @knownasilya |
| Jonathan Johnson | @jrjohnson |
| ember-tomster | @ember-tomster |
| Julien Guimont | @juggy |
| Xaser Acheron | @XaserAcheron |
| samcic | @samcic |
| Josemar Luedke | @josemarluedke |
| Robert Clancy | @robclancy |
| maxwondercorn | @maxwondercorn |
| Denis Toledo | @dnstld |
| Markus Sanin | @mkszepp |
| davideferre | @davideferre |
| st-h | @st-h |
| stopfstedt | @st-h |
| Michael Rykov | @rykov |
| Chris Manson | @mansona |
| François de Metz | @francois2metz |
| NullVoxPopuli | @NullVoxPopuli |
| Font Awesome Team | @FortAwesome |
If we've missed someone (which is quite likely) submit a Pull Request to us and we'll get it resolved.
See DEVELOPMENT.md
See the Contributing guide for details.
This project is licensed under the MIT License.