Icon Theme Application

Version 54.1 by Admin on 2021/03/16 17:56

wrenchManage and display icons used all over the wiki
Developed by

XWiki Development Team

1 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Standard


Since 6.2M1

Installable with the Extension Manager



  • Have a set of icon names that will render differently depending on the selected Icon Theme.
  • Select your Icon Theme just like you select your Color Theme.
  • Handle both icons made with images and icons made with fonts.

Icon List

The current list of available icons in Icon Themes is there as a draft.

To ensure the retro-compatibility, we will try to have a an equivalent to each silk icons in every icon theme.

Some of the Icon Themes available:

 Theme StatusType
 Silk (Bundled) PNG
 Font Awesome (Default) (BundledFont
 Glyphicons (Contrib)Font
 Font Awesome 5(Contrib) (Experimental)Font, SVG

For Users

Selecting the Icon Set

Go to the "presentation" section of the administration of your wiki.


Select the icon set you want to use.

Displaying using Wiki Syntax

You can display an icon using XWiki Syntax 2.1+ by using the format: image:icon:<icon name>

For example:


At the moment, this feature only works for the Silk Icon set. In the future, the icon will be displayed using the selected Icon Set.

For Developers

Displaying in a Script

To display an icon, you just need to use the $services.icon script service. For example:


If you are inside the {{html}} macro, you should use the following which will generate HTML directly:


Since 6.3RC1, you can render an icon from any specific icon theme present on the wiki, referenced by its name:

$services.icon.render('add', 'Silk')
$services.icon.render('add', 'Font Awesome')

## The last argument is used to disable the fallback to the default 
## icon theme if the icon 'add' does not exist in the 'Font Awesome' theme.
$services.icon.render('add', 'Font Awesome', false)

The icon could be either an image or a font icon. XWiki will automatically generates the good output to display correctly the image.

Since 10.6RC1, you can manually display an icon using its metadata:

## Since 10.6RC1:
## Metadata of 'add' icon with current icon theme.
## Metadata of 'add' icon using Silk theme.
$services.icon.getMetaData('add', 'Silk')
## Metadata of 'add' icon using Silk theme, without fallback.
$services.icon.getMetaData('add', 'Silk', false)

## Output example:
$services.icon.getMetaData('add', 'Silk')         ## {iconSetName=Silk, cssClass=, iconSetType=IMAGE, url=/xwiki/resources/icons/silk/add.png}
$services.icon.getMetaData('add', 'Font Awesome') ## {iconSetName=Font Awesome, cssClass=fa fa-plus, iconSetType=FONT, url=}
$services.icon.getMetaData('add', 'Invalid', false)  ## {}

## Usage:
#set ($metadata = $services.icon.getMetaData('add'))
#if ($metadata.iconSetType == 'IMAGE')
 {{html}}<img src="$metadata.url" alt="Icon" />{{/html}}
#elseif ($metadata.iconSetType == 'FONT')
 {{html}}<span class="$metadata.cssClass"></span>{{/html}}

The previous methods automatically pull the necessary resources to display the icon but you can also do it manually in case you are retrieving the icon from a REST API:

## Since 10.6RC1:
## Pull the resources of the current icon theme
## Pull the resources of the Silk icon theme

Creating a new Icon Set

To create a new Icon Set, you should create a page inside the IconThemes space. Then, go to the objects edit mode, and add an IconThemesCode.IconThemeClass object into your page. 


Then, edit your page with the wiki editor, and there you should fill the following content:

## General settings
xwiki.iconset.type =
xwiki.iconset.render.wiki =
xwiki.iconset.render.html =
xwiki.iconset.css =
xwiki.iconset.ssx =
xwiki.iconset.jsx =

## Icons
accept =
add =
xwiki.iconset.typetype of your icon set. Could be "image" or "font".
xwiki.iconset.render.wikienter here the wiki syntax that will display the icon. This line will be parsed by Velocity, and the $icon variable will correspond to the icon to display.
Example: xwiki.iconset.render.wiki = image:path:$xwiki.getSkinFile("icons/silk/${icon}.png")
xwiki.iconset.render.htmlenter here the HTML code that will display the icon. This line will be parsed by Velocity, and the $icon variable will correspond to the icon to display.
Example: xwiki.iconset.render.html = <img src="$xwiki.getSkinFile("icons/silk/${icon}.png")" alt="Icon" />
xwiki.iconset.css(optional) URL of a CSS file to enable to display the icon correctly. Will be parsed by Velocity.
Example: xwiki.iconset.css = $services.webjars.url('font-awesome/4.1.0/css/font-awesome.min.css')
xwiki.iconset.ssx(optional) Name of a page containing a Style Sheet Extension to enable to display the icon correctly.
Example: xwiki.iconset.ssx = IconThemes.FontAwesome
xwiki.iconset.jsx(optional) Name of a page containing a JavaScript Extension to enable to display the icon correctly.
Example: xwiki.iconset.jsx = IconThemes.FontAwesome Since 6.2-M2

Then, you enter all the icons with the following format:

name = value


add = fa-plus-circle

Script API

The icon module provides some script services:

$services.icon.render('home') ## generate the wiki syntax to display the icon
$services.icon.render('home', 'Font Awesome') ## same, but also sets the icon theme to use
$services.icon.render('home', 'Font Awesome', true) ## same, but enable or not the fallback, ie if the default icon theme is used if the icon theme specified does not exist or does not contain the specified icon.
$services.icon.renderHTML('home') ## generate the HTML code to display the icon
$services.icon.renderHTML('home', 'Font Awesome') ## see previously
$services.icon.renderHTML('home', 'Font Awesome', true) ## see previously
$services.icon.iconSetNames ## returns the list of all icon theme available in the wiki
$services.icon.iconNames ## returns the list of all icons that contains the current icon theme
$services.icon.getIconNames('Font Awesome') ## returns the list of all icons that contains the specified icon theme
$services.icon.currentIconSetName ## returns the name of the current icon theme (which is setted in the preferences)

Icon Picker

Since XWiki 6.4M2 This application proposes a picker to help user selecting an image inside the list of supported icons.


There is 2 ways for enabling it in your scripts: via a wiki macro or directly in javascript.

Icon Picker Macro

Using this macro is the easiest way to enable the icon picker.


{{iconPicker id="" class="" prefix="" /}}


id (optional)DOM id of the input field where the picker will apply
class (optional)CSS class of inputs where the picker will apply
prefix (optional)Prefix to add before the name of the icon in the input field (default: "image:icon:")


 <p>Field 1: <input type="text" id="myPicker" /></p>
 <p>Field 2: <input type="text" class="fieldWithPicker" /></p>

{{iconPicker id="myPicker" class="fieldWithPicker" prefix="icon:" /}}

Icon Picker Widget

The Icon Picker is a jQuery plugin that you can use through requirejs. It is far more easier to use the User Picker Macro, but in case you need it, we describe here an example of use.


With Velocity and HTML:

## Enable the CSS of the picker:
#set($discard = $xwiki.ssx.use('IconThemesCode.IconPicker'))

## JavaScript code:
<script language="javascript">
  // Configure requirejs to load the picker code
    paths: {
      'xwiki-icon-picker': '$xwiki.getURL($services.model.createDocumentReference('', 'IconThemesCode', 'IconPicker'), 'jsx', "minify=$!{escapetool.url($request.minify)}")'

  // Require jquery and the icon picker
  require(['jquery', 'xwiki-icon-picker'], function($) {
    // Here you can bind the picker to some elements.
    // Examples:
    $('#someElement').xwikiIconPicker(); // apply the picker to the field #someElement
    $('#someElement').xwikiIconPicker({prefix: 'image:icon:'}); // change the prefix inserted before the icon name

## The icons themes may need some SSX, so we ask for a rendering of an icon of each icon theme, to be able to display
## all icon themes in the picker
## ToDo: since it is a bit hacky, a better system would be to dynamically load the needed SSX on demand
#foreach($iconSetName in $services.icon.iconSetNames)
 #set($discard = $services.icon.render('wiki', $iconSetName))

Silk Icon Theme

The Silk Icon Theme uses the Silk icons set to be mapped as an Icon Theme. This is an icon library launched in 2005 that contains over 1000 png images at 16px resolution.

The Silk Icon Theme is the default theme and the one used for fallbacks.



Version Compatibility

XWiki versionSilk version used
6.2M1, 9.101.3


Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.

You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:

  1. Log in the wiki with a user having Administration rights
  2. Go to the Administration page and select the Import category
  3. Follow the on-screen instructions to upload the downloaded XAR
  4. Click on the uploaded XAR and follow the instructions
  5. You'll also need to install all dependent Extensions that are not already installed in your wiki


Dependencies for this extension (org.xwiki.platform:xwiki-platform-icon-ui 13.1):

  • org.xwiki.platform:xwiki-platform-icon-script 13.1
  • org.xwiki.platform:xwiki-platform-icon-default 13.1
  • org.webjars:requirejs 2.3.6
  • org.webjars:jquery 2.2.4

Get Connected