Theme Configuration
By configuring a custom theme, you can do the following:
You can configure these features through a theme.json
configuration file (1) in the theme folder:
frontend
└── themes
└── my-theme
├── components/
└── styles.css
└── theme.json (1)
Style Sheets 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
:
{
"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
|
npm packages must be added to the project
The importCss configuration does not import the npm packages themselves to the project.
You need to do that by using the @NpmPackage annotation.
|
Similarly 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"]
}
Other Assets 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
|
npm packages must be added to the project
The assets configuration does not 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.
{
"assets": {
"@fortawesome/fontawesome-free": {
"svgs/regular/**": "fontawesome/icons",
"webfonts/**": "webfonts"
},
"@fortawesome/free-solid-svg-icons": {
"*.js": "solids"
}
}
}
Extending Custom Themes
A custom theme can extend another custom theme by configuring a “parent theme” in theme.json
.
This can be useful for splitting your styles into a base theme shared by all applications, and multiple “sub-themes” for different applications or sub-brands.
The parent theme can be in the same project as the sub-theme, or in a separate dependency.
{
"parent": "my-base-theme"
}
With a parent and sub theme configuration like this, the CSS load order is as follows:
-
Lumo styles
-
Parent theme styles
-
Sub-theme styles
-
Manually loaded additional style sheets (for example, using
@CssImport
in Flow)
DEEC970B-F6BD-4F38-B401-1D317F33EBED