Show TOC

Creating Themable User InterfacesLocate this document in the navigation structure

There are several things you should keep in mind to ensure that an application can actually be themed.

General Aspects

Do not hard-code colors and fonts if you want your control or application to be themable in the theme designer tool.

For example, if you hard-coded the font color to black, this color cannot be adjusted when you apply a custom theme. This can be problematic if you want to apply a custom theme with a dark background color because the font color cannot be adjusted to a light color.

Stable Theme Parameters
  • Themes in SAPUI5 are built with the CSS preprocessor “less” and make use of a complex parameter structure.
  • SAPUI5 applications have access to these parameters at runtime via the API-call (sap.ui.core.theming.Parameters.get() ). These parameters not only differ in terms of themes, they are also not necessarily stable across different versions of SAPUI5. For this reason, you cannot rely on the complete set of parameters.
  • To allow developers to build theme-dependent, custom-styled applications or controls, a subset of 70 parameters representing colors for different types of usage (such as Border, Backgrounds, Charts) is available.
  • The parameters in this subset can be considered as "stable", in that:
    • We will not change naming for these parameters.
    • The contrast ratio between foreground- colors like text and the related background will remain stable.
  • Always choose parameters that fit best from a semantic perspective, do not choose them based on their color value.
  • This set is available across the two predefined themes sap_bluecrystal and sap_hcb and should be handled with care. You should test your implementations for both themes to ensure the results are as expected.
  • We must stress that this approach can only cover the most common use cases. In addition, be aware that due to parameter value changes with future versions of SAPUI5, it might be necessary to rework your applications even when using the “stable” theme parameters described here.
  • For charting, two individual sets are available, Chart Accent and Chart Semantic. Both sets are logically independent. Therefore only one of these sets is to be used consistently across individual charts.
  • You can view the entire set of basic theme parameters as a sample in the Explored section of the Demo Kit.
SAPUI5 application developers writing custom HTML should consider the following:
  • LESS parameters are not accessible via CSS; only support for standard libraries.
  • To ensure theme-dependent styling, only use basic theme parameters.
  • Read appropriate parameter values via API and set the elements' CSS properties rather than hard-coding colors or borrowing arbitrary style classes from control sets:
    jQuery.sap.require("sap.ui.core.theming.Parameters");
    var myColor = sap.ui.core.theming.Parameters.get("sapUiDarkBG");
SAPUI5 control developers should consider the following:
  • Use the theme LESS parameters in CSS class definitions and rules.
  • Use the appropriate level of parameter for the control, creating new ones as appropriate. For example, do not use color values or quick theming parameters directly in CSS rules.
  • Follow the control parameter hierarchy conventions.