Skip to main content

Customize the Default CSS Stylesheet

Flowable CSS should be customized through user themes. The currentUser.theme property returned by the back end is used by a CSS class injected in one of the parent DOM nodes. This means it might exist as many CSS themes as theme configurations exist, e.g., user-1 might be configured with theme-1, user-2 with theme-2, and so on.

There are specific recommended steps to follow to achieve this successfully:

  • Configure user theme

  • Customize the theme stylesheet

  • Fonts customization

  • Logo customization

Configure User Themes#

User themes should be configured as part of a user configuration in the tenant setup file. For instance, based on the following user configuration, the user Shane is associated with the my-custom-theme:

{ "firstName": "Shane", "lastName": "Bowen", "login": "shane.bowen", "personalNumber": "12345678", "technicalNumber": "123456", "entityId": "HK-030", "language": "en", "theme": "my-custom-theme", "userDefinitionKey": "user-client-advisor"}

This results in a CSS class applied to the parent DOM component as follows (note the theme- prefix applied to the specified theme name):

<div className="flw-root-app theme-my-custom-theme"> ...</div>

Customize the Theme in Flowable#

Option 1 - Customize the Theming Configuration#

The Theming Configuration can be configured during Runtime, by adding the allowedFeature = themeManagement.

Expanded

Expanded

Expanded

Then the Theme Management app appears in Flowable and the logos as well as several colors can be set.

Furthermore, the Theming configuration can also be set in the backend, by adding a JSON configuration file to following path in your classpath resources/com/flowable/themes/custom.

The JSON configuration file for the theming has the following format:

{  "overwrite": true,  "tenantIds": ["acme", "megacorp"],  "themes": [    {      "name": "flowable-theming",      "options": {        "logoUrl": "data:image/svg+xml;base64,<base64-encoded-image>",        "logoUrlFull": "data:image/svg+xml;base64,<base64-encoded-image>",        "subMenu": "#0b0f18",        "topNavBar": "#ffffff",        "switcherItemFgHover": "#ccd1d6",        "switcherSelectedBgHover": "#216c7d",        "subMenuSelectedItemBorder": "#b03b39",        "subMenuSelectedItemBg": "#111e2c",        "switcherItemFg": "#b0b8bf",        "switcherBase": "#111e2c",        "switcherSelectedFg": "#ffffff",        "switcherActionHover": "#e54d42",        "switcherSelectedBg": "#1d5d6d",        "subMenuSelectedItemFg": "#ffffff",        "subMenuItemFgHover": "#ccd1d6",        "switcherAction": "#b03b31",        "subMenuItemFg": "#b0b8bf",        "buttonBg": "#E1E1E1",        "buttonFg": "#333333",        "buttonHoverBg": "#eeeeee",        "buttonHoverFg": "#333333",        "buttonPrimaryBg": "#1d5d6d",        "buttonPrimaryFg": "#ffffff",        "buttonPrimaryHoverBg": "#226e81",        "buttonPrimaryHoverFg": "#ffffff",        "flwColorLightgray": "#cccccc",        "flwFontSans": "-apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Helvetica Neue, Arial, Noto Sans, sans-serif",        "flwFormsBackgroundColor": "#FFFFFF",        "flwFormsBlueBackgroundColor": "#d8eafc",        "flwFormsBorderColor": "#e5e5e5",        "flwFormsColor": "#0ac3db",        "flwFormsColorHover": "#0998aa",        "flwFormsColorSecondary": "#538187",        "flwFormsDebugBorder": "#ff0097",        "flwFormsErrorColor": "#f0506e",        "flwFormsGreenBackgroundColor": "#edfbf6",        "flwFormsLabelTextColor": "#333333",        "flwFormsMutedBackgroundColor": "#f8f8f8",        "flwFormsMutedTextColor": "#999999",        "flwFormsOrangeBackgroundColor": "#fef5ee",        "flwFormsOrangeColor": "#faa05a",        "flwFormsRedBackgroundColor": "#fef4f6",        "flwFormsSelectedRowBackgroundColor": "#FFFFDD",        "flwFormsShadowColor": "#000000",        "flwFormsSuccessColor": "#32d296",        "flwFormsTextColor": "#666666",        "flwGutter": "6px",        "flwText2Xl": "27px",        "flwText3Xl": "30.6px",        "flwTextBase": "14px",        "flwTextLg": "21px",        "flwTextMed": "13px",        "flwTextSm": "12px",        "flwTextTiny": "10px",        "flwTextXl": "22.95px",        "flwTextXs": "11px",        "fontFamily": "Roboto"      }    }  ]}

