Icons

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:

• Use the XWiki Syntax for icons . As of now, these icons do not follow the current icon theme and are always rendered using Silk. See XWIKI-10758: Bind icons of the wiki syntax to the icon theme . Moreover, using this syntax can pose a security threat.
• Use icon references as the image background of your HTML node. This method should be avoided to reduce technical debt.

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’.

Updating the icon set

1. Removing an icon
   • If an icon does not fit anymore in the current context, it should be deprecated and not fully removed. This means that it is moved at the end of the iconTheme mapping files and under a section that provides the version this icon was deprecated in. Deprecated icons should not be used in new content.
2. Adding an icon
   • If there's a need for a new icon, the XWiki icon set can be extended. Such an extension is a non reversible change, it should be discussed with the community on the forum. In the proposal, make sure to provide a mapping for at least four icon themes: Silk, FA4, Glyphicons and the Material Icons. 
   • Even if the XWiki core Development Team only supports Silk and FA4, we still want to make sure that the proposed icons represent concepts generic enough so that they can be mapped to all or most icon themes that can exist.
   • If not all of those mappings are possible, provide an extra justification for its inclusion in the XWiki icon set.
   • Do not duplicate icons. Note that mappings can be similar with different semantics (that can change mappings on only some icon themes).
3. Renaming an icon
   • Such a decision should be checked with the community too. Make sure to still follow our naming convention. Once the decision is validated, deprecate the old name and add the mappings for the new names.

Icon themes

XWiki allows to use multiple icon themes. The XWiki Standard flavor bundles the Silk and Font Awesome (FA) icon themes. As of now, the default icon theme in the Standard flavor is Font Awesome 4. Naturally, all icons from the Icon Set should be present in every Icon Theme!

The 2 icon themes supported by the core XWiki core Development Team are:

• Silk
• Font Awesome

List of available icon theme extensions

Mapping

The icons are sorted alphabetically.

