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.

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 "name" => "path/to/icon.svg" 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 File:SomeFile.svg). On Wikimedia wikis this is rsvg, but you can also use others.

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 name => path/to.svg 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.)

For example, the MobileFrontend defines (in PHP) the module:

SVG best practices
svgo --pretty --disable=removeXMLProcInst --disable=cleanupIDs --disable=collapseGroups
 * 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, a sample command line 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,
 * find the icon you want in the demos or style guide above, e.g. the "Remove" icon
 * see if it has a variant with the intention color you want, if any, e.g. destructive remove.
 * find the image set that contains it; in this case it's in icons (core).
 * express a dependency on the ResourceLoader module for the image set 'oojs-ui.styles.setname; in this case it's 'oojs-ui.styles.icons'
 * apply the class  to the div or span where you want the icon; in this case it's  . The module CSS also defines rules for several related CSS selectors. XXX Not quite this simple

If the icon is not available in the color you want, you have access to the SVGs and can create your own ResourceLoaderImageModule.