From 8e42dad8f223627edfe5888c788589b9d1b123f7 Mon Sep 17 00:00:00 2001 From: Yaroslav Admin Date: Sat, 20 Apr 2024 18:49:35 +0200 Subject: [PATCH] Document how to use custom icons Fixes #172 --- docs/guide/custom-icons.md | 64 +++++++++++++++++++ docs/usage.md | 1 + docs/usage/explicit-reference.md | 12 ++++ docs/usage/icon-library.md | 12 ++++ projects/demo/src/app/app.component.ts | 4 +- src/testing/helpers.ts | 2 +- testing/src/icon/mock-icon-library.service.ts | 2 +- tsconfig.json | 2 +- 8 files changed, 94 insertions(+), 5 deletions(-) create mode 100644 docs/guide/custom-icons.md diff --git a/docs/guide/custom-icons.md b/docs/guide/custom-icons.md new file mode 100644 index 0000000..052cb5a --- /dev/null +++ b/docs/guide/custom-icons.md @@ -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 + + + + +``` + +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. diff --git a/docs/usage.md b/docs/usage.md index 7d046c0..06dc8d9 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -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) diff --git a/docs/usage/explicit-reference.md b/docs/usage/explicit-reference.md index 19553ba..9782d4c 100644 --- a/docs/usage/explicit-reference.md +++ b/docs/usage/explicit-reference.md @@ -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" + } +} +``` + diff --git a/docs/usage/icon-library.md b/docs/usage/icon-library.md index e7b7348..6d6bcb4 100644 --- a/docs/usage/icon-library.md +++ b/docs/usage/icon-library.md @@ -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. diff --git a/projects/demo/src/app/app.component.ts b/projects/demo/src/app/app.component.ts index 4e9dc83..766d88b 100644 --- a/projects/demo/src/app/app.component.ts +++ b/projects/demo/src/app/app.component.ts @@ -8,6 +8,7 @@ import { faBell, faCircle, faCoffee, + faCog, faEllipsisH, faFighterJet, faFlag as solidFlag, @@ -15,7 +16,6 @@ import { faMagic, faSpinner, faSquare, - faCog, faTimes, faUser, } from '@fortawesome/free-solid-svg-icons'; @@ -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; diff --git a/src/testing/helpers.ts b/src/testing/helpers.ts index 3c63f1e..ad0af75 100644 --- a/src/testing/helpers.ts +++ b/src/testing/helpers.ts @@ -34,5 +34,5 @@ export const queryByCss = (fixture: ComponentFixture, 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']], }; diff --git a/testing/src/icon/mock-icon-library.service.ts b/testing/src/icon/mock-icon-library.service.ts index 7686951..2cc2f2a 100644 --- a/testing/src/icon/mock-icon-library.service.ts +++ b/testing/src/icon/mock-icon-library.service.ts @@ -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({ diff --git a/tsconfig.json b/tsconfig.json index eb808d1..4f50121 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -15,7 +15,7 @@ "declaration": false, "downlevelIteration": true, "experimentalDecorators": true, - "moduleResolution": "node", + "moduleResolution": "bundler", "importHelpers": true, "target": "ES2022", "module": "ES2022",