Name	Silk	Font Awesome	Glyphicon (Bootstrap)	Elusive
add	add	fa-plus	glyphicon-plus	el-icon-plus
align-center	text_align_center	fa-align-center	glyphicon-align-center	el-icon-align-center
align-justify	text_align_justify	fa-align-justify	glyphicon-align-justify	el-icon-align-justify
align-left	text_align_left	fa-align-left	glyphicon-align-left	el-icon-align-left
align-right	text_align_right	fa-align-right	glyphicon-align-right	el-icon-align-right
anchor	anchor	fa-anchor
arrow-in	arrow_in	fa-window-minimize
arrows	arrow_out	fa-arrows-alt	glyphicon-fullscreen
attach	attach	fa-paperclip	glyphicon-paperclip	el-icon-paper-clip
backward	control_rewind	fa-backward	glyphicon-backward	el-icon-backward
bell	bell	fa-bell	glyphicon-bell	el-icon-bell
bold	text_bold	fa-bold	glyphicon-bold	el-icon-bold
bomb	bomb	fa-bomb
book	book	fa-book	glyphicon-book	el-icon-book
branch	arrow_branch	fa-code-fork
briefcase	briefcase	fa-briefcase	glyphicon-briefcase	el-icon-briefcase
bug	bug	fa-bug
building	building	fa-building
bullet-black	bullet_black	fa-circle
calculator	calculator	fa-calculator
calendar	calendar	fa-calendar	glyphicon-calendar	el-icon-calendar
camera	camera	fa-camera	glyphicon-camera	el-icon-camera
car	car	fa-car	glyphicon-bed	el-icon-car
caret-down	bullet_arrow_down	fa-caret-down	glyphicon-triangle-bottom	el-icon-caret-down
caret-right	bullet_go	fa-caret-right	glyphicon-triangle-right	el-icon-caret-right
caret-up	bullet_arrow_up	fa-caret-up	glyphicon-triangle-top	el-icon-caret-up
certificate	rosette	fa-certificate	glyphicon-certificate	el-icon-certificate
chart-bar	chart_bar	fa-bar-chart-o
chart-organisation	chart_organisation	fa-sitemap
check	accept	fa-check	glyphicon-ok	el-icon-ok
clock	clock	fa-clock-o
cloud	weather_clouds	fa-cloud	glyphicon-cloud	el-icon-cloud
coffee	cup	fa-coffee
cog	cog	fa-cog	glyphicon-cog	el-icon-cog
columns	text_columns	fa-columns
comment	comment	fa-comment	glyphicon-comment	el-icon-comment
comments	comments	fa-comments
contrast	contrast	fa-adjust
copy	page_copy	fa-copy	glyphicon-edit	el-icon-file-edit
creditcard	creditcards	fa-credit-card	glyphicon-credit-card	el-icon-credit-card
cross	cross	fa-times	glyphicon-remove	el-icon-remove
cube	box	fa-cube
cubes	bricks	fa-cubes
cut	cut	fa-cut
database	database	fa-database
delete	delete	fa-minus-circle	glyphicon-minus-sign	el-icon-minus-sign
desktop	computer	fa-desktop
dollar	money_dollar	fa-dollar
down	arrow_down	fa-arrow-down	glyphicon-arrow-down
download	application_put	fa-download	glyphicon-download-alt	el-icon-download-alt
drive	drive	fa-hdd-o	glyphicon-hdd	el-icon-hdd
edit	page_edit	fa-edit	glyphicon-edit	el-icon-edit
eject	control_eject	fa-eject	glyphicon-eject	el-icon-eject
emoticon-smile	emoticon_smile	fa-smile-o	glyphicon-user	el-icon-smiley
envelope	email	fa-envelope-o	glyphicon-envelope	el-icon-envelope
error	exclamation	fa-exclamation-circle	glyphicon-exclamation-sign	el-icon-exclamation-sign
euro	money_euro	fa-euro	glyphicon-euro	el-icon-euro
eye	eye	fa-eye	glyphicon-eye-open	el-icon-eye-open
fastforward	control_fastforward	fa-fast-forward	glyphicon-fast-forward	el-icon-fast-forward
fastbackward	control_rewind	fa-fast-backward
female	female	fa-female
file	page	fa-file	glyphicon-file	el-icon-file
file-archive	page_white_compressed	fa-file-archive-o
file-code	page_white_code	fa-file-code-o
file-excel	page_white_excel	fa-file-excel-o
file-pdf	page_white_acrobat	fa-file-pdf-o
file-powerpoint	page_white_powerpoint	fa-file-powerpoint-o
file-text	page_white_text	fa-file-text-o
file-white	page_white	fa-file-o
file-word	page_white_word	fa-file-word-o
film	film	fa-film	glyphicon-film	el-icon-film
filter	find	fa-filter
flag	flag_blue	fa-flag	glyphicon-flag	el-icon-flag
floppydisk	disk	fa-floppy-o	glyphicon-floppy-disk	el-icon-floppy-disk
folder	folder	fa-folder	glyphicon-folder-open	el-icon-folder-open
font	font	fa-font	glyphicon-font	el-icon-font
gamepad	controller	fa-gamepad
gbp	money_pound	fa-gbp	glyphicon-gbp	el-icon-gbp
glass	drink	fa-glass	glyphicon-glass	el-icon-glass
group	group	fa-group
heart	heart	fa-heart	glyphicon-heart	el-icon-heart
heart-empty	heart	fa-heart-o	glyphicon-heart-empty	el-icon-heart-empty
home	house	fa-home	glyphicon-home	el-icon-home
image	image	fa-image	glyphicon-picture	el-icon-picture
indent-left	text_indent	fa-indent	glyphicon-indent-left	el-icon-indent-left
indent-right	text_indent_remove	fa-outdent	glyphicon-indent-right	el-icon-indent-right
info	information	fa-info-circle	glyphicon-info-sign	el-icon-info-sign
italic	text_italic	fa-italic	glyphicon-italic	el-icon-italic
key	key	fa-key
keyboard	keyboard	fa-keyboard-o
left	arrow_left	fa-arrow-left	glyphicon-arrow-left
lightbulb	lightbulb	fa-lightbulb-o
link	link	fa-link	glyphicon-link	el-icon-link
list	application_view_list	fa-list-alt	glyphicon-list-alt	el-icon-list-alt
list-bullets	text_list_bullets	fa-list-ul	glyphicon-list	el-icon-list
list-numbers	text_list_numbers	fa-list-ol
lock	lock	fa-lock	glyphicon-lock	el-icon-lock
login	user_go	fa-sign-in	glyphicon-log-in	el-icon-circle-arrow-right
logout	user_go	fa-sign-out	glyphicon-log-out	el-icon-circle-arrow-right
male	male	fa-male
menu	bullet_arrow_down	fa-bars	glyphicon-menu-hamburger	el-icon-lines
minus-square	bullet_toggle_minus	fa-minus-square	glyphicon-minus-sign	el-icon-minus-sign
money	money	fa-money
more-vertical	bullet_arrow_down	fa-ellipsis-v	glyphicon-option-vertical	el-icon-chevron-down
move	page_go	fa-external-link	glyphicon-new-window	el-icon-share
music	music	fa-music	glyphicon-music	el-icon-music
page	page_white_text	fa-file-o	glyphicon-file	el-icon-file
paste	paste_plain	fa-paste
pause	control_pause	fa-pause	glyphicon-pause	el-icon-pause
pencil	pencil	fa-pencil	glyphicon-pencil	el-icon-pencil
phone	telephone	fa-phone
play	control_play	fa-play	glyphicon-play	el-icon-play
plus-square	bullet_toggle_plus	fa-plus-square	glyphicon-plus-sign	el-icon-plus-sign
print	printer	fa-print
question	help	fa-question-circle	glyphicon-question-sign	el-icon-question-sign
random	arrow_switch	fa-random	glyphicon-random	el-icon-random
refresh	arrow_refresh	fa-refresh	glyphicon-refresh
remove	cancel	fa-times-circle	glyphicon-remove-sign	el-icon-remove-sign
repeat	arrow_redo	fa-repeat	glyphicon-retweet
right	arrow_right	fa-arrow-right	glyphicon-arrow-right
rotate-left	arrow_rotate_anticlockwise	fa-rotate-left
rotate-right	arrow_rotate_clockwise	fa-rotate-right	glyphicon-repeat
rss	feed	fa-rss
search	magnifier	fa-search	glyphicon-search	el-icon-search
search-minus	zoom_out	fa-search-minus
search-plus	zoom_in	fa-search-plus
shield	shield	fa-shield
shoppingcart	cart	fa-shopping-cart	glyphicon-shopping-cart	el-icon-shopping-cart
soccer	sport_soccer	fa-futbol-o
space	folder	fa-folder-open	glyphicon-folder-open	el-icon-folder-open
star	star	fa-star
step-forward	control_end	fa-step-forward	glyphicon-step-forward	el-icon-step-forward
step-backward	control_start	fa-step-backward	glyphicon-step-backward	el-icon-step-backward
stop	control_stop	fa-stop	glyphicon-stop	el-icon-stop
strikethrough	text_strikethrough	fa-strikethrough
subscript	text_subscript	fa-subscript
sun	weather_sun	fa-sun-o
superscript	text_superscript	fa-superscript
switch	arrow_switch	fa-random	glyphicon-random	el-icon-random
table	table	fa-table
table-sort	table_sort	fa-sort
terminal	application_osx_terminal	fa-terminal	glyphicon-console
th	application_view_tile	fa-th	glyphicon-th	el-icon-th
translate	page_white_world	fa-language	glyphicon-globe	el-icon-globe
trash	bin	fa-trash	glyphicon-trash	el-icon-trash
truck	lorry	fa-truck
underline	text_underline	fa-underline
undo	arrow_undo	fa-undo
unlink	link_break	fa-unlink
unlock	lock_open	fa-unlock
up	arrow_up	fa-arrow-up	glyphicon-arrow-up
user	user	fa-user
volume-up	sound	fa-volume-up
volume-down	sound_low	fa-volume-down
volume-off	sound_none	fa-volume-off
warning	error	fa-exclamation-triangle	glyphicon-warning-sign	el-icon-warning-sign
wiki	world	fa-globe	glyphicon-globe	el-icon-globe
world	world	fa-globe	glyphicon-globe	el-icon-globe
wrench	wrench	fa-wrench	glyphicon-wrench	el-icon-wrench
yen	money_yen	fa-yen

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.