Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document how to use custom icons #438

Merged
merged 1 commit into from
Apr 20, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 64 additions & 0 deletions docs/guide/custom-icons.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
# Custom icons

This guide explains how to use custom icons with `angular-fontawesome`.

First of all, you'll need a valid SVG file containing the icon you want to use. Please refer to
the [Icon Design Guidelines](https://docs.fontawesome.com/web/add-icons/upload-icons/icon-design)
and [Prep Icons for Upload](https://docs.fontawesome.com/web/add-icons/upload-icons/prep-icons) to learn how to create
an SVG icon which can be used with Font Awesome.

## Icon definition

To use a custom icon in the project, you need to define an object specified by the `IconDefinition` type. All icons are
defined using the same structure, so you can refer to existing icons as examples. The object should contain the
following properties:

```typescript
export interface IconDefinition {
prefix: string; // prefix of the icon
iconName: string; // name of the icon
icon: [
number, // viewBox width
number, // viewBox height
string[], // ligatures (not used in `angular-fontawesome`)
string, // unicode (not used in `angular-fontawesome`)
string | string[], // single path for a simple icon or array of two paths for a duotone icon
];
}
```

Knowing the icon structure, you can easily convert the SVG file to the `IconDefinition` object by picking up the
relevant parts. Given an example SVG file:

```xml

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
<path d="M256 512A256 256 0 1 0 256 0a256 256 0 1 0 0 512z"/>
</svg>
```

The icon definition will look like the following:

```typescript
import { IconDefinition } from '@fortawesome/angular-fontawesome';

const myIcon: IconDefinition = {
prefix: 'fac',
iconName: 'my-icon',
icon: [
512,
512,
[],
'',
'M256 512A256 256 0 1 0 256 0a256 256 0 1 0 0 512z',
],
};
```

You can also use a [Font Awesome Kit](https://fontawesome.com/kits) to upload your custom icons or pick only the icons
you'd like to use.

## Use custom icon

To use a custom icon is no different from a Font Awesome icon. You can either add it to
the [icon library](./icon-library.md) or use an [explicit references](./explicit-reference.md) approach.
1 change: 1 addition & 0 deletions docs/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,7 @@ Take your icons to the next level with these advanced features.
Guides on specific topics or use cases.

* [Testing](./guide/testing.md)
* [Custom icons](./guide/custom-icons.md)
* [Storybook](./guide/storybook.md)
* [Advanced uses](./guide/advanced-uses.md)
* [Styling icon internals](./guide/styling-icon-internals.md)
12 changes: 12 additions & 0 deletions docs/usage/explicit-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,3 +58,15 @@ export class AppComponent {
}
```

Kit packages use a [subpath exports](https://nodejs.org/api/packages.html#subpath-exports) feature of Node.js. If you
get an error like `Cannot find module '@awesome.me/kit-KIT_CODE/icons/classic/solid' or its corresponding type
declartions.`, you may need to update your `tsconfig.json` to set `moduleResolution` to `bundler`:

```json
{
"compilerOptions": {
"moduleResolution": "bundler"
}
}
```

12 changes: 12 additions & 0 deletions docs/usage/icon-library.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,18 @@ export class AppComponent {
}
```

Kit packages use a [subpath exports](https://nodejs.org/api/packages.html#subpath-exports) feature of Node.js. If you
get an error like `Cannot find module '@awesome.me/kit-KIT_CODE/icons' or its corresponding type declartions.`, you may
need to update your `tsconfig.json` to set `moduleResolution` to `bundler`:

```json
{
"compilerOptions": {
"moduleResolution": "bundler"
}
}
```

## Changing the default prefix

The default prefix, `fas`, can be adjusted by injecting the `FaConfig` and modifying the `defaultPrefix` property.
Expand Down
4 changes: 2 additions & 2 deletions projects/demo/src/app/app.component.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,14 @@ import {
faBell,
faCircle,
faCoffee,
faCog,
faEllipsisH,
faFighterJet,
faFlag as solidFlag,
faHeart,
faMagic,
faSpinner,
faSquare,
faCog,
faTimes,
faUser,
} from '@fortawesome/free-solid-svg-icons';
Expand Down Expand Up @@ -48,7 +48,7 @@ export class AppComponent {
faDummy: IconDefinition = {
prefix: 'fad',
iconName: 'dummy',
icon: [512, 512, [], 'f030', ['M50 50 H412 V250 H50 Z', 'M50 262 H412 V462 H50 Z']],
icon: [512, 512, [], '', ['M50 50 H412 V250 H50 Z', 'M50 262 H412 V462 H50 Z']],
};

notificationsCounter = 1000;
Expand Down
2 changes: 1 addition & 1 deletion src/testing/helpers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -34,5 +34,5 @@ export const queryByCss = (fixture: ComponentFixture<any>, cssSelector: string):
export const faDummy: IconDefinition = {
prefix: 'fad',
iconName: 'dummy',
icon: [512, 512, [], 'f030', ['M50 50 H412 V250 H50 Z', 'M50 262 H412 V462 H50 Z']],
icon: [512, 512, [], '', ['M50 50 H412 V250 H50 Z', 'M50 262 H412 V462 H50 Z']],
};
2 changes: 1 addition & 1 deletion testing/src/icon/mock-icon-library.service.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ import { FaIconLibraryInterface, IconDefinition, IconName, IconPrefix } from '@f
export const dummyIcon: IconDefinition = {
prefix: 'fad',
iconName: 'dummy',
icon: [512, 512, [], 'f030', 'M50 50 H462 V462 H50 Z'],
icon: [512, 512, [], '', 'M50 50 H462 V462 H50 Z'],
};

@Injectable({
Expand Down
2 changes: 1 addition & 1 deletion tsconfig.json
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
"declaration": false,
"downlevelIteration": true,
"experimentalDecorators": true,
"moduleResolution": "node",
"moduleResolution": "bundler",
"importHelpers": true,
"target": "ES2022",
"module": "ES2022",
Expand Down
Loading