ResourceLoader/Core modules

This page lists modules that ship with MediaWiki core by default. It reflects the current development version of MediaWiki and may vary from the latest stable release. It does not claim to be as comprehensive and up to date as Wikimedia's JS documentation on doc.wikimedia.org, but offers much additional guidance. For older modules, see the Migration guide.

The modules  and   together form the base environment ("startup") and are always present. They must not be declared as dependencies.

mediawiki


This is the MediaWiki base module. It initialises the  global object.

mw.config
For a list of stable config keys to read from, see Manual:Interface/JavaScript.

mw.hook
A framework for registering and firing events in JavaScript (as opposed to doing everything on document ready). For example, the snippet below provides a message once the categories on a page load:

In user scripts and gadgets you can fire hooks/events prefixed by "userjs.". E.g.: Then you subscribe to this event like so:

hook execution order
Note that hooks are run in a sequence (and in place where they are fired).

Above will result in following order:
 * 1) before init
 * 2) before hooks, Object { abc: "default" }
 * 3) inside a hook, Object { abc: "changed in hook" }
 * 4) after hooks, Object { abc: "changed in hook" }
 * 5) after init, Object { abc: "changed in hook" }

mw.html
Helper functions for escaping and creating strings of HTML.

mw.loader.load
Load one or more modules, a script or a stylesheet. To load an external script or stylesheet, the URL must start with either " ", " " or " " (protocol-relative), or " " (local path). Provide a MIME-type as second parameter (either " " or " "). If no MIME-type is provided, the default " " is assumed. creates an asynchronous request, if you need to run code that depends on a module, use mw.loader.using instead (which provides a callback). If you need a callback from an external script, use mw.loader.getScript (or ).

Loader instructions represent the intent that a module by that name should be loaded. It will not load the same module a second time if it has already been loaded previously. This does not apply to scripts and stylesheets – they will be loaded each time, even if loaded previously. If a script defines, you can use   to check if that script has already been loaded.

mw.loader.using
Load one or more modules, and execute a function once those modules are loaded. See

mw.loader.getScript
Load a script by URL. Returns a jQuery promise object which can be used to specify callbacks.

Example: To get a single callback from multiple promises, use  or Promise.all

mw.inspect
Shortcut for. Shows in the console a list of all ResourceLoader modules that are loaded on this page, sorted by the total size of each module's JavaScript, CSS, etc.



mw.log
Collection of methods to help log messages to the console.

mw.message

 * See also Manual:Messages API
 * See also Manual:Messages API

If the  module is loaded, the behaviour of this module changes significantly. See above link.

mw.now
Get the current time, measured in milliseconds since January 1, 1970 (UTC).

On browsers that implement the Navigation Timing API, this function will produce floating-point values with microsecond precision that are guaranteed to be monotonic. On all other browsers, it will fall back to using.

mw.track
Track an analytic event.

This method provides a generic means for MediaWiki JavaScript code to capture state information for analysis. Each logged event specifies a string topic name that describes the kind of event that it is. Topic names consist of dot-separated path components, arranged from most general to most specific. Each path component should have a clear and well-defined purpose. Data handlers are registered via `mw.trackSubscribe`, and receive the full set of events that match their subscription, including those that fired before the handler was bound.

The WikimediaEvents extension demonstrates how to add a subscriber for the "timing" and "counter" topics (example).

mw.notify
Creates bubble notifications. Basic examples: For available options, see Bubble notifications § API.

mediawiki.user


Module that represents information about the current user.

mw.user.clientPrefs
Available since 1.41.0-wmf.20

Can be used to manipulate certain classes on the HTML element such that they do not result in a flash of unstyled content. This can be utilized where you need to make render blocking changes for anonymous users.

By design the only classes that can be manipulated are classes with the suffix -clientpref-[A-Za-z0-9]. This is to prevent unintended manipulation of classes as well as serving as an indicator to people viewing the HTML source of what classes are subject to manipulation.

mw.user.options
Contains the preferences of the user, or the defaults when logged out.

This module is loaded asynchronously and may depend on a separate HTTP request for the  module. Always declare the relevant dependencies for your module, or use.

mw.user.tokens
This contains an object, pre-populated with tokens for use by.

mediawiki.api


This module provides the  constructor. The main methods of the  object are ,  , and. The  module (and its plugins) return a  – similar to   (and its derivatives such as ,   and  ).

Before MediaWiki 1.32, the methods were part of separate modules named under. These have been merged into the main module, so you only have to depend on that module. The submodules have been deprecated with warnings. These submodules have been removed in MediaWiki 1.33.

