Skip to content

Font Awesome Pro

If you have an active Font Awesome Pro subscription1, you can use it with RIL in just two easy steps.

First, enable Font Awesome Pro via the fontawesome.pro_enabled setting.

fontawesome.pro_enabled: Controls whether Font Awesome Pro is enabled.

fontawesome.pro_enabled controls whether RIL allows the use of icons exclusive to Font Awesome Pro.

[tool.ril.fontawesome]
pro_enabled = true

[fontawesome]
pro_enabled = true

RIL_FONTAWESOME__PRO_ENABLED=true

Second, set the FONTAWESOME_PACKAGE_TOKEN environment variable to your Font Awesome package token.

FONTAWESOME_PACKAGE_TOKEN: Your Font Awesome package token.

A Font Awesome package token enables access to Font Awesome's private, Pro-only, package registry.

This special setting can only be configured via an environment variable or .env file and is not prefixed with RIL_.

FONTAWESOME_PACKAGE_TOKEN=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

That's it — you can now use Pro icons without any further setup.

Using a Kit

Kits are all-in-one management utilities for Font Awesome icons. You can read more about them at Font Awesome's documentation.

There is literally no downside to using a Kit

Using a Kit helps you save on registry bandwith and allows you to use custom icons. It also means RIL's Font Awesome component introduces only three Node.js dependencies to your project instead of up to 18.

Kits should be always be preferred over plain Font Awesome Pro.

Setup

First, follow the instructions above to set up Font Awesome Pro.

Second, choose the Kit you want to use (or create a new one), head into its settings, and ensure Features > Enable Installing Your Kit as a Package is checked.

Font Awesome Pro "Enable Installing Your Kit as a Package" setting

Third, find your Kit code. Use the image below as a reference.

Font Awesome Pro Kit code example

Finally, set the fontawesome.kit_code setting to your Kit code.

fontawesome.kit_code: A Font Awesome Kit code.

Setting fontawesome.kit_code allows you to use the corresponding Kit with RIL.

Your Kit code is not a secret and is safe to commit to version control or share with other people.

[tool.ril.fontawesome]
kit_code = "abcde12345"

[fontawesome]
kit_code = "abcde12345"

RIL_FONTAWESOME__KIT_CODE=abcde12345
Protecting your Kit from unauthorized use

It is strongly recommended that you set at least one allowed domain for your Kit. If you don't set any, anyone with your Kit code will be able to use your Kit via Font Awesome's CDN and your pageviews might unexpectedly go through the roof.

You can use your own domain if you have one, or example.com if you don't.

This setting has absolutely no effect on RIL regardless of where your Reflex project is hosted.

Using custom icons

You can use custom icons via fa.kit().

import RIL as icons

icons.fa.kit("name-of-icon")

Duotone custom icons are unavailable for now

Duotone custom icons are currently not available in Kit packages, so you can't use them with RIL. This is a limitation on Font Awesome's side, so you'll have to wait for things to change on their end.

Updating Kits

If you add, remove, or edit icons or styles in your Kit, you can get those changes in your Reflex project by having Reflex reinstall your project's frontend packages:

reflex init && reflex run

Continous integration

If you plan to build your Reflex project in a continuous integration environment, you are strongly advised to cache your dependencies in order to preserve your registry bandwith.

Do I need to worry about this?

This only applies to users who are statically building their project with reflex export in a CI environment. If you're unsure whether that's you, it probably isn't.

Your cache should save the entire .web directory and be keyed on both .web/bun.lockb and .web/package-lock.json. (1)

  1. If the REFLEX_WEB_WORKDIR environment variable is set, use its value in place of .web.

Below are links to the relevant documentation for several popular CI providers:

Using alternate registries (advanced)

You can use the fontawesome.npm_registry setting to specify an alternate registry from which to install Font Awesome Pro packages. The registry must implement the CommonJS package registry specification.

This is an advanced capability that most users won't need.

fontawesome.npm_registry: Controls where Reflex will install Font Awesome Pro packages from.

fontawesome.npm_registry controls the registry from which Reflex will install packages in the @fortawesome and @awesome.me namespaces.

Don't open any issues if you use this setting

If you set the fontawesome.npm_registry setting to anything other than its default of https://npm.fontawesome.com, don't open any Font Awesome-related issues in RIL's repository. You will be asked for information that will reveal you have configured this setting, at which point your issue will be closed without further response.

[tool.ril.fontawesome]
npm_registry = "https://example.registry.com"

[fontawesome]
npm_registry = "https://example.registry.com"

RIL_FONTAWESOME__NPM_REGISTRY="https://example.registry.com"

Troubleshooting

"Incorrect or missing password" error

If you're trying to use Font Awesome Pro icons and NPM emits an error like:

npm error code E401
npm error Incorrect or missing password.

It's probably because your Font Awesome package token is incorrect or missing. You should:

  • Double-check that the token matches the one on your Font Awesome account page.
  • Make sure your token is exposed by the FONTAWESOME_PACKAGE_TOKEN environment variable. Casing doesn't matter, but the spelling must otherwise be exact. There are no alternative ways of setting a token — trying to put it in a pyproject.toml or ril.toml file won't work.
    • If you're using a .env file, make sure it's located in the current working directory — i.e., the directory in which reflex run or reflex export is being executed. Also, make sure it's named .env exactly.

If things still aren't working, open an issue.

  1. You must be actively paying for Font Awesome Pro. A perpetual fallback license won't cut it. ↩