namespace sap.ui.core.IconPool

Control sample: sap.ui.core.IconPool
Visiblity: public
Available since: N/A
Module: sap/ui/core/IconPool
Application Component: CA-UI5-COR

The IconPool is a static class for retrieving or registering icons. It also provides helping methods for easier consumption of icons. There are already icons registered in IconPool, please use the Demo App named "Icon Explorer" to find the name of the icon.

In order to use the icon inside an existing control, please call sap.ui.core.IconPool.getIconURI and assign the URI to the control's property which supports icons. If you want to support both, icons and standard images in your own control, please use the static method sap.ui.core.IconPool.createControlByURI to either create an Icon in case the first argument is an icon-URL or another control which you define by providing it as the second argument.


Nodes Overview

Node Description

Methods Overview

Method Description
sap.ui.core.IconPool.addIcon

Register an additional icon to the sap.ui.core.IconPool.

sap.ui.core.IconPool.createControlByURI

Creates an instance of sap.ui.core.Icon if the given URI is an icon URI, otherwise the given constructor is called. The given URI is set to the src property of the control.

sap.ui.core.IconPool.fontLoaded

Checks if the icon font is loaded

sap.ui.core.IconPool.getIconCollectionNames

Returns all names of registered collections in IconPool

sap.ui.core.IconPool.getIconForMimeType

Returns the icon url based on the given mime type

sap.ui.core.IconPool.getIconInfo

Returns an info object for the icon with the given iconName and collectionName.

Instead of giving name and collection, a complete icon-URI can be provided as iconName. The method will determine name and collection from the URI, see IconPool.isIconURI for details.

The returned info object has the following properties:

  • string: name Name of the icon
  • string: collection Name of the collection that contains the icon or undefined in case of the default collection
  • string: uri Icon URI that identifies the icon
  • string: fontFamily CSS font family to use for this icon
  • string: content Character sequence that represents the icon in the icon font
  • string: text Alternative text describing the icon (optional, might be empty)
  • boolean: suppressMirroring Whether the icon needs no mirroring in right-to-left mode

sap.ui.core.IconPool.getIconNames

Returns all name of icons that are registered under the given collection.

sap.ui.core.IconPool.getIconURI

Returns the URI of the icon in the pool which has the given iconName and collectionName.

sap.ui.core.IconPool.insertFontFaceStyle

Adds CSS code to load an icon font to the DOM

sap.ui.core.IconPool.isIconURI

Returns whether the given uri is an icon URI.

A string is an icon URI when it can be parsed as a URI and when it has one of the two forms

  • sap-icon://collectionName/iconName
  • sap-icon://iconName
where collectionName and iconName must be non-empty.

sap.ui.core.IconPool.registerFont

Registers an additional icon font to the icon pool

sap.ui.core.IconPool.addIcon

Register an additional icon to the sap.ui.core.IconPool.

Param Type DefaultValue Description
iconName string

the name of the icon.

collectionName string

the name of icon collection. The built in icons are with empty collectionName, so if additional icons need to be registered in IconPool, the collectionName can't be empty.

iconInfo object

the icon info which contains the following properties:

fontFamily string

is the name of the font when importing the font using @font-face in CSS

content string string[]

is the special hexadecimal code without the prefix, for example "e000" or several of them

overWrite boolean false

indicates if already registered icons should be overwritten when the same name and collection are given. The built in icons can never be overwritten.

suppressMirroring boolean false

indicates whether this icon should NOT be mirrored in RTL (right to left) mode.

resourceBundle module:sap/base/i18n/ResourceBundle

ResourceBundle to be used for translation. Key format: "Icon.".

sap.ui.core.IconPool.createControlByURI

Creates an instance of sap.ui.core.Icon if the given URI is an icon URI, otherwise the given constructor is called. The given URI is set to the src property of the control.

Param Type DefaultValue Description
setting string object

Contains the properties which will be used to instantiate the returned control. All properties of the associated constructor can be used. Unknown properties are ignored. It should contain at least a property named src. If it's given with a string type, it will be taken as the value of src property.

constructor function

The constructor function which is called when the given URI isn't an icon URI

sap.ui.core.IconPool.fontLoaded

Checks if the icon font is loaded

Param Type DefaultValue Description
sCollectionName string

icon collection name

sap.ui.core.IconPool.getIconCollectionNames

Returns all names of registered collections in IconPool

Param Type DefaultValue Description

sap.ui.core.IconPool.getIconForMimeType

Returns the icon url based on the given mime type

Param Type DefaultValue Description
sMimeType string

the mime type of a file (e.g. "application/zip")

sap.ui.core.IconPool.getIconInfo

Returns an info object for the icon with the given iconName and collectionName.

Instead of giving name and collection, a complete icon-URI can be provided as iconName. The method will determine name and collection from the URI, see IconPool.isIconURI for details.

The returned info object has the following properties:

Param Type DefaultValue Description
iconName string

Name of the icon, or a complete icon-URI with icon collection and icon name; must not be empty

collectionName string

Name of the icon collection; to access built-in icons, omit the collection name

loadingMode string "sync"

The approach for loading the icon info, if it is not already available: sync - font metadata is loaded synchronously and the icon info is returned immediately async - a promise is returned that returns the icon info when the font metadata is loaded mixed - until the font metadata is loaded a promise is returned, afterwards the icon info

sap.ui.core.IconPool.getIconNames

Returns all name of icons that are registered under the given collection.

Param Type DefaultValue Description
collectionName string

the name of collection where icon names are retrieved.

sap.ui.core.IconPool.getIconURI

Returns the URI of the icon in the pool which has the given iconName and collectionName.

Param Type DefaultValue Description
iconName string

Name of the icon, must not be empty

collectionName string

Name of the icon collection; to access built-in icons, omit the collection name

sap.ui.core.IconPool.insertFontFaceStyle

Adds CSS code to load an icon font to the DOM

Param Type DefaultValue Description
sFontFace string

the file name of the font face

sPath string

the path to the font file

sCollectionName string

the collection name, if not specified the font face is used

sap.ui.core.IconPool.isIconURI

Returns whether the given uri is an icon URI.

A string is an icon URI when it can be parsed as a URI and when it has one of the two forms

where collectionName and iconName must be non-empty.

Param Type DefaultValue Description
uri string

The URI to check

sap.ui.core.IconPool.registerFont

Registers an additional icon font to the icon pool

Param Type DefaultValue Description
oConfig object

configuration object for registering the font

fontFamily string

the file name of the font face

collectionName string

a collection name for the font, if not specified the font face will be used

fontURI sap.ui.core.URI

the location where the font files are physically located

metadata object

a configuration object mapping the icon name to the hexadecimal icon address in the font

metadataURI object

an URI to a file containing the configuration object specified with oConfig.metadata

lazy boolean

load the icon font metadata only when an icon is requested with #.getIconInfo if not specified a JSON file with the name oConfig.fontFamily will be loaded from the location specified in oConfig.fontURI