Examples of methods that are available:


 * - Edit an existing page.
 * - Changes one or more user preferences.
 * - Add a given title (or titles) to the user's watchlist.

mediawiki.cookie


Cookie module that uses the same settings as the MediaWiki server-side configuration (except for ).

Usage example:

This module prepends the cookie names with  (e.g. " enwiki myCookie=some-value").

Avoid accessing the same cookie in different ways, for example via  and via , because you may encounter issues if doing so.

See the API documentation for available options.

mediawiki.errorLogger


Stub for logging Javascript errors; always loaded. Provides a method for logging caught exceptions: Sends two kinds of events: By default nothing is done with these events; an  handler can forward them to the appropriate logging API. See e.g. clientError.js in WikimediaEvents, or Sentry.
 * : this is where errors logged via  go
 * : uncaught exceptions reported by the browser

mediawiki.feedback


User interface for collecting feedback, particularly on new features.

mw.ForeignApi
Al. , an extension of  specifially geared toward handling everything required to communicate with another MediaWiki wiki via cross-origin requests (CORS). See Manual:CORS.

mw.ForeignRest
Extension of mw.Rest.

mw.ForeignUpload
Extension of mw.Upload.

mediawiki.jqueryMsg


This module upgrades the  parser to support basic wikitext localisation and formatting features. For example,  is required for plural and gender support, the int: magic word and links.

mediawiki.storage


Wrapper for HTML5 Web Storage (localStorage, and sessionStorage).

If you are migrating from, note that   and   only store string values. Use  and   or  /  accordingly when setting and getting non-string values. You may also use  and    so that MediaWiki transparently interleaves a JSON serialization.

mediawiki.ui


Please use Codex instead.

UI module developed as part of the Agora project. It defines  CSS styles. It is used in the Login and Create account forms and several extensions. It provides one appearance for Vector and another for the rest of the skins.

mediawiki.widgets


Module providing MediaWiki-specific OOUI widgets like user input widget or namespace input widget.

addCSS
Adds a element to the HEAD and returns the CSSStyleSheet object.

The CSSStyleSheet object can be used to disable the CSS rules at any later time and re-enable them as well. This can be done through the 'disabled' attribute. When setting this to true, the rules no longer apply. When setting to false, the rules apply again.

See also W3 on CSSStyleSheet for more info.

addPortlet
This function allows you to create a new portlet in the page.

Only the first argument is required which is the ID of the new portlet. When only using the first argument, no portlet will be added to the page and you must insert it yourself using the return value. When only specifying the first value, you must append the portlet before using the mw.util.addPortletLink API. The second argument allows you to create a label - which is important for menus that appear in the sidebar or as dropdowns.

The third parameter when used will automatically append the portlet to the page before the provoided selector. It also provides a hint to skins which will make the new portlet mimic the styling of that portlet.

See the for more details.

Note about appending portlets in different locations:
Sometimes you will want to use the third parameter to mimic the styling of the portlet, but not to append before. To do this you must use the return value, and relocate it to another location.

addPortletLink
This function is ported from the legacy wikibits keeping it fully backwards compatible, with a few adjustments that support all core skins and with added support for a CSS-selector as. Note that it doesn't support MobileFrontend with the Minerva skin for logged-out users.

Only the first three arguments are required. In case you need to execute a custom function when the user clicks on a portlet, use the jQuery(...).on('click', .. ) on returned Element object to attach a callback that runs the code that should be executed.

See the for details.

Note about icons: The id will be used to construct an icon class in certain skins (for example mw-ui-icon-vector-gadget-cx-language in Vector). Callers are expected to add their own CSS in addition to calling addPortletLink if needed.

hidePortletLink
This function allows you to hide a portlet (menu) consistently across skins.

clearSubtitle
Usually called alongside addSubtitle when you want to refresh the subtitle contents. Given you can only add to the subtitle, you must clear its existing contents if you want to redraw.

$content
A jQuery object for a page's overall content area regardless of the skin used. This is, for example,  in the Vector-skin (before 1.20 it was  ).

This does not refer to the area where the page content goes. If you wish to work with that area of the page instead of the overall content area you should use  instead.

This property is populated on document ready. To use it, wait for  and be sure to have a module dependency on   which will ensure your document ready handler fires after initialization.

Because of the lazy-initialised nature of this property, you are discouraged from using it.

Here is a more advanced example involving loading in extra content with an AJAX request. Run this example on a page other than the main page.

getParamValue
This function returns the value of the specified URL parameter. By default it uses the current window's address. Optionally you can pass it a custom location.

