Docs

Docs

Loading Styles, Fonts & Images from npm Packages

Describes how to load theme resources from npm packages.

Stylesheets and other theme-related resources like font and image files can be loaded from npm packages through the theme configuration file theme.json.

Loading Stylesheets from npm Packages

You can configure a custom theme to import style sheets from npm packages included as dependencies in the project by defining them in an importCss array in theme.json. Below is an example of a theme.json for importing CSS from npm packages:

{
  "importCss": [
    "@fortawesome/fontawesome-free/css/regular.css",
    "@fortawesome/fontawesome-free/css/all.min.css"
  ]
}

This loads the external style sheets as if they were imported as local style sheets through styles.css.

Note
 The npm packages must be added to the project. The importCss configuration doesn’t import the npm packages themselves to the project. You need to do that by using the @NpmPackage annotation.

Similar to the document root style sheet, style sheets can be forced to the document root for embedded Flow application or component use cases through a corresponding documentCss array, which can be useful for font-face declarations in npm packages:

The following example theme.json defines importing of CSS from npm packages into doc root:

{
  "documentCss": ["@fortawesome/fontawesome-free/css/all.min.css"]
}

Loading Fonts and Images from npm Packages

In addition to style sheets, other assets like fonts, images, and icons can also be included from npm packages added to the project, by mapping them from the dependency to local URIs in an assets block in theme.json.

Syntax for mapping assets from npm package to local URIs goes as follows:

{
  "assets": {
    "package-name": {
      "asset/glob/pattern": "local/target/path"
    }
  }
}

For example, to use SVG icons from @fortawesome/fontawesome-free npm package, the SVG files should be mapped to some local path as follows:

{
  "assets": {
    "@fortawesome/fontawesome-free": {
      "svgs/regular/**": "fontawesome/icons"
    }
  }
}
Note
 The npm packages must be added to the project. The assets configuration doesn’t import the npm packages themselves to the project. You need to do that by using the @NpmPackage annotation.

The SVG images mapped by the example above are now available on the path fontawesome/icons relative to the theme’s root folder, so they can be referenced in styles.css as follows:

.icon-snowflake {
  background-image: url('./fontawesome/icons/snowflake.svg');
}

The assets block supports multiple packages and multiple mappings per package. Below is an example of theme.json mapping multiple packages and assets per package:

{
  "assets": {
    "@fortawesome/fontawesome-free": {
      "svgs/regular/**": "fontawesome/icons",
      "webfonts/**": "webfonts"
    },
    "@fortawesome/free-solid-svg-icons": {
      "*.js": "solids"
    }
  }
}

3e46fe3b-00d6-4cf7-908c-342a364210db