The option overwrite configures if the server needs to overwrite the themes on server startup (and restart). This configuration is optional and can also be configured globally by setting the following application property to true or false - flowable.platform.theme.force-overwrite.

The tenantIds is a list of tenants where this theming configuration becomes applicable. This is also an optional configuration. Without setting any tenantIds the theming becomes applicable overall tenants.

The themes is a list of themes which is represented in the example above with one element of a theme configuration.

Option 2 - Customize the Theme Stylesheet#

Custom CSS can be implemented with CSS or Sass which is an extension of CSS. Any .css or .scss file found under /frontend can be imported and bundled as part of the application CSS.

In your CSS you can override the CSS variables like this.

:root {  --flw-font-family: "Roboto";  --flw-switcher-base: #111e2c;  --flw-switcher-item-color: #b0b8bf;  --flw-switcher-item-color-hover: #ccd1d6;  --flw-switcher-selected-bgcolor: #1d5d6d;  --flw-switcher-selected-bgcolor-hover: #216c7d;  --flw-switcher-selected-color: #fff;  --flw-subMenu-bgcolor: #0b0f18;  --flw-subMenu-item-color: #b0b8bf;  --flw-subMenu-item-color-hover: #ccd1d6;  --flw-subMenu-selected-bgcolor: #111e2c;  --flw-subMenu-selected-color: #fff;  --flw-subMenu-selected-color-border: #b03b39;  --flw-subMenu-action-color: #b03b39;  --flw-subMenu-action-color-hover: #e54d42;  --flw-navigationBar-bgcolor: #fff;  --flw-color-lightgray: #cccccc;  --flw-button-bg: #e1e1e1;  --flw-button-fg: #333333;  --flw-button-hover-bg: #d4d4d4;  --flw-button-hover-fg: #333333;  --flw-button-primary-bg: #1d5d6d;  --flw-button-primary-fg: #ffffff;  --flw-button-primary-hover-bg: #226e81;  --flw-button-primary-hover-fg: #ffffff;  --flw-forms-background-color: #ffffff;  --flw-forms-blue-background-color: #d8eafc;  --flw-forms-border-color: #e5e5e5;  --flw-forms-color: #1e87f0;  --flw-forms-color-hover: #0f6ecd;  --flw-forms-color-secondary: #538187;  --flw-forms-debug-border: #ff0097;  --flw-forms-error-color: #f0506e;  --flw-forms-green-background-color: #edfbf6;  --flw-forms-label-text-color: #333333;  --flw-forms-muted-background-color: #f8f8f8;  --flw-forms-muted-text-color: #999999;  --flw-forms-orange-background-color: #fef5ee;  --flw-forms-orange-color: #faa05a;  --flw-forms-red-background-color: #fef4f6;  --flw-forms-selected-row-background-color: #ffffdd;  --flw-forms-shadow-color: #000000;  --flw-forms-success-color: #32d296;  --flw-forms-text-color: #666666;}

Notice. For backwards compatibility we still support changing some variables by importing and calling the SASS mixin theme(...). This mechanism is deprecated and support will be removed from version 3.10.0.

Export/Import a theme customization#

The Theme Customizations can be exported to a Json file using the Export button from the Theme card action menu.

Export button

The generated JSON file has the following format:

{  "logoUrl": "data:image/svg+xml;base64,<base64-encoded-image>",  "logoUrlFull": "data:image/svg+xml;base64,<base64-encoded-image>",  "subMenu": "#0b0f18",  "topNavBar": "#ffffff",  "switcherItemFgHover": "#ccd1d6",  "switcherSelectedBgHover": "#216c7d",  "subMenuSelectedItemBorder": "#b03b39",  "subMenuSelectedItemBg": "#111e2c",  "switcherItemFg": "#b0b8bf",  "switcherBase": "#111e2c",  "switcherSelectedFg": "#ffffff",  "switcherActionHover": "#e54d42",  "switcherSelectedBg": "#1d5d6d",  "subMenuSelectedItemFg": "#ffffff",  "subMenuItemFgHover": "#ccd1d6",  "switcherAction": "#b03b31",  "subMenuItemFg": "#b0b8bf",  "buttonBg": "#E1E1E1",  "buttonFg": "#333333",  "buttonHoverBg": "#eeeeee",  "buttonHoverFg": "#333333",  "buttonPrimaryBg": "#1d5d6d",  "buttonPrimaryFg": "#ffffff",  "buttonPrimaryHoverBg": "#226e81",  "buttonPrimaryHoverFg": "#ffffff",  "flwColorLightgray": "#cccccc",  "flwFontSans": "-apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Helvetica Neue, Arial, Noto Sans, sans-serif",  "flwFormsBackgroundColor": "#FFFFFF",  "flwFormsBlueBackgroundColor": "#d8eafc",  "flwFormsBorderColor": "#e5e5e5",  "flwFormsColor": "#0ac3db",  "flwFormsColorHover": "#0998aa",  "flwFormsColorSecondary": "#538187",  "flwFormsDebugBorder": "#ff0097",  "flwFormsErrorColor": "#f0506e",  "flwFormsGreenBackgroundColor": "#edfbf6",  "flwFormsLabelTextColor": "#333333",  "flwFormsMutedBackgroundColor": "#f8f8f8",  "flwFormsMutedTextColor": "#999999",  "flwFormsOrangeBackgroundColor": "#fef5ee",  "flwFormsOrangeColor": "#faa05a",  "flwFormsRedBackgroundColor": "#fef4f6",  "flwFormsSelectedRowBackgroundColor": "#FFFFDD",  "flwFormsShadowColor": "#000000",  "flwFormsSuccessColor": "#32d296",  "flwFormsTextColor": "#666666",  "flwGutter": "6px",  "flwText2Xl": "27px",  "flwText3Xl": "30.6px",  "flwTextBase": "14px",  "flwTextLg": "21px",  "flwTextMed": "13px",  "flwTextSm": "12px",  "flwTextTiny": "10px",  "flwTextXl": "22.95px",  "flwTextXs": "11px",  "fontFamily": "Roboto"}

Is it possible to import a Custom Theme Json file using the Import button in the theme management view.

Import button

Notice. Once the file has been uploaded, the user will be prompted to add a name for the new theme and any existing theme with the same name will be overridden.

Font Customization#

Fonts are exposed through a Sass file within the ../lib folder. This way the same fonts can be easily used for custom components:

@import "../lib/_fonts.scss";.my-custom-component { font-family: $flowable-fonts-roboto; ...}...

Customize Font Family#

We can also set the font family for the whole application. As mentioned above using the theme() mixin you can set the font family between the native supported fonts, e.g:

@import "~@flowable/work/theme.scss";
@include theme((... fontFamily: "Roboto", ...));
  • Supported Font Families: Roboto, Fira Sans.

Adding External Font Families#

As part of font family customizations, we can add font families that are not natively supported in Flowable Front-End.

To add it, we can create a ./src/fonts/ folder and then copy the font files inside. You can organize these font families creating a folder for each one with the font family name, e.g: ./src/fonts/DancingScript

To make use of this font we need to expose it through the @font-face API. E.g:

  @import '~@flowable/work/theme.scss';
  @font-face {    font-family: 'DancingScript';    src: url('src/fonts/DancingScript/DancingScript-Regular.ttf') format('truetype');  }
  ...
  @include theme(    (      ...      fontFamily: 'DancingScript',      ...    )  );

The fonts folder will be copied to dist folder as static assets when we execute work-scripts flowbuild build command to generate custom.js and custom.css files. All generated files should be copied to the server external folder as usual.


NOTE

For a complete list of free font families, you can visit Google Fonts page.

You can learn more about @font-face API and browser support here.


Logo and Favicon Images#

The favicon can be customized by adding the favicon.ico file into following classpath folder /src/main/resources/public.

The application logo is customized by overwriting certain CSS classes with the code below. The image files should be available under the resources folder in the web application, e.g., /src/main/resources/static/ext.

@media all and (-ms-high-contrast: none), (-ms-high-contrast: active) { /* SideBar logo */ .flw-switcher__nav {  &__logo {   background-image: url("./logo.png");   background-size: auto;   svg {    display: none;   }  }  &__collapsed .flw-switcher__nav__logo {   background-image: url("./logo_min.png");   background-size: auto;  } } /* Login logo */ .flw-login__logo {  background-image: url("./logo.png");  background-size: auto;  svg {   display: none;  } }}

The desktop notification logo can be overwritten by adding a custom image file in the configured folder path for this, there is an application property to specify the notification logo path: flowable.frontend.notificationLogoUrl. As fallback, the Flowable logo is used if no notification.png file is found.