It returns  if the parameter is not present. Returns an empty string if it was an empty parameter (such as

isIPv4Address
This function returns bool for passed string is valid IPv4 Address or not.

isIPv6Address
This function returns bool for passed string is valid IPv6 Address or not.

rawurlencode
This function returns an encoded string in its raw form for use in urls.

For building query strings, you may want to use jQuery.param instead:

wikiScript
This function returns the location of a script on the current wiki. Much like  in GlobalFunctions.php.

Parameters:  - Name of the script (e.g. 'api'), defaults to 'index'.

mediawiki.RegExp

 * See ResourceLoader/Migration guide § mediawiki.RegExp

mediawiki.Title


This sets the  constructor, which has several methods in its prototype. Basic example:

moment

 * Upstream documentation: https://momentjs.com/

Moment.js can parse, manipulate, and format date-time timestamps. Localisation is automatically loaded and configured for the current user interface language.

oojs


OOjs is a libary that provides a consistent way of implementing object-oriented design in JS.

oojs-ui


OOUI is a user interface toolkit based on OOjs. Note that  is just a legacy name for the module. See all the known OOUI module names.

jquery
More information about jQuery's presence in MediaWiki, see jQuery. For more about jQuery in general and all its core functions, refer to https://api.jquery.com/

ResourceLoader provides jQuery as part of its base environment (the loader client uses jQuery internally), therefore this module is always loaded and should not (and in fact can not) be loaded through ResourceLoader (as dependency or otherwise).

jquery.chosen
“Chosen is a jQuery plugin that makes long, unwieldy select boxes much more user-friendly.” — harvesthq.github.io

In fact, it turns a select into a combo box with autocomplete functionality by default but also supports grouping, and "tagging" (i.e. multiple values).

jquery.client

 * JS Documentation

A plugin that extracts information about the client's browser, layout engine, and operating system.

jQuery.client.profile
Here a few examples: Check for possible values of browser names, layout engines and platforms.

jquery.cookie
To use jQuery cookie methods, load the  module. It is recommended that you use  interface as it automatically applies appropiate settings based onMediaWiki site configuration (such as domain, path, and retention).

This plugin allows you to set, get and delete cookies.

When deleting a cookie, you must use the same path and domain used when the cookie was set.

Note that when MediaWiki server-side code sets a cookie it usually prefixes it with the database name; this prefix is available to JavaScript code as the  variable.

Note that users will likely get separate cookies for  and   paths in page URLs if you do not specify the extra option   when setting a cookie.

jquery.makeCollapsible

 * See also Manual:Collapsible elements.



Makes elements collapsible. It supports lots of variations such as:
 * Simple: Add " " to an element (a for example) with some content and save the page. The inner content of this element will be treated as collapsible content. Prepended to the element, before the collapsible content, is a toggle-link with a localized label (collapsible-expand, collapsible-collapse)
 * Initial state: Adding " " as additional class will cause the element to be initially collapsed when the page is loaded.
 * Custom label:HTML5 only Using the  and   attributes one can define a custom text for the toggle labels added by the script. When added in wikitext these could be populated by a localized message like:


 * Remote toggle: If you don't want the script to put the default toggle link (whether or not with a custom label) in your element, you can make one of your own. This could reside anywhere inside or outside the collapsible element. Its relationship to the collapsible element is detected by using an ID attribute with the prefix  and a corresponding class attribute with prefix   for the collapsible element and the togglelink respectively.

Example: Simple collapsible div or table

Input:

Output:

This is text is collapsible.

Example: Hide the collapsible element by default, the toggle element resides outside of it

Input:

Output:

Click here to toggle the element Lorem ipsum dolor sit amet... Clicking will toggle it also!

For other live examples, see Test Wikipedia - Collapsing Testpage.

jquery.tipsy
The library will be available for the forseeable future, but overlaps with functionality within OOUI and provides a suboptimal experience to mobile users. Where jQuery.tipsy is being used, we encourage developers to inspect OOUI and feedback on how the library might be improved to support the usecase that jquery.tipsy provides.

Example page; jQuery project page

jquery.ui
Please use Codex instead.

For more information on and demos for jQuery UI, refer to http://jqueryui.com/.

site
This module loads site scripts from the pages:


 * and  (depending on the current skin).
 * and  (depending on the current skin).

If is disabled by configuration, then the module is empty.

user
This module loads:


 * (depending on current skin),
 * (for each group the current user is a member of, e.g. "sysop", "bureaucrat" etc.)
 * (for each group the current user is a member of, e.g. "sysop", "bureaucrat" etc.)
 * (for each group the current user is a member of, e.g. "sysop", "bureaucrat" etc.)

If is disabled by configuration, then the "User" sub pages are not included.

If is disabled by configuration, then the "MediaWiki:Group-" pages are not included.