Show TOC

Setting ThemesLocate this document in the navigation structure

You define which theme is used by you app SAPUI5 either in the bootstrap of you app, by using an URL parameter, or by using method sap.ui.getCore.applyTheme.

  • The initial theme can be hardcoded in the application (in the script tag of the bootstrap loading SAPUI5) or in a JS configuration object defined before SAPUI5 is loaded, for example:
    <script id="sap-ui-bootstrap" 
    This setting has the lowest priority.
  • A URL parameter (for example: html?sap-ui-theme=sap_belize) can be used when starting a SAPUI5 application to set or override the initial theme.

    If you use the UI theme designer to define an own custom theme, you can append the location of the custom theme as a server-relative path to the sap-ui-theme parameter, separated by an @ sign:
    Although a full URL can be specified, the framework will only use the path information of the URL to prevent CSS-based attacks that would otherwise be possible by referencing CSS from a malicious server. In a more complex landscape, e.g. if the infrastructure of the UI theme designer is running on a separate server, either a Web dispatcher can be used to combine both servers in one namespace, or you should set a full URL using method sap.ui.getCore.applyTheme for custom apps as described below.

    The UI theme designer infrastructure stores themes for multiple technologies in the same location, each in its own subdirectory (UI5/ for SAPUI5). Other SAP products (like SAP Enterprise Portal) append only the common root URL to the sap-theme parameter. SAPUI5 therefore appends folder UI5/ to any given path that is defined in the sap-theme parameter.

  • You can use method sap.ui.getCore.applyTheme to switch themes on the fly. The application state is not lost, there is no server roundtrip (except for loading the CSS, if not cached), only the style sheets are exchanged.

    You can specify a second parameter containing the root URL of the theme. The URL is not restricted in any way, therefore the caller has to make sure that the URL is valid and safe. If the URL points to the theme infrastructure, it must already contain the folder suffix UI5/. SAPUI5 adds only this folder for the sap-ui-theme parameter.


You can also use these options to, for example, offer the possibility to switch themes in your app.

Using Custom Themes
To load an external custom theme, you set this theme either by static declaring in the page or by using the Core.setThemeRoot() method. This is very much like using registerModulePath() for libraries that are at a different location as follows:
  1. Define the path to the theme with the following code: sap.ui.getCore().setThemeRoot("my_theme", ""); so that SAPUI5 loads all theme resources from below this URL, for example, the library.css file of the sap.ui.core library will be loaded from:

    This base directory can also be given as second argument to method core.applyTheme(...).

    If some parts of the theme are at are at different locations than others, you can use the above call to set the default, but override the theme location for specific libraries by specifying them in an array as second parameter: sap.ui.getCore().setThemeRoot("my_theme", ["","my.lib.two"], "");

  2. Configure the theme, by using one of the following options:
    • Use the same object structure as JSON string in an attribute of the SAPUI5 bootstrap script tag, for example:
      <script id="sap-ui-bootstrap" 
      	data-sap-ui-theme-roots='{"my_theme" : ""}'>
    • Specify the location of a theme with a URL parameter:
    • Use the global configuration object. Insert the following before the bootstrap script tag:
      <script type="text/javascript">
      window["sap-ui-config"] = {
      	themeRoots : {
      		"my_preconfigured_theme" : "",
      		"my_second_preconfigured_theme" : {
      			"" : "",
      			"sap.ui.core" : ""

      The first theme is completely at one location, while the second theme has the default location changed plus the location changed for the part of the theme that covers the sap.ui.core library.

Listening to ThemeSwitch-event

Whenever the theme is switched, an event is thrown indicating that there was a theme-switch triggered. If you want your application to be responsive to this event for whatever reason, you can use the following callback: