docs

Icon and Icon Pool

The sap-icon:// protocol supports the use of icons in your application based on the icon font concept, which uses an embedded font instead of a pixel image.

Compared to image-based icons, icon font is easily scalable and you can change the color and apply various effects via CSS. OpenUI5 provides the Icon control in the sap/ui/core/Icon module and a set of predefined icons available in IconPool in the sap/ui/core/IconPool module.

Note:

The icon font will not work if Web fonts are blocked for the user’s operating system, for example, by the Blocking Untrusted Fonts feature in Microsoft Windows (see Block untrusted fonts in an enterprise in the Microsoft Windows IT Center).

Using Custom Icons

To display your custom icons in all browsers that OpenUI5 supports, you need the woff2 version of your icon file. To use your own icon font file in the Icon control, the font file and the metadata for the icons in the font file need to be registered in the IconPool. You can register both of them by calling the IconPool.registerFont with a config object which contains the following options:

Note:

If neither metadata nor metadataURI is provided, a request is sent to fontURI/fontFamily.json to load the metadata.

Example:

The sap.tnt library provides an extra icon set. The sap/tnt/themes/base/fonts folder contains the SAP-icons-TNT.woff2 font file as well as the SAP-icons-TNT.json JSON file, which contains the mapping of the icon name and the icon’s hex code:

{
    "technicalsystem": "e000",
    "systemjava": "e001",
    "systemabap": "e002",
    "systemrecommendations": "e003",
    "system": "e004",
    "systemtrex": "e005",
    "systemtracks": "e006",
    "technicalinstance": "e008",
    "technicalscenario": "e007",
    "throughput-backlog": "e009",
    ...
}

Theme-Dependent Icons

Since UI5 version 1.117, a config section can be defined, into which the path configuration for the theme-dependent icon designs (e.g. Horizon theme) can be written. The key defines a regluar expression that matches the theme name, and the value represents the font file location for the respective theme. If the config property is defined, the mapping of the icons’ names and hex codes must be defined under an icons property as shown below.

Since UI5 version 1.117, the SAP-icons-TNT.json file contains the theme-dependent path configuration:

{
    "config": {
        "path": {
            "^sap_horizon.*": "sap/tnt/themes/base/fonts/horizon"
        }
    },
    "icons": {
        "technicalsystem": "e000",
        "systemjava": "e001",
        "systemabap": "e002",
        "systemrecommendations": "e003",
        "system": "e004",
        "systemtrex": "e005",
        "systemtracks": "e006",
        "technicalinstance": "e008",
        "technicalscenario": "e007",
        "throughput-backlog": "e009",
        ...
    }
}

The JSON file has the same name as the woff2 file, so it is not necessary to set metadataURI. To register the icon in the IconPool, use the following code. Note that in the example the metadata is not loaded until one icon from this icon set is used because lazy is set to true.

// "IconPool" required from module "sap/ui/core/IconPool"
IconPool.registerFont({
    collectionName: "tnt",
    fontFamily: "SAP-icons-TNT",
    fontURI: sap.ui.require.toUrl("sap/tnt/themes/base/fonts"),
    lazy: true
});

Referencing Icons

To reference icons, you assign the icon URI to a control by setting sURI for the control’s corresponding property. To get the icon URI, the following two options exist:

Using Icons in Controls

The following code snippet shows how the sap.m.Dialog control that already supported image URI has been adapted to also support icon URI. IconPool.createControlByURI returns an instance of Icon if sURI is an icon URI. Otherwise, the second parameter is called as a constructor method to create an instance. The sURI is set for the src property of the instance.

    // "IconPool" required from module "sap/ui/core/IconPool"
    // "Image" required from module "sap/m/Image"
    // "Device" required from module "sap/ui/Device"
    Dialog.prototype.setIcon = function(sURI){
        this.setProperty("icon", sURI, true);
        if (!Device.os.ios){
           //icon is only shown in non iOS platform
           if (this._iconImage) {
               this._iconImage.setSrc(sURI);
           } else {
               this._iconImage = IconPool.createControlByURI({
                   src: sURI //src is mandatory
                   /* other properties can be put here, such as id, ...*/
               }, Image);
           }
       }
       return this;
    };

If the img tag is rendered directly in the control, and not by creating an image control, use the writeIcon method on sap/ui/core/RenderManager. The writeIcon method accepts a URI as the first parameter. Depending on this parameter, it renders either an img or a span tag. The classes and attributes defined in the second and third parameter are also added to the rendered tag.

Font face is inserted into the style sheet dynamically when Icon or writeIcon are used for the first time. If the special character needs to be written into the CSS to show the icon in a control, call the IconPool.insertFontFaceStyle function to insert the built in font face in your CSS. This is shown in the following code snippet:


    // "IconPool" required from module "sap/ui/core/IconPool"
    IconPool.insertFontFaceStyle();
});

Styling the Icon Control

If you render the icon span directly in your control, or use icon font in your CSS, you have the maximal freedom to style the Icon control.

If you use the icon by creating an instance of Icon within your control, however, use the CSS class sapUiIcon to add a new style to the icon. To avoid influencing the style of icons used elsewhere, wrap the icon CSS class with your control’s root DOM class.

Consuming SAP Icon Font in a Non-UI5 Environment

You can consume the predefined SAP-icons icon font also in an environment where UI5 isn’t available. An integration could look like the following:

This site is open source. Improve this page.