# Getting Started - Font Awesome 5

# Font Awesome

Psst! These demos are for you, an official Supporter. Please don't distribute them to the general public.

# Getting Started with Font Awesome 5

Hey, thanks for supporting Font Awesome 5 and downloading a copy of our working project! The files in this folder are meant to serve as demos which show off all of the redesigned icons as well as how to use them.

## How to Use

From the beginning Font Awesome has always focused on making things easy for you. With version 5 we've completely re-thought how we do things. We're introducing the new JavaScript-based SVG Framework and also including an SVG sprite for each style. Here are all of your options.

SVG Framework | Web Fonts | SVG Sprites
--- | --- | ---
Uses the ridiculously flexible and powerful scalable vector graphics format (SVG) | The same battle-tested and reliable way Font Awesome has worked from the beginning | Clean, simple, and the perfect foundation for advanced users willing to do some work
You might be a good candidate to use a method if…

- You agree with us: SVG is probably the best way to use icons
- Using JavaScript sounds simpler than web fonts
- You want the new features
- You need the most backwards compatibility

- You want to stick with same technique FA 4 uses (and need IE9 support)
- You aren't quite ready for SVG icons and don't mind web fonts
- You need the most rock-solid low-risk way to use icons
- The prospect of using JavaScript doesn't sound appealing

- You are an advanced user
- You are familiar with this technique and prefer it
- No dependencies on JavaScript or Web Fonts makes you giddy
- You are willing to write your own CSS and dominate lovingly control everything

## Use Icons via SVG Framework

Level of difficulty to use: Easy & Recommended!

Our SVG Framework lets you reference icons just as you always have with Font Awesome and renders them as SVGs within your UI, complete with all of the supportive styling you know and love. This requires the use of JavaScript. Here's how to try it out:

1. Grab the base Font Awesome loader at `js/fontawesome.js`.
2. Grab one or more of the styles (ex: `js/packs/solid.js`) in the `js/packs` directory.
3. Place these files in your project static files.
4. Include them in the `<head>` of your document.
5. Reference Font Awesome icons (using the inventory for easy copying/pasting) in the `<body>` of your document.

### Example:

`<head> <script defer src="/js/packs/solid.js"></script> <script defer src="/js/fontawesome.js"></script> </head> <body> <i class="fa fa-user"></i> </body>`

### Example with multiple styles:

`<head> <script defer src="/js/packs/light.js"></script> <script defer src="/js/packs/regular.js"></script> <script defer src="/js/fontawesome.js"></script> </head> <body> <i class="fal fa-user"></i> <i class="far fa-magic"></i> </body>`

Need another example? Check out the SVG Framework demo.

Need Font Awesome 4 icon names that are missing in 5? Learn how to shim using the JavaScript version.

### Browser Compatibility

Platform | Edge | IE | Chrome | Firefox | Safari | Opera | Yandex
--- | --- | --- | --- | --- | --- | --- | ---
Desktop | last 2 major versions | last 2 major versions (11, 10) | last 2 major and business versions | last 2 major and ESR versions | last 2 major versions | last 2 major versions | 14
Mobile | N/A | N/A | iOS latest Android 6, 5, 4 | iOS latest Android 6, 5, 4 | iOS 9, 10 | N/A | N/A

## Use via Web Font

Level of difficulty to use: Easy

A Font Awesome traditionalist? We get ya. Font Awesome 5 still lets you load your icons as a custom icon font (using CSS's `@font-face`). Here's how:

1. Grab the base Font Awesome icon font supporting styling at `css/font-awesome-core.css`
2. Grab one or more of the style CSS files (ex. `css/font-awesome-light.css`) in the `css/` directory.
3. Grab the corresponding web font files (ex. `webfonts/fontawesome-light-300.woff2`) in the `webfonts/` directory.
4. Place these files in your project static files.
5. Include a reference to the CSS files in the `<head>` of your document.
6. Reference Font Awesome icons (using the inventory for easy copying/pasting) in the `<body>` of your document.

### Example:

`<head> <link rel="stylesheet" href="css/font-awesome-solid.css"> <link rel="stylesheet" href="css/font-awesome-core.css"> </head> <body> <i class="fa fa-user"></i> </body>`

### Example with multiple styles:

`<head> <link rel="stylesheet" href="css/font-awesome-light.css"> <link rel="stylesheet" href="css/font-awesome-regular.css"> <link rel="stylesheet" href="css/font-awesome-core.css"> </head> <body> <i class="fal fa-user"></i> <i class="far fa-magic"></i> </body>`

Need another example? Check out the Web Font demo.

### Browser Compatibility

Platform | Edge | IE | Chrome | Firefox | Safari | Opera | Yandex
--- | --- | --- | --- | --- | --- | --- | ---
Desktop | last 2 major versions | last 3 major versions (11, 10, 9) | last 2 major and business versions | last 2 major and ESR versions | last 2 major versions | last 2 major versions | 14
Mobile | N/A | N/A | iOS latest Android 6, 5, 4 | iOS latest Android 6, 5, 4 | iOS 9, 10 | N/A | N/A

## Use Icons via SVG Sprites

Level of difficulty to use: Advanced

Want to use Font Awesome icons as SVGs in your project but want to do it without JavaScript or manage things more directly? We've prepped all of the icon styles as individual SVG sprites.

1. Grab one of the sprite files (`sprites/solid.svg`) in the `sprites` directory.
2. Place this file in your project static files.
3. In the `<body>` of your document call an individual icon like this…

### Example:

`<body> <svg> <use xlink:href="solid.svg#user"></use> </svg> </body>`

Need another example? Check out the SVG Sprites demo.

### Browser Compatibility

Platform | Edge | IE | Chrome | Firefox | Safari | Opera | Yandex
--- | --- | --- | --- | --- | --- | --- | ---
Desktop | last 2 major versions | No* | last 2 major and business versions | last 2 major and ESR versions | last 2 major versions | last 2 major versions | 14
Mobile | N/A | N/A | iOS latest Android 6, 5, 4 | iOS latest Android 6, 5, 4 | iOS 9, 10 | N/A | N/A

* IE will not automatically download SVG documents referenced with `xlink:href`

### Cross-origin caveat

This requires that you are serving the sprite from the same domain and port as the page.

### Serving locally

For this sprite to load you need to be serving it from http or https. If you try to open `docs/svg-sprite.html` from the file system (if your address begins with `file://`) it will fail to load.

## Use Icons on the Desktop

Level of difficulty to use: Advanced

Want to use Font Awesome 5's icons in your favorite Desktop Design tools or on a print-based project? No problem. Here's how to get that started:

1. Grab one or more of the web font files for the icon styles you want to use (ex. `webfonts/fontawesome-light-300.ttf`) in the `webfonts/` directory.
2. Add them to your Font Management Software (for Macs that often Font Book or Font Explorer X).
3. Activate each added font you want to use in your applications.
4. Open a file in a design application (ex. Sketch, Adobe Illustrator, etc.) and create a new text layer/area.
5. Copy and paste the corresponding Font Awesome 5 glyph you want to add from the webfont demo (the little version of the icon next to each icon's unicode value).

Or grab one or more of the svg files from any style (ex. `svg/solid/user.svg`) in the `svg/` directory.

## Upgrading from Font Awesome Version 4

For those that are super-stoked to start using version 5, you can upgrade the version of Font Awesome you're using on a site or project. Below are the basic steps we recommend following:

1. Remove the files associated with Font Awesome Version 4 from your project - including the `fontawesome/` folder of web fonts and CSS/SCSS/LESS (if you're using Font Awesome's CDN, you can skip this step.)

2. Remove the reference to Font Awesome V4's JS or CSS from the `<head>` of your document.

   `<link rel="stylesheet" href="path/to/font-awesome-v4/css/font-awesome.min.css">`
   `<script src="https://use.fontawesome.com/your-embed-code.js"></script>`
3. Pick your method of using Font Awesome 5: SVG Framework, Web Font Framework, or SVG Sprite.
4. Follow the instructions and example code + demos for the method you've chosen.
5. Find and replace any icons that have different names between V4 and V5 (with SVG Sprites, you'll need to change the syntax of every icon's reference more drastically + provide your own styling to support how they look).
6. Update or remove any custom styling you've added around Font Awesome icons (if applicable).
7. Click through your project's UI to make sure all icons are rendering as expected (optional, but recommended with betas).

### Heads up about referencing icons

Not all icons and aliases from V4 are the same in V5. So what's changed?

- We no longer have aliases in version 5, an icon has one official name
- Some names have been changed to be more consistent
- Any brand icons now have a prefix of `fab`
- Any icon that ended with `-o` now has a prefix of `far` and no `-o` suffix

### Need help? Use the shim.

We know that these changes can really slow you down in adopting V5. To help out we've created a shim file if you decide to use the JavaScript method. You can use the old names and aliases and it will automatically convert things for you as your icons get replaced with SVG icons.

### Example Font Awesome version 4 shim (JavaScript method only):

`<head> <script defer src="/js/packs/regular.js"></script> <script defer src="/js/packs/brands.js"></script> <script defer src="/js/packs/solid.js"></script> <script defer src="/js/v4-shim.js"></script> <script defer src="/js/fontawesome.js"></script> </head> <body> <i class="fa fa-close"></i> <!-- "close" is an alias to "times", V5 is <i class="fa fa-times"></i> --> <i class="fa fa-picture"></i> <!-- Renamed to "image", V5 is <i class="fa fa-image"></i> --> <i class="fa fa-twitter"></i> <!-- Needs the "fab" prefix, V5 <i class="fab fa-twitter"></i> --> <i class="fa fa-circle-o"></i> <!-- "far" prefix, lose the "-o", V5 <i class="far fa-circle"></i> --> </body>`

## Questions? Comments? Feedback?

We're still in beta land with Font Awesome 5, so we need your help. Please provide feedback about this release specifically in our designated thread. Design feedback, bugs and questions are welcome there. For future feature and icon requests, check out our contributing doc.