Manual:ResourceLoaderImageModule.php

Embedded images
When you reference images in CSS or LESS files, you can indicate that ResourceLoader should automatically create inline data URIs for them. See @embed documentation.

Generating icons from SVG files
SVG (Scalable Vector Graphics) files are preferable to raster images because they are resolution-independent. However, browser support for them varies, so you need to provide a raster image as a fallback.

ResourceLoaderImageModule: To use it, in your module definition (in extension.json or skin.json or the old PHP entry point), you specify at a minimum: ResourceLoader generates a CSS class rule for each image that specifies the icon as the  property for a selector and includes a fallback raster image.
 * abstracts the implementation of SVG and fallback images in CSS
 * generates the fallback image on-the-fly from the SVG
 * intelligently chooses the appropriate image for right-to-left and different languages according to your specification
 * generates multiple colored images from a single SVG according to your specification.
 * : a set of  file mappings
 * a specification for the name of the CSS rule for each image, either
 * a  to put in front of each name as , or
 * , a CSS selector name which includes the placeholder
 * , a CSS selector name which includes the placeholder

For example, the Gather extension's  includes When you request or depend on the  ResourceLoader module, it generates a CSS file that specifies the SVG as the background-image for the selector. In other words the response to https://en.wikipedia.org/w/load.php?modules=ext.gather.menu.icon&only=styles (reformatted for clarity) is:

Recent browsers will use the SVG embedded as a data URI, and others will fall back to requesting the rasterized background image, which ResourceLoader generates on-the-fly by converting the SVG to a PNG.

SVG conversion to raster
To convert the SVG original to a PNG raster image, ResourceLoader uses the same that you configure to create raster images of SVG files uploaded to the wiki (as in File:Example.svg). On Wikimedia wikis this is rsvg, which has some extra optimizations, but any converter will work.

Identifying different icons
If you need to use a different icon for right-to-left languages,, you can specify different icons in the  key. Instead of a simple  mapping for each icon name, for each name you provide a   key with different icons for   and. ResourceLoader determines the text direction according to the  parameter to the load request, and uses the appropriate icon. For example (in PHP): the CSS rule for  will use the appropriate SVG as the background image according to the direction of lang.

Similarly, if the icon is different in different languages (such as 'B' for Bold becomes 'G' in French), you can specify in the  key a default icon and then icons for particular languages. For example (in JSON):

Variants
The MediaWiki theme uses color to convey meaning, for example "destructive" operations appear red, and "progressive" operations that are part of a sequence of steps appear blue. See Intention colors in the Living style guide. Or you may want to define a gray variant, or an inverted white-on-black icon.

Instead of creating a set of nearly-identical icons for each color, ResourceLoader can generate these different icons as variants, as both SVG and raster images, from a single source SVG,

The way you indicate what variants to provide is by specifying a  key and for each variant, give its. Then rather than a simple  key, you specify   which has a   placeholder as well as a   placeholder; you can also provide a   key. creates a CSS rule for each variant of each name, and applies the color of the variant to the SVG. (To do so the  class wraps the SVG with a new group and sets the fill color.)

In order to make a given image available in a given variant, either the variant must be defined as, or the image definition must specify allowed variants. Since each variant requires some additional data to be sent to user's browser, variants shouldn't be made global unless you actually use each of the images in each of the variants.

For example, the MobileFrontend defines the following module, using global variants: The above is equivalent to the following, without global variants:

Loading data from separate JSON file
ResourceLoaderImageModule can also load the module definition (all options except the required ) from a separate JSON file, which can be convenient if the list gets too long. Any options in the module definition override options from the JSON file. Note that the paths to images in the separate JSON file must be the same as if they were in extension.json – they are not relative to that file.

SVG best practices

 * It's worth optimizing SVGs to reduce their size and thus the size of ResourceLoader responses, just as you optimize raster images.
 * You can hand-edit SVG XML to simplify them and remove extraneous objects.
 * Wikimedia uses the SVGO optimizer tool, the usual command line invocation is:


 * In order for variant color generation to work, the SVG should not set the color explicitly for any shape, otherwise that color won't change.

OOjs UI images
The MediaWiki theme of OOjs UI defines dozens of icons: see icons in the OOjs UI Demos and Iconography in the Living style guide. When clients request OOjs UI support with, it adds ResourceLoader resources such as 'oojs-ui.styles.icons' to the page. Since T92551 MediaWiki generates the CSS definition of these icons from SVG. To further reduce boilerplate code, it generates sets of icons from JSON files containing the icon information, using a specialized class.

Using OOjs UI images
If you want to use one of these icons in your own code, Now that the necessary styles will be loaded, you can use the icon: The icons can also be shown using OOjs UI widgets:
 * 1) find the icon you want in the demos or style guide above, e.g. the "block" icon
 * 2) see if it has a variant with the intention color you want, if any, e.g. destructive block. (If the icon is not available in the color you want, you have to access the SVGs and create your own ResourceLoaderImageModule.)
 * 3) find the image set that contains it; in this case it's in the "moderation" set.
 * 4) express a dependency on the ResourceLoader module for the image set 'oojs-ui.styles.icons-setname '; in this case it's 'oojs-ui.styles.icons-moderation'
 * 1) apply the classes   and one of   or   to the div or span where you want icons
 * 2) apply the class   or   to choose the icon to use; in this case it's.
 * 1) load OOjs UI: see OOjs UI/Using OOjs UI in MediaWiki
 * 2) display an IconWidget:
 * 3) * PHP:
 * 4) * JavaScript: