Skip to Content

Icons

Version 4.2 by Lucas Charpentier (Sereza7) on 2024/08/06
Warning: For security reasons, the document is displayed in restricted mode as it is not the current version. There may be differences and errors due to this.

Using icons in XWiki

In order to add an icon in XWiki content, use the Icon Macro in your velocity template. This is the recommended way, by default it will fetch the icon from the current icon theme.

In order to add an icon in a Velocity script, you can use the icon manager script service with syntax such as $services.icon.renderHTML('add').

In order to access an icon, you can also use the Icon REST API. It's recommended to not query a specific icon theme but let the API share the icon of the current icon theme.

In the codebase, you might still find some other ways to use icons that are deprecated:

Icon set

XWiki supports one icon set. It is often referenced in the documentation as The XWiki Icon Set or the Icon Set. This is the set of icons that XWiki wants to support.

Icon naming convention

In order to keep long term consistency on the icon names, a set of rules have been discussed. Those must be followed when introducing a new icon to the XWiki Icon Set.

  • Use kebab-case.
  • For composite icon names, the main noun is the first in the name.
  • Remove hyphens from compound nouns.

Examples:

  • ‘file-add’ and not ‘add-file’ because the main noun is ‘file’ here ‘add’ is the action
  • ‘pdf-export’ and not ‘export-pdf’ because the main noun is ‘pdf’ and ‘export’ is the action.
  • ‘bullet-black’ and not ‘black-bullet’ because the main noun is ‘bullet’ and ‘black’ is an adjective
  • ‘emoticon-smile’ and not ‘smile-emoticon’ because the main noun is ‘emoticon’ and ‘smile’ is a complementary noun.
  • ‘fastforward’ is a compound noun from which we removed the hyphen.
  • ‘file-pdf’ and not ‘pdf-file’ because in the meaning of this icon, the main meaning is ‘file’, while ‘pdf’ only helps to refine the meaning. On the contrary, ‘pdf-file’ would mean that we want a ‘file’ variation on the main concept of ‘pdf’.

Icon themes

XWiki supports multiple icon themes. On a standard flavor of XWiki, Silk and Font Awesome (FA) are available. As of now, the default on the standard flavor is Font Awesome 4. Naturally, all icons from the Icon Set should be present in every Icon Theme!

List of available icon theme extensions

Mapping

Error

TODO

  Split this table in between multiple columns and move those to the appropriate piece of documentation.
  Finish to add all of the mapping lines as iconMappingClass objects on this page

The icons are sorted alphabetically.

Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [xwiki:Documentation.DevGuide.FrontendResources.Icons.WebHome]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.

Icon strategy

As of now, there's a consensus that the skeuomorph based Silk icons do look out of place in our modern UI.
One of the long term goals of the development team is to migrate the default to a more up to date icon theme.
However, integration of Silk icons in some UIs sometimes pre-dated the icon theme feature. This is why some elements of the XWiki interface use hard coded Silk icons. Replacing those icons with actual icontheme references is not always easy, because the concept they picture is not always mappable in other icon themes, and there's no easy conversion from Silk to the icon theme. This is especially apparent for technical icons: in Font Awesome, there's no icon for all kind of fields we could show in Silk, and there's no icon for the `composite` icons from Silk such as `addfile`, `editfile`, `addcomment`, `adduser`. Technically, most of those icons could be done with Font Awesome icon stacking, but those icons are difficult to find in any icon theme, so it might not make the most sense to add them to the icon set.

As of now, we can see that hard coded Silk references are still present.

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected